The Simple and Protected GSS-API Negotiation (SPNEGO) trust association interceptor (TAI) in IBM WebSphere Application Server V6.1 and in the SPNEGO Web Authentication feature in WebSphere Application Server V7.0 can be a powerful tool for achieving a seamless single sign-on (SSO) environment between Microsoft Windows desktops and WebSphere-based servers. Although the WebSphere Application Server Information Center explains how to configure the SPNEGO TAI in WebSphere Application Server V6.1 and in SPNEGO Web Authentication in WebSphere Version Application Server V7.0, there are key issues that can confuse users of the SPNEGO feature. This article addresses the most commonly asked questions.
You can see the WebSphere Application Server Information Center for complete configuration details and then read this article to learn more about some of the subtleties.
What is SPNEGO?
A Windows desktop, when configured to use an Active Directory (AD) domain, uses a security infrastructure that is at its core Kerberos. Kerberos has long supported distributed authentication and the TAI leverages that function. Microsoft has extended Kerberos with a protocol known as Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) for sharing Windows credentials with Web servers. This protocol permits a client machine and the Web server to negotiate what protocols they will communicate with each other. It also defines a way for the client machine to send verifiable authentication data to the Web server. If the Web server understands the SPNEGO token, then this token is used to implement secure SSO. Thus, the user's identity is negotiated in a secure manner to the Web server. This is what users often experience today when accessing Microsoft's Internet Information Server (IIS). Be aware that SPNEGO supports Active Directory credentials based on Kerberos or on the older style (and less secure) NTLM credentials. IBM's TAI solutions support only the Kerberos based credentials. IBM Tivoli® Access Manager supports both NTLM and Kerberos credentials.
SPNEGO is an internationally recognized standard.
How does SPNEGO fit into WebSphere?
Depending on the version of WebSphere Application Server, there are different ways to implement SSO using SPNEGO. Before mentioning these different approaches, let's introduce some WebSphere Application Server security concepts.
In the most basic case, WebSphere Application Server HTTP clients, such as Web browsers, are limited to either simple authentication mechanisms based upon certificates, or user ID and password challenges, either through a Form login, or through a BasicAuth challenge. WebSphere Application Server's advanced authentication feature known as trust association interceptors (TAIs) makes it possible for WebSphere Application Server to trust a third party that has performed this authentication before it sent the request to WebSphere Application Server.
Essentially, when a request arrives at the application server, the WebSphere Application Server security runtime will ask a TAI to identify the user if an appropriate TAI is available. TAIs are commonly used for integration with authenticating proxies, such as Tivoli Access Manager WebSEAL. Such authenticating proxy servers typically perform their authentication, and then project the user's identity to WebSphere Application Server via their own proprietary mechanism and a corresponding TAI.
WebSphere Application Server V6.1 introduced an authentication model based upon Windows desktop authentication using Kerberos and the SPNEGO protocol. While other authenticating proxies usually achieve single sign-on (SSO) by asking the user to log into the proxy once, and then projecting that identity downstream to every WebSphere Application Server instance, the SPNEGO TAI enables WebSphere Application Server to integrate with a user's Windows domain login, and then invisibly authenticate the user to WebSphere Application Server using the user's Windows credentials. In other words, the user logs on once to his Windows desktop using his Windows domain account and password. Accesses to WebSphere Application Server can result in automatically authenticating the user to WebSphere Application Server by silently asking the browser for his Windows credentials.
WebSphere Application Server V7.0 moved the SPNEGO logic to earlier in the Web authentication process before TAIs are called. It also made the SPNEGO configuration a first class administrative object within the admin console. Many small changes were made during this transition, but at its heart, SPNEGO Web Authentication in V7.0 is very close to its V6.1 TAI counterpart.
Alternatives that support Windows single sign-on with WebSphere Application Server
Users have a number of solution options from IBM that can achieve this integration between Windows and WebSphere Application Server:
- A product solution called IBM Tivoli Access Manager (TAM) V5.1 (and later) includes explicit support for Windows SSO using SPNEGO. TAM works with WebSphere Application Server V5.x and later.
- Users with WebSphere Application Server Version 5.1.1.x and 6.0.x can obtain a custom service offering solution from IBM Software Services for WebSphere (ISSW). This solution comes with the source code, and you maintain the custom code yourself. To obtain more information about the ISSW SPNEGO TAI services offering for WebSphere Application Server V5.1.1 and V6.0, contact IBM Software Services for WebSphere.
- WebSphere Application Server Version 6.1 ships a TAI based upon the ISSW version mentioned above, which is a fully supported product code. However, you do not get the source code with this version.
- WebSphere Application Server V7.0 includes SPNEGO function via a new SPNEGO Web Authentication. (V7.0 still ships, but has deprecated, the SPNEGO TAI.)
This article focuses primarily on the third and fourth options listed above because the issues are similar for both, with occasional information regarding the second option.
How does SPNEGO work in WebSphere Application Server?
This section highlights the key parts of the SPNEGO authentication process.
In this scenario, a user has authenticated to Windows (obtaining Active Directory credentials) and then, using a Web browser client (hereafter called "client"), invokes a Web application, which is deployed on a WebSphere server that supports SPNEGO. The steps of the protocol are as follows:
- The user requests a secured Web resource.
- The server responds with an HTTP challenge response (HTTP 401) containing an
"Authenticate: Negotiate" header.
- The client recognizes the Negotiate header because it has been configured to support "Integrated Windows Authentication".
- The client parses the requested URL for the host name.
- The client requests a Ticket Granting Ticket (TGT) from the Kerberos Authentication Service (AS).
- The client receives a TGT.
- The client requests a Service ticket from the Kerberos Ticket Granting
Service (TGS) for the SPN, for example,
HTTP/serverrc4.ibm.net@ IBM.NET. 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>Note: You must register the SPN with the Kerberos Key Distribution Center (KDC) when configuring the environment.
- The client receives the service ticket.
- The client resends the original request for the secured resource. This time, the user name is contained in the encrypted Kerberos service ticket, encapsulated in a SPNEGO token passed via an HTTP Authorization header.
- The application server sees the HTTP Authorization header with the SPNEGO token. It extracts and decrypts (this validates that it must have come from the TGS) the SPNEGO token to retrieve the user name and this user name is asserted to the server. You may need to map the user name to a principal that is meaningful in the server's registry.
- The server's security system validates the user against its security registry and obtains other security information about the user. The user is logged into the server.
- The server caches this user security information in an in-memory object known as a Java™ Subject to avoid further authentication challenges.
- 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 WebSphere SSO
domain to be sent without a re-authentication needing to occur.
- If the user is authorized to access the resource, the response is an HTTP 200 response, and the requested resource is served.
- If not, an "HTTP 403 Not Authorized" response is sent to the client.
Figure 1 depicts the steps that occur during the scenario described above.
Figure 1. SPNEGO overview
Notice that the user is not prompted to authenticate in this scenario. The client "flows" the user's existing AD credentials to the server. The user's access to the server is via his Windows credentials. The user is never once being presented with a prompt to login to a target WebSphere Application Server server.
Must SPNEGO use Windows?
The rest of the article is deliberately vague in our use of terms. Strictly speaking, there is no requirement for Windows to be used. To be precise:
- WebSphere Application Server definitely does not need to be a Windows server. In fact, when WebSphere Application Server is running on Windows, there are known issues that you need to avoid (we will discuss those in later sections). We have deployed the SPNEGO solutions on real customer environments on most of the available supported WebSphere Application Server platforms.
- The desktop does not need to be a Windows desktop. Any desktop that supports a Kerberos login and whose Web client includes support for the SPNEGO protocol will work. This includes Linux® and Apple® desktops. We have configured SPNEGO solutions for such environments.
- The Information Center states that the Kerberos Key Distribution Center (KDC) and Ticket Granting Servers (TGS) are required to be Windows 2000, Windows 2003, or Windows 2008 servers.
- You do not need to configure the WebSphere registry to be Microsoft Active
Directory via the Lightweight Directory Access Protocol (LDAP). In general, the
user ID obtained from the service ticket is known as the Kerberos
UserPrincipalName. Specifically Microsoft calls it the ClientPrincipalName. This
user ID must map to a meaningful name in the WebSphere Application Server security registry. The
simplest mapping is where the WebSphere Application Server registry is the LDAP provided by Active
Directory. We have considerable experience configuring WebSphere Application
Server SPNEGO authentication with trivial
and non-trivial mappings, including where the WebSphere Application Server registry was a:
- WebSphere Application Server federated repository composed of one or more underlying LDAP registries
- Single Active Directory domain LDAP
- Set of Active Directory LDAP servers configured as an Active Directory Forest
- IBM Tivoli Directory Server LDAP
- Domino LDAP
- z/OS® RACF registry
- Custom User Registry (various types)
These mapping solutions require the creation of customer-specific custom code, typically in the form of a LoginModule to morph the Java Subject built by the SPNEGO authentication code that contains the Windows identity, into a new Java Subject containing the mapped-to user ID valid in the WebSphere registry. The mechanics of these LoginModules are beyond the scope of this article and require an expert to create.
When reading the rest of this article, consider the use of "Windows" in the text to be typical, but not necessary.
Kerberos principal names and how they relate to WebSphere Application Server
We have described at a high level what the SPNEGO protocol is and how the SPNEGO Web Authentication works. Let's now discuss some frequently confusing issues for those new to Kerberos-based security systems. Many of these issues center around the topic of Kerberos principal names. So what are principal names?
Kerberos uses principal Names to identify, well, "principals" within Kerberos. Principals can represent end users, systems, or even ephemeral identities.
User principal names
When you log into a traditional Kerberos system, this is usually done with your UserPrincipalName. A UserPrincipalName for a user is typically in the form of "userid@REALM", or for example, "lansche@IBM.NET". When you log into a Windows domain, you use the Windows User logon name (pre-Windows 2000), which is also known as the sAMAccountName.
Consider this account in Windows shown in Figure 2. The field circled in red is the sAMAccountName.
Figure 2. Property Sheet for a typical Windows Active Directory user
Microsoft also stores a UserPrincipalName for the user within its Active Directory. It is formed by the "User login name", and the realm name (in the above "@ibm.net" form). The SPNEGO negotiation returns a name that Microsoft calls the ClientPrincipalName. This is the sAMAccountName plus the Kerberos realm. By default, the ClientPrincipalName and the UserPrincipalName are the same for a user in Active Directory. However, this is not always the case. Consider this second account shown in Figure 3.
Figure 3. A property sheet for an uncommon, but valid user ID
Figure 4 shows an account that has UserPrincipalName (a searchable LDAP
Figure 4. An LDAP browser's view of this uncommon user's UserPrincipalName
However, the sAMAccountName is "keys" as shown in Figure 5.
Figure 5. The LDAP browser's view of this uncommon user's sAMAccountName
Therefore, the ClientPrincipalName for this user, which is not a searchable LDAP attribute, is "keys@IBM.NET".
By default, the "User logon name" and ":sAMAccountName" are initially set to be the same value, but there is no reason why you cannot change them. Some enterprises enforce a policy to change the sAMAccountName. This can cause havoc to the SPNEGO authentication in WebSphere Application Server, since all it sees is the sAMAccountName and somehow this must be mapped back to a searchable name in its registry. If the sAMAccountName is unique, you can search for it. Unfortunately, sAMAccountNames are guaranteed to be unique only within a single domain. If you have an Active Directory forest, it is possible that the sAMAccountNames across domains within the same forest are duplicated.
In summary, the mapping of a user's principal name into a meaningful name to the WebSphere registry must be considered when planning a SPNEGO WebSphere Application Server deployment. When all users are within a single Active Directory domain, and the WebSphere Application Server registry is configured for that same single Active Directory LDAP, no mapping is required. When the users span multiple Active Directory domains in a forest, and the WebSphere Application Server registry is configured to that forest via LDAP, the mapping might be a problem when the "User logon name" and "sAMAccountName" are not the same. If the mapping is to another registry, then the mapping must depend on creative solutions within a custom JAAS login module. Such a mapping is outside the scope of this article.
Service principal names
Kerberos principals can also represent systems or services. A service's principal
name (ServicePrincipalName or SPN) is in the form of
SERVICE/name@REALM. The actual value of the string
"SERVICE" is by convention. For our purposes, note two important conventions used
by Active Directory and SPNEGO:
- Web server SPNs are prefixed with the string "HTTP/". This is regardless of
whether the protocol used is HTTP or HTTPS. An example SPN for a Web server at
HTTP/someserver.ibm.net@IBM.NET. In Active Directory, all "HTTP/" SPNs are added onto Windows service accounts. A service account in Active Directory is an account whose sole role in life is to exist to support some application or service. For the SPNEGO Web Authentication, we create service accounts for the sole purpose of "owning" an SPN. Note that a service account may have multiple SPNs defined. It may "own" multiple "HTTP/" SPNs.
- Active Directory objects of type "Computer" are also Kerberos services and
have SPNs. Their SPNs are prefixed with "HOST/". A "Computer" object in our test
AD realm IBM.NET called wasserv01 would have two SPNs defined for it:
A common problem encountered when deploying the SPNEGO Web Authentication in WebSphere Application Server is to have SPN name clashes within Active Directory.
Recommendation: Always access SPNEGO via a virtual host name
Question: If instead of accessing the application from our browser at http://someserver.ibm.net (we had instead used http://wasserv01.ibm.net), which SPN would AD use when asked for a service ticket for this request?
Answer: HOST/wasserv01.ibm.net@IBM.NET. This causes problems with the SPNEGO Web Authentication in WebSphere Application Server.
In a pure Kerberos system, the key validation is done in one of two ways:
- Contact the TGS/KDC.
- Use a keytab file that contains a secret (shared with the TGS/KDC).
SPNEGO Web Authentication only uses a keytab file with a shared secret to perform this validation. This shared secret is the password of a user account in the KDC. Since there is no way to define a password for a "Computer" object in Active Directory, you must set a password on a custom service account, and then define an SPN on that account. If there exists more than one object in Active Directory with a possible match for an SPN, AD chooses the "HOST/" SPN, not the "HTTP/" SPN when it builds the service ticket. This obviously causes problems to the SPNEGO code in WebSphere Application Server, since it will try to use the shared secret based on the password for the service account (as embodied in the keytab file), to decrypt the service ticket.
If WebSphere Application Server is running on a Windows computer object, then you should use the host name of the computer in the HTTP request because the service ticket generated could be for the HOST/, not HTTP/ SPN. This means that you need a second host name for the server SPN that you want to use. Interestingly, this is only an issue in small, sandbox, proof-of-concept (POC) systems, or developer environments.
In most typical actual WebSphere Application Server environments, we have already resolved this problem because of the extra network components deployed in the solution. We typically have a cluster of application servers running on at least two machines. To the user, there is the illusion of a single large server called, for example, "someserver.ibm.net" that is always available and scaleable. In fact, the user request flows through a number of machines before it is processed on the application server. This is achieved through the magic of virtual host names. Figure 6 shows a minimal "real" WebSphere Application Server environment.
Figure 6. A minimal "real" WebSphere Application Server environment
In this environment, the user never accesses the application via
http://wasserv01.ibm.net. That host name is irrelevant
in this real world example. In fact, the firewalls above would probably prevent
such access. Similarly, the names of the individual Web servers would also not be
known or accessible.
It is in the simple, single machine Windows environment where there the real machine name is frequently known to the user, and the cause of the name-clash problem. To avoid this name-clash problem, treat this simple environment as a degenerate example of the above complex environment. When you remove the firewalls, the sprayer, and the redundant servers, and even collapse the Web Server and WebSphere Application Server tier, we arrive at the following scenario shown in Figure 7.
Figure 7. Simple sandbox or developer environment
To avoid the name-clash problem, the user should access the server not by the
machine's real Windows host name, but rather via a virtual host name. If this is a
POC, or a development server, then hand coding an
etc/hosts file can bypass the DNS resolution of the
host name and is an easy workaround. If the server is a production server, then you
must add a second DNS entry for the virtual host. This can be achieved using a
second DNS host (A) record for the IP address of the server or a DNS alias
(CNAME). See the discussion below regarding considerations for WebSphere
Application Server, SPNEGO, and DNS aliases.
Before we leave this topic, let's consider the slightly larger environment where the WebSphere Application Server is fronted by a Windows-based Web server. In this case, the user should not use the real host name of the Web server. Instead, use a virtual host name to avoid the name-clash with the "Computer" object in Active Directory for the Web server computer. Figure 8 shows a typical two machine setup.
Figure 8. A typical two machine WebSphere environment
How many SPNs to use?
The previous section explained the problem with SPN name-clashes due to using the host name of the computer objects in AD. In general, the best practice is to use a single SPN per service. This is based on the virtual host name of the Web application as known to the user's browser address field. This is true, regardless of the complexity or simplicity of your environment.
When are multiple SPNs recommended?
The only time that we recommend the use of multiple SPNs in the configuration is when the overall WebSphere cell supports multiple applications and where the applications are hosted on different virtual host names. This is a complex area of discussion outside the boundaries of most deployments.
Note that we categorically argue against setting up multiple SPNs so that SSO access to the application will work, regardless of the access path. Consider this anti-pattern shown in Figure 9.
Figure 9. The wrong way to set up SPNs for WebSphere
The idea here is to allow SPNEGO SSO access via all possible host names by:
How might such a deployment occur? We usually see it occur when the system is built up from a single server, for example, wasserv1.ibm.net, and SPNEGO is configured on that single server. Developers are used to that host name, but then by evolution, the server is clustered. The second server, wasserv2.ibm.net, is added to the mix. To confirm that SPNEGO is not broken, a second SPN is added to the keytab file. Users can access the application via either of the two WebSphere instances.
Developers realize that accessing the application directly on the WebSphere instances of Web containers does not really model what will happen in production, so they introduce a single Web server. To confirm that SPNEGO works there, they add a third SPN for webserv1.ibm.net. Lastly, before going to production, they add a second Web srver, and add the fourth SPN for the service. Just before going to production, they acquire access to an IP sprayer. Since the IP sprayer has another host name, they add the fifth SPN, someserver.ibm.net.
While is it possible to configure the SPNEGO Web Authentication this way, we strongly recommend against it. When these servers are Windows servers in the AD forest, you will have all the name-clash issues described above. In addition, such access violates all normal hardening practices for a production system because users should not have direct access to the internal servers.
If such testing access is desired, edit the
file on the tester desktop. Enter the IP address for the targeted access point as
equal to someserver.ibm.net, then test SPNEGO SSO. For example:
127.0.0.1 localhost # SPNEGO TAI Lab - uncomment the access point you want 126.96.36.199 someserver.ibm.net #Really wasserv01.ibm.net #188.8.131.52 someserver.ibm.net #Really wasserv02.ibm.net #184.108.40.206 someserver.ibm.net #Really webserv01.ibm.net #220.127.116.11 someserver.ibm.net #Really webserv02.ibm.net
Where does the SPN go in Active Directory?
Before we leave the topic of SPNs, let's address the question of where the SPN is supposed to go within the world of Active Directory. In an earlier section, we described the keytab file as containing a secret shared with the AD Key Distribution Center (KDC) that was the password of a "userid" in AD. The ktpass tool is used by the AD Domain administrator to:
- Set the SPN on an account
- Generate a key in a keytab file for use with other Kerberos systems.
However, which user ID to use?
We have encountered customers who have made the mistake of trying to use as few user IDs as possible in the AD for WebSphere Application Server. For WebSphere Application Server V6.1 or later, where you are using the AD as your LDAP either via the standalone LDAP registry, or as part of a federated registry, you need to define:
- The LDAP Bind account and password: This is the account that the WebSphere runtime uses when making LDAP searches and queries. For example, this is frequently a "wasbind" account.
- A server user identity: If V6.1 or later, this identity is optional. If V6.0 and earlier, this is not optional. The various WebSphere processes use it to authenticate to each other. A user ID and password are required. This account is usually "wasserver".
- A primary administrative user ID: This is the super administrator account that is used only to grant "real users" in the registry, the necessary administrative rights that are needed. This is frequently a "wasadmin" account.
The first two accounts are considered "Service Accounts" in the registry. These accounts do need not any special operating system (OS) privileges. The changing of the passwords for these accounts are controlled and not automatically allowed to change. If they are changed in the registry, but not changed in the WebSphere configuration, WebSphere will not work. You can change the primary administrative account password without changing any configuration in WebSphere.
Question: Which of the above accounts should you put the SPN?
Answer: None of the above. As a best practice, we recommend that you create a third service account, perhaps called "wasspnegospn", where you define the ServicePrincipalName.
Note: Do not use any of the above three accounts, or you will end up with operational problems. In particular, when the password for this service account changes, you must regenerate the keytab file, and re-distribute it through your WebSphere cell. This requires a WebSphere outage.
If you must use multiple SPNs within a SPNEGO configuration (see When are multiple SPNs recommended? in the previous section for the only time we recommend that you do so), we recommend that you group SPNs together on a single account that represents all possible SPNs used by a common cluster of applications in the WebSphere Application Server configuration. Consider this example cell content shown in Table 1. The cell hosts four applications owned by three different lines of business.
Table 1. A real-world cell of multiple application, virtual hosts, and SPNs
|Apps Cluster||App1 and App2||app1.ibm.net and app2.ibm.net||
Clearly, we need four SPNs, since to the user, they are four different virtual hosts. The Portal and HR applications run on their own WebSphere clusters. They are best served by each having a separate service account containing a single SPN as shown in Table 2.
Table 2. Mapping SPNs to service accounts
The "Apps cluster" needs careful analysis. If the two applications are tightly coupled (they are deployed together, must run at the same time, have a linked lifecycle, owned by a common line-of-business), then the multiple SPNs can be "owned" by a single service account. Password changes on this service account and the retirement of this service account will affect both applications.
On the other hand, if App1 and App2 are loosely coupled (they have different qualities of service, have different lifecycles, or are owned by separate lines of business), then they should have their own unique service account with their unique SPN. A password change for the service account or the retiring of one application (and therefore, its service account) will not affect the other application (see Table 3).
Table 3. Possible mapping of coupled application's SPNs and service accounts
|If App1 and App2 are tightly coupled:|
|Or, if App1 and App2 are loosely coupled:|
In an AD forest, where to define a SPN account?
What if you have a real-world Active Directory forest with a complex hierarchy of domains? Where to define the SPN service account in that forest?
An Active Directory forest defines a hierarchy of AD domains. Between these domains, there exists a trust relationship. There is no specific requirement for defining an SPN in a particular place in the AD forest. The criteria for decision on where to define the SPN may be more administrative than technical. It may be easier to change in a lower level AD domain than to make the same change to a higher-level domain, or at the root of the AD forest. This must be counter-balanced with the network costs of requesting service tickets across the forest. Consider the following example shown in Figure 10.
Figure 10. Example of corporate AD forest
The AD forest, with a root at ibm.net (Kerberos realm is IBMNET), has sub-domains of na.ibm.net and eu.ibm.net. Their Kerberos realms are NA and EU, respectively. These domains are further subdivided into:
- us.na.ibm.net (US)
- ca.na.ibm.net (CA)
- uk.eu.ibm.net (UK)
- fr.eu.ibm.net (FR)
- de.eu.ibm.net (DE)
Let's assume that the http://someserver.ibm.net is hosted on computers run by the na.ibm.net domain. Let us further assume that 75% of all users are in the us.na.ibm.net domain.
Since the site's DNS name is held at the corporate, or forest level, you can argue to define the SPN as "HTTP/someserver.ibm.net@IBMNET". Creating user IDs at the top of the forest level may require universe-moving approvals (administrative). It is important to realize that the search for service tickets will follow the forest hierarchy. If the SPN is defined at the top of the forest, in IBMNET, then a user in the U.S. domain will first ask its TGS for a ticket for the service. This results in the usdc.us.na.ibm.net sending a request for a TGT for the user from the nadc.na.ibm.net, and in turn, a TGT for the user from rootdc.ibm.net. The client's request for a service ticket for the service hosted at IBMNET must traverse two levels of the forest for completion. In this example, most of the requests for service tickets will have to make two such redirections. In this example, there are only a small set of clients in the root and second level domains. Most are in the third level domains. This may cause excess AD traffic on the WAN (operational).
Administratively, it may be easier to place the SPN in the na.ibm.net domain as "HTTP/someserver.ibm.net@NA". By adding an explicit inter-domain trust between EU and NA, service ticket requests from Europe only require two hops. In addition, the Active Directory administrator can define individual inter-domain trusts between the country domains and the NA domain so that all "foreign" domain requests require only a single hop.
Because most of the service ticket requests will be from the U.S. realm, it may make sense to place the SPN within the U.S. realm, as "HTTP/someserver.ibm.net@US".
Do not secure URLs at the Web server
Note that if a Web server is used to front WebSphere Application Servers, then it needs to be "Integrated Windows Authentication" transparent. The Web server serves as (possibly) an SSL terminator and as a location to run the WebSphere plug-in to enable Web workload management. However, the Web server should not be authenticating the user's requests. If SSL client authentication is enabled, why are you also considering SPNEGO as an authentication mechanism?
For the IBM HTTP Server, and for the "vanilla" Apache Web server, this is not usually an issue. These Web servers are typically not enabled to perform authentication of requests in their default configuration.
However, Microsoft's IIS servers, by default, enable security on the folders in their default Web site. Integration Windows Authentication (IWA) is enabled by default within IIS.
In this scenario, the original request flows through to the WebSphere Application Server SPNEGO Web Authentication code. The "HTTP 401 Authenticate/Negotiate" response is returned to the client. The client re-submits the request with the Authorization header containing the SPNEGO header. The IIS server sees that authorization header and tries to process it. Since the header is for the virtual host name, not the name of the IIS server, it rejects the request and sends a "401" back to the client. This causes a BasicAuth header to be presented. This is not the single sign-on user experience that is desired.
If the Web server processes IWA, there is no way that the SPNEGO Web Authentication code will work because the Web server will have tried to process the SPNEGO token, failed, and returned back a BasicAuth challenge. This BasicAuth header will not be acceptable to the Web authenticator when it sees it.
WebSphere Application Server, SPNEGO, and DNS aliases
In an earlier section, Where does the SPN go in Active Directory?, we told you to define a virtual host name for your WebSphere server, especially when the WebSphere server is a Windows "Computer" object within Active Directory. There are two ways to set up this virtual host name:
- In DNS, add an alias, or (CNAME) record that provides the second host name as
shown in Figure 11.
Figure 11. The someserver DNS record incorrectly set as a DNS alias
- In DNS, add a second host record that maps to the same IP address as the does
the original host name as shown in Figure 12.
Figure 12. The someserver DNS record correctly set as a second DNS host record
An earlier version of this paper recommended that you avoid using a DNS alias for the host name used by the SPNEGO Web Authentication code. With a significant fix, found in ISSW SPNEGO TAI Version 1.1.5 and in APAR PK84184 for WebSphere Application Server, DNS aliases are now fully supported. In fact, with this fix applied the use of DNS is recommended over defining duplicate DNS host records. While both approaches work fine with SPNEGO authentication, native Kerberos support in WebSphere Application Server V7.0 will not function correctly when duplicate DNS host records are used.
When the browser receives a "401 Authenticate/Negotiate" response from the SPNEGO Web Authentication code, it asks for a service ticket. The host name that it asks for is the original aliased host name. When "someserver.ibm.net" is an alias, the service ticket produced above is for "HTTP/wasserv01.ibm.net@IBM.NET". Based upon the discussion above, if wasserv01 is a Windows computer object in the Active Directory, then using an alias can result in a HOST/wasserv01.ibm.net@IBM.NET service ticket. Desktop browsers should be configured to send Integrated Windows Authentication credentials to the actual host name.
To get DNS aliases to work with the WebSphere Application Server SPNEGO:
- In Active Directory, on the SPN account, you must define the SPN only for the
real hostname, not the alias. In the above example, define only:
- Create the keytab containing this SPN and copy the file to the WebSphere Application Server systems.
The next steps you perform depend on which implementation of SPNEGO you have.
If you are using the ISSW SPNEGO TAI, perform these steps :
- Use Version 1.1.5 of the ISSW SPNEGO TAI.
- Define the property
com.ibm.websphere.security.krb.canonical_host=true. This must be defined as a Custom JVM property on every server on which you want the SPNEGO TAI to be active.
- In the SPNEGO configuration, create the property with the SPN for the real host name:
If you are using WebSphere Application Server 7.0 SPNEGO Web authentication (not the TAI), perform these steps:
- You must apply APAR PK84184 (in WebSphere Application Server 7.0 Fix Pack 18.104.22.168).
- Define the property
com.ibm.websphere.security.krb.canonical_host=true. This must be defined via a Custom Property in the Global Security panel. This property can be inherited, or overwritten within a security domain.
- In the SPNEGO configuration, create the properties, with the SPN for the
real host name:
If you are using WebSphere Application Server V6.1 SPNEGO TAI, perform these steps:
- You must apply APAR PK84184 (in WebSphere Application Server 6.1 Fix Pack 22.214.171.124).
- Define the property
com.ibm.websphere.security.krb.canonical_host=true. This must be defined via a Custom Property in the Secure administration, applications, and infrastructure panel.
- In the SPNEGO TAI configuration, create the properties, with the SPN for the real host name:
After making the appropriate changes above, stop and restart all servers, node agents, and deployment managers in the cell.
This article covered a variety of best practices and tips for defining service principal names when using WebSphere Application Server SPNEGO Web Authentication and the SPNEGO TAI. We have built these practices based upon numerous customer deployments of the ISSW SPNEGO TAI, WebSphere Application Server V6.1 SPNEGO TAI, and the WebSphere Application Server V7.0 SPNEGO Web Authentication feature.
- The Simple and Protected GSS-API Negotiation Mechanism
- WebSphere Developer Technical Journal: Advanced authentication in WebSphere Application Server
- WebSphere Application Server Information Center: Single sign-on for HTTP requests using SPNEGO
Dig deeper into WebSphere on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.