Part 5a: Configure Microsoft Auto Enrollment Servlet on Windows

The following outlines how to install the PrimeKey Auto Enrollment Servlet on a dedicated Windows host.

It is recommended to install the servlet on the same Microsoft Certificate Services host for a single server installation. This can greatly reduce complexity from a permissions, firewall rule and installation perspective. Using a single service account, on a single Windows host can eliminate many variables in the auto enrollment installation troubleshooting.

Once the solution is in place, a second servlet server can be added for redundancy purposes if desired. If load balancing between two hosts, the Tomcat servers certificate should have the VIP that is being load balanced through in the SAN of the certificate.

The following instructions have been tested on Windows Server 2016 Datacenter 64 bit | Apache Tomcat 8.5 & 9

Configuring the Microsoft Auto Enrollment Servlet on Windows is performed in the following steps:


The examples below use the following denotations:

  • The domain used is yourcompany.com.
  • The domain realm is YOURCOMPANY.COM.
  • The EJBCA server hostname is ejbcaserver.yourcompany.com.
  • The Tomcat server hostname is tomcatserver.yourcompany.com.

Labels indicated in bold should be replaced with names in your environment. The following instructions assume that the path to the Tomcat server is C:\Program Files\Apache Software Foundation\Tomcat 9.0.

Step 1 - Install Apache Tomcat and Auto Enrollment Servlet

To install Apache Tomcat and Autoenrollment Servlet on the Tomcat Server, do the following:

  1. Install Apache Tomcat for Windows

    1. Download and install Java JRE (jdk-8u211-windows-x64).
    2. Download and install 32/64 bit Windows Service Installer (apache-tomcat-9.0.19).

    3. Specify Tomcat credentials for the Admin GUI.
    4. Confirm the Java JRE path (C:\Program Files\Java\jre1.8.0_211).
    5. Start the Tomcat service.
  2. Download the Auto Enrollment Servlet war file v 1_0_1 (autoenroll.war).
  3. Copy the war file (autoenroll.war) to the Tomcat webapps directory (C:\Program Files\Apache Software Foundation\Tomcat 9.0\)

  4. Tomcat will deploy the war file automatically and create an autoenroll folder (alternatively, the war file can be deployed via the Tomcat manager http://localhost:8080/manager/html).
  5. Ensure a new Tomcat webapps directory appears, named autoenroll.

Step 2 - Configure Auto Enrollment Servlet

The Servlet is composed of multiple parts to configure the security, flexibility, and support of enrollment with EJBCA. The following sections cover configuring the Auto Enrollment Servlet on the Tomcat Server.

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.

login.conf

The login.conf file provides authentication technologies to Java applications. The Krb5LoginModule is used to configure Kerberos protocol settings for Tomcat.

Create a file named login.conf in your Tomcat directory (C:\Program Files\Apache Software Foundation\Tomcat 9.0\):

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

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

The Krb5LoginModule configures Kerberos protocol settings for Tomcat.

SettingDescription

storeKey

Specifies if the principal’s key is to be stored in the Subject’s private credentials.

isInitiator

Specifies if to act as acceptor or initiator. If configured to true (initiator) the credentials are acquired via AS exchange, if configured to false (acceptor) the credentials are not acquired via AS exchange.

principal

The name of the principal that should be used. The principal can be a simple username or a service name.

useKeyTab

Specifies if the module gets the principal’s key from the keytab.

keyTab

The location of the keytab file to obtain the principal’s secret key.

For more information about JAAS authentication, refer to the Oracle Documentation.

krb5.conf

The krb5.conf file contains Kerberos configuration information, including defaults for the current realm and Kerberos applications, the location of the KDC, and mappings of hostnames to Kerberos realms.

Create the krb5.conf file according to the following and ensure to update references in the file to your own domain.

  1. Create a file named krb5.conf in your Tomcat directory (C:\Program Files\Apache Software Foundation\Tomcat 9.0\).

    [libdefaults]
      default_realm = YOURCOMPANY.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]
      YOURCOMPANY.COM = {
      kdc = YOURCOMPANY.COM
      default_domain = YOURCOMPANY.COM
    }
    
    [domain_realm]
    .yourcompany.com = YOURCOMPANY.COM

    The following sections and settings are available.

    SettingsDescription
    [libdefaults]Section for settings used by the Kerberos V5 library and the realms section specifies properties for each realm.

    default_realm

    Identities the default Kerberos realm for the client.

    permitted_enctypes

    Specifies the list of encryption types that are permitted for use in session key encryption.
    It is recommended to use aes256-cts as the only option to limit the support of weaker encryption types.
    Visit MIT Kerberos documentation for all supported encryption types

    [realms]

    Section specifying properties for each realm.

    kdc

    Specifies the name or address of a host running a KDC for that realm.

    default_domain

    Specifies the domain used to expand hostnames when translating Kerberos 4 service principals to Kerberos 5 principals.

    [domain_realm]

    Section providing a translation from a domain name or hostname to a Kerberos realm name. The tag name can be a hostname or domain name, where domain names are indicated by a prefix of a period.

server.xml

The server.xml file is responsible for specifying the Tomcat’s configuration on startup such as server, services, connectors, containers, and nested components. A Java Key Store (JKS) and password are necessary to enable HTTPS connections on Tomcat. Java Key Stores contains SSL certificates, however, obtaining the server’s JKS is out of the scope of this document.

Edit the server.xml file according to the following and ensure to update the SSL server certificate and the keystore password with your own in the file:

  1. Copy the tomcat_server.jks and aewsclient.jks keystores that we issued earlier to C:\CertStore\. If the directory doesn't exist, create it.
  2. Edit C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf\server.xml.
  3. Add the following section to enable SSL, (below the already commented out 8443 section) and update the SSL server certificate and the keystore password with your own:

    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" 
     maxThreads="150" scheme="https" secure="true" 
     clientAuth="false" sslProtocol="TLS" 
     keystoreFile="C:\\CertStore\\tomcat_server.jks" 
     keystorePass="PASSWORD" 
     />

    Connectors allow the Tomcat service to accept certificate requests through HTTPS on the port specified using an SSL certificate and the corresponding password.

    SettingDescription

    port

    The TCP port number on which this connector will create a server socket and await incoming connections.

    keystoreFile

    The pathname of the keystore file where the server certificate and private key is to be loaded from.

    keystorePass

    The password used to access the server certificate and private key from the specified keystore file.

    For more information about connectors, refer to the Tomcat documentation.

web.xml

The web.xml file contains servlet deployment configurations that describe settings for the web application such as the servlet name, servlet mappings, and filters.

Edit the web.xml file according to the following:

  • Update the spnego.preauth.username and spnego.preauth.password values with your service account (servlet-service) credentials
  • Update the spnego.krb5.conf path to ${catalina.home}/krb5.conf
  • Update the spnego.login.conf path to ${catalina.home}/login.con

autoenroll_config_directory.properties

The autoenroll_config_directory.properties file configures the servlet to look for the files msaes.properties, MSEnrollmentServlet.properties, and MSTemplateToSettings.properties in the specified directory. These three files are important because they configure settings for the LDAP connection to Active Directory, the connection to EJBCA, and attributes of the certificate request.

If the properties files are contained in a subtree of the servlet home directory, each redeployment of the servlet will overwrite the properties files. This file allows you to move the properties files to a directory outside of the servlet subtree to prevent being overwritten and still being locatable by the servlet code.

Edit the autoenroll_config_directory.properties file according to the following:

  1. Navigate to C:\Program Files\Apache Software Foundation\Tomcat 9.0\webapps\autoenroll\WEB-INF directory:

  2. Update the autoenroll_config_directory.properties file with the path where the configuation files will be stored.

    # Specify the path to config directory
    # e.g. Config_Directory=/path/to/directory
    # You may remark this line if all config files are in WEB-INF/ directory
    Config_Directory=C:\\Program Files\\Apache Software Foundation\\Tomcat 9.0\\webapps\\autoenroll\\WEB-INF\\
  3. Back up web.xml and autoenroll_config_directory.properties in case of overwritten by redeployment:

    copy autoenroll_config_directory.properties autoenroll_config_directory.properties.bak
    copy web.xml web.xml.bak
  • Config_Directory: Full path to the config directory containing msaes.properties, MSEnrollmentServlet.properties, and MSTemplateToSettings.properties.
  • If no directory is specified, the servlet will search for the properties files in the WEB-INF directory in the servlet home directory.

msaes.properties

Certificate requests do not supply subject information during enrollment. In order for the servlet to query for the subject details, an LDAP connection to Active Directory is required. The msaes.properties file configures the LDAP connection details to Active Directory. Note that the Active Directory BIND account must have privileges to read AD objects.

Create and edit the msaes.properties file according to the following:

  1. Navigate to C:\Program Files\Apache Software Foundation\Tomcat 9.0\webapps\autoenroll\WEB-INF.

  2. Create the msaes.properties file, update the login information for the Active Directory Bind account and ensure to update references to your own domain:

    # Set to true if the connection should use SSL.  Ensure the Trusted Root CA certificates for your LDAP servers are in the Java truststore.
    usessl=true
    
    # Provide the port number for the Active Directory connection.
    port=636
    
    # Provide login for a user with access to read objects in Active Directory.  
    logindn=CN=autoenrollmentbind,CN=Users,DC=Company,DC=com
    
    #Provide the password for the logindn user
    loginpassword=<PASSWORD
    


SettingDescription

usessl

Specifies if the connection to Active Directory should be using LDAP over SSL (true) or just LDAP (false).

port

The port number of the connection to Active Directory. Available options: 389 (standard LDAP), 636 (standard LDAPS), or the custom LDAP port to connect to Active Directory.

logindn

The fully distinguished name or the user principal name of the BIND account with read permissions in Active Directory. The BIND account must be in the Cert Publishers group in Active Directory to publish certificates.

loginpassword

The password for the BIND account.

MSEnrollmentServlet.properties

The MSEnrollmentServlet.properties file contains authentication and connection details to the Certificate Authority issuing certificates for enrollment requests.

Edit the MSEnrollmentServlet.properties file according to the following:

  • 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=C:\\CertStore\\aewsclient.jks
    EJBCA_KeyStore=C:\\CertStore\\aewsclient.jks
    EJBCA_TrustedKeyStorePassword=<PASSWORD>
    EJBCA_WebServiceUrl=https://ejbcaserver.yourcompany.com:8443/ejbca/ejbcaws/ejbcaws?wsdl
    EJBCA_CAName=Issuing CA

    The following settings specify the keystore containing the EJBCA Web Service API client certificate, the truststore containing the EJBCA certificate chain, the EJBCA Web Services API URL, and the certificate authority that will be signing the certificate requests.

    SettingDescription

    EJBCA_TrustedKeyStore

    EJBCA_TrustedKeyStorePassword

    The path and password to the EJBCA server’s keystore.

    EJBCA_KeyStore and EJBCA_KeyStorePassword

    The path and password to the Web Services client’s keystore.

    EJBCA_WebServiceUrl

    The API endpoint for the servlet to send SOAP requests.

    EJBCA_CAName

    The certificate authority issuing out the certificates.


MSTemplateToSettings.properties

After the servlet queries Active Directory for the requester’s object, the servlet must know which attributes should be included in the certificate request. The MSTemplateToSettings.properties file configures 5 core functionalities for each certificate template enrollment.

1) The first functionality enables an entry and maps the certificate template object identifier (OID) to it. An OID is a unique string of numbers that is created for each certificate template.

SettingDescription

used

Enables the entry to be used. “X” is a number of increasing sequential order identifying the entry.

oid

The certificate template OID that maps the following settings to the certificate template.

2) The second functionality specifies the certificate profile and the end entity profile from EJBCA to use. The certificate profile and end entity profile must be enabled to use the certificate authority configured in MSEnrollmentServlet.properties.

SettingDescription

certprofile

The certificate profile the enrollment will use.

eeprofile

The end entity profile the enrollment will use.

3) The third functionality constructs the Subject of the certificate request. The administrator can specify which attributes of the requester’s object from Active Directory should be placed in the Subject Distinguished Name (Subject DN). Options include the requester’s common name, distinguished name, DNS name, principal name, and email. Also, the administrator can specify additional Subject DN attributes for all certificate requests using that template.oid.

SettingDescription

subject_name_format

Specifies the values to take from the requester’s Active Directory object for the Subject DN.
Available options are common_name, fully_distinguished_name, dnsName, and userPrincipalName.

include_email_in_subjectdn

Specifies if the email of the requester should be included in the Subject DN.

additional_subjectdn_attributes

Specifies any other attributes that is to be included in the Subject DN.

4) The fourth functionality constructs the Subject Alternative Name (SAN) of the certificate request. The administrator can specify which attributes of the requester’s object from Active Directory should be placed in the SAN. Options include the requester’s DNS name, principal name, service principal name, NetBIOS name, domain name, and object GUID.

SettingDescription

include_dns_name_in_san

Specifies if the DNS Name of the requester should be included in the Subject Alternative Name.

include_upn_in_san

Specifies if the User Principal Name of the requester should be included in the Subject Alternative Name.

include_spn_in_san

Specifies if the Service Principal Name of the requester should be included in the Subject Alternative Name.

include_netbios_in_san

Specifies if the NetBIOS name of the requester should be included in the Subject Alternative Name.

include_domain_in_san

Specifies if the Domain name of the requester should be included in the Subject Alternative Name.

include_objectguid_in_san

Specifies if the object GUID of the requester should be included in the Subject Alternative Name.

5) The fifth functionality toggles if the certificate is to be published to the requester’s object in Active Directory. The servlet uses the BIND account configured in msaes.properties to publish the certificate.

SettingDescription

publish_to_active_directory

Specifies if the certificate received from EJBCA should also be published to the requester’s Active Directory object.

There is a maximum of 100 entries that can be configured in this file. The end entity profiles must accommodate for the Subject DN and SAN attributes.

Edit the MSTemplateToSettings.properties file according to the following:

  1. Update/add your User_Auto_Enrollment template OID and set the EJBCA Certificate Profile and End Entity Profile that should map to the OID. 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.additional_subjectdn_attributes=O=Company, OU=IT Department
    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.publish_to_active_directory=true

    (warning) Note that the following is required if the requirement is to publish the User certificates in Active Directory and Credential Roaming is enabled in the Auto-Enroll Group Policy Object (GPO):

    • Set publish_to_active_directory to true.
    • The Active Directory account autoenrollmentbind must be made a member of the  Cert Publishers security group in the domain.

  2. Update/add your Computer_Auto_Enrollment template OID and set the EJBCA Certificate Profile and End Entity Profile that should map to the OID. Update other attributes as desired.

    #Computer
    id2.used=true
    id2.oid=1.3.6.1.4.1.311.21.8.10623644.2526593.8537745.534905.15291053.121.4337766.12547917
    id2.certprofile=Computer_Certificate_Profile
    id2.eeprofile=Computer_End_Entity_Profile
    id2.subject_name_format=dns_name
    id2.include_email_in_subjectdn=false
    id2.include_email_in_san=false
    id2.include_dns_name_in_san=true
    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

log4j.properties

The log4j.properties file contains settings for the Tomcat log file that is created by the servlet using Apache’s log4j libraries.

Edit the logging file log4j.properties according to the following example.

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

The rootLogger setting specifies the level and appender name for the root Logger. Available options for log level: TRACE, DEBUG, INFO, WARN, ERROR, and FATAL.

Restart Tomcat

Finally, restart the Tomcat service to reload the configurations.

Step 3 - Test Auto Enrollment with EJBCA

The following describes testing the auto enrollment set up.

Delete Cashed Policy Information

For any user logged in previously, you may need to delete the cached policy information in the local user account directory.

Locations of cashed policies:

  • The location of the cached user policy is C:\Users\<username>\AppData\Local\Microsoft\Windows\X509Enrollment.
  • The location of the cached machine policy is C:\ProgramData\Microsoft\Windows\X509Enrollment.

Test Auto Enrollment

To test auto enrollment for users and/or computers, do the following:

  • To test auto enrollment for users, log in to any Windows PC on the domain.
  • To test auto enrollment for computers, reboot the machine on the domain.

Confirm Certificate Generation

To confirm that the user and computer certificate were generated, do the following:

  • Verify that the user certificate was generated by opening the Certificate Manager certmgr.msc (select Current User > Personal > Certificates).
    • Ensure the user certificate in the personal store is generated by EJBCA.
  • Verify that the computer certificate was generated by opening the Microsoft Management Console mmc.exe as Administrator (enter an account that belongs to the Domain/Enterprise Admin group), and add the Certificates snap-in (select Local Computer > Personal > Certificates).
    • Ensure that the computer certificate in the personal store is generated by EJBCA.