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 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.
