WSO2 Security Token Service is shipped as the resident identity provider of WSO2 Identity Server. The responsibility of a Security Token Service (STS) is to provide tokens that are trusted by a relying party to a requester or service consumer. This topic includes the following sections.
Terms and concepts
The following terminology is used extensively in this topic:
RST: Request for a Security Token. This is the initial request sent by a requester to a STS requesting for a security token. Basically this is a XML tag introduced in the WS-Trust specification.
RSTR: Response for a Security Token Request. This is the response issued by the STS along with a signed security token to the requested party.
- Claim: A statement made about something. For example,
<email>[email protected]</email>is a claim about client’s email address.
- Relying Party: The service provider who trusts the security token service. In the figure below, ‘Web Service’ is considered a relying party. (This is referred to as ‘Relying Party’ since STS is also a service provider as well as a Web service that can be described using WSDL).
How STS works
The following communication paths are illustrated in the above figure using arrows.
- The requester provides credentials to STS and grant a security token by sending a RST to the STS or from a third party application.
- STS validates the client credentials and reply with security token (SAML) to the requester.
- The token is then submitted to the relying party(web service) by the requester in order to access its services.
- The Web service either trusts the issuing security token service or may request a token service to validate the token (or the Web service may validate the token itself).
- Then STS send the decision to the web service.
- If the token is valid then web service allow accessing the protected resource(s).
Configuring the Identity Server to request tokens
You must do the configuration in this section to simulate the scenario with WSO2 identity Server. According to the specification, there are three parties communicating with each other and trusting each other. You can equate each party to the following in order to understand the simulation of the scenario.
- STS: WSO2 Identity Server’s resident identity provider (WSO2 STS)
- Relying Party: Echo Service of WSO2 ESB
- Requester: STS Sample Client
Do the following to configure this.
- Run WSO2 Identity Server on the default port (9443). See the Installation Guide guide for information on how to download and run the product.
- Navigate to the resident identity provider section from Main menu, by clicking Resident under Identity Providers.
- Expand the Security Token Service Configuration section under Inbound Authentication Configuration.
- Set inbound authentication properties by providing the username token to authenticate requesters before issuing tokens. This is done to secure the STS from issuing tokens to every individual who sends a RSTs. To do this, click Apply Security Policy.
- Select UserNameToken (in this security scenario, the requester should submit a username and a password in order to get a security token, as described in WS-Security. By default, the username and password are similar to management console user name and password (“admin”,”admin”).
- Add all user groups from the next window and click Finish.
Running the requester
You can run the STS client without setting the relying party in IS in order to grant a security token. It is not necessary to have a relying party to grant the security token from the STS.
- Download the client from here. The client code is written to send RSTs to a given endpoint defined in the src/main/resources/client.properties file.
- The following is the service URL of the STS if you have started the IS on default port: https://localhost:9443/services/wso2carbon-sts
Without changing other properties you can safely run the client via shell script located at sts-client folder via the following command.
It prints the received SAML assertion on the terminal. You also can view the RST and RSTR on the SOAP tracer of the Management Console in the Identity Server.
Changing the client properties
Client configurations can be modified using the client.properties file, which is located in the src/main/resources directory.
You can change the relying party address in this file. In this instance, the endpoint URL of the WSO2 ESB echo service is provided.
The SAML version of the RST can be changed in this file (depending on the version, the SAML assertion issued from the STS can be modified).
You can also specify the username and password for the UsernameToken security policy.
Renewing received tokens
The SAML 2.0 tokens that are received by the Identity Server can eventually expire according to the following attribute specification. This section defines how to renew the received bearer type SAML 2.0 token using the WSO2 Identity Server’s resident token service.
After the security token service is configured(refer Configuring the Identity Server to request tokens) you can follow the below steps to run the STS client as the token renewer.
Running the client
The client supports command line arguments to select the SAML Version and send token renew requests.
Using the configuration file in src/main/resources/ you can enable the renew property to send renew requests to the server.
You can specify SAML version on the command line. For SAML version 2.0, the following is the command.
For SAML 1.1, the following can be used.
Testing out the scenario
If you want to send a request for a SAML 2.0 security token, then to renew it and validate the renewed token you can do following configurations.
Then run the following for the version of SAML you are using.
You can see the original SAML assertion and the renewed assertion printed on the console.
Here is the response for SAML 2.0 security token request and a renewal response.
Additionally, if the renewed token is validated, you can see the following.