DirX Identity Web Center - Kerberos Authentication

This document describes how to set up Kerberos authentication for Web Center via the SPNEGO mechanism.

Introduction

Some terms used in this document:

Host - The simple name of the host with the Tomcat server Web Center is deployed into.For example, “alpha“.
Domain - The fully qualified domain name of the host; for example, “beta.com“.
Service Principal Name - The service principal name is http/host.domain@DOMAIN, for example “http/alpha.beta.com@BETA.COM“.
tomcat_install_path - The installation folder of the Tomcat server, for example “C:/Program Files/Apache/Tomcat 9016”.Note that “tomcat_install_path“ is just a notation used in this document.Always replace it with the real path name of the Tomcat installation folder.

Restrictions:

Kerberos authentication does not work if browser and Tomcat run on the same machine.

Windows Prerequisites

For Kerberos on Windows, you must create a Windows user account, register the service principal name for that account, and create a keytab for the service principal name.This section describes how to perform these steps on a Windows Server 2012 R2. The details might be different on other server versions like Windows Server 2016 and 2019.

Creating an Active Directory User Account

Create a user account for Kerberos in Active Directory via program “Active Directory Users and Computers”.Assign a “User logon name” and a password.Check the flag “Password never expires”.

Kerberos on Windows works with one of three different encryption modes:

RC4-HMAC-NT – The default 128-bit encryption.
AES256-SHA1 – AES256-CTS-HMAC-SHA1-96 encryption. This is the recommended encryption mode.
AES128-SHA1 – AES128-CTS-HMAC-SHA1-96 encryption.

When using AES encryption for Kerberos (as recommended), open the created user account and select tab “Account”. In the options list, check the flag “This account supports Kerberos AES 128-bit encryption” or “This account supports Kerberos AES 256-bit encryption” as appropriate.

In the following examples, we assume the logon name is “beta\kerberosUser”.

Registering the Service Principal Name

Use the windows tool setspn to register the service principal name for the created Kerberos account:

setspn -u -s <servicePrincipalName> <accountName>

For example

setspn -u -s http/alpha.beta.com@BETA.COM beta\kerberosUser

Note that the service principal name must not be registered for more than one account. You can check this with

setspn -q <servicePrincipalName>

For example

setspn -q http/alpha.beta.com@BETA.COM

You can unregister a service principal name with

setspn -d <servicePrincipalName> <accountName>

After having registered the service principal name, open the Kerberos user account again and select the new tab “Delegation”. Select the option “Trust this user for delegation to any service (Kerberos only)”.

Creating the Keytab File

Use the Windows utility ktpass to create a keytab for the service principal name. The keytab is used on the Tomcat server to perform Kerberos authentications.

ktpass /princ <servicePrincipalName>
       /ptype KRB5_NT_PRINCIPAL
       /mapuser <accountName>
       /out <keytabFileName>
       /crypto <AES256-SHA1 or AES128-SHA1 or RC4-HMAC-NT>
       /pass *
       /kvno 0

For example:

ktpass /princ http/alpha.beta.com@BETA.COM
       /ptype KRB5_NT_PRINCIPAL
       /mapuser beta\kerberosUser
       /out alpha.keytab
       /crypto AES256-SHA1
       /pass *
       /kvno 0

You are prompted for the password of the Kerberos user twice.

Note that you must create a new keytab file each time you change the Kerberos account in Active Directory.

Now open the Kerberos user account again and select tab “Account”.The “User logon name” should have changed to the service principal name.

Tomcat Configuration

In this section, we create some configuration files on the Tomcat server.We suggest putting the files into the folder tomcat_install_path/conf but you can choose any other folder as well.Make sure that all the created files are readable by the Tomcat service.

Keytab

Copy the keytab file to tomcat_install_path/conf.In the subsequent examples, we assume the keytab file is copied to tomcat_install_path/conf/alpha.keytab.

File krb5.conf

Create file tomcat_install_path*/conf/krb5.conf* with the following content:

#
# Kerberos configuration file for running JGSS applications.
# Adapt the entries to your environment.
#

[libdefaults]
    default_realm = <DOMAIN>
    permitted_enctypes = aes256-cts aes128-cts
    allow_weak_crypto = false
    kdc_timesync = 0
    kdc_default_options = 0x40000010
    clockskew = 300
    check_delegate = 0
    ccache_type = 3
    kdc_timeout = 60000

[realms]
    <DOMAIN> = {
        kdc = <keyDistributionCenter>:<keyDistributionCenterPort>
    }

[domain_realm]
    .<domain> = <DOMAIN>

Note that some lines have been splitted for better readability.

Replace each occurrence of

<DOMAIN> with the fully qualified domain name in uppercase letters.
<domain> with the fully qualified domain name in lowercase letters.
<keyDistributionCenter> with the IP address or fully qualified host name of the Kerberos key distribution center, which is part of the Windows domain controller.
<keyDistributionCenterPort> with the port number of the Kerberos key distribution center, which is usually 88.

Adjust the encryption types if necessary. They must include the encryption type of the created Windows user account. For example, add “rc4-hmac” if necessary.

The krb5.conf file for our sample data is:

#
# Kerberos configuration file for running JGSS applications.
# Adapt the entries to your environment.
#

[libdefaults]
    default_realm = BETA.COM
    permitted_enctypes = aes256-cts aes128-cts
    allow_weak_crypto = false
    kdc_timesync = 0
    kdc_default_options = 0x40000010
    clockskew = 300
    check_delegate = 0
    ccache_type = 3
    kdc_timeout = 60000

[realms]
    BETA.COM = {
        kdc = dc.beta.com:88
    }

[domain_realm]
    .beta.com = BETA.COM

File krb5-jaas.conf

Create file tomcat_install_path/conf/krb5-jaas.conf with the following content:

/**
 * JAAS configuration file for JGSS.
 * Modify the entries to suit your environment.
 */

/* Needed for SPNEGO/Kerberos */
com.sun.security.jgss.krb5.accept {
    com.sun.security.auth.module.Krb5LoginModule required
        debug=true
        doNotPrompt=true
        useKeyTab=true
        keyTab="<keytabPathName>"
        storeKey=true
        principal="<servicePrincipalName>"
    ;
};

Replace

<servicePrincipalName> with the service principal name.
<keytabPathName> with the full path name of the keytab file.

The krb5-jaas.conf file for our sample data is:

/**
 * JAAS configuration file for JGSS.
 * Modify the entries to suit your environment.
 */

/* Needed for SPNEGO/Kerberos */
com.sun.security.jgss.krb5.accept {
    com.sun.security.auth.module.Krb5LoginModule required
        debug=true
        doNotPrompt=true
        useKeyTab=true
        keyTab="tomcat_install_path/conf/alpha.keytab"
        storeKey=true
        principal="http/alpha.beta.com@BETA.COM"
    ;
};

Java System Properties

Assign the path names of the Kerberos configuration files to Java system properties of the Tomcat service:

-Djava.security.krb5.conf=<krb5PathName>
-Djava.security.auth.login.config=<krb5jaasPathName>

Replace

<krb5PathName> with the full path name of file krb5.conf.
<krb5jaasPathName> with the full path name of file krb5-jaas.conf.

The values for our sample data are

-Djava.security.krb5.conf=tomcat_install_path/conf/krb5.conf
-Djava.security.auth.login.config
                         =tomcat_install_path/conf/krb5-jaas.conf

You can also enable some output for debugging purposes which will be written to some Tomcat log files:

-Dsun.security.krb5.debug=true
-Dsun.security.jgss.debug=true

To set the Java system properties for a Tomcat running as a Windows service, open the service’s “Configure Tomcat” item in the Windows start menu; another way to start the configurator is to run the program tomcat9w.exe in Tomcat’s bin folder manually. In the configurator, select the Java tab and then add the properties to the list of Java Options.

If running Tomcat from a batch script, assign the system properties to the environment variable “CATALINA_OPTS” before starting Tomcat, for example:

set KRB5_FILE=-Djava.security.krb5.conf=
               tomcat_install_path/conf/krb5.conf
set KRB5_JAAS_FILE=-Djava.security.auth.login.config =
               tomcat_install_path/conf/krb5-jaas.conf
SET KRB5_DEBUG=-Dsun.security.krb5.debug=true
SET JGSS_DEBUG=-Dsun.security.jgss.debug=true
SET CATALINA_OPTS=%KRB5_FILE% %KRB5_JAAS_FILE% %KRB5_DEBUG% %JGSS_DEBUG%

Note that some lines have been splitted for better readability.

Copying the SPNEGO Jar File

Copy the SPNEGO jar file spnego-tomcat9.jar delivered with DirX Identity to Tomcat’s lib folder tomcat_install_path/lib.

Increasing the Maximum HTTP Header Size

Tomcat limits the maximum size of HTTP headers by default to 4kb and discards any request with larger headers. Kerberos tickets are transferred from the browser to the server in an HTTP header. For Windows users with many groups the Kerberos ticket may become quite large so that the header size easily exceeds the default maximum size.

Therefore, you should increase the maximum HTTP header size permitted by Tomcat to 32kb or 64kb by adding the property maxHttpHeaderSize to your HTTP and/or HTTPS connector configuration in the file tomcat_install_path/conf/server.xml.

<Connector port="8080" ...
    maxHttpHeaderSize="65536" .../>
<Connector port="8443" ...
    maxHttpHeaderSize="65536" .../>

Web Center Configuration

Activating SPNEGO Authentication

File web.xml

Uncomment the security settings in the deployment descriptor WEB-INF/web.xml:

<!-- SPNEGO Windows single sign-on security settings -->
<security-constraint>
    <web-resource-collection>
        <web-resource-name>Restricted Area</web-resource-name>
        <url-pattern>*.do</url-pattern>
        <url-pattern>*.jsp</url-pattern>
        <url-pattern>/saveFile</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>SpnegoAuthenticatedUser</role-name>
    </auth-constraint>
</security-constraint>

<security-role>
    <description>SPNEGO authenticated users</description>
    <role-name>SpnegoAuthenticatedUser</role-name>
</security-role>

File webCenter-dxiDomain.xml

Add the Kerberos authentication elements “Realm” and “Valve” to Web Center’s context descriptor file webCenter-dxiDomain.xml.

The file is located in the folder tomcat_install_path*/conf/engineName/hostName, where engineName and hostName depend on your Tomcat installation. In most cases, the location is tomcat_install_path/conf/Catalina/localhost*.

<Context ...>
  ...
  <!-- Kerberos authentications -->
  <Realm
      className="com.siemens.symphonia.spnego.SPNEGOVoidRealm"/>

  <Valve
     className="com.siemens.symphonia.spnego.SPNEGOAuthenticator"
     servicePrincipalName="<servicePrincipalName>"
     changeSessionIdOnAuthentication="false"/>
</Context>

Replace

<servicePrincipalName> with the service principal name.

The context descriptor file for our sample data is:

<Context ...>
  ...
  <!-- Kerberos authentications -->
  <Realm
      className="com.siemens.symphonia.spnego.SPNEGOVoidRealm"/>

  <Valve
     className="com.siemens.symphonia.spnego.SPNEGOAuthenticator"
     servicePrincipalName="http/alpha.beta.com@BETA.COM"
     changeSessionIdOnAuthentication="false"/>
</Context>

Configuring User Mapping

A Kerberos authentication provides the authenticated user’s Windows account name and the fully qualified Windows domain name. The task is to map these data to a user in the DirX Identity database. Usually this is done by searching for a target system matching the domain name, and then by looking for an account matching the Windows account name in that target system. If the Windows credentials are stored in a user attribute, an alternative way is to search the user directly in the user tree.

The user mapping configuration is done in the deployment descriptor WEB-INF/web.xml.

Note that since web.xml is an XML file, ampersands in configuration values must be replaced with the corresponding XML character entity reference “&”.

Some configuration parameters accept a regular expression as value. The syntax for regular expressions is described in the Java API documentation of Java class “java.util.regex.Pattern”. The part of a pattern marked in bold letters shows the captured substring.

Activating the SSO Header Filter

Enable the filter by uncommenting it:

<!-- SSO header filter definition -->
<filter>
  <filter-name>SSOHeaderFilter</filter-name>
  <display-name>SSO Header Filter</display-name>
  <description>
    Evaluates single sign-on information passed in HTTP headers
  </description>
  <filter-class>
	com.siemens.webMgr.filter.SSOHeaderFilter
  </filter-class>
  ...
</filter>

Set the filter’s authentication type to “SPNEGO/Kerberos”:

<init-param>
	<param-name>authType</param-name>
	<param-value>SPNEGO/Kerberos</param-value>
</init-param>

Set the filter’s header name to “RemoteUser”:

<init-param>
	<param-name>headerName</param-name>
	<param-value>RemoteUser</param-value>
</init-param>

Once you have Kerberos authentication with Web Center running, you can switch the log level back to “error”.

Other initialization parameters are described in the following sections.

Activate the mappings for the SSO header filter by uncommenting them:

<!-- SSOHeaderFilter mappings -->
<filter-mapping>
	<filter-name>SSOHeaderFilter</filter-name>
	<url-pattern>*.do</url-pattern>
</filter-mapping>

<filter-mapping>
	<filter-name>SSOHeaderFilter</filter-name>
	<url-pattern>*.jsp</url-pattern>
</filter-mapping>

<filter-mapping>
	<filter-name>SSOHeaderFilter</filter-name>
	<url-pattern>/saveFile</url-pattern>
</filter-mapping>

While the filter definition sequence is arbitrary, the filter mapping sequence is not. Insert the mappings of the SSO header filter directly before the mappings of the Session filter.

User Mapping via Target System and Account

Extracting Account and Domain Name

The Windows credentials are passed in the format accountName*@*fullDomainName. The first task is to extract the Windows account name and domain name from the credentials string.

Set the type of the SSO header filter to “account”:

<init-param>
	<param-name>type</param-name>
	<param-value>account</param-value>
</init-param>

By default, the extracted account name is the substring of the Windows credentials preceding the first @ character

<init-param>
	<param-name>accountRegExpr</param-name>
	<param-value>([^@]*)@.*</param-value>
</init-param>

By default, the extracted domain name is the substring between the first @ character and the next dot, which gives the simple domain name:

<init-param>
	<param-name>domainRegExpr</param-name>
	<param-value>[^@]+@([^.]+)(?:[.].*)?</param-value>
</init-param>

To extract the fully qualified domain name, use

<init-param>
	<param-name>domainRegExpr</param-name>
	<param-value>[^@]+@(.*)</param-value>
</init-param>

For example, if the provided Windows credentials are “smith@beta.com”, the extracted account name is “smith”, while the domain name is “beta” for the first domain pattern, and “beta.com” for the second domain pattern.

Finding the DirX Identity Target System

The target system is by default the one whose attribute “dxrTSDomainName” matches the domain name extracted in the previous step.

You can configure base and filter for the search operation via context parameters:

<context-param>
  <param-name>
      com.siemens.webMgr.auth.targetSystemBase
  </param-name>
  <param-value>cn=TargetSystems,cn=<dxiDomain></param-value>
</context-param>

<context-param>
  <param-name>
    com.siemens.webMgr.auth.targetSystemFilter
  </param-name>
  <param-value>
    (&amp;(objectclass=dxrTargetSystem)(dxrTSDomainName=%DOMAIN))
  </param-value>
</context-param>

Replace

<dxiDomain> with your DirX Identity domain.

The placeholder “%DOMAIN” is replaced at runtime with the extracted Windows domain.

The search filter for the the Windows credentials “smith@beta.com” is

(&(objectClass=dxrTargetSystem)(dxrTSDomainName=beta.com))

when using the first of the above domain patterns, and

(&(objectClass=dxrTargetSystem)(dxrTSDomainName=beta))

when using the second pattern.

Finding the DirX Identity Account

The account is by default the one whose attribute dxmADsSamAccountName matches the extracted account name. The search base is the target system found in the previous step. If no target system was found, the search extends over all target systems.

You can configure the filter for the search operation via a context parameter:

<context-param>
  <param-name>
      com.siemens.webMgr.auth.accountFilter
  </param-name>
  <param-value>
      (&amp;(objectclass=dxrTargetSystemAccount)
          (dxmADsSamAccountName=%ACCOUNT))
  </param-value>
</context-param>

The placeholder “%ACCOUNT” is replaced at runtime with the Windows account extracted from the provided Windows credentials, the placeholder “%DOMAIN” (which is not used by default) with the extracted Windows domain.

The search filter for our sample Windows credentials “smith@beta.com” is

(&(objectClass=dxrTargetSystemAccount)
  (dxmADsSamAccountName=smith))

Finding the DirX Identity User

The user is the one referenced by attribute “dxrUserLink” of the DirX Identity account found in the previous step.

You can configure a different attribute via a context parameter:

<context-param>
  <param-name>
      com.siemens.webMgr.auth.accountUserLink
  </param-name>
  <param-value>
      dxrUserLink
  </param-value>
</context-param>

User Mapping via User Attribute

Extracting the Windows Credentials

The Windows credentials are passed in the format accountName*@*fullDomainName. The first task is to extract the part of the credentials that is needed to find the corresponding DirX Identity user.

Set the type of the SSO header filter to “user”:

<init-param>
	<param-name>type</param-name>
	<param-value>user</param-value>
</init-param>

The value to be extracted for the user filter is either the complete Windows credentials with account and fully qualified domain name, or a substring thereof.

The first example extracts the complete credentials with account and fully qualified domain name:

<init-param>
	<param-name>userRegExpr</param-name>
	<param-value>(.*)</param-value>
</init-param>

To extract the credentials with simple domain name, use:

<init-param>
	<param-name>userRegExpr</param-name>
	<param-value>([^@]+@[^.]+)(?:[.].*)?</param-value>
</init-param>

To extract the Windows account only, use:

<init-param>
	<param-name>userRegExpr</param-name>
	<param-value>([^@]*)@.*</param-value>
</init-param>

For example, if the provided Windows credentials are “smith@beta.com”, the extracted substring is “smith@beta.com” for the first pattern, “smith@beta” for the second pattern, and just “smith” for the third one.

Finding the DirX Identity User

You can configure base and filter for the search operation via context parameters:

<context-param>
  <param-name>
      com.siemens.webMgr.auth.userBase
  </param-name>
  <param-value>cn=Users,cn=<dxiDomain></param-value>
</context-param>

<context-param>
  <param-name>
    com.siemens.webMgr.auth.userFilter
  </param-name>
  <param-value>
    (&amp;(objectclass=dxrUser)(<attrName>=%USER_ID))
  </param-value>
</context-param>

Replace

<dxiDomain> with your DirX Identity domain.
<attrName> with the name of the user attribute holding the Windows credentials.

The placeholder “%USER_ID” is replaced at runtime with the Windows credentials extracted in the previous step.

The search filter with attribute name “description” for the Windows credentials “smith@beta.com” is

(&(objectClass=dxrUser)(description=smith@beta.com))

when using the first of the above user patterns,

(&(objectClass=dxrUser)(description=smith@beta))

when using the second pattern, and

(&(objectClass=dxrUser)(description=smith))

when using the third pattern.

Browser Settings

Internet Explorer

This section describes how to configure an Internet Explorer for Windows domain authentication based on Kerberos.This configuration requires Internet Explorer 11.

Configuring Local Intranet Sites

Internet Explorer requires servers to be configured in the category “Local intranet” to run Windows domain authentication based on Kerberos.

Check if the Tomcat server belongs to the browser category “Local intranet” when accessing it.Go to the home page of your Tomcat, select item Properties from the Page menu, and check property Zone.

If “Local intranet” is shown when accessing Tomcat, you can skip the configuration steps for local intranet sites.
Configure local intranet sites:
- In Internet Explorer, click Tools, and then click Internet Options.
- Click the Security tab.
- Click Local intranet.
- Click Sites.
Ensure that Include all sites that bypass the proxy server is checked, then click Advanced.
In the Local intranet (Advanced) dialog box, enter all relative domain names that will be used for Tomcat servers with enabled Windows domain authentication (for example, *.beta.com).
Click Close to close the dialog boxes.

Configuring Intranet Authentication

Next, click the Security tab, click Local intranet, and then Click Custom Level.
In the Security Settings dialog box, scroll down to the User Authentication section of the list.
Select Automatic logon only in Intranet zone. This setting enables integrated Windows domain authentication in the Internet Explorer.
Click OK to close the Security Settings dialog box.

Firefox

This section describes how to configure Firefox for Windows domain authentication based on Kerberos.

Open Firefox and enter “about:config” in the browser’s address bar.
Enter “network.negotiate” in the search bar.search bar.
- Add the fully qualified domain name to parameter “network.negotiate-auth.trusted-uris”.
- Add the fully qualified domain name to parameter “network.negotiate-auth.delegation-uris”.
- Set “network.negotiate-auth.allow-non-fqdn” to “true”.

Chrome

Kerberos authentication in Google Chrome should work out-of-the-box if you have configured it for Internet Explorer.

Testing

Restart Tomcat for the configuration changes to become effective.

Open a browser and enter the URL

http://<tomcatHost>:<tomcatPort>/webCenter-<dxiDomain>

Replace

<tomcatHost> with the fully qualified host name of Tomcat.
<tomcatPort> with the HTTP port of Tomcat.
<dxiDomain> with your DirX Identity domain.

For example:

http://alpha.beta.com:8080/webCenter-My-Company

If everything works fine, you will be authenticated to Web Center and see Web Center’s home page.

If it works, test again using the simple host name:

http://alpha:8080/webCenter-My-Company

Note that Kerberos usually doesn’t work if browser and Tomcat run on the same machine.

Logging and Debugging

Kerberos Ticket Evaluation

Logging for the standard Java classes evaluating and verifying Kerberos tickets and the keytab file is activated via

Two Java system properties of the Tomcat service:

-Dsun.security.krb5.debug=true
-Dsun.security.jgss.debug=true

A debug parameter in file krb5-jaas.conf:

com.sun.security.jgss.krb5.accept {
    com.sun.security.auth.module.Krb5LoginModule required
        debug=true
        ...

For details see section “Tomcat Configuration”.

The logs are written to Tomcat’s standard output, which is usually redirected to a Tomcat log file (like tomcat_install_path/logs/tomcat9-stdout.date.log) or the Tomcat console window.

Logging for the ticket evaluation classes in jar file spnego-tomcat9.jar is activated by setting the general log level in file WEB-INF/web.xml:

<context-param>
    <param-name>com.siemens.webMgr.log.level</param-name>
    <param-value>2</param-value>
</context-param>

The logs are also written to Tomcat’s standard output.

User Mapping

Logging for the components involved in mapping the Windows credentials to a DirX Identity user is activated via the general log level in file WEB-INF/web.xml:

<context-param>
    <param-name>com.siemens.webMgr.log.level</param-name>
    <param-value>2</param-value>
</context-param>

The logs are written to Tomcat’s standard output.

Viewing Tickets

Use the Windows command “klist” to display the list of currently cached Kerberos tickets.

Listing the currently cached tickets:

klist

Deleting the tickets:

klist purge

DirX Identity Web Center - Kerberos Authentication

Introduction

Windows Prerequisites

Creating an Active Directory User Account

Registering the Service Principal Name

Creating the Keytab File

Tomcat Configuration

Keytab

File krb5.conf

File krb5-jaas.conf

Java System Properties

Copying the SPNEGO Jar File

Increasing the Maximum HTTP Header Size

Web Center Configuration

Activating SPNEGO Authentication

File web.xml

File webCenter-dxiDomain.xml

Configuring User Mapping

Activating the SSO Header Filter

User Mapping via Target System and Account

Extracting Account and Domain Name

Finding the DirX Identity Target System

Finding the DirX Identity Account

Finding the DirX Identity User

User Mapping via User Attribute

Extracting the Windows Credentials

Browser Settings

Internet Explorer

Configuring Local Intranet Sites

Configuring Intranet Authentication

Firefox

Chrome

Testing

Logging and Debugging

Kerberos Ticket Evaluation

User Mapping

Viewing Tickets

Links