You can use single sign-on for HTTP requests by using the Simple and Protected GSS-API
Negotiation Mechanism (SPNEGO) web authentication for WebSphere® Application Server Liberty. SPNEGO single sign-on enables HTTP users
to log in to a Microsoft® domain controller only once at their desktop and to achieve single sign-on
(SSO) with the Liberty server.
Before you begin
Configure the following software and ensure that it is available:
- A Microsoft Windows® Server running an Active
Directory Domain Controller and associated Kerberos Key Distribution Center (KDC). For this topic,
an example host for such a domain controller is myAdMachine.example.com. The domain
controller name is mydomain.example.com and the Kerberos realm name is
MYDOMAIN.EXAMPLE.COM, which is the domain controller name in all uppercase
letters.
- A Microsoft Windows® domain member (client) that
supports the SPNEGO authentication mechanism as defined in IETF RFC 2478. Examples of an appropriate
client might be a modern browser or a Microsoft .NET
client. Most modern browsers support SPNEGO authentication. For this topic, an example host for the
client is myClientMachine.example.com.
- A server platform with a Liberty server
that has a protected resource within an application. Users in the Active Directory must be able to
access Liberty server protected resources by
using a native Liberty server authentication
mechanism. For this topic, an example Liberty
server host is myLibertyMachine.example.com.
Note: The software configuration must have a running domain controller, at least one client
machine in that domain and a server platform with a Liberty server that has a protected resource
within an application, for a total of three required machines. Using SPNEGO directly from the domain
controller is not supported.
Note: Ensure the clocks for the client, Microsoft Active Directory server, and Liberty server are synchronized to within 5
minutes of each other, by default. The allowable difference in synchronization is
configurable.
Note: Only IBM® JDKs are supported
currently. Non-IBM JDKs are not supported.
About this task
The objective of this task is to allow users to successfully access Liberty server resources without having to
authenticate again, and thus achieve Microsoft Windows®
desktop single sign-on capability.
This task demonstrates how to configure a Liberty server to support single sign-on for HTTP
requests by using SPNEGO web authentication.
Procedure
- On the Microsoft domain controller
(myAdMachine.example.com), create a Kerberos service principal name (SPN) and
keytab file for the Liberty server:
- Create a user account for the Liberty
server. This account is used to map to the Kerberos service principal name (SPN). For Active
Directory machines, this account creation can typically be done by going to , right-clicking on Users in the panel, and selecting . This topic assumes that the user myLibertyMachine_http is created
with password security.
- Run the Microsoft
setspn command to map the user account to a Kerberos SPN. This user account
represents the Liberty server as being a
Kerberos service with the KDC. An example of the setspn
command:
C:\> setspn -a HTTP/myLibertyMachine.example.com myLibertyMachine_http
Registering ServicePrincipalNames for CN=myLibertyMachine_http,CN=Users,DC=MYDOMAIN,DC=EXAMPLE,DC=COM
HTTP/myLibertyMachine.example.com
Updated object
Note: If
your Microsoft
setspn command version supports the -S option, then you must use
the -S option instead of -A.
- Create the Kerberos keytab file by using the Microsoft
ktpass tool. The default name for this file is
krb5.keytab.
An example of the ktpass command:
C:\> ktpass -out krb5.keytab -princ HTTP/myLibertyMachine.example.com@MYDOMAIN.EXAMPLE.COM -mapUser myLibertyMachine_http -mapOp set -pass security -crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL
Targeting domain controller: myAdMachine.MYDOMAIN.EXAMPLE.COM
Using legacy password setting method
Successfully mapped HTTP/myLibertyMachine.example.com to myLibertyMachine_http.
Key created.
Output keytab to krb5.keytab:
Keytab version: 0x502
keysize 93 HTTP/myLibertyMachine.example.com@MYDOMAIN.EXAMPLE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 3 etype 0x17 (RC4-HMAC) keylength 16 (0x148d643db283327d3f3d44547da8cade)
Make sure that there is not a duplicated SPN in the Microsoft forest by using one of these commands:
- If your Microsoft
setspn command version supports the -X option to search for a
duplicated SPN, then use setspn
-X:
C:\>setspn -X HTTP/myLibertyMachine.example.com
Processing entry 0
found 0 group of duplicate SPNs.
- You can also use the Microsoft
ldif command. The following example shows that one entry was returned, meaning
there is not a duplicated
SPN.
C:\>ldifde -f check_SPN.txt -t 3268 -d "" -l servicePrincipalName -r "
(servicePrincipalName=HTTP/myLibertyMachine.example.com)" -p subtree
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
For information on creating SPNs and keytab files on different KDC systems, see Creating a Kerberos service principal name and keytab file.
- On the Liberty server machine
(myLibertyMachine.example.com), enable the Kerberos keytab and configuration files
and SPNEGO web authentication.
- Copy the Kerberos keytab file from the domain controller to the Liberty server machine. The default name of this
file is krb5.keytab and the default location varies depending on the platform
but is the same directory as the Kerberos configuration file. For default locations for various
platforms, see the next step.
- Create a Kerberos configuration file.
The Kerberos configuration file contains client configuration information. This information
includes the locations of KDCs for the realms of interest, defaults for the current Kerberos realm,
and mappings of host names onto Kerberos realms. For Liberty servers, you must create this file
manually.
Here is a sample Kerberos configuration file for the AIX,
z/OS, HP-UX, or Solaris platforms (based on the default
keytab location):
[libdefaults]
default_realm = MYDOMAIN.EXAMPLE.COM
default_keytab_name = FILE:/etc/krb5/krb5.keytab
default_tkt_enctypes = rc4-hmac
default_tgs_enctypes = rc4-hmac
forwardable = true
renewable = true
noaddresses = true
clockskew = 300
udp_preference_limit = 1
[realms]
MYDOMAIN.EXAMPLE.COM = {
kdc = myAdMachine.example.com:88
default_domain = example.com
}
[domain_realm]
.example.com = MYDOMAIN.EXAMPLE.COM
Note: Realm names are usually specified in uppercase letters. If you are using Microsoft Active Directory, realm names are must be uppercase.
Note: Not all of the KDC solutions available support all encryption types. Before you choose an
encryption type, ensure that the KDC supports the encryption type that you want to use by consulting
your Kerberos Administrator's and User's Guide.
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 also support the
RC4-HMAC encryption type and the Kerberos configuration file must list
RC4-HMAC first in the default_tgt_enctypes and
default_tkt_enctypes parameters.
For additional information and requirements on the content of this file, see Creating a Kerberos configuration file.
- Verify the Kerberos configuration and keytab files.
After the kinit command, you can use the klist command to
list the Kerberos ticket. If you get the Kerberos ticket, then the Kerberos keytab and configuration
are valid.
- Configure and enable SPNEGO web authentication on the Liberty server.
You can enable SPNEGO web authentication by enabling the spnego-1.0 feature of
Liberty.
- Add the spnego-1.0 feature to the server.xml
file.
<featureManager>
<feature>spnego-1.0</feature>
<feature>appSecurity-2.0</feature>
...
</featuremanager>
Adding
the spnego-1.0 feature automatically enforces a certain minimum configuration. You
do not need to specify a <spnego> element in the
server.xml file. Without specifying a <spnego> element,
the following configuration is
implicit.
<spnego
canonicalHostName="true"
disableFailOverToAppAuthType="true"
trimKerberosRealmNameFromPrincipal="true"
includeClientGSSCredentialInSubject="true" />
Note: The
runtime forms the default SPN in the following
format:
"HTTP/" + java.net.InetAddress.getLocalHost().getCanonicalHostName();
If
the default SPN does not match what you have in the krb5.keytab file, then you
need to specify the servicePrincipalNames, for
example:
<spnego id="mySpnego" servicePrincipalNames="HTTP/myLibertyMachine.example.com"/>
Note: When
the spnego-1.0 feature is enabled and the <spnego> element
is either omitted or not configured with an authFilterRef attribute, all requests
to access protected resources use SPNEGO authentication.
For more information on
configuring the authentication filter, see Authentication Filters.
Note: When values for the krb5Config or
krb5Keytab attributes are not given, each respective file is expected to exist at
its default location. The default locations for the Kerberos configuration and keytab files on
various platforms are given earlier in this example.
- Optional: Specify any additional configuration options as necessary. The Liberty supports many common SPNEGO scenarios and
configurations. For example, you can filter HTTP requests to require SPNEGO authentication for only
certain requests, web applications, hosts, or user agents. Also, you can move the Kerberos
configuration and keytab files away from their respective default locations. Here is a sample
configuration that changes the default <spnego>
settings:
<server>
<featureManager>
<feature>spnego-1.0</feature>
<feature>appSecurity-2.0</feature>
...
</featureManager>
...
<authFilter id="myAuthFilter">
<host id="myHost" name="example.com" matchType="contains" />
<webApp id="myWebApp" name="protectedApp" matchType="equals" />
</authFilter>
<spnego id="mySpnego"
includeClientGSSCredentialInSubject="false"
krb5Config="${server.config.dir}/resources/security/kerberos/krb5.conf"
krb5Keytab="${server.config.dir}/resources/security/kerberos/krb5.keytab"
servicePrincipalNames="HTTP/myLibertyMachine.example.com"
authFilterRef="myAuthFilter" />
</spnego>
...
</server>
With
this configuration, SPNEGO authentication is used for any requests that are received containing the
host name example.com for resources within the web application
protectedApp. In addition, the client's GSS credentials are not added to the user
subject upon successful authentication. Finally, the Kerberos configuration and keytab files to be
used by the server are given specific locations within the server configuration directory instead of
their respective default locations.
For more configuration options, see The Simple and Protected GSS-API Negotiation Mechanism (SPNEGO).
For
information on mapping Kerberos principal names to WebSphere user registry IDs, see Mapping of a client Kerberos principal name to the WebSphere user registry ID.
In the rare event that you wish
to use Kerberos principal names for authorization, see Using Kerberos principal name for authorization with SPNEGO authentication. These steps should be followed only when
necessary and by users who specifically choose not to use the default mapping or JAAS custom login
module mapping.
- Configure the client application on the client application machine
(myClientMachine.example.com).
The following steps must be done only on the client machine. Starting a browser on the Active
Directory machine or Liberty server machine
and performing these steps does not work.
The following steps are for users who are accessing SPNEGO-protected resources from a browser.
You must have a browser installed that supports SPNEGO authentication.
Microsoft Internet Explorer:
- At the desktop, log in to the Windows Active Directory
domain.
- In the Internet Explorer window, click . In the window that is displayed, click the Security tab.
- 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.
- In the Local intranet window, complete the Add this website to the zone
field with the web address of the host name so that single sign-on (SSO) can be enabled for the list
of websites that are shown in the websites field. Your site information technology staff provides
this information. Close the second Local intranet window and click OK to
complete this step and close the Local intranet window.
- On 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 your Microsoft Internet Explorer to activate this configuration.
Mozilla Firefox:
- At the desktop, log in to the Windows Active Directory
domain.
- In the address field in Firefox, type about:config.
- In the Filter/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.
Note: You must set the value for
network.negotiate-auth.trusted-uris.
- 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.
- Click OK. The configuration reflects the updates.
- Restart your Firefox browser to activate this configuration.
Note: The user must be logged in to the domain controller for SPNEGO to work. Using the previous
example machines, a user must log in to the domain controller at
MYDOMAIN.EXAMPLE.COM\username in order for SPNEGO authentication through the
browser to work.
Note: If you are prompted multiple times for a user ID and password, make sure that you enabled
SPNEGO support on your client browser by following the previous instructions. You must also make
sure that the disableFailOverToAppAuthType attribute in the
<spnego> configuration is set to false.
Results
Your Internet browser is now properly configured for SPNEGO authentication. You can use
applications with secured resources that are deployed on
Liberty servers without being prompted for a user
ID and password.
To verify that SPNEGO is working, you can log in to the domain controller and
then access a protected resource on the Liberty server, and because you are logged in to the domain controller, you are not prompted for
credentials. However, if you do not log in to the domain controller and attempt to access a
protected resource, you are prompted for credentials.