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.
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.
- void setSignaturePropertiesFile(String signaturePropertiesFile)
- void setEncryptionPropertiesFile(String encryptionPropertiesFile)
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.
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.
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 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.
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.