Configure SPNEGO authentication in Liberty

We can use single sign-on for HTTP requests using the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) web authentication for WebSphere Application Server Liberty. SPNEGO single sign-on (SSO) enables HTTP users to log in to a Microsoft domain controller only once at their desktop and to achieve SSO with the Liberty server.

The latest documentation about configuring SPNEGO for Liberty is available on the Open Liberty website. Remember:

• SPNEGO SSO is also known as Integrated Windows Authentication (IWA) for Windows platform.
• Liberty supports SPNEGO for IWA but not Kerberos and NT LAN Manager (NTLM).
• Beginning with 19.0.0.1, the IBM SDK, the Oracle JDK, and OpenJDK are supported. Before 19.0.0.1, only the IBM SDK was supported.
• SPENGO and constrained delegation do not support IBM hybrid JDK.

• The commands for this task and much of the SPNEGO configuration are case sensitive.

• The clocks for the client, Microsoft Active Directory server, and Liberty server must be synchronized to within 5 minutes of each other, by default. The allowable difference in synchronization is configurable.

• The software configuration must have a running domain controller, at least one client machine in that domain and a server platform with a Liberty server that has a protected resource within an application, for a total of three required machines. Use SPNEGO directly from the domain controller is not supported.

Configure the following software and ensure that it is available:

1. A Microsoft Windows Server running an Active Directory Domain Controller and associated Kerberos Key Distribution Center (KDC). For this topic, an example host for such a domain controller is myAdMachine.example.com. The domain controller name is mydomain.example.com and the Kerberos realm name is MYDOMAIN.EXAMPLE.COM, which is the domain controller name in all uppercase letters.
2. A Microsoft Windows domain member (client) that supports the SPNEGO authentication mechanism as defined in IETF RFC 2478. Examples of an appropriate client might be a modern browser or a Microsoft .NET client. Most modern browsers support SPNEGO authentication. For this topic, an example host for the client is myClientMachine.example.com.
3. A server platform with a Liberty server that has a protected resource within an application. Users in the Active Directory must be able to access Liberty server protected resources using a native Liberty server authentication mechanism. For this topic, an example Liberty server host is myLibertyMachine.example.com.

The objective of this task is to allow users to successfully access Liberty server resources without having to authenticate again, and thus achieve Microsoft Windows desktop single sign-on capability.

This task demonstrates how to configure a Liberty server to support single sign-on for HTTP requests using SPNEGO web authentication.

1. On the Microsoft domain controller (myAdMachine.example.com), create a Kerberos service principal name (SPN) and keytab file for the Liberty server:

   1. Create a user account for the Liberty server. This account is used to map to the Kerberos service principal name (SPN). For Active Directory machines, this account creation can typically be done by going to Start > Administrative Tools > Active Directory Users and Computers, right-clicking on Users in the panel, and selecting New > User. This topic assumes the user myLibertyMachine_http is created with password security.

   2. Run the Microsoft setspn command to map the user account to a Kerberos SPN. This user account represents the Liberty server as being a Kerberos service with the KDC. An example of the setspn command:

      C:\> setspn -a HTTP/myLibertyMachine.example.com myLibertyMachine_http
      
      Registering ServicePrincipalNames for CN=myLibertyMachine_http,CN=Users,DC=MYDOMAIN,DC=EXAMPLE,DC=COM
               HTTP/myLibertyMachine.example.com
      Updated object

      Note: If the Microsoft setspn command version supports the -S option, then use the -S option instead of -A.

   3. Create the Kerberos keytab file using the Microsoft ktpass tool. The default name for this file is krb5.keytab.

      An example of the ktpass command:

      C:\> ktpass -out krb5.keytab -princ HTTP/myLibertyMachine.example.com@MYDOMAIN.EXAMPLE.COM -mapUser myLibertyMachine_http -mapOp set -pass security -crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL
      
      				Targeting domain controller: myAdMachine.MYDOMAIN.EXAMPLE.COM
      				Use legacy password setting method
      				Successfully mapped HTTP/myLibertyMachine.example.com to myLibertyMachine_http.
      				Key created.
      				Output keytab to krb5.keytab:
      				Keytab version: 0x502
      				keysize 93 HTTP/myLibertyMachine.example.com@MYDOMAIN.EXAMPLE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 3 etype 0x17 (RC4-HMAC) keylength 16 (0x148d643db283327d3f3d44547da8cade)

      Make sure that there is not a duplicated SPN in the Microsoft forest using one of these commands:

      • If the Microsoft setspn command version supports the -X option to search for a duplicated SPN, then use setspn -X:

        C:\>setspn -X HTTP/myLibertyMachine.example.com 
        
        Processing entry 0 
        found 0 group of duplicate SPNs. 

      • We can also use the Microsoft ldif command. The following example shows that one entry was returned, meaning there is not a duplicated SPN.

        C:\>ldifde -f check_SPN.txt -t 3268 -d "" -l servicePrincipalName -r " 
        (servicePrincipalName=HTTP/myLibertyMachine.example.com)" -p subtree 
        
        Connecting to "myAdMachine.MYDOMAIN.EXAMPLE.COM" 
        Logging in as current user using SSPI 
        Exporting directory to file check_SPN.txt 
        Searching for entries... 
        Writing out entries. 
        1 entries exported 

      We can also use the MS ktpass command to include an existing keytab file with the newly created keytab using the -in option. The following example command includes the myOtherKrb5.keytab keytab.

      ktpass -in myOtherKrb5.keytab -out krb5.keytab -princ HTTP/myLibertyMachine.example.com@MYDOMAIN.EXAMPLE.COM -mapUser myLibertyMachine_http -mapOp set -pass security -crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL

      The example command produces the following output.

      Targeting domain controller: myAdMachine.MYDOMAIN.EXAMPLE.COM
      Use legacy password setting method
      Successfully mapped HTTP/myLibertyMachine.example.com to myLibertyMachine_http.
      Key created.
      Output keytab to krb5.keytab:
      Keytab version: 0x502
      keysize 93 HTTP/myLibertyMachine.example.com@MYDOMAIN.EXAMPLE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 3 etype 0x17 (RC4-HMAC) keylength 16 (0x148d643db283327d3f3d44547da8cade)

      For information on creating SPNs and keytab files on different KDC systems, see Create a Kerberos service principal name and keytab file.

2. On the Liberty server machine (myLibertyMachine.example.com), enable the Kerberos keytab and configuration files and SPNEGO web authentication.

   1. Copy the Kerberos keytab file from the domain controller to the Liberty server machine. The default name of this file is krb5.keytab and the default location varies depending on the platform but is the same directory as the Kerberos configuration file. For default locations for various platforms, see the next step.

   2. Create a Kerberos configuration file.

      The Kerberos configuration file contains client configuration information. This information includes the locations of KDCs for the realms of interest, defaults for the current Kerberos realm, and mappings of host names onto Kerberos realms. For Liberty servers, we must create this file manually. The default location and name of this file varies depending on the operating system:

      c:\windows\krb5.ini.
      • Linux - The default location is /etc/krb5.conf. /etc/krb5/krb5.conf.

      Here is a sample Kerberos configuration file for the AIX, z/OS, HP-UX, or Solaris platforms (based on the default keytab location):

      [libdefaults]
        default_realm = MYDOMAIN.EXAMPLE.COM
        default_keytab_name = FILE:/etc/krb5/krb5.keytab
        default_tkt_enctypes = rc4-hmac 
        default_tgs_enctypes = rc4-hmac 
        forwardable  = true
        renewable  = true
        noaddresses = true
        clockskew  = 300
        udp_preference_limit = 1
      [realms]
        MYDOMAIN.EXAMPLE.COM = {         kdc = myAdMachine.example.com:88
              default_domain = example.com
      			}
      [domain_realm]
              .example.com = MYDOMAIN.EXAMPLE.COM

      Note: Realm names are usually specified in uppercase letters. If we are using Microsoft Active Directory, realm names are must be uppercase.

      Note: Not all of the KDC solutions available support all encryption types. Before we choose an encryption type, ensure that the KDC supports the encryption type we want to use by consulting your Kerberos Administrator's and User's Guide.

      Ensure that we have a common encryption type for the Kerberos configuration file, Kerberos keytab file, Kerberos SPN, and Kerberos client. For example, if the Kerberos client uses the RC4-HMAC encryption type, the target server must also support the RC4-HMAC encryption type and the Kerberos configuration file must list RC4-HMAC first in the default_tgt_enctypes and default_tkt_enctypes parameters.

      For additional information and requirements on the content of this file, see Create a Kerberos configuration file.

   3. Verify the Kerberos configuration and keytab files.

      To verify the Kerberos configuration and keytab files, use the klist and kinit commands.

      • We can use the JDK command klist to list the SPN in the keytab file.

        klist -k -t /etc/krb5.keytab

      • We can use the JDK command kinit to validate the SPN in the keytab file and the Kerberos configuration file.

        kinit -k -t /etc/krb5.keytab HTTP/myLibertyMachine.example.com

      After the kinit command, we can use the klist command to list the Kerberos ticket. If we get the Kerberos ticket, then the Kerberos keytab and configuration are valid.

   4. Configure and enable SPNEGO web authentication on the Liberty server.

      We can enable SPNEGO web authentication by enabling the spnego-1.0 feature of Liberty.

      1. Add the spnego-1.0 feature to server.xml.

         <featureManager>
                 <feature>spnego-1.0</feature>
                 <feature>appSecurity-2.0</feature>
                 ...
         </featuremanager>
         

         Add the spnego-1.0 feature automatically enforces a certain minimum configuration. We do not need to specify a <spnego> element in server.xml. Without specifying a <spnego> element, the following configuration is implicit.

         <spnego
                canonicalHostName="true"
                disableFailOverToAppAuthType="true"
                trimKerberosRealmNameFromPrincipal="true"
                includeClientGSSCredentialInSubject="true" />
         

         Note that the runtime forms the default SPN in the following format:

         "HTTP/" + java.net.InetAddress.getLocalHost().getCanonicalHostName();

         If the default SPN does not match what we have in the krb5.keytab file, then we need to specify the servicePrincipalNames, for example:

         <spnego id="mySpnego" servicePrincipalNames="HTTP/myLibertyMachine.example.com"/>

         Note: When the spnego-1.0 feature is enabled and the <spnego> element is either omitted or not configured with an authFilterRef attribute, all requests to access protected resources use SPNEGO authentication.

         For more information on configuring the authentication filter, see Authentication Filters.

         Note: When values for the krb5Config or krb5Keytab attributes are not given, each respective file is expected to exist at its default location. The default locations for the Kerberos configuration and keytab files on various platforms are given earlier in this example.

      2. Optional: Specify any additional configuration options as necessary. The Liberty supports many common SPNEGO scenarios and configurations. For example, we can filter HTTP requests to require SPNEGO authentication for only certain requests, web applications, hosts, or user agents. Also, we can move the Kerberos configuration and keytab files away from their respective default locations. Here is a sample configuration that changes the default <spnego> settings:

         <server>
                 <featureManager>
                 <feature>spnego-1.0</feature>
                 <feature>appSecurity-2.0</feature>
                 ...
                 </featureManager>
                 ...
                 <authFilter id="myAuthFilter">
                  <host id="myHost" name="example.com" matchType="contains" />
                  <webApp id="myWebApp" name="protectedApp" matchType="equals" />
                 </authFilter>
         
                 <spnego id="mySpnego"
                 includeClientGSSCredentialInSubject="false"
                 krb5Config="${server.config.dir}/resources/security/kerberos/krb5.conf"
                 krb5Keytab="${server.config.dir}/resources/security/kerberos/krb5.keytab"
                 servicePrincipalNames="HTTP/myLibertyMachine.example.com"
                 authFilterRef="myAuthFilter" />
                 </spnego>        
                 ...
         </server>

         With this configuration, SPNEGO authentication is used for any requests that are received containing the host name example.com for resources within the web application protectedApp. In addition, the client's GSS credentials are not added to the user subject upon successful authentication. Finally, the Kerberos configuration and keytab files to be used by the server are given specific locations within the server configuration directory instead of their respective default locations.

         For more configuration options, see The Simple and Protected GSS-API Negotiation Mechanism (SPNEGO).

         For information on mapping Kerberos principal names to WebSphere user registry IDs, see Mapping of a client Kerberos principal name to the WebSphere user registry ID.

         In the rare event that you wish to use Kerberos principal names for authorization, see Use Kerberos principal name for authorization with SPNEGO authentication. These steps should be followed only when necessary and by users who specifically choose not to use the default mapping or JAAS custom login module mapping.

      If we use the Oracle JDK, add the java.security.krb5.kdc and java.security.krb5.realm JVM system properties to the jvm.options file as in the following example:

      -Djava.security.krb5.kdc=myKdcMachine.example.com
      -Djava.security.krb5.realm=EXAMPLE.COM

3. Configure the client application on the client application machine (myClientMachine.example.com).

   The following steps must be done only on the client machine. Starting a browser on the Active Directory machine or Liberty server machine and performing these steps does not work.

   The following steps are for users who are accessing SPNEGO-protected resources from a browser. We must have a browser installed that supports SPNEGO authentication. Microsoft Internet Explorer:

   1. At the desktop, log in to the Windows Active Directory domain.

   2. In the Internet Explorer window, click Tools > Internet Options. In the window that is displayed, click the Security tab.

   3. Select the Local intranet icon and click Sites.

   4. If we are using Internet Explorer version 9 or older, go to the next step. If we are using Internet Explorer 10 or later, click Advanced in the Local intranet window.

   5. In the Local intranet window, complete the Add this website to the zone field with the web address of the host name so that single sign-on (SSO) can be enabled for the list of websites that are shown in the websites field. Your site information technology staff provides this information. Close the second Local intranet window and click OK to complete this step and close the Local intranet window.

   6. On the Internet Options window, click the Advanced tab and scroll to Security settings. Ensure that the Enable Integrated Windows Authentication box is selected.

   7. Click OK. Restart your Microsoft Internet Explorer to activate this configuration.
   Mozilla Firefox:
   1. At the desktop, log in to the Windows Active Directory domain.

   2. In the address field in Firefox, type about:config.

   3. In the Filter/Search box, type network.n.
   4. Double-click network.negotiate-auth.trusted-uris. This preference lists the sites that are permitted to engage in SPNEGO Authentication with the browser. Enter a comma-delimited list of trusted domains or URLs.

      Note: We must set the value for network.negotiate-auth.trusted-uris.

   5. If the deployed SPNEGO solution is using the advanced Kerberos feature of Credential Delegation, double-click network.negotiate-auth.delegation-uris. This preference lists the sites for which the browser can delegate user authorization to the server. Enter a comma-delimited list of trusted domains or URLs.

   6. Click OK. The configuration reflects the updates.

   7. Restart your Firefox browser to activate this configuration.

   Note that the user must be logged in to the domain controller for SPNEGO to work. Use the previous example machines, a user must log in to the domain controller at MYDOMAIN.EXAMPLE.COM\username in order for SPNEGO authentication through the browser to work.

   Note: If we are prompted multiple times for a user ID and password, make sure that we enabled SPNEGO support on your client browser by following the previous instructions. We must also make sure that the disableFailOverToAppAuthType attribute in the <spnego> configuration is set to false.

To verify that SPNEGO is working, we can log in to the domain controller and then access a protected resource on the Liberty server, and because we are logged in to the domain controller, we are not prompted for credentials. However, if we do not log in to the domain controller and attempt to access a protected resource, we are prompted for credentials.