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 ismydomain.example.com
, and the Kerberos realm name isMYDOMAIN.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
On the
myAdMachine.example.com
domain controller, create a Kerberos service principal name and keytab file.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).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 thesetspn
command:setspn -S HTTP/myLibertyMachine.example.com myLibertyMachine_http
Create the Kerberos keytab file by running the Microsoft
ktpass
command.
The default name for the keytab file iskrb5.keytab
. The following example shows how to run thektpass
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
If you have multiple SPNs, merge your keytab files.
To merge the files, run thektpass
command with the-in
option to include an existing keytab file with the newly created keytab file. The following example includes themyOtherKrb5.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
On the Open Liberty server,
myLibertyMachine.example.com
, set up the Kerberos keytab and configuration files and SPNEGO web authentication.Copy the Kerberos keytab file from the domain controller to the Open Liberty server.
The default name of this file iskrb5.keytab
, and the default location of the file is the same directory as the Kerberos configuration file, but varies depending on the operating system.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
anddefault_tgs_enctypes
parameters. In a production environment, you might want to choose a stronger encryption type than RC4-HMAC.
Verify the Kerberos configuration and keytab files.
To verify the Kerberos configuration and keytab files, use theklist
andkinit
commands.Run the
klist
command to list the SPN in the keytab file:klist -k -t /etc/krb5.keytab
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
Enable SPNEGO web authentication by adding the SPNEGO feature to your
server.xml
file:<featureManager> <feature>spnego-1.0</feature> ... </featuremanager>
If you use any Oracle JDK, add the
java.security.krb5.kdc
andjava.security.krb5.realm
JVM system properties to thejvm.options
file, as shown in the following example:-Djava.security.krb5.kdc=myAdMachine.example.com -Djava.security.krb5.realm=MYDOMAIN.EXAMPLE.COM
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
Open the Control Panel and click Internet Options. In the window that’s displayed, click the Security tab.
Select the Local intranet icon and click Sites.
Click Advanced in the Local intranet window.
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.
Click OK, and close the Local intranet window.
In the Internet Options window, click the Advanced tab and scroll to Security settings. Ensure that the Enable Integrated Windows Authentication box is selected.
Click OK. Restart Chrome to activate this configuration.
Google Chrome on Mac or Linux
Add the
--auth-server-whitelist
parameter to thegoogle-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
Log in to the Active Directory domain.
In an Internet Explorer window, click Tools > Internet Options. In the window that’s displayed, click the Security tab.
Select the Local intranet icon and click Sites.
Click Advanced in the Local intranet window.
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.
Click OK, and close the Local intranet window.
In the Internet Options window, click the Advanced tab and scroll to Security settings. Ensure that the Enable Integrated Windows Authentication box is selected.
Click OK. Restart Internet Explorer to activate this configuration.
Mozilla Firefox
Log in to the Active Directory domain.
In the Firefox address field, type
about:config
.In the search box, type
network.n
.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.
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.
Click OK. Restart Firefox to activate this configuration.
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.