Kerberos usage overview for Web services

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. WS-Security uses the key from the Kerberos token to sign and encrypt the message parts as described in the OASIS WS-Security Kerberos Token Profile V1.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 that is 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 V5 only.

• 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.

• You must import an unrestricted Java security policy when you use 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 WS-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 WS-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 appserver can use the stored token for downstream calls.

 

Token format and reference

For JAX-WS applications, use the existing custom policy set or admin command scripts for the custom policy to specify the Kerberos token type, the message signing, and message encryption. The JAX-WS model for WAS 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. Use the Kerberos token for authentication, but we cannot use it for message signing or encryption. WAS supports the following callback handler classes for the Kerberos V 5 token:

• com.ibm.websphere.wssecurity.callbackhandler.KRBTokenConsumeCallbackHandler

  This class is a callback handler for Kerberos V5 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 V5 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 WS-Security Kerberos Token Profile Version 1.1 spec 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 WS-Security Kerberos Token Profile V1.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 WS-Security must map the key identifier to a cached Kerberos token for further processing. IBM WAS 7.0 supports this SHA1 caching as described in the profile, by default. However, the appserver also provides the ability to generate new AP_REQ tokens for each request with the existing service Kerberos ticket. When you interoperate with Microsoft .NET, do not use pSHA1 caching; generate an AP_REQ packet for each request.

---

 

Related concepts

WS-Security Kerberos token for authentication in a single or cross Kerberos realm environment
Kerberos token

 

Related information

WS-Security Kerberos Token Profile V1.1 specification
Kerberos Token Profile 1.1 Approved Errata