Configuring Microsoft Windows single sign-on on IBM WebSphere and Domino platforms

Introduction

Microsoft® Windows® single sign-on (SSO) allows the client in an Active Directory domain to be authenticated with the server, without being prompted for a user name and password, by leveraging Simple and Protected GSS-API Negotiation Mechanism (SPNEGO).

As of WebSphere® Application Server version 6.1, WebSphere provides the native support for Windows SSO by SPNEGO trust association interceptor (TAI). In version 7.0, WebSphere introduced better support for Kerberos, including the Kerberos mechanism for server-to-server authentication, as well Kerberos Web Authenticator.

As of version 8.5.1, Lotus Domino also started to support Windows SSO, though only on the Windows platform. In this article we introduce the Windows SSO configuration process on both the WebSphere and Domino platforms.

Common configurations

Windows SSO is based on Kerberos/SPNEGO protocols, and there are some steps we need to do on Kerberos before configuring either WebSphere Application Server or Lotus Domino. These common configurations include time synchronization and register service principal names (SPN) for the Web application.

Time synchronization

Timestamp is a critical factor in Kerberos authentication, and Kerberos requires the clocks of the involved hosts to be synchronized. Thus, the time of WebSphere Application Server or Domino in the SSO domain must be synchronized with the domain controller; otherwise, the Kerberos authentication will probably fail.

You can use the domain controller as the time server and run the Windows schedule task on all participating nodes to synchronize the time with the domain controller. For more information about how to use the domain controller as the time server, refer to the Microsoft Support document, “How to configure an authoritative time server in Windows Server.” For more information about running the Windows schedule task, see “Time synchronization may not succeed when you try to synchronize with a non-Windows NTP server in Windows Server 2003.”

For example, if lotus.ibm.com is both the domain controller and the Network Time Protocol (NTP) time server, then the TimeSyn.bat file would contain the following commands:

w32tm /config /manualpeerlist:lotus.ibm.com,0x8 /syncfromflags:MANUAL net stop w32time net start w32time w32tm /resync

Register SPN for Web applications

An SPN uniquely identifies a service in the Kerberos environment, and you must create an SPN to identify the Web application you want to enable with Windows SSO.

An SPN is typically composed of a service name, a fully qualified host name, and a realm name, for instance HTTP/lotus.ibm.com@IBM.COM. For Web applications, the service name is always HTTP. To register an SPN for the application, perform the following steps:

1. Log in to the Windows Domain Controller. You must know which server is the domain controller and have an administrative-level user name and password.
2. In Active Directory Users and Computers settings, select Action – New – User, to create a new service account that holds the SPN.
3. In the New Object - User window, enter an account name into the User logon name field and specify the domain in the corresponding field. For example, in the User logon name field, you could add appuser01, and in the domain field, you could select @ibm.com. Click Next.
4. Enter a password for the account in the Password field and Confirm password.
5. Select the User cannot change password and Password never expires check boxes. By preventing the password from expiring, you avoid having to recreate the keytab file (which you do in the next step) after the password is changed. Click Next and Finish, to save the new user information.
6. Map the SPN to the user account you just created, and then generate a keytab file by running the ktpass command on the domain controller. To run the ktpass utility, you must have Windows Support Tools installed (refer to Install Windows Support Tools for more details). Run the ktpass command as follows:

ktpass –princ <SPN> -out <path_to_keytab> -mapuser <account_name> -mapOp set –pass <account_password>

where you provide values for the following variables:

• <SPN>: The Kerberos SPN, which is composed of the “HTTP/” prefix and host name through which your Web application is accessed. Note that, in a network deployment, if your Web application is accessed via the IBM HTTP server, you should specify the host name of the HTTP server in SPN.
• <path_to_keytab>: File path in which you want to store the generated keytab file.
• <account_name>: The service account name you created in the previous step.
• <account_password>: Password associated with the service account. Note that, if you are configuring Windows SSO on WebSphere Application Server, you may optionally use the -rndPass option of ktpass utility, to generate a random password for better security.

For example:

ktpass -princ HTTP/lotus.ibm.com@IBM.COM -out c:\keytab 

-mapuser appuser01 -mapOp set -pass mypassword

You will need the keytab file when configuring Windows SSO for WebSphere Application Server.

Configuring SSO on WebSphere Application Server

In this section we describe the steps to enable Windows SSO on WebSphere Application Server, covering the configurations for both WebSphere Application Server V6.1 and V7.0. Because WebSphere Application Server is based on Java^TM Virtual Machine (JVM), the configuration process includes the steps to enable JVM with Kerberos and the WebSphere-specific configuration for inbound Web requests.

Create a Kerberos configuration file

To enable the JVM in WebSphere Application Server with Kerberos capabilities, you must create a Kerberos configuration file, which is normally named krb5.conf. The wsadmin utility in WebSphere Application Server can help you create this file.

NOTE: If you are in a network deployment environment, once you generate the configuration file, you must copy the configuration file to \java\jre\lib\security\krb5.conf on all servers in the cell.

On the wsadmin command line, enter the following command:

$AdminTask createKrbConfigFile 

{    

-krbPath <appserver>\java\jre\lib\security\krb5.conf 

-realm <REALM> 

-kdcHost <kdc_hostname> 

-dns <dns_hostname> 

-keytabPath <path_to_keytab>

}

where you provide values for the following variables:

• <appserver>: The path to the WebSphere Application Server root directory. The krbPath parameter defines where the resulting krb5.conf configuration file is stored. It is recommended to use \java\jre\lib\security\krb5.conf, as it is the default location for krb5.conf. However, if you want to use a non-default location for the krb5.conf file, you MUST specify a java.security.krb5.conf custom property for each JVM in the WebSphere Application Server cell.
• <REALM>: The Kerberos realm. Specify the realm in all uppercase letters.
• <kdc_hostname>: The name of the Active Directory key distribution center host. This name is typically the domain controller server.
• <dns_hostname>: The DNS server name of the domain controller server.
• <path_to_keytab>: The path to the keytab file. If you are in a network deployment environment, after you have generated the keytab, you must copy the keytab file to the same location on all servers in the cell, or use a unified path that points to a shared location on the network.

Listing 1 shows a sample configuration file.

Listing 1. Sample configuration file

[libdefaults]

default_realm = IBM.COM

default_keytab_name = FILE:C:\keytab

default_tkt_enctypes = des-cbc-md5 rc4-hmac

default_tgs_enctypes = des-cbc-md5 rc4-hmac

kdc_default_options = 0x54800000

# forwardable  = true

# proxiable  = true

# noaddresses = true

[realms]

IBM.COM = {

kdc = ibm.com:88

default_domain = ibm.com

}

[domain_realm]

.lotus.ibm.com = IBM.COM

Once the krb5.conf file is ready, you must restart WebSphere Application Server, to pick up the configurations and enable the underlying JVM with Kerberos capabilities. To verify the Kerberos configurations, type the following command to determine whether it can successfully get the Kerberos ticket:

<appserver>/java/jre/bin/kinit -k HTTP/lotus.ibm.com@IBM.COM

Create an HTML page

There are cases in which SPNEGO is not supported by browsers, or the clients have not logged into the Active Directory domain. In those cases, it is commonly desired that users can still log into the Web application with their user name and password via traditional form-based authentication.

Listing 2 shows a static HTML file that is used to redirect users whose Web browsers do not support SPNEGO to a non-SPNEGO-protected page that asks for authentication credentials. You should store the HTML file on a public place that is accessible to all the servers in the cell.

Listing 2. HTML file to redirect users

<!DOCTYPE HTML PUBLIC "-//W3C/DTD HTML 4.0 Transitional//EN">

<META HTTP-EQUIV="Content-Type" CONTENT="text/html">

<!--

Notes:

- This file should be served from an unprotected Web site. Alternatively, 

it can be loaded from the WebSphere Application Server file system.

- Any embedded graphics/javascript/css MUST BE loaded from an unprotected 

Web site.

- This file will be loaded after when the WebSphere Application Server is 

initialized. If changes to this file are necessary, the Application Server 

should be restarted.

- This file is returned whenever the SPNEGO TAI receives an NTLM 

token for ANY application in the cell. In other words, this file is 

generic for all applications. However, by using the JavaScript 

document.location, we can get the original URL, and redirect to that 

original URL with the "?noSPNEGO" text added - thus forcing the standard 

application userid/password challenge.

-->

<html>

<script language="javascript">

var origUrl=""+document.location;

if (origUrl.indexOf("noSPNEGO")<0) {

if (origUrl.indexOf('?')>=0) origUrl+="&noSPNEGO";

else origUrl+="?noSPNEGO";

}

function redirTimer() {

self.setTimeout("self.location.href=origUrl;",0);

}

</script>

<META HTTP-EQUIV = "Pragma" CONTENT="no-cache">

<script language="javascript">

document.write("<title> Redirect to "+origUrl+ " </title>"); 

</script>

<head>

</head>

<body onLoad="redirTimer()"/>

</html>

Enable SPNEGO TAI (version 6.1 only)

In WebSphere Application Server 6.1, SPNEGO TAI is used to perform the SPNEGO authentication. Perform the following steps to enable SPNEGO TAI in WebSphere Application Server:

1. Log into the WebSphere Application Server Integrated Solutions Console, if you have a standalone deployment, or into the Deployment Manager, if you have a network deployment.
2. Add custom properties to the Web Security settings by completing the following steps:

1. Expand Security and then select Secure administration, applications, and infrastructure. Expand Web Security, and then click Trust association.
2. Select Enable trust association.
3. Select Interceptors – com.ibm.ws.security.spnego.TrustAssociationInterceptorImpl – Custom properties.
4. Click New, to add each property, and then enter the details of the following properties:

com.ibm.ws.security.spnego.SPN1.hostName=<hostname> 

com.ibm.ws.security.spnego.SPN1.NTLMTokenReceivedPage=<TAIRedirectPage_location> 

com.ibm.ws.security.spnego.SPN1.spnegoNotSupportedPage=<TAIRedirectPage_location> 

com.ibm.ws.security.spnego.SPN1.filter=request-url!=noSPNEGO;<other_product_specific_filters>

com.ibm.ws.security.spnego.SPN1.filterClass=com.ibm.ws.security.spnego.HTTPHeaderFilter 

where

<hostname>: Name of the server from which your Web applications are accessed. It should be the same as the hostname used in the SPN.

<TAIRedirectPage_location>: File path to the HTML redirect file that you created in the previous step. The path should always start with file://. For example, file:///c:/share/TAIRedirect.html.

e. Click OK and then Save, to save each new custom property.

3. From the main Integrated Solutions Console, expand Servers, and then select Application servers.
4. Click the server name (for example, server1), expand Java and Process Management, and then select Process Definition – Java Virtual Machine – Custom Properties.
5. Add the custom property, com.ibm.ws.security.spnego.isEnabled = true.
6. Click OK and then Save, to save the custom property.
7. Repeat steps 3 through 6 for each server in the WebSphere Application Server cell.

Enable SPNEGO Web Authenticator (version 7.0 only)

SPNEGO Web Authenticator was introduced in WebSphere Application Server version 7.0 as the successor to SPNEGO TAI. Although SPENGO TAI still works, it is recommended to move to the SPNEGO Web Authenticator as it expand the capability of SPNEGO TAI.

To configure SPNEGO Web Authenticator, perform these steps:

1. Log in to the WebSphere Application Server Integrated Solutions Console if you have a standalone deployment, or into the Deployment Manager, if you have a network deployment.
2. Expand Security, select Global Security, and in the Authentication section, expand Web and SIP Security, and click SPNEGO Web authentication.
3. In the SPNEGO filter section, click New, to create a new filter and specify the following properties:

1. In the Host name field specify the name of the server from which your Web applications are accessed. It should be the same as the one used in SPN.
2. In the Kerberos realm name field specify the Kerberos realm name, for instance IBM.COM.
3. In the Filter criteria field specify request-url!=noSPNEGO;. Specific Lotus products might have different filter configurations.
4. In the Filter class field enter com.ibm.ws.security.spnego.HTTPHeaderFilter.
5. In the SPNEGO not supported error page URL and NTLM token received error page URL fields specify the shared location of the static HTML page created in Section 3.2 above. Note that the page URL should start with file://.
6. Put a check mark in the Trim Kerberos realm from principal name and Enable delegation of Kerberos credentials check boxes.

4. Click OK and Save, to save the new filter.
5. On the SPNEGO web authentication page, select the Dynamically update SPNEGO, Enable SPNEGO, and Allow fall back to application authentication mechanism check boxes.
6. In the Kerberos configuration file with full path field, specify the location of krb5.conf that was generated in Section 3.1 above.
7. You can leave the Kerberos keytab file name with full path field blank, to use the default keytab specified in krb5.conf, or specify the location of the keytab file generated in Section 2.2.

Authenticate on an unprotected URI (optional)

By default, SPNEGO TAI and SPNEGO Web Authenticator will authenticate the user once a URI is accessed, regardless of whether it requires authenticated access or not. However, in many cases, it is desirable to authenticate only when needed; for instance, when a user requests a protected page or resource.

The steps below describe how to avoid SPNEGO authentication on an unprotected URI by setting the performTAIForUnprotectedURI custom property.

To set a custom property that disables SPNEGO-TAI authentication when an unprotected URI is accessed in WebSphere Application Server 6.1:

1. Select Security – Secure administration, applications, and infrastructure – Custom properties.
2. Click New and enter the custom property:

com.ibm.websphere.security.performTAIForUnprotectedURI=false

3. Click OK and then click Save, to save the new property.

NOTE: This configuration works only from WebSphere Application Server version 6.1.0.21. Refer to IBM Support document #PK64013 for more detailed information.

To set a custom property that disables SPNEGO-TAI authentication when an unprotected URI is accessed in WebSphere Application Server 7.0:

1. Select Security – Global Security – Custom properties.
2. Click New and enter the custom property:

com.ibm.websphere.security.performTAIForUnprotectedURI=false

3. Click OK and then click Save, to save the new property.

NOTE: This configuration works only from WebSphere Application Server version 7.0.0.13. See IBM Support document #4027626 for more details.

Generate SPN for WebSphere Application Server (version 7.0 optional)

A Kerberos authentication mechanism for server-to-server communication was introduced in WebSphere Application Server 7.0. Although most of time Kerberos authentication is not required, we believe it is a good practice, to achieve a more secure deployment.

Below are the instructions to enable Kerberos authentication for server-to-server communications. The steps are generally the same as generating an SPN for WebSphere applications.

1. Log in to the Windows Domain Controller. You must know which server is the domain controller and have an administrative-level user name and password.
2. In Active Directory Users and Computers settings, select Action – New – User, to create a new service account that holds the SPN.
3. In the New Object - User window, enter an account name in the User logon name field and specify the domain in the corresponding field. For example, in the User logon name field, you could add wasuser01, and in the domain field, you could select @ibm.com. Click Next.
4. Enter a password for the account in the Password field and Confirm password.
5. Select the User cannot change password and Password never expires check boxes. By doing this, you avoid having to recreate the keytab file (which is done in the next step) after the password is changed. Click Next and Finish, to save the new user information.
6. Map the SPN to the user account you just created, and then generate a keytab file by running the ktpass command on the domain controller. To run ktpass command you must have Window Support Tools installed (refer to Install Windows Support Tools for more details). Run the ktpass command as follows:

ktpass –princ <SPN> -out <path_to_keytab> -mapuser <account_name> -mapOp set –pass <account_password>

where you provide values for the following variables:

• <SPN>: The Kerberos SPN for WebSphere Application Server, which is composed of the “WAS/” prefix and the host name of WebSphere Application Server in the cell.
• <path_to_keytab>: File path in which you want to store the generated keytab file.
• <account_name>: The service account name you created in the previous step.
• <account_password>: Password associated with the service account.

7. Repeat steps 2 through 6 for all WebSphere Application Server instances in the cell; you will get one keytab file for each WebSphere Application Server.
8. Merge all the generated keytabs into one keytab file created in the previous steps, using the ktab utility provided in JVM:

<appserver>/java/jre/bin/ktab -m <generated-keytab> <keytab-destination>

9. Once you merge the keytabs, use the klist utility to list the merged keytab file and verify whether all the merged keytab entries are shown in the output.

<appserver>/java/jre/bin/klist -k

10. If you are in a network deployment environment, once you merge the keytab, you must copy the merged keytab file to the same location on all servers in the cell, which will override the original keytab file created in Section 2.2.

Enable WebSphere Application Server for Kerberos (version 7.0 optional)

Beginning in WebSphere Application Server version 7.0, SPNEGO can be used for communications between the Deployment Manager and server nodes in WebSphere Application Server cells. It is a suggested configuration, and is not necessary in all deployments. To do this:

1. Log in to the WebSphere Application Server Integrated Solutions Console, if you have a standalone deployment, or the Deployment Manager, if you have a network deployment.
2. Expand Security, select Global Security, and click Kerberos configuration in the Authentication section.
3. In the Kerberos Authentication Mechanism section, specify the following:

1. In the Kerberos service name field, enter WAS as the service name, which is the default value.
2. In the Kerberos configuration file with full path field, specify the location of the krb5.conf that was generated in Section 3.1 above.
3. Leave the Kerberos keytab file name with full path field blank, to use the default keytab specified in krb5.conf, or specify the location of the keytab file generated in Section 3.6 above.
4. Place a check mark in the Trim Kerberos realm from principal name and Enable delegation of Kerberos credentials check boxes.
5. In the Kerberos realm name field, specify the Kerberos realm name, for instance IBM.COM. Click OK and Save, to save the changes.

4. In the Authentication section, click Kerberos and LTPA, if it is not already selected. Then click Apply.

Configuring on Lotus Domino

In this section, we introduce the steps to enable Windows SSO on Windows Domino as well as the Windows SSO solution for non-Windows Domino.

NOTE: Before configuring Windows SSO on Lotus Domino, make sure you have configured SSO based on Ltpa Token. For more details, refer to the wiki article titled, “Configuring single sign-on with an LTPA token on IBM WebSphere and IBM Lotus Domino platforms.”

Enable Windows SSO on Lotus Domino

In Lotus Domino, once you have configured SSO, you can quite easily enable Windows SSO in the Web SSO Configuration document, using these steps:

1. In the Domino Directory, select Configuration – Web – Web Configurations.
2. Double-click the Web SSO Configuration document, for example, Web SSO Configuration for LtpaToken.
3. In the Basic tab, set the Windows single sign-on integration (if available) option to be Enabled.
4. Click Save and Close to save the configurations.

Run Domino server with specific account

To successfully validate the Kerberos service tickets, the Domino server must be able to obtain the credential for the SPN generated for the Domino Web service, which means that the Domino server process must be run with the account that holds the SPN.

This is quite different from WebSphere Application Server, which uses a keytab file to hold the credential instead of retrieving it from runtime. There are two ways to achieve this. If your Domino server is registered as a Windows service:

1. In Windows, select Start – Control Panel – Administrative Tools – Services.
2. In the Windows services list, locate Lotus Domino Server, and double-click it to open the Properties dialog box.
3. In the Log on tab, specify the account that was chosen to hold the SPN in the previous steps and the password to that account.
4. Click OK to save the change and restart the Domino service.

Another option is to log in to Windows, using the account that was chosen to hold the SPN, and start the Domino service.

Mapping Kerberos log-on name to a Notes user (optional)

When configuring Windows SSO on Domino, normally you can opt to use Active Directory as the LDAP service for Domino using Directory Assistance; however, it is not a must. You can also use the Domino directory to map the Kerberos log-on name to a Notes user.

To enable the mapping, perform the following steps:

1. In the Domino Directory, select People – By Organization.
2. Select the Notes user from the right-hand-side list and click Edit Person.
3. On the Administration tab, specify the Active Directory (Kerberos) logon name for this Notes user, in the Client Information section.
4. Click Save & Close to save the changes.
5. Repeat Steps 1—4 for all users in the Domino Directory who have a Kerberos logon name.
6. Create a full-text index for the Domino Directory, to optimize searches of the Active Directory (Kerberos) logon name field.
7. Open the Notes.ini file in the Domino data directory and add WIDE_SEARCH_FOR_KERBEROS_NAMES=1 at the end of the configuration file.

NOTE: In this case, you SHOULD NOT enable Active Directory in Domino directory assistance.

Configure Windows SSO for non-Windows Domino (optional)

Due to the mechanism Domino used to retrieve service credentials, Windows SSO only works for Domino on the Windows platform. However, there is an open source project on www.openntf.org that provides a way to configure Windows SSO for non-Windows Domino.

The basic steps include enabling SSO between Windows Domino and non-Windows Domino, redirecting authentication requests to Windows Domino for Windows SSO, and then redirecting the requests back to non-Windows Domino. By this means, non-Windows Domino provides the Windows SSO capability by leveraging the capability on Windows Domino.

You can access the project, “SSO for Web for non Windows Servers,” for detailed information and instructions.

Browser configurations

For successful Windows SSO, users not only need to log in to the Active Directory domain but also need to enable the Windows SSO feature on their browsers. Below are the configuration instructions for both Microsoft Internet Explorer and Mozilla Firefox.

Microsoft Internet Explorer

1. From the Internet Explorer menu, select Tools – Internet Options, and then click the Security tab.
2. Click the Local intranet icon, and then click Sites.
3. Click Advanced, and then add the Web address of the host name of your Web applications –- typically the host name of HTTP server -– into the Add this website to the zone field. For example, *.enterprise.example.com.
4. Click OK to save the change and return to the main Security page.
5. Click Custom level, scroll to find User Authentication – Logon, and then select Automatic logon only in Intranet zone. Click OK to save the change and return to the main Security page.
6. On the Advanced tab, scroll to find Security, and then select Enable Integrated Windows Authentication. Click OK to save the change.
7. Restart the Web browser to apply the configuration changes.

Mozilla Firefox

Use the following steps to add the Web address of your Web application to the list of sites that are permitted to engage in SPNEGO authentication with the browser:

1. Open Firefox, and then type about:config in the location bar.
2. Type network.n into the Filter field, double-click network.negotiate-auth.trusted-uris, and then type the protocol and host name of the server that hosts your Web application. For example, http://enterprise.example.com, or https://enterprise.example.com, if you want to use HTTPS. To specify more than one server, separate them with a comma.
3. Click OK to save the change.
4. If the deployed SPNEGO solution is using the advanced Kerberos feature of Credential Delegation, double-click network.negotiate-auth.delegation-uris. This preference defines the sites for which the browser can delegate user authorization to the server. Enter a comma-delimited list of trusted domains or URLs.
5. Restart Firefox to apply the configuration change.

Conclusion

In this article we introduced the Windows SSO configurations on both WebSphere Application Server and Lotus Domino. The configurations include the common steps for Kerberos of time synchronization and SPN registration, and the platform-specific configurations owing to the different approaches that WebSphere and Lotus Domino use SPN credentials.

For WebSphere, the keytab file and krb5.conf file are used to enable JVM with Kerberos capabilities, and for Lotus Domino, the Domino server is run with the account under which the SPN is registered. Also included were some optional configurations that might be helpful to fulfill the requirements in your specific deployment. To incorporate with the Web server, we also provided the client browser configurations for successful Windows SSO.