Token Cancellation

SecurityTokens are cancelled in the STS using the TokenCanceller interface. This interface is very similar to the TokenProvider and TokenValidator interfaces. It contains three methods:

• void setVerifyProofOfPossession(boolean verifyProofOfPossession) - Whether to enable or disable proof-of-possession verification.
• boolean canHandleToken(ReceivedToken cancelTarget) - Whether this TokenCanceller implementation can cancel the given token
• TokenCancellerResponse cancelToken(TokenCancellerParameters tokenParameters) - Cancel a token using the given parameters

A client can cancel a security token using the STS by invoking the cancel operation. Assuming that the client request is authenticated and well-formed, the STS will iterate through a list of TokenCanceller implementations to see if they can "handle" the received token. If they can, then the implementation is used to cancel the received security token, and the cancellation result is returned to the client. The STS currently ships with a single TokenCanceller implementation, which can cancel SecurityContextTokens that were issued by the STS. Before looking at this implementation, let's look at the "cancelToken" operation in more detail. This method takes a TokenCancellerParameters instance, and returns a TokenCancellerResponse object.

The TokenCancellerParameters class is nothing more than a collection of configuration properties to use in cancelling the token, which are populated by the STS operations using information collated from the request, or static configuration, etc. The properties of the TokenCancellerParameters are:

• STSPropertiesMBean stsProperties - A configuration MBean that holds the configuration for the STS as a whole.
• Principal principal - The current client Principal object
• WebServiceContext webServiceContext - The current web service context object. This allows access to the client request.
• KeyRequirements keyRequirements - A set of configuration properties relating to keys.
• TokenRequirements tokenRequirements - A set of configuration properties relating to the token.
• TokenStore tokenStore - A cache used to retrieve tokens.
• ReceivedToken token - Represents the token that was received for cancellation.

The cancelToken method returns an object of type TokenCancellerResponse. Similar to the TokenCancellerParameters object, this just holds a collection of objects that is parsed by the STS operation to construct a response to the client. It currently only has a single property:

• ReceivedToken token - Represents the token that was received for cancellation. Its state will be STATE.CANCELLED if token cancellation was successful.

The STS ships with a single implementation of the TokenCanceller interface, namely the SCTCanceller. The SCTCanceller is used to cancel a token known as a SecurityContextToken, that is defined in the WS-SecureConversation specification. The SCTProvider and the SCTValidator were covered previously. A SecurityContextToken essentially consists of a String Identifier which is associated with a particular secret key. The SCTCanceller can cancel a SecurityContextToken in either of the following namespaces:

• http://schemas.xmlsoap.org/ws/2005/02/sc/
• http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512

Recall that the SCTValidator validates a received SecurityContextToken by checking to see whether it is stored in the cache. Therefore it is a requirement to configure a cache for the STS if you want to validate SecurityContextTokens. The same applies for the SCTCanceller. A received SecurityContextToken is successfully cancelled only if it is stored in the cache and is removed from the cache without any errors. This generally implies that the STS must have previously issued the SecurityContextToken and stored it in the cache, unless the STS is sharing a distributed cache with other STS instances.

Recall that the TokenCanceller interface has a setVerifyProofOfPossession method which defines whether proof-of-possession is required or not to cancel a security token. The default value for the SCTCanceller is true.

This means that for the client to successfully cancel a SecurityContextToken it must prove to the STS that it knows the secret key associated with that SecurityContextToken. The client must do this by signing some portion of the request with the same secret key that the SCTCanceller retrieves from the security token stored in the cache.