Standards for Web services security are required to ensure interoperability in heterogeneous environments. The WS-Security standard and its dependents such as a WS-Trust and WS-Security Policy are important standards in this area. WS-Security is security token agnostic, allowing the use of a variety of security token types. One security token type that is popular in Intranet scenarios is the Kerberos token. This is largely because Kerberos is an integral part of the security system in Microsoft Active Directory server.
It is reasonable to expect that Web services' security interoperability should be achievable using these standards, and that is certainly the case. However, there are some non-obvious steps required to achieve interoperability between Microsoft .NET and IBM WebSphere environments. This article provides end-to-end examples of how to use Kerberos security tokens as the authentication mechanism for Web services between Microsoft .NET and IBM WebSphere environments.
The remainder of this section of the article introduces the key technologies used in implementing this solution.
Kerberos is a network authentication protocol that was originally developed at the Massachusetts Institute of Technology. It was originally described in RFC 1510, and the latest version of the protocol is described under RFC 4120. The Kerberos protocol requires a trusted third party known as the Key Distribution Center (KDC). The KDC has two major components: an Authentication Server (AS), and a Ticket Granting Server (TGS). The Authentication Server shares a secret with each client and server in the Kerberos realm (domain). These shared secrets are used to derive the symmetric keys used to exchange encrypted information between a client or server and the KDC.
Figure 1. A conceptual view of Kerberos
The TGS issues "tickets" as the means to allow a client to authenticate itself to a server. One of the benefits of the KDC design is that a server requires no communication with the KDC when validating a ticket that it receives from a client. Figure 1 shows the sequence of steps from when a client authenticates through to when they authenticate to a server application.
- UserA authenticates to the Authentication Server. UserA's password is not required to travel over the network to the Authentication Server. A ticketing granting ticket (TGT) is returned upon successful authentication. The TGT allows UserA to contact the Ticket Granting Server to request tickets for other servers.
- UserA uses the TGT to authenticate to the Ticket Granting Server. The TGT can be validated by the TGS because it is encrypted with the TGS' secret key. UserA obtains a service ticket for use with ServerB.
- UserA provides the service ticket obtained in the previous step to ServerB. ServerB can validate this ticket locally by decrypting it with its secret key.
In Microsoft Windows server releases since (and including) Windows 2000, the security subsystem in the Microsoft Active Directory has been based in part on Kerberos. When a user logs onto a desktop configured into a Microsoft Active Directory domain, they are authenticating to the Microsoft implementation of a Kerberos Authentication Server. Kerberos tickets can then be obtained from Microsoft Active Directory for authentication to other servers, such as the Microsoft Internet Information Server (IIS) via the Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO).
The Microsoft Web site provides content focused on the Kerberos implementation in Windows Server 2003.
Useful reference sites for Kerberos are found at:
Microsoft Web Services Enhancements
Microsoft Web Services Enhancements is a supported extension to the Microsoft .NET framework to provide advanced capabilities in the area of Web services. While the .NET framework provides some Web services capabilities, including basic security, WSE contains the Microsoft implementation of key industry standards in Web services such as WS-Security and WS-Trust. WSE provides integration with the Microsoft Visual Studio development environment and is wire compatible with the newer Microsoft Windows Communications Foundation (WCF).
Web services are secured in WSE through "policy assertions". A number of built-in assertions (turnkey assertions) are provided. Examples of turnkey assertions are:
- usernameOverTransportSecurity - Authenticate using a UsernameToken, but don't encrypt or sign the messages;
- usernameForCertificateSecurity - Client is authenticated using a UsernameToken. Server authentication is provided using an X.509 certificate and message level security is performed.
- kerberosSecurity - Client and server are authenticated using Kerberos tokens and message-level security is performed.
Security policy is commonly configured declaratively using policy configuration files that contain references to the Microsoft .NET assemblies containing the policy assertion class as well as any configuration for each security policy assertion. The policy configuration file is referenced in the application's configuration file (that is, Web.config or app.config), and the application itself specifies the name of the policy configuration to be used. Listing 2 contains an example of a policy configuration file, which expected a UsernameToken to authenticate the incoming Web service requests.
Listing 1. An example of a WSE 3.0 policy file
<policies xmlns="http://schemas.microsoft.com/wse/2005/06/policy"> <extensions> <extension name="usernameOverTransportSecurity" \ type="Microsoft.Web.Services3.Design.UsernameOverTransportAssertion, \ Microsoft.Web.Services3, Version=220.127.116.11, Culture=neutral, \ PublicKeyToken=31bf3856ad364e35" /> <extension name="requireActionHeader" \ type="Microsoft.Web.Services3.Design.RequireActionHeaderAssertion, \ Microsoft.Web.Services3, Version=18.104.22.168, Culture=neutral, \ PublicKeyToken=31bf3856ad364e35" /> </extensions> <policy name="ServicePolicy"> <usernameOverTransportSecurity /> <requireActionHeader /> </policy> </policies>
Tivoli Federated Identity Manager
Tivoli Federated Identity Manager (TFIM) is the IBM solution for identity propagation in SOA. The core component of TFIM that enables identity propagation in SOA is the Security Token Service (STS). The STS supports the WS-Trust specification (see Resources), which provides a standards-based mechanism for SOA infrastructure to access an identity service to validate, transform, and issue security tokens representing identities. The interaction between an SOA component and the TFIM STS is shown in Figure 2.
Figure 2. Using the TFIM STS in SOA
In the TFIM STS, different identity propagation configurations can be specified. These configurations are called "trust module chains". Incoming requests to the STS are matched to trust module chains in TFIM based on the values of the AppliesTo, Issuer and TokenType parameters. In this way, the same logical STS instance can support a variety of different identity requirements.
The TFIM STS can operate with a number of different security token types, including:
- SAML 1.0
- SAML 1.1
- SAML 2.0
- X.509 certificate
- Lightweight Third Party Authentication (LTPA)
- Tivoli Access Manager
Additionally, new security token modules can be developed for custom security tokens if required.
Kerberos support in TFIM
TFIM 6.1.1 included a Kerberos STS module for validating Kerberos tokens but has no facility for generating these tokens. TFIM 6.2 extends this capability by supporting validation and generation of Kerberos tokens. In addition, TFIM 6.2 introduces a new STS module, the Kerberos Delegation module, that uses the Windows Server 2003 constrained delegation Kerberos extension.
The Kerberos Delegation STS module has the advantage of not requiring the client's password when issuing a Kerberos token. The Kerberos STS module provides generic Kerberos security token functionality but, when issuing Kerberos tokens, requires the client's password to be accessible through the STS Universal User object in the TFIM trust module chain processing.
One other consideration is that the Kerberos Delegation module must run under an account with the Act as part of the Operating System privilege (for example, the Local System account).
The relative merits of the two STS modules are summarized in Table 1.
Table 1. Comparing the TFIM STS Kerberos modules
|Kerberos module||Kerberos Delegation module|
|Platform for TFIM STS||Any||Windows Server 2003 only|
|Requires Operating System Privilege||No||Yes|
|Kerberos KDC||Any||Microsoft Active Directory only|
|Client password required?||Yes||No|
Use of the Kerberos Delegation STS module should be considered if:
- Kerberos tokens are only required to be issued, not validated;
- The TFIM Runtime is running on a Windows Server 2003 server under an account with Act as part of the Operating System privilege;
- The Windows Server 2003 server hosting the TFIM Runtime is part of an Active Directory domain that will act as the Kerberos KDC; and
- Active Directory has been configured for constrained delegation.
If any of these conditions are not met, then use the Kerberos STS module.
The advantage of the Kerberos Delegation STS module not requiring a client password can be mitigated in some circumstances. For example, if the Kerberos STS module is part of an STS module chain that includes the validation of an incoming Username token and that token includes the password of a principal defined in the KDC, then this password can be used when issuing the Kerberos token. If the password cannot be obtained from the incoming token, it can be supplied through an STS mapping module, such as the Tivoli Access Manager Global Sign-on mapping module.
Kerberos interoperability between Microsoft .NET and IBM WebSphere Application Server
Microsoft WSE provides a turnkey security assertion, which uses Kerberos security tokens. Among other things, the turnkey security assertion will:
- Generate a Kerberos security token for the client
- Include the Kerberos security token in the WS-Security header of the Web service request
- Sign one or more elements of the request using a Kerberos security token
- Encrypt one or more elements of the request using a Kerberos security token
- Generate a Kerberos security token for the service
- Sign one or more elements of the response using a Kerberos security token
- Encrypt one or more elements of the response using a Kerberos security token
The turnkey security assertion in Microsoft WSE is not able to interoperate with an IBM solution using WebSphere Application Server and Tivoli Federated Identity Manager. While a compatible Kerberos security token can be validated and generated by Tivoli Federated Identity Manager, the message level signing and encryption, which is mandatory with the turnkey security assertion, is not currently supported by the IBM solution.
Instead, a custom security assertion for Microsoft WSE has been developed that provides interoperability for message authentication only. The source code is supplied as part of the sample code in the Download section of this article. The Echo application download contains a Microsoft Visual Studio 2005 project named "KerberosOverTransport". This project is composed of three classes:
This class extends the Microsoft.Web.Services3.Design.SecurityPolicyAssertion class. It registers the custom classes it will use to filter incoming and outgoing messages (see the next two classes in this list), and parses the WSE policy configuration for any configuration parameters.
This class is referenced by the KerberosOverTransportAssertion class. Its SecureMessage() method is invoked when an outgoing Web service message is being composed. The SecureMessage() method creates a Kerberos security token and adds it to the set of security tokens that will be included in the outgoing message's WS-Security SOAP header.
This class is also referenced by the KerberosOverTransportAssertion class. Its ValidateMessageSecurity() method is invoked when an incoming Web service message is received and is being validated. The ValidateMessageSecurity() method verifies that the Kerberos security token in the incoming message is valid, and then uses the identity from the Kerberos security token in the execution context for the SOAP message.
When using the security assertion to validate the incoming Kerberos token received by a Web service, no further configuration is required, other than to specify an empty kerberosOverTransportAssertion element, as shown in Listing 2.
Listing 2. Specifying the kerberosOverTransportAssertion as part of a Web service policy
<policies xmlns="http://schemas.microsoft.com/wse/2005/06/policy"> <extensions> <extension name="kerberos" \ type="Microsoft.Web.Services3.Design.KerberosTokenProvider,Microsoft.Web.Services3,\ Version=22.214.171.124, Culture=neutral, PublicKeyToken=31bf3856ad364e35" /> <extension name="kerberosOverTransportAssertion" \ type="KerberosOverTransport.KerberosOverTransportAssertion,KerberosOverTransport" /> </extensions> <policy name="ServerPolicy"> <kerberosOverTransportAssertion/> </policy> </policies>
When using the security assertion to add a Kerberos security token to a Web service request, the Kerberos principal name of the server/service needs to be specified, as shown in Listing 3.
Listing 3. Specifying the kerberosOverTransportAssertion as part of a Web service client policy
<policies xmlns="http://schemas.microsoft.com/wse/2005/06/policy"> <extensions> <extension name="kerberos" \ type="Microsoft.Web.Services3.Design.KerberosTokenProvider,Microsoft.Web.Services3,\ Version=126.96.36.199, Culture=neutral, PublicKeyToken=31bf3856ad364e35" /> <extension name="kerberosOverTransportAssertion" \ type="KerberosOverTransport.KerberosOverTransportAssertion,KerberosOverTransport" /> </extensions> <policy name="ClientPolicy"> <kerberosOverTransportAssertion> <!-- For a Web service hosted in Microsoft .NET, the targetPrincipal will be of the form host/<hostname>, where <hostname> is the name of the host running the service. For a Web service hosted in and IBM WebSphere environment where the TFIM Kerberos STS module is used to validate the Kerberos token in the incoming message, the targetPrincipal must match the value in the STS module's configuration parameters. --> <targetPrincipal>fimservice</targetPrincipal> </kerberosOverTransportAssertion> </policy> </policies>
Example: Interoperability with the TFIM Echo application
The TFIM Web Services Security Managment (WSSM) component includes example J2EE Web service client and server applications. This article provides a download link to example WSE 3.0 Web service client and server applications. The goal is to communicate from the WSE client application to the J2EE Web service application and from the J2EE client application to the WSE Web service application. In both cases a Kerberos security token is used for message level authentication of the Web service request.
In the remainder of this section, the following pre-requisite environment is assumed to exist:
- A TFIM management domain has been created;
- The TFIM runtime has been deployed;
- The example J2EE applications, echoclientapplication.ear and echoapplication.ear, have been installed; and
- A Windows Server 2003 SP2 or higher is installed, with Active Directory and the Windows Server Support Tools (which includes Kerberos command line utilities) installed and configured.
Figure 3 shows the deployment of the various applications. The TFIM server, fimserver.fim.example.com, hosts the TFIM runtime using the embedded version of WebSphere Application Server that ships with TFIM. The example J2EE applications are deployed to a separate instance of WebSphere Application Server 6.1. The machine hosting the TFIM server does not have to be part of the Active Directory domain.
The Active Directory server, fimtest.fim.test.com, hosts the example Microsoft WSE applications. In a production environment, it would be more common to have the WSE applications running on a separate server. In that case, the server hosting the Microsoft WSE applications would have to be part of the Active Directory domain.
Figure 3. Example application environment
The following preliminary steps are performed on the Active Directory server as a domain administrator.
- Create a user in Active Directory under fim.test.com called fimclient with a password of Passw0rd. The password contains both uppercase and lowercase characters and a numeric to satisfy the default password policy.
- Create another user under fim.test.com called fimservice, also with a password of Passw0rd.
From the command line, run ksetup to map the fimservice Kerberos principal name to the fimservice user account.
ksetup /mapuser fimservice/fimtest.fim.test.com@FIM.TEST.COM fimservice
From the command line, run ktpass to create a keytab file for fimservice. The keytab file provides access to a server entity's secret key (as opposed to a user who can enter their password into an interactive application).
ktpass -out fimservice.keytab -princ fimservice/fimtest.fim.test.com@FIM.TEST.COM -Crypto RC4-HMAC-NT -mapUser fimservice@FIM.TEST.COM -pass Passw0rd -ptype KRB5_NT_PRINCIPAL
Copy the generated fimservice.keytab file to a location on the TFIM server.
The following preliminary steps are performed on the TFIM server.
- Using the TFIM console, navigate to the Default Kerberos Token module instance and update its properties to specify the location of the krb5.conf and jaas.conf configuration files. Example krb5.conf and jaas.conf files are installed with the TFIM WSSM component and can be found in C:\Program Files\IBM\FIM\wssm\examples\etc on Windows and /opt/IBM/FIM/wssm/examples/etc on Linux/UNIX®.
- Verify that the contents of the krb5.conf configuration file are correct, by making sure that the Kerberos realm name and location of the KDC are correct.
- The jaas.conf configuration should not need modification.
IBM WebSphere Client to Microsoft .NET Service
The following steps describe the installation of the WSE Web service application, the configuration of a TFIM STS module chain to generate a Kerberos security token on behalf of the J2EE client application, and running the J2EE client application.
- On the Active Directory server, install the example WSE Web service application under IIS with an alias of EchoService.
Use the browser to navigate to this application to ensure it is installed correctly. For example:
Using the TFIM console, create a trust chain that will be used to issue a Kerberos security token for inclusion by the J2EE client when communicating to the WSE Web service application.
- Set the AppliesTo address to REGEXP:(.*/EchoService/Echo.asmx) and the Issuer address to urn:itfim:wssm:tokengenerator.
- Create a chain consisting of the Default SAML 2.0 Token module in validate mode, the Default Map module, and the Default Kerberos Token module in issue mode.
- Configure the SAML 2.0 module to skip signature validation.
- Configure the map module by importing the wssm_test.xsl stylesheet that ships with TFIM. This stylesheet supplies the Kerberos client name (fimclient) and password (Passw0rd).
Configure the Kerberos module as shown in Figure 4. Set the realm name to FIM.TEST.COM (the name of the Active Directory domain) and the service name to host/fimtest.fim.test.com. The name host/fimtest.fim.test.com is the host principal name of the server on which the WSE Web service is running. This principal name is chosen because the IIS server runs under the local system account, which maps to that principal.
Figure 4. Kerberos Module Issue Configuration
- Ensure that TFIM configuration changes are updated in the TFIM runtime.
Use the browser to navigate to the J2EE client application. For example:
- Log onto the application with the fimclient user created earlier and select Kerberos as the token type.
Specify http://fimtest.fim.test.com/EchoService/Echo.asmx as the Echo Web service URL and click the WhoAmI button.
Figure 5 shows the result of the J2EE client application having invoked the WSE Web service. The WSE Web service returns information contained in the Kerberos security token including the client principal name and the target host principal name.
Figure 5. J2EE Client Application
Figure 6 illustrates the message flow between the J2EE client application and the WSE Web service application.
- The J2EE client application's deployment descriptor prescribes that a Kerberos security token be included with the Web service request.
- TFIM WSSM, on behalf of the application, makes a WS-Trust call to the TFIM STS to have a Kerberos securty token issued. It supplies the authenticated user's identity information to the STS in a SAML 2.0 security token.
- The TFIM STS executes the configured STS module chain and returns to WSSM a Kerberos security token for inclusion in the Web service request.
- The Web service request, including the Kerberos security token, is sent to the WSE Web service application. WSE validates the Kerberos security token and executes the Web service request under the identity of the fimclient user.
- The Web service executes, and the response is returned by the WSE Web service application to the J2EE client application.
Figure 6. J2EE Client to WSE Service
Sample SOAP messages between the Echo client and service, along with sample WS-Trust messages between TFIM WSSM and the TFIM STS are available in the Downloads section.
Microsoft .NET Client to IBM WebSphere Service
The following steps describe the configuration of a TFIM STS module chain to validate a Kerberos security token on behalf of the J2EE Web service application, the configuration of the WSE client application, and running the WSE client application.
Using the TFIM console, create a trust module chain that will be used to validate a Kerberos security token received by the J2EE web service application.
- Set the AppliesTo address to REGEXP:(.*/EchoApplication/services/EchoServiceKerberos) and the Issuer address to urn:itfim:wssm:tokenconsumer.
- Create a chain consisting of the Default Kerberos Token module in validate mode, the Default Map module, and the Default SAML 2.0 Token module in issue mode.
Configure the Kerberos module as shown in Figure 7. Set the keytab file name to the previously created fimservice.keytab file copied from the Active Directory server.
Figure 7. Kerberos Module Validate Configuration
- Configure the map module by importing the wssm_test.xsl stylesheet that ships with TFIM.
- Configure the SAML 2.0 module with the issuing organization set to fim.test.com and for no signing or encrypting of the SAML assertion.
On the Active Directory server, locate the EchoClient.exe.config file in the WSE client application's bin directory and update the URL to that of the J2EE web service. For example:
The wse3policyCache.config file is in this same directory and specifies the target principal as fimservice/fimtest.com.test.com. This does not need to be changed in this environment, but would be changed to match whatever service principal is created in Active Directory for a different service.
- From the command line, run the WSE client application, EchoClient.exe. The J2EE web service returns information from its login context including the user identity.
Figure 8 illustrates the message flow between the WSE client application and the J2EE Web service application.
- The WSE client sends a Web service request, including a Kerberos security token, to the J2EE Web service application.
- TFIM WSSM, on behalf of the application, makes a WS-Trust call to the TFIM STS to have the Kerberos securty token validated.
- The TFIM STS executes the configured STS module chain, validates the Kerberos security token using the configured keytab file and returns the user's identity information to TFIM WSSM in a SAML 2.0 security token.
- The Web service executes, and the response is returned by the J2EE Web service application to the WSE client application.
Figure 8. WSE Client to J2EE Service
Sample SOAP messages between the Echo client and service, along with sample WS-Trust messages between TFIM WSSM and the TFIM STS are available in the Downloads section.
This section lists some of the common configuration issues and possible solutions. The error messages described below will be visible in the Echo client application. The values for configuration parameters described here correspond to those used in the example above.
- WSE594 The network path was not found
A WSE594 error is displayed by the Microsoft WSE client application if an invalid target principal name is configured. Review the wse3policyCache.config file and ensure the targetPrincipal is fimservice/fimtest.fim.test.com.
- NullPointerException returned by J2EE Web service
A NullPointerException is returned by the J2EE Web service application and displayed in the Microsoft WSE client if the wrong target principal name was specified by the Microsoft WSE client. Review the wse3policyCache.config file and ensure the targetPrincipal is fimservice/fimtest.fim.test.com. Ensure the Kerberos STS module is configured to use the generated fimservice.keytab file.
- STSClientException - Null credential
An STSClientException is returned by the J2EE Web service application and displayed in the Microsoft WSE client if the realm name configured in the Kerberos STS module is invalid. Ensure the Kerberos STS module is configured with the realm name FIM.TEST.COM.
- STSClientException - Server not found in Kerberos database
An STSClientException is returned by the J2EE Web service application and displayed in the Microsoft WSE client if the service name configured in the Kerberos STS module is invalid. Ensure the Kerberos STS module is configured with the service name host/fimtest.fim.test.com.
- WSE594 Logon failure: unknown user name or bad password
A WSE594 error is returned by the WSE Web service application and displayed in the J2EE client if the wrong service name is configured in the Kerberos STS module. Ensure the Kerberos STS module is configured with the service name host/fimtest.fim.test.com.
- No Kerberos security tokens were present in the incoming request
The WSE Web service application expects Kerberos security tokens with a specific value type. Ensure the Kerberos STS module is configured to use the GSS_Kerberosv5_AP_REQ value type.
This article demonstrates the steps required for secure, Kerberos enabled, interoperable Web services between Microsoft .NET and IBM WebSphere environments. IBM Tivoli Federated Identity Manager is a key enabler for this solution with its ability to integrate with IBM WebSphere Application Server, and flexibly validate and issue Kerberos security tokens.
|Echo client and service for Microsoft .NET/WSE 3.01||Echo.zip||170 KB|
|SOAP messages from running the examples||kerberos-messages.zip||15 KB|
- Includes the Kerberos custom security assertion for Microsoft® .NET/WSE 3.0.
- The Tivoli Federated Identity Manager Version 6.2 Information Center.
- Microsoft Web Services Enhancements 3.0
- Specification: WS-Trust 1.3
- IBM Redbooks: Understanding SOA Security
- Redpaper: Propagating Identity in SOA with IBM Tivoli Federated Identity Manager
- Implementing Message Layer Security with Kerberos in WSE 3.0
- Browse the technology bookstore for books on these and other technical topics.
Get products and technologies
- Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
Dig deeper into Tivoli (service management) 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.