How To: Configure the Identity Server to Issue Security Tokens

This topic expands on how to access the Security Token Service (STS) in the WSO2 Identity Server programmatically by using the instructions below.

Understanding different confirmation methods

Subject confirmation methods are how a relying party (or the end service) can make sure that a particular security token issued by a Security Token Service (STS), is brought by the legitimate subject. If this is not done, a third party can take the token from the wire and send any request it wants including that token. As a result, the relying party may trust that illegitimate third party.

The following are the three methods of confirmation.

Bearer: This is actually not a confirmation method as subject confirmation is not really needed. The relying party simply trusts whoever brings the token.
Holder of Key (HoK):
- STS includes the public key of the client inside the security token and signs it.
- Before sending the token, the client itself signs the request.
- When the relying party receives the token, it first validates the STS signature and then validates the client's signature with the public key embedded inside the token.
Sender Vouches:
- Rather than authenticating with the STS, the client authenticates with an intermediate service.
- The intermediary gets the security token from the STS and signs the request before sending it to the relying party.
- The relying party trusts both the intermediary and the STS. So, it validates both of them.

Configuring STS to issue security tokens

Start the WSO2 Identity Server.
Log in as an admin to access the management console.
Do the following steps if you are using a Holder of Key confirmation method. See here for more information.
1. Navigate to the Service Providers section by clicking Add in the Main menu under Service Providers.
2. Add a Service Provider Name and Description and click Register.
3. In the resulting page, expand the Inbound Authentication Configuration and the WS-Trust Security Token Service Configuration sections. Click Configure.
4. Enter the trusted relying parties and upload the public certificate of the trusted relying party (against its end-point).
  
  These relying parties will accept security tokens from the Identity Server.
  
  The tokens issued are encrypted using the public key of the trusted relying party. Accordingly, even the client who obtains the token to send to the RP has no visibility to the included token.
5. Click Apply.
Now, apply the security to the STS. To do this, do the following.

This is to be done for both the Holder of Key confirmation method and the Bearer confirmation method. You must provide UsernameToken-based security, which means that the client should have a valid user account with the Identity Server to obtain a token from the STS.
1. In the management console, click List under Identity Providers in the Main menu.
2. Click Resident Identity Provider.
3. In the resulting page, expand the Inbound Authentication Configuration section and the WS-Trust / WS-Federation (Passive) Configuration section.
4. Click Apply Security Policy to configure security and go through the wizard.
Configure security and go through the wizard by using the following steps.
1. Select Yes from the Enable Security? dropdown.
2. Select UsernameToken from the Basic Scenarios list.
3. Click Next.
4. Choose Internal/everyone from the User Groups list.
5. Click Finish.

This is all you need to do to configure Identity Server STS to issue security tokens.

The client code

package org.apache.ws.axis2;

    import org.apache.axiom.om.OMAbstractFactory;
    import org.apache.axiom.om.OMElement;
    import org.apache.axiom.om.OMFactory;
    import org.apache.axiom.om.impl.builder.StAXOMBuilder;
    import org.apache.axis2.context.ConfigurationContext;
    import org.apache.axis2.context.ConfigurationContextFactory;
    import org.apache.neethi.Policy;
    import org.apache.neethi.PolicyEngine;
    import org.apache.rahas.RahasConstants;
    import org.apache.rahas.Token;
    import org.apache.rahas.TrustUtil;
    import org.apache.rahas.client.STSClient;
    import org.apache.rampart.policy.model.RampartConfig;
    import org.apache.ws.secpolicy.Constants;
    import org.opensaml.XML;

    public class IdentitySTSClient {

    /**
    * @param args
    */

    final static String RELYING_PARTY_SERVICE_EPR = "http://192.168.1.2:8280/services/echo";
    final static String STS_EPR = "https://localhost:9443/services/wso2carbon-sts";

    /**
    * @param args
    * @throws Exception
    */
    public static void main(String[] args) throws Exception {
    ConfigurationContext confContext = null;
    Policy stsPolicy = null;
    STSClient stsClient = null;
    Policy servicePolicy = null;
    Token responseToken = null;
    String trustStore = null;

    // You need to import the Identity Server, public certificate to this key store.
    trustStore = "clientkeystore.jks";
    // We are accessing STS over HTTPS - so need to set trustStore parameters.
    System.setProperty("javax.net.ssl.trustStore", trustStore);
    System.setProperty("javax.net.ssl.trustStorePassword", "wso2carbon");

    // Create configuration context - you will have Rampart module engaged in the client.axis2.xml
    confContext = ConfigurationContextFactory.createConfigurationContextFromFileSystem("repo","repo/conf/client.axis2.xml");

    stsClient = new STSClient(confContext);

    stsClient.setRstTemplate(getRSTTemplate());
    stsClient.setAction(RahasConstants.WST_NS_05_02 + RahasConstants.RST_ACTION_SCT);

    // This is the security policy we applied to Identity Server STS.
    // You can see it by https://[IDENTITY_SERVER]/services/wso2carbon-sts?wsdl
    stsPolicy = loadPolicy("sts.policy.xml");

    // This is the security of the relying party web service.
    // This policy will accept a security token issued from Identity Server STS
    servicePolicy = loadPolicy("service.policy.xml");

    responseToken = stsClient.requestSecurityToken(servicePolicy, STS_EPR, stsPolicy, RELYING_PARTY_SERVICE_EPR);

    System.out.println(responseToken.getToken());

    }

    private static Policy loadPolicy(String xmlPath) throws Exception {
    StAXOMBuilder builder = null;
    Policy policy = null;
    RampartConfig rc = null;
    builder = new StAXOMBuilder(xmlPath);
    policy = PolicyEngine.getPolicy(builder.getDocumentElement());
    rc = new RampartConfig();
    rc.setUser("admin");
    // You need to have password call-back class to provide the user password
    rc.setPwCbClass(PWCBHandler.class.getName());
    policy.addAssertion(rc);
    return policy;
    }

    private static OMElement getRSTTemplate() throws Exception {
    OMFactory fac = OMAbstractFactory.getOMFactory();
    OMElement elem = fac.createOMElement(Constants.RST_TEMPLATE);
    TrustUtil.createTokenTypeElement(RahasConstants.VERSION_05_02, elem).setText(XML.SAML_NS);
    TrustUtil.createKeyTypeElement(RahasConstants.VERSION_05_02, elem,
    RahasConstants.KEY_TYPE_SYMM_KEY);
    TrustUtil.createKeySizeElement(RahasConstants.VERSION_05_02, elem, 256);
    return elem;
    }
    }