Apache CXF STS documentation - part VIII

Previous blog posts on the Apache CXF STS have focused on how tokens are provided, validated and canceled in the STS. These operations are (at least in theory) relatively independent of WS-Trust. For example, they could be used as an API to provide/validate/etc tokens. In the next couple of posts we will look at the bigger picture of how this internal token handling functionality works in the context of a client invocation. In this post we will cover some common functionality that is used by all of the WS-Trust operations in the STS implementation.

1) AbstractOperation

In the first post of this series of articles, the STS provider framework in Apache CXF was introduced. A number of interfaces were defined for each of the operations that can be invoked on the STS. Before looking at the implementations of these interfaces that ship with the STS, we will look a base class that all of the operations extend, namely the AbstractOperation class. This class defines a number of properties that are shared with any subclasses, and can be accessed via set/get methods:

• STSPropertiesMBean stsProperties - A configuration MBean that holds the configuration for the STS as a whole, such as information about the private key to use to sign issued tokens, etc.
• boolean encryptIssuedToken - Whether to encrypt an issued token or not. The default is false.
• List<ServiceMBean> services - A list of ServiceMBean objects, which correspond to "known" services. This will be covered later.
• List<TokenProvider> - A list of TokenProvider implementations to use to issue tokens.
• boolean returnReferences - Whether to return SecurityTokenReference elements to the client or not, that point to the issued token. The default is true.
• STSTokenStore tokenStore - A cache used to store/retrieve tokens.

Several of the properties refer to issuing tokens - this is because this functionality is shared between the issuing and validating operations. At least one TokenProvider implementation must be configured, if the STS is to support issuing a token. Some of these properties have been seen in previous posts, for example the STSTokenStore cache was covered in a previous blog post. This cache could be shared across a number of different operations, or else kept separate. AbstractOperation also contains some common functionality to parse requests, encrypt tokens, create references to return to the client, etc.

1.1) STSPropertiesMBean

The AbstractOperation object must be configured with an STSPropertiesMBean object. This is an interface that encapsulates some configuration common to a number of different operations of the STS:

• void configureProperties() - load and process the properties
• void setCallbackHandler(CallbackHandler callbackHandler) - Set a CallbackHandler object. This is used in the TokenProviders/TokenValidators to retrieve passwords for various purposes.
• void setSignatureCrypto(Crypto signatureCrypto) - Set a WSS4J Crypto object to use to sign tokens, or validate signed requests, etc.
• void setSignatureUsername(String signatureUsername) - Set the default signature username to use (e.g. corresponding to a keystore alias)
• void setEncryptionCrypto(Crypto encryptionCrypto) - Set a WSS4J Crypto object to use to encrypt issued tokens.
• void setEncryptionUsername(String encryptionUsername) - Set the default encryption username to use (e.g. corresponding to a keystore alias)
• void setIssuer(String issuer) - Set the default issuer name of the STS
• void setSignatureProperties(SignatureProperties signatureProperties) - Set the SignatureProperties object corresponding to the STS.
• void setRealmParser(RealmParser realmParser) - Set the object used to define what realm a request is in. This will be covered later.
• void setIdentityMapper(IdentityMapper identityMapper) - Set the object used to map identities across realms. This will be covered later.

The STS ships with a single implementation of the STSPropertiesMBean interface - StaticSTSProperties. This class has two additional methods:

• void setSignaturePropertiesFile(String signaturePropertiesFile)
• void setEncryptionPropertiesFile(String encryptionPropertiesFile)

If no Crypto objects are supplied to StaticSTSProperties, then it will try to locate a properties file using these values, and create a WSS4J Crypto object internally from the properties that are parsed.

1.2) SignatureProperties

A SignatureProperties object can be defined on the STSPropertiesMBean. Note that this is unrelated to the signaturePropertiesFile property of StaticSTSProperties. This class provides some configuration relating to the signing of an issued token, as well as symmetric key generation. It has the following properties:

• boolean useKeyValue - Whether to use a KeyValue or not to refer to a certificate in a signature. The default is false.
• long keySize - The (default) key size to use when generating a symmetric key. The default is 256 bits.
• long minimumKeySize - The minimum key size to use when generating a symmetric key. The requestor can specify a KeySize value to use. The default is 128 bits. 
• long maximumKeySize - The maximum key size to use when generating a symmetric key. The requestor can specify a KeySize value to use. The default is 512 bits.

For example, when the client sends a "KeySize" element to the STS when requesting a SAML Token (and sending a SymmetricKey KeyType URI), the SAMLTokenProvider will check that the requested keysize falls in between the minimum and maximum key sizes defined above. If it does not, then the default key size is used.

2) Request Parsing

The first thing any of the AbstractOperation implementations do on receiving a request is to call some functionality in AbstractOperation to parse the request. This parsing is done by the RequestParser object, which iterates through the objects of the JAXB RequestSecurityTokenType. The request is parsed into two components, TokenRequirements and KeyRequirements, which are available on the RequestParser object and are subsequently passed to the desired TokenProvider/TokenValidator/etc objects.

2.1) TokenRequirements

The TokenRequirements class holds a set of properties that have been extracted and parsed by RequestParser. These properties loosely relate to the token itself, rather than anything to do with keys. The properties that can be set by RequestParser are:

• String tokenType - The desired TokenType URI. This is required if a token is to be issued.
• Element appliesTo - The AppliesTo element that was received in the request. This normally holds a URL that indicates who the recipient of the issued token will be.
• String context - The context attribute of the request.
• ReceivedToken validateTarget - This object holds the contents of a received "ValidateTarget" element, i.e. a token to validate.
• ReceivedToken onBehalfOf - This object holds the contents of a received "OnBehalfOf" element.
• ReceivedToken actAs - This object holds the contents of a received "ActAs" element.
• ReceivedToken cancelTarget - This object holds the contents of a received "CancelTarget" element, i.e. a token to cancel.
• Lifetime lifetime - The requested lifetime of the issued token. This just holds created and expires Strings, that are parsed from the request.
• RequestClaimCollection claims - A collection of requested claims that are parsed from the request. This will be covered later.

The ReceivedToken class mentioned above parses a received token object, which can be a JAXBElement<?> or a DOM Element. If it is a JAXBElement then it must be either a UsernameToken, SecurityTokenReference, or BinarySecurityToken. If it is a reference to a security token in the security header of the request, then this token is retrieved and set as the ReceivedToken instead.

2.2) KeyRequirements

The KeyRequirements class holds a set of properties that have been extracted and parsed by RequestParser. These properties are anything to do with key handling or creation. The properties that can be set by RequestParser are:

• String authenticationType - An optional authentication type URI. This is currently not used in the STS.
• String keyType - The desired KeyType URI.
• long keySize - The requested KeySize to use when generating symmetric keys.
• String signatureAlgorithm - The requested signature algorithm to use when signing an issued token. This is currently not used in the STS.
• String encryptionAlgorithm - The requested encryption algorithm to use when encrypting an issued token.
• String c14nAlgorithm - The requested canonicalization algorithm to use when signing an issued token. This is currently not used in the STS.
• String computedKeyAlgorithm - The computed key algorithm to use when creating a symmetric key.
• String keywrapAlgorithm - The requested KeyWrap algorithm to use when encrypting a symmetric key.
• X509Certificate certificate - A certificate that has been extracted from a "UseKey" element, for use in the SAML case when a PublicKey KeyType URI is specified.
• Entropy entropy - This object holds entropy information extracted from the client request for use in generating a symmetric key. Only BinarySecret elements are currently supported. 

2.3) SecondaryParameters

RequestParser also supports parsing a "SecondaryParameters" element that might be in the request. This could be extracted from the WSDL of a service provider that specifies an IssuedToken policy by the client and sent to the STS as part of the RequestSecurityToken request. Only KeySize, TokenType, KeyType and Claims child elements are currently parsed.