How To

Summary

Enabling single sign-on for the Windows desktop. Where the user authenticates to a desktop PC by using AD domain log in and then can securely access the web application without prompting you to log in. Specifically, you configure the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) feature on the Liberty server that hosted a web application.

Microsoft extended Kerberos with a protocol known as Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) for sharing Windows credentials with Liberty Server. This protocol permits a window client machine and the Liberty server to negotiate where the Client machine sends a SPNEGO token wrapped within a Kerberos Token. On the Liberty server, SPNEGO is initialized and understands the SPNEGO token, then this token is used to implement secure SSO.

Objective

This document contains the overall step by step instructions for setting this up SSO within Liberty using Spnego

Steps

How Does SPNEGO Work in Liberty Server?

This section highlights the essential parts of the SPNEGO authentication process flow. It explains how Microsoft and IBM components are involved in the SPNEGO SSO flow.

image-20190903093914-1

In this scenario, a user has authenticated to Windows (obtaining Active Directory credentials) and then, using a Web browser client, invokes a Web application, which is deployed on a Liberty server that supports SPNEGO. The sequence of steps for SSO communication follows:

1. After the user logs in to the Windows Domain from their workstation (PC/Laptop). The user attempts to access the secured Web resources using a browser with URL. For Example, http://mywebsiteurl.rtp.raleigh.ibm.com:29080/snoop, i.e. the browser sends an HTTP request to Liberty Server

2. Liberty Server receives the HTTP request from Client (Windows Client).

3 & 4. Liberty Server will perform a DNS lookup as an HTTP request comes in, and then Liberty server check if the application is protected and respond with an HTTP challenge response (HTTP 401) containing an "Authenticate: Negotiate" header to client.

5. The client recognizes the Negotiate header because it has been configured to support "Integrated Windows Authentication."

5a. The browser issues a DNS lookup for the hostname mywebsiteurl.rtp.raleigh.ibm.com; If the DNS server returns an A-record with the IP address for mywebsiteurl.rtp.raleigh.ibm.com it is considered to be the canonical DNS name of the Liberty server. However, if DNS replies with a CNAME (DNS alias) record for mywebsiteurl.rtp.raleigh.ibm.com and then resolves the alias to an A-record with a different hostname server2.rtp.raleigh.ibm.com, then this second hostname will be considered to be the canonical DNS name of the Liberty server.

5b. On the Client PC, Internet Explorer will parse the URL typed (FQDN or alias) in the address bar to extract the hostname and use the hostname to compute an SPN.

6. Using the SPN that is passed in, LSASS requests a Kerberos ticket to a domain controller (KDC) Which means client (PC that logged in to domain) contacts the KDC on the domain controller and requests a ticket for the SPN based on what the browser client sent as the hostname (FQDN or alias) and that is determined by network (DNS, DHCP) settings. This tells the web browser that it needs to check with the local OS (Client Window 10 or 8) regarding what options it has available from the Negotiate Security Support Provider (SSP) to authenticate the user and Client begins a Kerberos authentication sequence.

7. The client requests a Ticket Granting Ticket (TGT) from the Kerberos Authentication Service (AS). as_request ( AS_REQ) Where client PC telling to KDC server. For example, Hi, I am ramarika. Can I have a ticket for getting tickets?

8. The client receives a TGT. as_reply ( AS_REP) KDC will provide example Here's a ticket-grating ticket, encrypted with ramarika secret key.

9. The client requests a Service ticket from the Kerberos Ticket Granting Service (TGS) ( tgs_request (TGS_REQ) Again client computer communicate with KDC server tells. Here is my TGT, could I have a ticket for the requested service which is HTTP/mywebsiteurl.rtp.raleigh.ibm.com@AUSTIN.IBM.COM. A service ticket will be encrypted with the server's key, with the encryption type AES256 in the TGS) for the SPN, for example, HTTP/mywebsiteurl.rtp.raleigh.ibm.com@AUSTIN.IBM.COM. The client constructs the SPN by parsing the requested URL for the protocol and the host name, and uses the client's own domain name as the Kerberos Security Realm: <protocol>/<host's FQDN>@<Client's Kerberos Security Realm>

10. The client receives the service ticket. The ticket is encrypted using a private key. The private key is a key constructed from the hash of the user account's password for the account associated with the SPN. Tickets contain a copy of the session key and some metadata, all encrypted with the service’s secret. Likewise, the user’s copy of the session key is encrypted using the password. tgs_reply (TGS_REP) It contains the ticket which will be sent to WebSphere. Here you can see the client name (this is the user that logged on to the client) which is ramarika@AUSTIN.IBM.COM

11. The client (Browser/PC) resends the original request for the secured resource. The request headers now contain "Authorization: Negotiate <base64 encoding>" (for example, Authorization: Negotiate YIIGUQY<remainder of base64 encoded string>). This time, the username is contained in the encrypted Kerberos service ticket, encapsulated in a SPNEGO token (SPNEGO token is a container of authentication method ids/tokens) passed in an HTTP Authorization header.

12. The Liberty server sees the incoming SPNEGO token (Authorization: Negotiate YIIGUQY) and this SPNEGO token is a wrapper of the Windows Kerberos token. Windows includes the PAC information of the user in the Kerberos token. Liberty server extracts the token using the IBM Java Generic Security Service (JGSS) API, and uses the keytab to decrypt (this validates that it must have come from the TGS) the SPNEGO token to retrieve the username and this username is asserted to the server. You may need to map the username to a principal that is meaningful in the server's registry.

13. The server's security system validates the user against its security registry and obtains other security information about the user. The user is logged in to the server.

14. The server sends the content back to the user together with the LTPA token as a cookie. This cookie enables subsequent requests to the same SSO domain to be sent without a re-authentication needing to occur.

   14a. If the user is authorized to access the resource, the response is an HTTP 200 response, and the requested resource is served.

   14b. If not, an "HTTP 403 Not Authorized" response is sent to the client

High-Level Steps

1. Set up Active Directory users and Map the service principal name (SPN).

2. Set up Kerberos configuration file in Liberty.

3. Deploy the sample application libertyDefaultApplication in Liberty.

4. Configure LDAP user registry and SPNEGO authentication in Liberty.

5. Enable SPNEGO authentication in Liberty.

6. Configure IE and Firefox browser.

7. Test the snoop application to validate the spnego.

8. How to debug the Spnego problem by using traces.

1. Set up Active Directory users and Map the service principal name (SPN).

Log on to the Active Directory Domain Controller Server (KDC server) with administrative level user name and password and then create a service account to map the SPN in Active Directory.

Create a user name spnliberty in Active Directory Domain Controller Server (KDC server) and Make sure select the password never expires and User cannot change password. By preventing the password from expiring, you avoid having to re-create the keytab file after the password has changed.

image-20190903094459-2

image-20190903094459-3

Check the option “This account support AES 256 encryptions” in user properties if you want to use higher encryption keys.

image-20190903094459-4

Create a service principal name (SPN) and Map the service principal name to the account that you created on the AD server. So In this example, the Active Directory user is spnliberty, and it is associated with service name HTTP/ by running the ktpass command on the domain controller.

Always use the latest version of the ktpass command for the right Windows version.

The realm name is all uppercases of the MS Active Directory domain name.

SPN is the Kerberos service principal name. The hostname specified in the SPN should match with the hostname of the URL that you are trying to do SSO, which means it could be your Webserver or VIP or Liberty Server depends on your scenario.

Generate the keytab file using Microsoft tool ktpass command on Active Directory Domain Controller Server (KDC server)

ktpass -princ hostname_of_web_site@ACTIVE_DIRECTORY_DOMAIN_NAME -ptype KRB5_NT_PRINCIPAL -mapuser SPNuser -mapOp set -pass your_spnuserpassword -out full_path_to_keytab_file -crypto cipher

Example command:

hostname_of_web_site = mywebsitehost.rtp.raleigh.ibm.com

ACTIVE_DIRECTORY_DOMAIN_NAME = AUSTIN.IBM.COM

your_spnuserpassword = Existing password that used by this account spnliberty

cipher = encryption type AES256-SHA1 that is used by the Kerberos client

ktpass -princ HTTP/mywebsitehost.rtp.raleigh.ibm.com@AUSTIN.IBM.COM -ptype KRB5_NT_PRINCIPAL -mapUser spnliberty -mapOp set -pass password -out krb5.keytab -crypto AES256-SHA1

image-20190903094459-5

In the above command -mapOp set Flush other Service Principal Names that are associated with the user and set the one provided by -princ

image-20190903094459-6

More details, see the following Microsoft link.

https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/ktpass

Kerberos Encryption Type Details

image-20190916082643-1

If your Microsoft setspn command version supports the -X option to search for a duplicated SPN, then use setspn -X will check entire Domain.

image-20190903094459-7

2. Set up Kerberos configuration file.

Kerberos configuration file contains client configuration information.

default_realm: Identifies the Kerberos realm for the client

default_keytab_name: Provides the file system location of the Kerberos keytab file

default_tgs_enctypes: Identifies the supported list of session key encryption types that the client should request when making a TGS-REQ

default_tkt_enctypes: Identifies the supported list of session key encryption types that the client should request when making an AS-REQ

kdc : Specifies a list of the hostname of the Kerberos Key Distribution Center (KDC) for this realm and port number

domain_realm: This section provides a translation from a domain name or hostname to a Kerberos realm name.

The following example file is set up for using domain and realm settings. For windows default file name is krb5.ini and on Unix platforms file name is krb5.conf.

image-20190903094459-8

3. Deploy the sample application libertyDefaultApplication in Liberty.

I am providing a sample application called libertyDefaultApplication.ear.

Click here to download the SAMPLE application ==> libertyDefaultApplication.ear

Deploying libertyDefaultApplication in Liberty Server

Place this libertyDefaultApplication.ear under the dropins folder, ${server.config.dir}/dropins (that is, wlp/usr/servers/server_name/dropins). By default, the dropins directory is automatically monitored. If you drop an application into this directory, the application is automatically deployed on the server.

image-20190903094459-9

Add the following line to the server.xml file

<feature>appSecurity-2.0</feature>

<applicationManager autoExpand="true"/>

When you add the appSecurity-2.0 feature to your server, you need to configure a user registry (LDAP or Federated Repository) This feature support for securing the server runtime environment and applications. This feature enables servlet-3.0 and web application security, support for LDAP and basic user registries, and SSL.

4. Configure LDAP user registry and SPNEGO authentication in Liberty.

Add the ldapRegistry-3.0 Liberty feature to the server.xml file. This will enable the LDAP User Registry feature.

<feature>ldapRegistry-3.0</feature>

To configure an LDAP in Liberty, you need the following information.

1. Host name of the AD server

2. LDAP port of AD server (typically 389)

3. Bind DN with which WebSphere will connect to query entries.

4. Bind password corresponding to DN.

5. The search base under which all users exist.

6. Configuring the LDAP filter.

<ldapRegistry id="ldap" realm="myldap.austin.ibm.com:389"
   host="myldap.austin.ibm.com" port="389" ignoreCase="true"
   baseDN="DC=AUSTIN,DC=IBM,DC=COM"
   bindDN="CN=wasadmin,CN=IBMSecurity,Ou=Techspport,DC=AUSTIN,DC=IBM,DC=COM"
   bindPassword="password"
   ldapType="Microsoft Active Directory">
   <activedFilters
   userFilter="(&(|(sAMAccountName=%v)(displayName=%v))(objectclass=user))"
   groupFilter="(&(cn=%v)(objectcategory=group))"
   userIdMap="user:sAMAccountName"
   groupIdMap="*:cn"
   groupMemberIdMap="memberOf:member" >
</activedFilters>
   </ldapRegistry>

5. Enable SPNEGO authentication in Liberty.

Add the spnego-1.0 Liberty feature to the server.xml file.

<feature>spnego-1.0</feature>

Here is a sample configuration in server.xml that changes the default <spnego> settings

Example for the LDAP registry and SPNEGO authentication from the Liberty server.xml file.

image-20190903094459-10

6. Configure IE and Firefox browser.

Microsoft Internet Explorer:

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

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

c. Select the Local intranet icon and click Sites.

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.

d. In the Local intranet window, complete the Add this website to the zone field with the web address of the hostname so that single sign-on (SSO) can be enabled for the list of websites that are shown in the websites field.

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

f. Click OK. Restart your Microsoft Internet Explorer to activate this configuration.

image-20190903094459-11

Mozilla Firefox:

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

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

c. In the Filter/Search box, type network.n.

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

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

image-20190903094459-12

g. Click OK. The configuration reflects the updates.

h. Restart your Firefox browser to activate this configuration.

7. Test the snoop application to validate the spnego.

To confirm whether SPNEGO is working correctly at the Liberty server by accessing the snoop servlet using the Web browser on client desktop that logged in to the Windows Active Directory domain. The snoop servlet that deployed on Liberty server’s application will retrieve information about a servlet request. If Liberty Security is enabled, then the users must authenticate with the server to initiate the servlet. If SPNEGO is configured and working correctly in liberty server, then the user is automatically logged in by using a SPNEGO token without prompting for credentials. If SPNEGO is working, you should see the following information.

image-20190903094459-13

image-20190903094459-14

8. How to debug the Spnego problem by using traces.

Add the following string to the <logging> element in the server.xml file:

com.ibm.ws.security.*=all:com.ibm.ws.webcontainer.security.*=all:com.ibm.websphere.wim.*=all:com.ibm.wsspi.wim.*=all:com.ibm.ws.wim.*=all

image-20190903094459-15

Insert the following generic JVM arguments in the jvm.options file:

-Dcom.ibm.security.jgss.debug=all
-Dcom.ibm.security.krb5.Krb5Debug=all

image-20190903094459-16

image-20190903094459-17

How can I find in the traces has spnego debug property is enabled?

In the traces file search for JGSS_ you will see the following message

image-20190903094459-18

Document Location

Worldwide

[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSD28V","label":"WebSphere Application Server Liberty Core"},"Component":"spnego","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF043","label":"Red Hat"},{"code":"PF033","label":"Windows"}],"Version":"All versions","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Tips

How to Setup Single Sign-On (SSO) for HTTP requests using SPNEGO authentication in Liberty