Part 5b: Configure Microsoft Auto Enrollment Servlet on Linux

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

Note that it is recommended to install the servlet on the same host running the Microsoft Certificate Services, following the instructions in Configure Microsoft Auto Enrollment Servlet on Windows.

Configuring the Microsoft Auto Enrollment Servlet on Linux 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 and in the examples below, the the text enclosed in angle brackets should be replaced with names in your environment. Note the following instructions assumes that the path to the Tomcat server is /opt/tomcat.

Step 1 - Install Apache Tomcat and Autoenrollment Servlet

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

  1. Unpack Apache Tomcat:

    sudo tar -xvzf ~/apache-tomcat-*.tar.gz -C /opt
  2. Set symbolic link:

    sudo ln -s /opt/apache-tomcat-* /opt/tomcat
  3. Download the Auto Enrollment Servlet war file (autoenroll.war):
  4. Copy the war file (autoenroll.war) to the Tomcat webapps directory (/opt/tomcat/webapps):

    sudo cp ~/autoenroll.war /opt/tomcat/webapps
  5. Start Tomcat:

    /opt/tomcat/bin/catalina.sh start
  6. A new directory will appear in the Tomcat webapps directory 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.

To create the login.conf file, do the following:

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

    vi /opt/tomcat/login.conf
    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 (/opt/tomcat):

    vi /opt/tomcat/krb5.conf
    [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 issued earlier to /opt/tomcat:
  2. To edit the server.xml:

    vi /opt/tomcat/conf/server.xml
  3. Add the following section to enable SSL, below the already commented 8443 section:

    <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" 
     />

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:

vi web.xml
  • 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.conf

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 the WEB-INF directory:

    cd /opt/tomcat/webapps/autoenroll/WEB-INF/
  2. Update the autoenroll_config_directory.properties file with the path where the configuration files will be stored.
  3. Create the Auto Enroll configuration directory (for example, /opt/tomcat/autoenroll_conf):

    mkdir /opt/tomcat/autoenroll_conf
  4. Move msaes.properties, MSEnrollmentServlet.properties, and MSTemplateToSettings.properties to /opt/tomcat/autoenroll_conf:

    mv msaes.properties /opt/tomcat/autoenroll_conf
    mv MSEnrollmentServlet.properties /opt/tomcat/autoenroll_conf
    mv MSTemplateToSettings.properties /opt/tomcat/autoenroll_conf
  5. Back up the web.xml and autoenroll_config_directory.properties files in case of the files being overwritten by redeployment:

    cp autoenroll_config_directory.properties autoenroll_config_directory.properties.bak
    cp 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.

Edit the msaes.properties file according to the following:

  1. Navigate to /opt/tomcat/autoenroll_conf:

    cd /opt/tomcat/autoenroll_conf
  2. Edit the msaes.properties file, update the login information for the Active Directory Bind account and ensure to update references to your own domain:

    vi msaes.properties
    # 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=yourcompany,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:

  1. To edit the MSEnrollmentServlet.properties file:

    vi MSEnrollmentServlet.properties
  2. 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.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. To edit MSTemplateToSettings.properties:

    vi MSTemplateToSettings.properties
  2. 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.10623644.2526593.8537745.534905.15291053.121.10044518.13424184
    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

    (warning) If the requirement is to publish the User certificates in Active Directory, and if Credential Roaming is enabled in the Auto-Enroll GPO, do the following:

    • Set publish_to_active_directory to true (publish_to_active_directory=true)
    • Ensure that the autoenrollmentbind Active Directory account is made a member of the Cert Publishers security group in the domain.


  3. 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.

The file must be in the classpath of Java and can be placed in the lib directory of Tomcat or the servlet (/opt/tomcat/lib or /<SERVLETHOME>/WEB-INF/lib).

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

Create the logging file log4j.properties according to the following example:

vi /opt/tomcat/lib/log4j.properties
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

To restart the Tomcat service to reload the configurations, run the following:

/opt/tomcat/bin/catalina.sh stop
/opt/tomcat/bin/catalina.sh start

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 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.