Kerberos usage overview for web services

Kerberos usage overview for web services

We can use a Kerberos token to complete similar functions that we might currently complete with other binary security tokens, such as LTPA and Secure Conversation tokens.

Token generator

After the Kerberos token is created from the Key Distribution Center (KDC), the Web Services Security generator encodes and inserts the token into the SOAP message and propagates the token for token consumption or acceptance. If a message integrity or confidentiality key is required, a Kerberos sub-key or a Kerberos session key from the Kerberos ticket is used. A key can be derived from either the Kerberos sub-key or the Kerberos session key. Web Services Security uses the key from the Kerberos token to sign and encrypt the message parts as described in the OASIS Web Services Security Kerberos Token Profile Version 1.1 specification. The type of key to use is predetermined by the Web Services Security configuration or policy. Also, the size of the derived key is configurable.
The value of the signature or encryption key is constructed from the value of one of the following keys:

The Kerberos sub-key when it is present in the authenticator
A session key directly from the ticket if the sub-key is absent
A key derived from either of the previous keys

When the Kerberos token is referenced as a signature key, the signature algorithm must be a hashed message authentication code, which is http://www.w3.org/2000/09/xmldsig#hmac-sha1. When the Kerberos token is referenced as an encryption key, use one of the following symmetric encryption algorithms:

http://www.w3.org/2001/04/xmlenc#aes128-cbc

http://www.w3.org/2001/04/xmlenc#aes256-cbc

http://www.w3.org/2001/04/xmlenc#tripledes-cbc

The Application Server supports Kerberos Version 5 only.

We can use a AES-type symmetric algorithm suite in Web Services Security when the Kerberos ticket complies with RFC-4120 only.

A Kerberos key with the RC4-HMAC 128-bit key type only is used when the KDC is on a Microsoft Windows 2003 server.

A Kerberos key with AES 128-bit or 256-bit key types is used when the KDC is on a Microsoft Windows 2008 server.

A Kerberos ticket must be forwardable and not contain an address when the service provider is running in a cluster.

We must import an unrestricted Java security policy when using an AES 256-bit encryption algorithm.

For information about using a Kerberos token in a cross or trusted realm environment, read the topic "Kerberos token security in a single, cross, or trusted realm environment."

Token consumer

The Web Services Security consumer receives and extracts the Kerberos token from the SOAP message. The consumer then accepts the Kerberos token by validating the token with its own secret key. The secret key of the service is stored in an exported keytab file. After acceptance, the Web Services Security consumer stores the associated request token information into the context Subject. We can also derive the corresponding key to the request token. The key is used to verify and decrypt the message. If the request token is forwardable and does not contain an address, the application server can use the stored token for downstream calls.

Token format and reference

For JAX-WS applications, use the existing custom policy set or administrative command scripts for the custom policy to specify the Kerberos token type, the message signing, and message encryption. The JAX-WS programming model for WebSphere Application Server provides minimal configuration to enable the Kerberos token profile with the Kerberos token.
For JAX-RPC applications, use the deployment descriptor to specify that the custom token use the Kerberos token. We can use the Kerberos token for authentication, but we cannot use it for message signing or encryption.
WebSphere Application Server supports the following callback handler classes for the Kerberos Version 5 token:

com.ibm.websphere.wssecurity.callbackhandler.KRBTokenConsumeCallbackHandler
This class is a callback handler for Kerberos Version 5 token on the consumer side. This instance is used to generate the WSSVerification and WSSDecryption objects to validate a Kerberos binary security token.

com.ibm.websphere.wssecurity.callbackhandler.KRBTokenGenerateCallbackHandler
This class is a callback handler for Kerberos Version 5 token on the generator side. This instance is used to generate the WSSSignature object and the WSSEncryption object to generate a Kerberos binary security token.

The OASIS Web Services Security Kerberos Token Profile Version 1.1 specification states that the Kerberos token is attached to the SOAP message with the <wsse:BinarySecurityToken> element. The following example shows the message format. The boldface type shows delineates the binary security token information from the other parts of the example.
<S11:Envelope xmlns:S11="" xmlns:wsu="">
   <S11:Header>
      <wsse:Security xmlns:wsse="">
          <wsse:BinarySecurityToken EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"                
                 ValueType="http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#Kerberosv5_AP_REQ"
                 wsu:Id="MyToken">boIBxDCCAcCgAwIBBaEDAgEOogcD
      </wsse:BinarySecurityToken>
                 </wsse:Security>
   </S11:Header>
   <S11:Body> </S11:Body>
</S11:Envelope>
The Kerberos token is referenced by the <wsse:SecurityTokenReference> element. The <wsu:Id> element, which is specified within the <wsse:BinarySecurityToken> element and is shown within the following example in boldface type, directly references the token in the <wsse:SecurityTokenReference> element.
The @wsse:TokenType attribute value within the <wsse:SecurityTokenReference> element matches the ValueType attribute value of the <wsse:BinarySecurityToken> element. The Reference/@ValueType attribute is not required. However, if the attribute is specified, its value must be equivalent to the @wsse11:TokenType attribute.
The following example shows the message format, the correlation between the<wsu:Id> and <wsse:SecurityTokenReference> elements, and the relationship between the @wsse:TokenType and ValueType attribute values.
<S11:Envelope xmlns:S11="" xmlns:wsu="">
   <S11:Header>
      <wsse:Security xmlns:wsse="">
          <wsse:BinarySecurityToken EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary" 
            ValueType="http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#Kerberosv5_AP_REQ"
            wsu:Id="MyToken">boIBxDCCAcCgAwIBBaEDAgEOogcD
          </wsse:BinarySecurityToken>
          </wsse:Security>
   </S11:Header>
</S11:Envelope>
      <wsse:Security>
       </wsse:Security>
          <wsse:SecurityTokenReference TokenType="http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#Kerberosv5_AP_REQ">
              <wsse:Reference URI="#MyToken" 
                       ValueType="http://docs.oasis-open.org/wss/
                       oasis-wss-kerberos-token-profile-1.1#Kerberosv5_AP_REQ">
              </wsse:Reference>
          </wsse:SecurityTokenReference>
                <wsse:Security>
      </wsse:Security>
    <S11:Header>
    </S11:Header>
    <S11:Body>
             </S11:Body>
 <S11:Envelope>
 </S11:Envelope>
The <wsse:KeyIdentifier> element is used to specify an identifier for the Kerberos token. The value of the identifier is a SHA1 hash value of the encoded Kerberos token in the previous message. The element must have a ValueType attribute with a #Kerberosv5APREQSHA1 value. The KeyIdentifier reference mechanism is used on subsequent message exchanges after the initial Kerberos token is accepted. The following example shows the key identifier information in boldface type:
<S11:Envelope xmlns:S11="" xmlns:wsse="" xmlns:wsu="">
    <S11:Header>
      <wsse:Security>
                   <wsse:SecurityTokenReference wsse11:TokenType=http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#Kerberosv5_AP_REQ>
               <wsse:KeyIdentifier ValueType="http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#Kerberosv5APREQSHA1">
                  GbsDt+WmD9XlnUUWbY/nhBveW8I=</wsse:KeyIdentifier>
          </wsse:SecurityTokenReference>
                 </wsse:Security>
   </S11:Header>
   <S11:Body>
            </S11:Body>
</S11:Envelope>
Multiple references to the Kerberos token

The client is not required to send a Kerberos token in every request after the Kerberos identity is validated and accepted by the service. The OASIS Web Services Security Kerberos Token Profile Version 1.1 specification suggests that you use a SHA1 encoded key with the <wsse:KeyIdentifier> element within the <wsse:SecurityTokenReference> element for every subsequent message after the initial AP_REQ packet is accepted. However, the runtime environment for Web Services Security must map the key identifier to a cached Kerberos token for further processing. IBM WebSphere Application Server 7.0 and later supports this SHA1 caching as described in the profile, by default. However, the application server also provides the ability to generate new AP_REQ tokens for each request with the existing service Kerberos ticket. When we interoperate with Microsoft .NET, do not use pSHA1 caching; generate an AP_REQ packet for each request.

Related concepts

Web Services Security Kerberos token for authentication in a single or cross Kerberos realm environment

Related information:

Web Services Security Kerberos Token Profile Version 1.1 specification
Kerberos Token Profile 1.1 Approved Errata