Configuring SPNEGO authentication

You can enable single sign-on (SSO) for HTTP requests by using Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) web authentication. With SPNEGO SSO, HTTP users log in only once to a Microsoft domain controller at their desktop.

SPNEGO enables users to log in to applications with their Microsoft Windows account login instead of using a separate account to log in to their Windows operating system. You can also configure SPNEGO to work on Linux operating systems. This task demonstrates how to configure an Open Liberty server to support SSO for HTTP requests with SPNEGO by doing the following things:

You must complete all of these steps to properly configure SPNEGO with Open Liberty.

Before you begin

To enable SPNEGO, the clocks for the client, Active Directory server, and Open Liberty server must be synchronized within 5 minutes of each other.

Make sure that the following resources are available:

  • A Microsoft Windows Server running an Active Directory Domain Controller and associated Kerberos Key Distribution Center (KDC). In this example, the hostname for the domain controller is myAdMachine.example.com, the domain controller name is mydomain.example.com, and the Kerberos realm name is MYDOMAIN.EXAMPLE.COM.

  • A Microsoft Windows domain member, which is called myClientMachine.example.com in this example.

  • A server platform with an Open Liberty server that has an application with a protected resource. In this example, the Open Liberty server hostname is myLibertyMachine.example.com.

Creating a Kerberos service principal name and keytab file

  1. Create a user account, for example, myLibertyMachine_http, for the Open Liberty server. This account is used to map to the Kerberos service principal name (SPN).

  2. Run the Microsoft setspn command to map the user account to a Kerberos SPN. This user account represents the Open Liberty server as a Kerberos service with the KDC. The following example shows how to run the setspn command:

    setspn -S HTTP/myLibertyMachine.example.com myLibertyMachine_http
  3. Create the Kerberos keytab file by running the Microsoft ktpass command. The default name for the keytab file is krb5.keytab. The following example shows how to run the ktpass command:

    ktpass -out krb5.keytab -princ HTTP/[email protected] -mapUser myLibertyMachine_http -mapOp set -pass <myLibertyMachine_http_password> crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL

    To verify that the command worked correctly and there isn’t a duplicated SPN in the Microsoft forest, run the Microsoft ldif command:

    ldifde -f check_SPN.txt -t 3268 -d "" -l servicePrincipalName -r "
    (servicePrincipalName=HTTP/myLibertyMachine.example.com)" -p subtree

    The following example output shows that one entry was returned, which indicates that there isn’t a duplicated SPN:

    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
  4. If you have multiple SPNs, you need to merge your keytab files. To merge the files, run the ktpass command with the -in option to include an existing keytab file with the newly created keytab file. The following example includes the myOtherKrb5.keytab file:

    ktpass -in myOtherKrb5.keytab -out krb5.keytab -princ HTTP/[email protected] -mapUser myLibertyMachine_http -mapOp set -pass <myLibertyMachine_http_password> -crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL

Copying the Kerberos keytab and configuration files

  1. Copy the Kerberos keytab file from the domain controller to the Open Liberty server. The default location of the file is the same directory as the Kerberos configuration file, which varies depending on the operating system:

    • For Windows operating systems, the default location is C:\windows\krb5.ini.

    • For Mac and Linux operating systems, the default location is /etc/krb5.conf.

  2. Create a Kerberos configuration file. This file includes the locations of KDCs for the realms of interest, defaults for the current Kerberos realm, and mappings of hostnames onto Kerberos realms. The following example shows a Kerberos configuration file:

    [libdefaults]
        default_realm = MYDOMAIN.EXAMPLE.COM
        default_keytab_name = FILE:c:\winnt\krb5.keytab
        default_tkt_enctypes = rc4-hmac aes256-cts-hmac-sha1-96
        default_tgs_enctypes = rc4-hmac aes256-cts-hmac-sha1-96
    [realms]
        MYDOMAIN.EXAMPLE.COM= {
            kdc = host1.example.com:88
            default_domain = example.com
    }
    [domain_realm]
        .example.com = MYDOMAIN.EXAMPLE.COM

    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 support the RC4-HMAC encryption type. The Kerberos configuration file must also list RC4-HMAC first in the default_tkt_enctypes and default_tgs_enctypes parameters. In a production environment, you might want to choose a stronger encryption type than RC4-HMAC.

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

    1. Run the klist command to list the SPN in the keytab file:

      klist -k -t /etc/krb5.keytab
    2. Run the kinit command to validate the SPN in the keytab file and the Kerberos configuration file:

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

Enabling SPNEGO web authentication

  1. Enable SPNEGO web authentication by adding the SPNEGO feature (spnego-1.0) to your server.xml file:

    <featureManager>
            <feature>spnego-1.0</feature>
            ...
    </featuremanager>
  2. If you use any Oracle JDK or Java 11, add the java.security.krb5.kdc and java.security.krb5.realm JVM system properties to the jvm.options file, as shown in the following example:

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

Configuring the client application on the client computer

The following steps are for users who access SPNEGO-protected resources from a browser and must be completed on the client computer. Ensure that browser supports SPNEGO authentication and that the user is logged in to the domain controller.

Google Chrome on Windows

  1. Open the Control Panel and click Internet Options. In the window that’s displayed, click the Security tab.

  2. Select the Local intranet icon and click Sites.

  3. Click Advanced in the Local intranet window.

  4. Complete the Add this website to the zone field with the web address of the hostname so that SSO can be enabled for the list of websites that are shown in the websites field. Close the second Local intranet window.

  5. Click OK, and close the Local intranet window.

  6. In 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 Chrome to activate this configuration.

Google Chrome on Mac or Linux

  1. Add the --auth-server-whitelist parameter to the google-chrome command. For example, to configure SPNEGO for Chrome on Linux, run the following command:

    google-chrome --auth-server-whitelist = "hostname/domain"

    This command runs Chrome and sets the --auth-server-whitelist parameter so that SPNEGO can work in the browser.

Microsoft Internet Explorer

  1. Log in to the Active Directory domain.

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

  3. Select the Local intranet icon and click Sites.

  4. Click Advanced in the Local intranet window.

  5. Complete the Add this website to the zone field with the web address of the hostname so that SSO can be enabled for the websites that are shown in the websites field. Close the second Local intranet window.

  6. Click OK, and close the Local intranet window.

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

  8. Click OK. Restart Internet Explorer to activate this configuration.

Mozilla Firefox

  1. Log in to the Active Directory domain.

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

  3. In the 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.

  5. If your SPNEGO solution uses 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. Restart Firefox to activate this configuration.

Verifying that SPNEGO is working

After you configure SPNEGO authentication, you can deploy applications in your company that users must log in to only once. To verify that SPNEGO is working, log in to the domain controller and access a protected resource on Open Liberty. Because you are logged in to the domain controller, you aren’t prompted for credentials. If you aren’t logged in to the domain controller and attempt to access a protected resource, you are prompted for credentials.

See also