Configuring SPNEGO authentication in Liberty

You can use single sign-on for HTTP requests by 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.

Before you begin

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. Using SPNEGO directly from the domain controller is not supported.

Configure the following software and ensure that it is available:

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.
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.
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 by using a native Liberty server authentication mechanism. For this topic, an example Liberty server host is myLibertyMachine.example.com.

About this task

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 by using SPNEGO web authentication.

Procedure

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

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 that the user myLibertyMachine_http is created with password security.
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 your Microsoft setspn command version supports the -S option, then you must use the -S option instead of -A.

Create the Kerberos keytab file by 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
				Using 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 by using one of these commands:

If your 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. 
```

You 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

You can also use the MS ktpass command to include an existing keytab file with the newly created keytab by 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
Using 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 Creating a Kerberos service principal name and keytab file.

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, you must create this file manually.
  The default location and name of this file varies depending on the operating system:
  - Windows - The default location is c:\windows\krb5.ini.
  - Linux® - The default location is /etc/krb5.conf.
  - AIX®, z/OS®, HP-UX, and Solaris - The default location is /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 you are using Microsoft Active Directory, realm names are must be uppercase.
  
  Note: Not all of the KDC solutions available support all encryption types. Before you choose an encryption type, ensure that the KDC supports the encryption type that you want to use by consulting your Kerberos Administrator's and User's Guide.
  
  Ensure that you 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 Creating 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.
  - You can use the JDK command klist to list the SPN in the keytab file.
```
klist -k -t /etc/krb5.keytab
```
  - You 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, you can use the klist command to list the Kerberos ticket. If you get the Kerberos ticket, then the Kerberos keytab and configuration are valid.
4. Configure and enable SPNEGO web authentication on the Liberty server.
  You can enable SPNEGO web authentication by enabling the spnego-1.0 feature of Liberty.
  1. Add the spnego-1.0 feature to the server.xml file.
```
<featureManager>
        <feature>spnego-1.0</feature>
        <feature>appSecurity-2.0</feature>
        ...
</featuremanager>
```
    Adding the spnego-1.0 feature automatically enforces a certain minimum configuration. You do not need to specify a <spnego> element in the server.xml file. Without specifying a <spnego> element, the following configuration is implicit.
```
<spnego
       canonicalHostName="true"
       disableFailOverToAppAuthType="true"
       trimKerberosRealmNameFromPrincipal="true"
       includeClientGSSCredentialInSubject="true" />
```
    Note: The runtime forms the default SPN in the following format:
    "HTTP/" + java.net.InetAddress.getLocalHost().getCanonicalHostName();
    If the default SPN does not match what you have in the krb5.keytab file, then you 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, you can filter HTTP requests to require SPNEGO authentication for only certain requests, web applications, hosts, or user agents. Also, you 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 Using 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 you 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
```
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. You 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 you are using Internet Explorer version 9 or older, go to the next step. If you 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: You 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: The user must be logged in to the domain controller for SPNEGO to work. Using 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 you are prompted multiple times for a user ID and password, make sure that you enabled SPNEGO support on your client browser by following the previous instructions. You must also make sure that the disableFailOverToAppAuthType attribute in the <spnego> configuration is set to false.

Results

Your Internet browser is now properly configured for SPNEGO authentication. You can use applications with secured resources that are deployed on Liberty servers without being prompted for a user ID and password.

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