The Security Token Service

The Security Token Service (STS) is deployed by default in the Data Services Server. You can see this by selecting Services > List menu and viewing the Deployed Services page. 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 issuing, renewing, canceling and validating functions done.

A security token is an XML payload 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 needs to access a service that 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 request First Name, Last Name and the Age in the security token in order to access it.

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

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 client's name and age to grant him access
• The client requests a security token from the STS
• The STS requests the client to validate his/her 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

A security token service issues tokens only to clients it trusts. Trusted relationships 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 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) etc.

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 not transparent to the client.

Security token service provided by WSO2

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

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

Follow the steps below to configure wso2carbon-sts.

1. Log in to the management console and select Services > List under the Main menu. 
2. In the Deployed Services window that opens, you can see wso2carbon-sts listed.
3. Click on wso2carbon-sts to open its dashboard.
4. In the dashboard, click Configure STS.
    
5. The STS Configuration window appears. Enter the relying parties you trust. In other words, mention which relying parties can accept security tokens from the STS Also, upload the public certificate of the trusted relying party against its endpoint. 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.