WS-Trust with Fresh Banana Service

This blog post explains the interactions of an STS client with an STS.

STS stands for Security Token Service.

What does an STS do ?

A security token service [STS] implements the protocol defined as per the WS-Trust specification.

WS-Trust specification defines message formats and message exchange patterns for; issuing, renewing, canceling and validating security tokens.

A given security token service provides one or more of these capabilities.

So - the client interacts with the STS - to get done any of the above functionalities, that is, issuing, renewing, canceling and validating security tokens.

In fact - why the client needs a security token...?

Client needs a security token - because it needs to access a service which requires a security token issued from a specific token issuer [STS].

Client can access the service, only if - client provides the security token issued from the specified token provider.

I guess - now we are clear about, what does an STS do and why does a client need a security token.

Wait a minute... still we don't know what is meant by the 'security token' ?

A security token is an XML payload - as requested by the relying party service.

If it is a SAML token then it represents a collection of claims in the form of Assertions.....

A claim is a statement made about a client, service or other resource (e.g. name, identity, key, group, privilege, capability, etc.)....

The service can say, in its service policy - what claims it requires... so, the client has to have those in the security token.

For example, the service can say - "if you want to access me, you should have your First Name, Last Name and the Age in the security token - if NOT don't even think about me.."

Now - we know what a security token is - it is issued by the STS, with the claims required by the service.

Before we dig in to further details - let's listen to a discussion between - the client, service and the STS.

Client / Service

Client : "Hey I want to access your Fresh-Banana service.."

Service: "Are you nuts.. Where is your security token..?"

Client: "Poh... you've gone mad - anyway tell me from where you want me to bring the token..."

Service: "Heh.. heh.. I know you from good old days - you never lied me.. ha :D - never expect to trust you again.. :P Bring the token from your Master if you want to have a Fresh-Banana, else - hmmm... you know what to do.. ;) '

Client: "Catch you later.. now tell me what you want to have in the security token.."

Service: "You got to have your Name and Age - we don't issue Fresh Banana's for baby monkeys..LOL :)"

Client / STS

Client: 'Hey man.. I need a token to access Fresh-Banana service - I know you can do it - can I have one...?'

STS: 'You got to be kidding.. I don't issue security tokens to monkeys I never know... "

Client: "Check this out man [monkey wags its tail]... I am your monkey..."

STS: "That looks fine.. Here's your token... this is valid only for 2 days..."

Client: "Thanks buddy.. you are quite smart ;) "

Client / Service

Client: "Hey man... I am back with the token... Give me my fresh banana .... Can't waste anymore time..."

Service: "Ho...ho... looks like token is fine.. enjoy the Fresh Banana..."

I guess, the above explains the information flow between the three parties involved in the trust relationship - at a very high-level.
Now, let's dig in to the interaction between the client and the STS - the rest we'll look in to in a future blog post.

Security token service[Monkey man] issues tokens only for client [The Monkey] it trusts.

Trust relationship between the client and the STS can be established via user name/password or certificates or via any other mean defined by the STS [Monkey was able to prove itself to the monkey man]

STS communicates this [the form of trust relationship] via its security policy as per WS-Security Policy.

For example, STS can enforce all its clients to sign the Request for the Security Token [RST] - or else - prove themselves via UsernameToken [that is user name / password].

The bottom line is - STS knows the client well and it knows how to authenticate the client.

As the first step - the client prepares the RST [ this is how we call the Request - under the terminology defined in WS-Trust spec] - and sends a web service request, secured to be compliant with the security policy of the STS.

This RST also includes the required claims for the response - or the security token.

What else the RST includes?

- The end point reference [EPR] of the service, where the client goes to use this token
- The desired valid time for the expecting security token
- Token type of the expecting security token [ SAML 1.1 / SAML 2.0]
- and more...

Lets discuss a simple flow between the client and the STS - without being bound to any heavy technical jargons - defined in the spec.

Once client sends the RST to the STS - STS will first validate the authenticity of the requester - by validating the request against the defined security policy of STS.

Then it will start preparing the security token [Request Security Token Response].

STS will first include all the requested claims - and will sign it with its private key .

Then - it finds the public certificate of the service which this token will be sent by the client and will encrypt the token with it.

Now, this security token is opaque to the requester - or the client - since it's encrypted with service's public key.

But - still the client needs to know way to refer to that token.
For - example, if client wants to cancel or renew the token, the it has to know which token its referring to.

To help the client with the above, STS adds two extra elements to the RSTR - which are visible to the client.

These elements are known as RequestedAttachedReference and RequestedUnattachedReference.

If client wants to refer the token within the SOAP message it self - the it will use the id from RequestedAttachedReference - if it wants to refer the token of the message itself, then it will be the RequestedUnattachedReference.

For example, when issuing a token, the STS caches the issued token in its side. So - if the client wants to Renew the token, then this can be done by client sending the id from the RequestedUnattachedReference to the STS.

Apart from the above - STS also adds another element called, Proof-of-Possession Token.

A proof-of-possession (POP) token is a security token that contains secret data that can be used to demonstrate authorized use of an associated security token..

The POP token is visible to the requester.

Proof of possession is needed when the client does not provide the public key to use and signs (authenticates) this using the corresponding private key, thereby proving possession.

Further, the STS includes a KeyInfo element in to Security Token, that can be used to validate the proof of possession token. This element is only visible to the relying party service.

Now, the STS will send the encrypted token to client.
This approach we discussed is known as Holder of Key approach - we'll discuss the other approaches in a future post.

[Thanks a lot Chanaka for the images...]