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.

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. Using SPNEGO directly from the domain controller isn’t supported.

  • 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.

Procedure

  1. On the myAdMachine.example.com domain controller, create 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, 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

  1. On the Open Liberty server, myLibertyMachine.example.com, set up the Kerberos keytab and configuration files and SPNEGO web authentication.

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

    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 default location and name of this file 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.

        The following example shows a Kerberos configuration file:

        [libdefaults]
    default_realm = MYDOMAIN.EXAMPLE.COM
    default_keytab_name = FILE:c:\windows\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

    4. Enable SPNEGO web authentication by adding the SPNEGO feature to your server.xml file:

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

    5. 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

  1. Configure the client application on the myClientMachine.example.com client application computer.

The following steps are for users who access SPNEGO-protected resources from a browser and must be completed on the myClientMachine.example.com client computer. Ensure that the 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.

  1. Verify 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

Single sign-on