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.

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.

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

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.

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.

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.

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.

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.

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.

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

   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:

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:

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.