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

   Setting	Description
   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 i n 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

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.

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

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

   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.

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.

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.