15.2. Configure Security Token Service (STS)

The EAP Security Token Service (STS) defines several interfaces that provide extension points. Implementations can be plugged in via configuration, and the default values can be specified for some properties via configuration. All STS configurations are specified in the picketlink.xml file, which belongs in the WEB-INF directory of the deployed application. The following are the elements that can be configured in the picketlink.xml file.


In the following text, a service provider refers to the Web service that requires a security token to be presented by its clients.
  • PicketLinkSTS: This is the root element. It defines some properties that allows the STS administrator to set a the following default values:
    • STSName: A string representing the name of the security token service. If not specified, the default PicketLinkSTS value is used.
    • TokenTimeout: The token lifetime value in seconds. If not specified, the default value of 3600 (one hour) is used.
    • EncryptToken: A boolean specifying whether issued tokens are to be encrypted or not. The default value is false.
  • KeyProvider: This element and all its sub elements are used to configure the keystore that are used by PicketLink STS to sign and encrypt tokens. Properties like the keystore location, its password, and the signing (private key) alias and password are all configured in this section.
  • RequestHandler: This element specifies the fully qualified name of the WSTrustRequestHandler implementation to be used. If not specified, the default org.picketlink.identity.federation.core.wstrust.StandardRequestHandler is used.
  • TokenProvider: This section specifies the TokenProvider implementations that must be used to handle each type of security token. In the example we have two providers - one that handles tokens of type SpecialToken and one that handles tokens of type SAMLV2.0. The WSTrustRequestHandler calls the getProviderForTokenType(String type) method of STSConfiguration to obtain a reference to the appropriate TokenProvider.
  • TokenTimeout: This is used by the WSTrustRequestHandler when no Lifetime has been specified in the WS-Trust request. It creates a Lifetime instance that has the current time as the creation time and expires after the specified number of seconds.
  • ServiceProviders: This section specifies the token types that must be used for each service provider (the Web service that requires a security token). When a WS-Trust request does not contain the token type, the WSTrustRequestHandler must use the service provider endpoint to find out the type of the token that must be issued.
  • EncryptToken: This is used by the WSTrustRequestHandler to decide if the issued token must be encrypted or not. If true, the public key certificate (PKC) of the service provider is used to encrypt the token.
The following is an example of STS configuration.

Example 15.3. STS Configuration

<PicketLinkSTS xmlns="urn:picketlink:identity-federation:config:1.0"  
         STSName="Test STS" TokenTimeout="7200" EncryptToken="true">  
  <KeyProvider ClassName="org.picketlink.identity.federation.bindings.tomcat.KeyStoreKeyManager">  
    <Auth Key="KeyStoreURL" Value="keystore/sts_keystore.jks"/>   
    <Auth Key="KeyStorePass" Value="testpass"/>  
    <Auth Key="SigningKeyAlias" Value="sts"/>  
    <Auth Key="SigningKeyPass" Value="keypass"/>  
    <ValidatingAlias Key="http://services.testcorp.org/provider1" Value="service1"/>  
    <ValidatingAlias Key="http://services.testcorp.org/provider2" Value="service2"/>  
    <TokenProvider ProviderClass="org.picketlink.test.identity.federation.bindings.wstrust.SpecialTokenProvider"  
    <TokenProvider ProviderClass="org.picketlink.identity.federation.api.wstrust.plugins.saml.SAML20TokenProvider"  
		<ServiceProvider Endpoint="http://services.testcorp.org/provider1" TokenType="http://www.tokens.org/SpecialToken"  
		<ServiceProvider Endpoint="http://services.testcorp.org/provider2" TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0"