Security Token Caching in Apache CXF 2.6 - part II

This post is the second in a two-part series on how security tokens are cached in Apache CXF 2.6. Part I covered how UsernameToken nonces and Timestamps are cached to prevent replay attacks, using a default caching implementation based on EhCache. In this post I will cover how security tokens are cached in the CXF WS-Security runtime and also in the STS.

1) CXF WS-Security runtime token caching

CXF caches tokens in the security runtime in the following circumstances:

• When the IssuedTokenInterceptorProvider is invoked to obtain an Issued token from an STS.
• When the STSTokenValidator is used to validate a received UsernameToken, BinarySecurityToken or SAML Assertion to an STS.
• When the SecureConversation protocol is used.
• When the WS-Trust SPNEGO protocol is used.
• When tokens are obtained from a Kerberos KDC.

In each of these use-cases, the retrieved token is cached to prevent repeated remote calls to obtain the desired security token. There is no built-in support as yet to cache tokens in the WS-Security layer to prevent repeat validation. Of course this could be easily done by wrapping the existing validators with a custom caching solution.

1.1) SecurityTokens

CXF defines a SecurityToken class which encapsulates all relevant information about a successful authentication event in the security runtime (as defined above). In particular, it contains the following items (amongst others):

• A String identifier of the token. This could be a SAML Assertion Id, the Identifier element of a SecurityContextToken, or the wsu:Id of a UsernameToken, etc.
• The DOM Element that represents that security token.
• Attached and Unattached reference elements for that token that might have been retrieved from an STS.
• A byte[] secret associated with the token.
• An expiration date after which the token is not valid.
• A String TokenType that categorizes the token.
• An X.509 Certificate associated with the token.
• The principal associated with the token.
• A hashcode that represents the security token (normally the hashcode of the underlying WSS4J object).
• An identifier of another SecurityToken that represents a transformed version of this token.

 1.2) TokenStores

CXF defines a TokenStore interface for caching SecurityTokens in the WS-Security runtime module. Prior to CXF 2.6, a simple default HashMap based approach was used to cache security tokens. In CXF 2.6, Ehcache is used to provide a suitable default TokenStore implementation to cache security tokens. Tokens are stored until the expiry date of the token if it exists, provided it does not exceed the maximum storage time of 12 hours. If it exceeds this, or if there is no expiry date provided in the security token, it is cached for the default storage time of 1 hour. If the token is expired then it is not cached. This default storage time is configurable. Note that while Ehcache is a compile time dependency of the WS-Security module in CXF, it can be safely excluded in which case CXF will fall back to use the simple HashMap based cache, unless the user specifically wants to implement an alternative TokenStore implementation and configure this instead.

Apache CXF 2.6 provides support for configuring caching via the following JAX-WS properties:

• "org.apache.cxf.ws.security.tokenstore.TokenStore" - The TokenStore instance to use to cache security tokens. By default this uses the EHCacheTokenStore if Ehcache is available. Otherwise it uses the MemoryTokenStore.
• "ws-security.cache.config.file" - Set this property to point to a configuration file for the underlying caching implementation. By default the cxf-ehcache.xml file in the CXF rt-ws-security module is used.

2) CXF STS token caching

Token caching in the CXF STS has been previously (briefly) covered in the STS documentation. Prior to CXF 2.6, the STS shipped an interface called "STSTokenStore" that contained some additional functionality related to storing SecurityTokens specific to the STS. In CXF 2.6, this interface has been removed, and instead the same TokenStore interface is used as in the security runtime. A TokenStore instance can be set on any of the STS operations (see AbstractOperation), and it will be used for caching in the token providers, validators, etc. The STS ships with two TokenStore implementations, a DefaultInMemoryTokenStore which just wraps the EHCacheTokenStore discussed above, and an implementation based on HazelCast.

Token caching works in different ways depending on where it is used. Both token providers (SAML and SecurityContextTokens) that ship with the STS cache a successfully generated token. When a SAML or SecurityContextToken (or UsernameToken) is received by the STS for validation, it will first check to see whether the token is stored in the cache. If it is then validation is skipped. If it is not, then the TokenValidator will re-validate the token, and store it in the cache if validation is successful. A slight caveat to this behaviour for SAML Tokens is that token validation is only skipped if the token that is stored in the cache originally was signed, as this signature value is used to check to see if the two SAML Tokens are equal. The TokenCanceller implementation for cancelling SecurityContextTokens in the STS removes the token from the cache, if the token is stored in the cache and proof-of-possession passes.

Finally, two significant changes in CXF 2.6.0 concerning caching in the STS relate to the length of time tokens are valid for. Prior to CXF 2.6.0, SecurityContextTokens and SAML Tokens issued by the STS were valid for a default (configurable) value of 5 minutes. In CXF 2.6.0, both tokens are now issued for a default value of 30 minutes, and are stored in the cache for this length of time as a result.