Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

Chapter 13. Single Sign-On with SAML

13.1. About Security Token Service (STS)

The Security Token Service generates and manages the security tokens. It does not issue tokens of a specific type. Instead, it defines generic interfaces that allows multiple token providers to be plugged in. As a result, it can be configured to deal with various types of token, as long as a token provider exists for each token type. It also specifies the format of the security token request and response messages.
A security token request message specifies the following:
  • Type of the request, such as Issue, Renew, and so on.
  • Type of the token.
  • Lifetime of the issued token.
  • Information about the service provider that requested the token.
  • Information used to encrypt the generated token.

Note

Support for PKCS#11 tokens has been added to JBoss EAP from version 6.3.0.
EAP security realms can accept PKCS#11 keys and trust store definitions by using the provider attribute. The value specified in this parameter is passed to the relevant KeyStore.getInstance("PKCS11") calls and the key and trust store are initialized.
Configuration for this new support is beyond the scope of EAP documentation. Users who wish to utilize this feature should familiarize themselves with the correct installation of PKCS#11 hardware and software as well as the correct entries required in the java.security policy file. Oracle's Java PKCs#11 Reference Guide document may be a useful resource for this information.
The token request message is sent in the body of the SOAP message. All information related to the token request is enclosed in the RequestSecurityToken element. The sample request contains two other WS-Trust elements: RequestType, which specifies that this request is an Issue request, and TokenType, which specifies the type of the token to be issued.
The following is an example of the WS-Trust request message.

Example 13.1. WS-Trust security token request message

<S11:Envelope xmlns:S11=".." xmlns:wsu=".." xmlns:wst="..">  
   <S11:Header>  
      ...  
   </S11:Header>  
   <S11:Body wsu:Id="body">  
      <wst:RequestSecurityToken Context="context">  
         <wst:TokenType>http://www.tokens.org/SpecialToken</wst:TokenType>  
         <wst:RequestType>  
            http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue  
         </wst:RequestType>  
      </wst:RequestSecurityToken>  
   </S11:Body>  
</S11:Envelope>
The following is an example of a security token response.

Example 13.2. Security token response message

    <wst:RequestSecurityTokenResponse Context="context" xmlns:wst=".." xmlns:wsu="..">  
       <wst:TokenType>http://www.tokens.org/SpecialToken</wst:TokenType>  
       <wst:RequestedSecurityToken>  
          <token:SpecialToken xmlns:token="...">  
             ARhjefhE2FEjneovi&@FHfeoveq3  
          </token:SpecialToken>  
       </wst:RequestedSecurityToken>  
       <wst:Lifetime>  
          <wsu:Created>...</wsu:Created>  
          <wsu:Expires>...</wsu:Expires>  
       </wst:Lifetime>  
    </wst:RequestSecurityTokenResponse>
In the example for the security token response, the TokenType element specifies the type of the issued token, while the RequestedSecurityToken element contains the token itself. The format of the token depends on the type of the token. The Lifetime element specifies when the token was created and when it expires.
Security Token Request Processing

The following are the steps in which the security token requests are processed:

  • A client sends a security token request to PicketLinkSTS.
  • PicketLinkSTS parses the request message, generating a JAXB object model.
  • PicketLinkSTS reads the configuration file and creates the STSConfiguration object, if needed. Then it obtains a reference to the WSTrustRequestHandler from the configuration and delegates the request processing to the handler instance.
  • The request handler uses the STSConfiguration to set default values when needed (for example, when the request doesn't specify a token lifetime value).
  • The WSTrustRequestHandler creates the WSTrustRequestContext, setting the JAXB request object and the caller principal it received from PicketLinkSTS.
  • The WSTrustRequestHandler uses the STSConfiguration to get the SecurityTokenProvider that must be used to process the request based on the type of the token that is being requested. Then it invokes the provider, passing the constructed WSTrustRequestContext as a parameter.
  • The SecurityTokenProvider instance process the token request and stores the issued token in the request context.
  • The WSTrustRequestHandler obtains the token from the context, encrypts it if needed, and constructs the WS-Trust response object containing the security token.
  • PicketLinkSTS dictates the response generated by the request handler and returns it to the client.
Report a bug