Advanced Techniques - Kerberos on Intrexx 8

For the sake of simplicity, the following acronyms will be used in this Advanced Techniques workshop: The following example will be used for the configuration:

KDC is available at: kdc.example.org
FQHN of the Tomcat server is: tomcat.example.org
Domain is called: EXAMPLE / EXAMPLE.ORG
Tomcat AD user login: tomcat_user
Tomcat AD user password: SECRET_PASSWORD

1. Preparations on the domain controller

An AD user account for the Tomcat service needs to be created with the following activated options: (The password is SECRET_PASSWORD in our example)

An SPN (Service Principal Name) needs to be created and assigned to the Tomcat user account. This is case-sensitive. Make sure that an SPN isn't already registered for the Tomcat user. The SPN is assigned to the Tomcat user with the following commands: 
setspn -A HTTP/tomcat.example.org tomcat_user
setspn -A HTTP/tomcat tomcat_user
Using the command setspn -L tomcat_user you can check whether an SPN has already been registered for the user.

If an SPN is already registered for the user, you can use the following command to remove the entries: 
setspn -D HTTP/tomcat.example.org tomcat_user
setspn -D HTTP/tomcat tomcat_user

2. Generate a keytab (on the Tomcat server)

The Tomcat service must register with the KDC (Active Directory Server) when it starts. That's why a user with the corresponding password was created on the AD. So that this information is available to the Tomcat service on startup, a keytab file with the required login data needs to be generated. We recommend using the Java Tool ktab.exe to generate this. This is included in the Windows JRE and therefore already installed on a client with a Portal Manager installation, for example. The ktab.exe must then be executed on the computer of the domain because information is retrieved from the KDC during the execution. The generated file will be copied to the Tomcat server later. Carry out the following steps to generate the file: Here is a short explanation of each of the options:

-a adds SPN and password
-k states the keytab file to be written to
-n0 is required to set the keytab counter (KVNO) to 0


Ktpass.exe, which is already installed on AD servers, should not be used for generating the keytab.

3. Installation on the Intrexx-side

3.1 Integrate Spnego library in Tomcat

The library is integrated automatically during a new installation of Intrexx 8; this point can be skipped in that case. If you have switched from an older version to Intrexx 8 by installing to the existing directory, the corresponding module must potentially be integrated manually. The corresponding library can be found in installation directory /lib and is called spnego-r7.jar. So that Tomcat uses this as well, an entry needs to be added to tomcat.wcf im installation directory /cfg 
wrapper.java.classpath.XX=lib/spnego-r7.jar
The numbering XX must be unique in accordance with the existing classpath entries.

3.2. Adjust spnego.login.conf and spnego.krb5.conf

The keytab was created and copied to the Intrexx server. It will now be integrated in the spnego.login which will then in turn be integrated in the web.xml. For the sake of simplicity, we will store all of the files used by Tomcat in the example path C:/PATH/TO/KEYTAB.FILE/ in the following. The keytab tomcat.keytab should already be stored there. We will store spnego.login.conf and spnego.krb5.conf there as well. Examples of both files can be found in the installation directory /samples/tomcat_kerberosauth/doc. This can be copied to the path named above and then adjusted accordingly. The two key entries in the spnego.login.conf are the path to the keytab (i.e. the keyTab= entry) and the Tomcat AD user (the principal= entry). The spnego.login.conf looks like this with the settings used in our example: 
------------------- spnego.login.conf START --

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

spnego-server {
    com.sun.security.auth.module.Krb5LoginModule required
    storeKey=true
    debug=true
    useKeyTab=true
    keyTab="file:///c:/PATH/TO/KEYTAB.FILE/tomcat.keytab"
    principal=tomcat_user;
};

------------------- spnego.login.conf END ----
In the spnego.krb5.conf, the Kerberos realm entries must be adjusted accordingly. From experience, this correspond to the domain entry. The entries must be written in block capitals. The spnego.krb5.conf will then look like this: 
------------------- spnego.krb5.conf START ---

[libdefaults]
                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
                default_realm   =             EXAMPLE.ORG

[realms]
                EXAMPLE  = {
                               kdc = kdc.example.org
                               default_domain = EXAMPLE.ORG
}

[domain_realm]
                .EXAMPLE.ORG = EXAMPLE.ORG

------------------- spnego.krb5.conf END -----

3.3. Adjust web.xml

The files created in the previous step (spnego.login.conf and spnego.krb5.conf) will at last be integrated in the web.xml. The web.xml can be found in the portal directory /external/htmlroot/WEB-INF/. By default, this contains an commented out entry for the spnego filter. The comments should be removed here and the path to both of the files should be adjusted accordingly so that the respective section looks like this: 
------------------- web.xml Excerpt START -----
<filter>
    <filter-name>SpnegoAuthenticationFilter</filter-name>
    <filter-class>de.uplanet.lucy.server.connector.servlet.SpnegoAuthenticationFilter</filter-class>

    <init-param>
        <param-name>spnego.allow.basic</param-name>
        <param-value>true</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.allow.localhost</param-name>
        <param-value>true</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.allow.unsecure.basic</param-name>
        <param-value>true</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.login.client.module</param-name>
        <param-value>spnego-client</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.krb5.conf</param-name>
        <param-value>C:/PATH/TO/KEYTAB.FILE/spnego.krb5.conf</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.login.conf</param-name>
        <param-value>C:/PATH/TO/KEYTAB.FILE/spnego.login.conf</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.preauth.username</param-name>
        <param-value></param-value>
    </init-param>

    <init-param>
        <param-name>spnego.preauth.password</param-name>
        <param-value></param-value>
    </init-param>

    <init-param>
        <param-name>spnego.login.server.module</param-name>
        <param-value>spnego-server</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.prompt.ntlm</param-name>
        <param-value>true</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.allow.delegation</param-name>
        <param-value>true</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.logger.level</param-name>
        <param-value>1</param-value>
    </init-param>
</filter>


<filter-mapping>
    <filter-name>SpnegoAuthenticationFilter</filter-name>
    <url-pattern>*</url-pattern>
</filter-mapping>

------------------- web.xml Excerpt END -------

3.4 Test the pre-authentication

After restarting the Tomcat service, Tomcat should now authenticate against the KDC. You can check whether this was successful in the tomcat_startup.log. 
INFO   | jvm 1    | 2016/05/18 15:28:28 | Debug is  true storeKey true useTicketCache false useKeyTab true doNotPrompt false ticketCache is null isInitiator true KeyTab is ///C:/PATH/TO/KEYTAB.FILE/tomcat.keytab refreshKrb5Config is false principal is tomcat_user tryFirstPass is false useFirstPass is false storePass is false clearPass is false
INFO   | jvm 1    | 2016/05/18 15:28:28 | principal is tomcat_user@EXAMPLE.ORG
INFO   | jvm 1    | 2016/05/18 15:28:28 | Will use keytab
INFO   | jvm 1    | 2016/05/18 15:28:28 | Commit Succeeded

3.5. Entries in LucAuth.cfg and om.cfg

In the following, the setup on the Intrexx-side will be described. So that Intrexx, or rather the respective portal, uses the Kerberos module for the authentication, a corresponding login provider must be added in the LucyAuth.cfg; this in turn needs to be integrated in the om.cfg for the respective service. Both files can be found in the portal directory /internal/cfg. For the entry in the LucyAuth.cfg, a LucyAuth.cfg with example entries can be found in the installation directory /samples/tomcat-kerberosauth/doc/. In general, the entry TomcatKerberosAuth2 should be sufficient. If the UserPrincipalName is different from the sAMAccountName, then the entry TomcatKerberosAuth3 is recommended.

Example

In the Active Directory, the aSAMAccount entry for the user Henry Miller is PRE2000EXAMPLE\henrym. The UserPrincipalName of the same user is henry.miller@example.org. The user import was performed with the Active Directory NTLM. If the pre2000 domain name differs from the UserPrincipal domain name, the pre2000 domain can be transferred explicitly with the following entry in LucyAuth.cfg: 
TomcatKerberosAuth3
{
	de.uplanet.lucy.server.auth.module.external.ExternalAuthenticationLoginModule required
		de.uplanet.auth.fixedLoginDomain="PRE2000EXAMPLE"
		debug=true;
};
In om.cfg, you now need to point to the corresponding entry, e.g. with the following lines: 
<binding scope="web" auth-type="TomcatKerberosAuth3"/>
If multiple domains are in use, these can be configured in more depth using Groovy scripting. In this case, the entry TomcatKerberosAuth4 provides the ability to refer to a Groovy script and perform additional configurations there. So that the changes take effect, the portal service needs to be restarted.

4. Browser-side adjustments

4.1. Internet Explorer

The Tomcat server needs to be added under Internet options / Security / Sites - in our example as tomcat.example.org.

4.2. Firefox

Enter about:config in the address bar. The Tomcat server needs to be added to network-negotiate-auth.trusted-uris.

5. Test

After the portal and Tomcat service have been restarted, you can test the authentication with any user from the AD. After logging on to the Windows system, this user - provided they are a user from the domain - should receive a Kerberos ticket; this can be checked using the following command: 
klist tgt
The portal can now be opened in the browser. If the login is not successful, looking at the portal.log is helpful; this can be found in the portal directory /log. If the login procedure fails, the corresponding login data is logged here. If the login information there doesn't match the login data of the corresponding Intrexx user, then this needs to be taken into account during the user replication by using a different profile or by adjusting the used replication profile accordingly.

Whether Kerberos Authentication can be implemented while using Tomcat on the target system, is heavily dependent on the system environment (Active Directory / Network).