Part 3: Configuring the Microsoft Autoenrollment Servlet

This section will cover:

  • Installing the Auto Enrollment servlet
  • Updating the servlet configuration
  • Testing Auto Enrollment with EJBCA

In the examples below, the domain used is primekey.com, the domain realm is PRIMEKEY.COM, the EJBCA server hostname is ejbcaserver.primekey.com, and the Tomcat server hostname is tomcatserver.primekey.com. This guide assumes the path to Tomcat server is /opt/tomcat.

The text highlighted in red should be replaced with names in your environment.

Note that commands copy pasted from this page may need formatting metadata scrubbed and may contain unintended spaced.

1. Install the Autoenrollment Servlet on Tomcat Server

  1. Download the Auto Enrollment Servlet war file
  2. With Tomcat running, deploy the war file to the Tomcat webapps directory (/opt/tomcat/webapps)
  3. A new directory will appear named autoenroll

2. Configure the Autoenrollment Servlet on Tomcat Server

2.1 Kerberos authentication

Spnego is a mechanism to extend Kerberos authentication to HTTP servers such as Tomcat. Users authenticate to the Tomcat servlet using Windows Integrated Authentication (Kerberos) the same way they would authenticate to an internal Windows resource.  When the Kerberos authentication protocol is used, the identity of the user, including the sAMAccountName is also passed to the Tomcat servlet as part of the Kerberos ticket.

2.1.1 Creating the login.conf file

  1. Create a file named login.conf in your Tomcat directory (/opt/tomcat).

Edit login.conf and insert the following content:

spnego-client {
  com.sun.security.auth.module.Krb5LoginModule required;
};

spnego-server {
  com.sun.security.auth.module.Krb5LoginModule required
  storeKey=true
  isInitiator=false;
};

2.1.2 Creating the krb5.conf file

  1. Create a file named krb5.conf in your Tomcat directory (/opt/tomcat).

Edit krb5.conf and insert the following content, ensure to update references to your own domain:

[libdefaults]
  default_realm = PRIMEKEY.COM
  default_tkt_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
  default_tgs_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
  permitted_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc

[realms]
  PRIMEKEY.COM = {
  kdc = PRIMEKEY.COM
  default_domain = PRIMEKEY.COM
}

[domain_realm]
.primekey.com = PRIMEKEY.COM

2.2 Editing the server.xml file

  1. Copy the tomcat_server.jks keystore and aewsclient.jks file downloaded earlier to /opt/tomcat
  2. Edit /opt/tomcat/conf/server.xml
    1. Add the following section, to enable SSL, below the already commented 8443 section. Update the SSL server certificate and the password entries with your own:
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
 maxThreads="150" scheme="https" secure="true"
 clientAuth="false" sslProtocol="TLS"
 keystoreFile="/opt/tomcat/tomcat_server.jks"
 keystorePass="<PASSWORD>"
 />

2.3 Editing the autoenroll_config_directory.properties file

  1. Navigate to /opt/tomcat/webapps/autoenroll/WEB-INF/
  2. Update the autoenroll_config_directory.properties file with the path where the config files will be stored.
  3. Create the auto enroll config directory (e.g. /opt/tomcat/autoenroll_conf)
  4. Move msaes.properties, MSEnrollmentServlet.properties, MSTemplateToSettings.properties, template_file_mapping.properties, and the Template_Mappings directory to /opt/tomcat/autoenroll_conf

web.xml and autoenroll_config_directory.properties should be backed up in case of a redeployment because these files will be overwritten.

# Specify the path to config directory
# e.g. Config_Directory=/path/to/directory/
# You may remark this line if all config files are to stay in WEB-INF directory
Config_Directory=/opt/tomcat/autoenroll_conf

2.4 Editing the web.xml file

  1. Edit web.xml
    1. Update the spnego.preauth.username and spnego.preauth.password values with your service account (servlet-service) credentials.
    2. Update the spnego.krb5.conf path to ${catalina.home}/krb5.conf
    3. Update the spnego.login.conf path to ${catalina.home}/login.conf
  2. If not done so yet, create the Active Directory Bind account (autoenrollmentbind) with privileges to read Active Directory objects (add the account to the Cert Publishers group if certificate publishing to Active Directory is needed)
  3. Navigate to /opt/tomcat/autoenroll_conf
  4. Edit msaes.properties

Enter the login information for the Active Directory Bind account

# This file is used to specify the connection details for Active Directory:
# set up your bind Certificate Publisher account here
# Set to true if the connection should use SSL. This setting is currently unsupported and will have no effect.
#usessl=false
# Provide the port number for the Active Directory connection.
#port=389
# Provide login for a user with access to read objects in Active Directory.
# It can be in the form of a fully distinguished name or user principal name.
# This user should also be in the Cert Publishers group in order to publish certificates.
logindn=CN=autoenrollmentbind,CN=Users,DC=Company,DC=com
#Provide the password for the logindn user
loginpassword=<PASSWORD>|

2.5 Editing the MSEnrollmentServlet.properties file

  1. Edit MSEnrollmentServlet.properties

Update the location of the keystore with permissions to access Web Services API, Web Services URL, and the name of the CA for Auto Enrollment.

EJBCA_KeyStorePassword=<PASSWORD>
EJBCA_TrustedKeyStore=/opt/tomcat/aewsclient.jks
EJBCA_KeyStore=/opt/tomcat/aewsclient.jks
EJBCA_TrustedKeyStorePassword=<PASSWORD>
EJBCA_WebServiceUrl=https://ejbcaserver.primekey.com:8443/ejbca/ejbcaws/ejbcaws?wsdl
EJBCA_CAName=Issuing CA

2.6 Editing the MSTemplateToSettings.properties file

  1. Edit MSTemplateToSettings.properties.
    1. Update/add your Microsoft certificate template OID in the MSTemplateToSettings.properties file and set the EJBCA Certificate Profile and End Entity Profile that should map to the OID. Below is an example of a User Template settings. Update other attributes as desired.
#User
id1.used=true
id1.oid=1.3.6.1.4.1.311.21.8.9377535.8819452.10569393.8297822.7357582.214.8450877.6015317
id1.certprofile=User_Certificate_Profile
id1.eeprofile=User_End_Entity_Profile
id1.subject_name_format=common_name
id1.include_email_in_subjectdn=false
id1.include_email_in_san=false
id1.include_dns_name_in_san=false
id1.include_upn_in_san=true
id1.include_spn_in_san=false
id1.include_netbios_in_san=false
id1.include_domain_in_san=false
id1.include_objectguid_in_san=false
id1.additional_subjectdn_attributes=
id1.publish_to_active_directory=false

This is one example showing how the Template Settings can be configurable. This example was for a typical Users enrollment. In the WEB-INF directory in the package you can look at the MSTemplateToSettings.properties file where there are 5 examples.

In these 5 examples, you will see they all have separate Certificate Profiles and End Entity Profiles. The key usages are configured in EJBCA Certificate Profiles. These values in the Certificate Profile will be used when creating the certificate and are not taken from Microsoft AD.

The typical template currently for Domain Controllers is Kerberos Authentication. In the id3 example in WEB-INF, all the settings you need to match the Microsoft template are pre-selected as true.  All you need to do is to make sure your EJBCA Certificate Profile, KerberosAuthenticationAE in this example, match the key usages and extended key usages as what you'll find in the Microsoft template.

You can create multiple Users-auto enrollment profiles. For example, if you wanted one for Client Authentication and another one for EFS, you could do something like the following (just make sure you set the proper key usages in the certificate profiles):

#User Client Authentication
id1.used=true
id1.oid=1.3.6.1.4.1.311.21.8.8363460.647874.2770861.12891986.167474.23.5536586.16651511
id1.certprofile=UserClientAuth
id1.eeprofile= UserClientAuthEEProfile
id1.subject_name_format=common_name
id1.include_email_in_subjectdn=false
id1.include_email_in_san=false
id1.include_dns_name_in_san=false
id1.include_upn_in_san=true
id1.include_spn_in_san=false
id1.include_netbios_in_san=false
id1.include_domain_in_san=false
id1.include_objectguid_in_san=false
id1.additional_subjectdn_attributes=
id1.publish_to_active_directory=true
#User EFS
id2.used=true
id2.oid=1.3.6.1.4.1.311.21.8.8363460.647874.2770861.12891986.167474.23.180725.6239834
id2.certprofile=UserEFS
id2.eeprofile= UserEFSEEProfile
id2.subject_name_format=common_name
id2.include_email_in_subjectdn=false
id2.include_email_in_san=false
id2.include_dns_name_in_san= false
id2.include_upn_in_san= false
id2.include_spn_in_san=false
id2.include_netbios_in_san=false
id2.include_domain_in_san=false
id2.include_objectguid_in_san=false
id2.additional_subjectdn_attributes=
id2.publish_to_active_directory=false

2.7 Editing the log4j.properties file

  1. Copy the log4j.properties file to /opt/tomcat/lib directory
  2. Edit the log4j.properties file

This file contains settings for the behavior of logging. You may change the logging level (INFO, DEBUG, TRACE, etc.).

log4j.rootLogger = INFO, file
# Define all the appenders
log4j.appender.file = org.apache.log4j.DailyRollingFileAppender
log4j.appender.file.File = ${catalina.base}/logs/msae.log
log4j.appender.file.Append = true
log4j.appender.file.Encoding = UTF-8
# Roll-over the log once per day
log4j.appender.file.DatePattern = '.'yyyy-MM-dd
log4j.appender.file.layout = org.apache.log4j.PatternLayout
log4j.appender.file.layout.ConversionPattern = %d %-5p - %m%n

2.8 Restart Tomcat

  • Restart Tomcat service to reload the configuration.

3. Test Auto Enrollment with EJBCA

  1. For any user who has logged in prior, you may need to delete the cached policy information in the local user account directory.
    1. The location of the cached user policy is: C:\Users\<username>\AppData\Local\Microsoft\Windows\X509Enrollment
    2. The location of the cached machine policy is: C:\ProgramData\Microsoft\Windows\X509Enrollment
  2. To test auto enrollment for users, you simply have to log in to any Windows PC on the domain.
  3. To test auto enrollment for computers, you can reboot the machine on the domain.
  4. Verify the user certificate was generated by opening certmgr.msc (Current User/ Personal/ Certificates).
    1. Ensure the user certificate in the personal store is generated by EJBCA.
  5. Verify the computer certificate was generated by opening mmc.exe and adding the Certificates snap-in. (Local Computer/ Personal/ Certificates - will need Admin privileges to check the Local computer certificate store).
    1. Ensure the computer certificate in the personal store is generated by EJBCA