This article discusses the implementation of security token providers for PicketLink STS.

The SecurityTokenProvider interface

All token provider implementations are required to implement the SecurityTokenProvider interface. This interface defines five methods:

   /**
    * <p>
    * Initializes the {@code SecurityTokenProvider} using the specified properties map.
    * </p>
    * 
    * @param properties a {@code Map<String, String>} that contains the properties that have been configured for
    * this {@code SecurityTokenProvider}.
    */
   public void initialize(Map<String, String> properties);

   /**
    * <p>
    * Generates a security token using the information contained in the specified request context and stores the
    * newly-created token in the context itself.
    * </p>
    * 
    * @param context the {@code WSTrustRequestContext} to be used when generating the token.
    * @throws WSTrustException if an error occurs while creating the security token.
    */
   public void issueToken(WSTrustRequestContext context) throws WSTrustException;

   /**
    * <p>
    * Renews the security token contained in the specified request context. This method is used when a previously
    * generated token has expired, generating a new version of the same token with different expiration semantics.
    * </p>
    * 
    * @param context the {@code WSTrustRequestContext} that contains the token to be renewed.
    * @throws WSTrustException if an error occurs while renewing the security token.
    */
   public void renewToken(WSTrustRequestContext context) throws WSTrustException;

   /**
    * <p>
    * Cancels the token contained in the specified request context. A security token is usually canceled when one wants
    * to make sure that the token will not be used anymore. A security token can't be renewed once it has been canceled.
    * </p>
    * 
    * @param context the {@code WSTrustRequestContext} that contains the token to be canceled.
    * @throws WSTrustException if an error occurs while canceling the security token.
    */
   public void cancelToken(WSTrustRequestContext context) throws WSTrustException;

   /**
    * <p>
    * Evaluates the validity of the token contained in the specified request context and sets the result in the context
    * itself. The result can be a status, a new token, or both.
    * </p>
    * 
    * @param context the {@code WSTrustRequestContext} that contains the token to be validated.
    * @throws WSTrustException if an error occurs while validating the security token.
    */
   public void validateToken(WSTrustRequestContext context) throws WSTrustException;

The initialize(Map<String, String> properties) method is a callback method called by the STS when the token provider is instantiated. The properties parameter is a map that contains all the configuration properties that have been specified for the provider in the picketlink-sts.xml configuration file.

The remaining methods, as their names imply, are responsible for issuing, renewing, cancelling, and validating security tokens. These methods use the information contained in the context parameter (and also the configuration properties set in the initialize method) to perform their work.

The WSTrustRequestContext class

The WSTrustRequestContext class is used by the token providers to:

1. provide information that may be needed to issue/renew/cancel/validate a security token. This includes the original WS-Trust request, the caller principal, and the proof-of-possession token that must be included in issued security tokens.
   
2. store the artifacts produced by the token provider, includeing the security token itself, attached and unattached references, and validation status.
   

All methods from SecurityTokenProvider that involve token processing receive a reference to the request context as a parameter. They use this reference to get the information needed in order to process the request. For example, the SAML20TokenProvider uses the Lifetime and AppliesTo sections of the WS-Trust request stored in the context to create the assertion Conditions element. It also uses the proof-of-possession token to create the SubjectConfirmation section of the SAML assertion, and the caller principal to build the assertion Subject.

After processing the token request, the SecurityTokenProvider must set all produced artifacts in the WSTrustRequestContext. These artifacts will be retrieved later by the STS engine to produce the WS-Trust response. Commonly produced artifacts include the security token, attached and unattached references, and the validation status.

Configuring the Token Provider

Token providers are configured in the picketlink-sts.xml file. The configuration of the SAML20TokenProvider can be seen bellow:

<TokenProvider ProviderClass="org.picketlink.identity.federation.core.wstrust.plugins.saml.SAML20TokenProvider"
     TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0"
     TokenElement="Assertion"
     TokenElementNS="urn:oasis:names:tc:SAML:2.0:assertion"/>

The token provider configuration must specify the provider class and three other attributes:

• TokenType: the token type URL. This value is normally defined in the token profile specification.
  
• TokenElement: the local name of the token element. Security tokens are represented as XML structures. This attribute identifies the name of the element that represents the token.
  
• TokenElementNS: the namespace of the security token that is handled by the token provider.
  

The TokenType attribute allows the STS to locate the token provider when the token type has been specified. The other two attributes, TokenElement and TokenElementNS,  allow the STS to locate the provider when only the security token is present in the request (for example, validation requests don't specify the token type, so the token provider has to be located using the security token itself). That is, the STS inspects the token contained in the request and uses the token local name and namespace to locate the provider that can handle the token request.

It is also possible to specify generic properties for a token provider using the Property element:

<TokenProvider ProviderClass="org.picketlink.test.identity.federation.core.wstrust.SpecialTokenProvider"
     TokenType="http://www.tokens.org/SpecialToken"
     TokenElement="SpecialToken"
     TokenElementNS="http://www.tokens.org">
     <Property Name="Property1" Value="Value1"/>
     <Property Name="Property2" Value="Value2"/>
</TokenProvider>

Reference Implementation

For a reference implementation of the SecurityTokenProvider interface, take a look at the SAML V2.0 token provider that has been implemented (renew and cancel not implemented yet) for PicketLink STS:

org.picketlink.identity.federation.core.wstrust.plugins.saml.SAML20TokenProvider