The Security Token Service

STS stands for Security Token Service. A security token service implements the protocol defined according to 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. The client interacts with the STS to get any of the above functionalities done; namely, issuing, renewing, canceling and validating security tokens.

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 another resource (e.g. name, identity, key, group, privilege, capability, etc.) A client who need to access a service which requires a security token issued from a specific token issuer [STS] should provide a security token issued from the specified token provider. Any service can state in its service policy, what claims it requires in order to be granted access. The client needs those claims fulfilled in the security token. For example, the service can state in simple language, "if you want to access me, you should have your First Name, Last Name and the Age in the security token. If not access will be denied."

In summery, a security token is issued by the STS with the claims required by the service.

The Interaction between the client and the STS.

The interaction between a client who wants to access a service and the STS is given in the example below.

Client wants to access service A.
Service A requests a security token with the clients name and age to grant him access.
The the client requests a security token from the STS.
The STS requests the client to validate his identity via username token.
The client provides his username/password.
The STS recognizes the client and provides a token.
The client presents the security token to the service and gains access to it.

As shown in this example, a security token service issues tokens only to client it trusts. Trusted relationship between the client and the STS can be established via user name/password, certificates or any other means defined by the STS. The STS communicates the form of trust relationship via its security policy as per WS-Security Policy.

For example, an 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). First, the client prepares the RST (the Request according to the terminology defined in the WS-Trust specification) 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. It also includes:

The end point reference (EPR) of the service, where the client uses 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.

Once a client sends the RST to the STS, the STS first checks the authenticity of the requester by validating the request against the defined security policy of the STS. It then starts preparing the security token (Request Security Token Response). The STS includes all the requested claims and signs the token with its private key . It then finds the public certificate of the service to which this token will be sent by the client and encrypts the token with the certificate. The encrypted security token is opaque to the client.

STS in a Running Carbon Server

The security token service offered by WSO2 is wso2carbon-sts. The STS facilitated is provided by the following feature, which is bundled by default in all WSO2 service hosting products.

Name: STS Feature
Identifier: org.wso2.carbon.sts.feature.group

If this feature is not available by default in the product you are using, you can install it by following the instructions in section Feature Management.

Follow the instructions below to configure the STS service.

1. Log on to the product's management console and select "List" under "Services."

2. You can see the STS deployed.

3. The service dashboard appears. Click on the "Configure STS" link.

4. The "STS Configuration" page appears. Enter the relying parties you trust. In other words, mention which relying parties can accept security tokens from the STS.

You need to upload the public certificate of the trusted relying party against its end point. For example,

Tokens are encrypted by the public key of the trusted relying party. Even the client who obtains the token to send to the relying party has no visibility to the included token.

5. The trusted service is added to the STS. You can remove it by clicking on the icon next to it or continue to add more trusted services.