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.