Red Hat

Developer Materials

WS-Trust Security Token Service

  • Author:
  • Contributors: Sande Gilda
  • Published: Nov 25, 2013
  • Level: Advanced
  • Technologies:WS-Trust, SAML
  • Target Product:EAP

What is it?

This example demonstrates how to deploy a fully compliant WS-Trust Security Token Service (STS).

WS-Trust extends the WS-Security specification to allow the issuance, renewal, and validation of security tokens. Many WS-Trust functions center around the use of a "Security Token Service", or STS. The STS is contacted to obtain security tokens that are used to create messages to talk to the services. The primary use of the STS is to acquire SAML tokens used to talk to the service. The STS also plays an important role when you need to propagate credentials between different layers, for example, the web and service layer.

PicketLink also supports different token providers, which means you can provide your own custom security tokens.

Note: This quickstart is not a fully functional application. It is a JAX-WS Endpoint based on PicketLink's WS-Trust implementation, which by default, allows you to issue, renew and validate SAML assertions. It is a service intended to be called by other applications.

How to use this quickstart

This quickstart is preconfigured to use the "picketlink-sts" security domain. By default, the STS is protected to only allow requests from authenticated users. All users and also their roles, are defined in two properties files:

    Users: src/main/resources/users.properties
    Roles: src/main/resources/roles.properties

You can view the WSDL for the STS at the following URL: http://localhost:8080/picketlink-sts?wsdl.

From a JAX-WS perspective, you can use any tool you want to start using the STS. Below is an example of a SOAP envelope asking the STS to issue a SAML v2.0 Assertion:

    <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:picketlink:identity-federation:sts">
        <soap:Header/>
        <soap:Body>
            <wst:RequestSecurityToken xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
                <wst:TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</wst:TokenType>
                <wst:RequestType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue</wst:RequestType>
            </wst:RequestSecurityToken>
        </soap:Body>
    </soap:Envelope>

There is a simple example of WS-Trush client usage provided by PicketLink. To use this example deploy PicketLink STS as described below and run the mvn exec:java command. The assertion from PicketLink STS is printed to the console. This process is described in detail below in the section entitled "Access the Application".

Note: This example is not suitable for production use. You must change the application security to comply with your organization's standards.

Where to Find Additional Information

System requirements

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 6.1 or later.

All you need to build this project is Java 6.0 (Java SDK 1.6) or later, Maven 3.0 or later.

Configure Maven

If you have not yet done so, you must Configure Maven before testing the quickstarts.

Configure the JBoss Server

NOTE - Before you begin:

  1. If it is running, stop the JBoss server.
  2. Backup the file: JBOSS_HOME/standalone/configuration/standalone.xml
  3. After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.

Configure the Security Domain Using the JBoss CLI

  1. Start the JBoss server by typing the following:

     For Linux:  JBOSS_HOME/bin/standalone.sh
     For Windows:  JBOSS_HOME\bin\standalone.bat
    
  2. Open a new command line, navigate to the root directory of this quickstart, and run the following command, replacing JBOSS_HOME with the path to your server:

     For Linux: JBOSS_HOME/bin/jboss-cli.sh --file=configure-security-domain.cli 
     For Windows: JBOSS_HOME\bin\jboss-cli.bat --file=configure-security-domain.cli 
    

    If you are running the controller on different host, pass the following argument, replacing HOST_NAME and PORT_NUMBER with the correct values:

     --controller=HOST_NAME:PORT_NUMBER You should see the following result when you run the script:
       
     #1 /subsystem=security/security-domain=picketlink-sts:add
     #2 /subsystem=security/security-domain=picketlink-sts/authentication=classic:add(  login-modules=[  {  "code" => "UsersRoles ",  "flag" => "required",  "module-options" => [  "usersProperties"=>"users.properties",  "rolesProperties"=>"roles.properties"  ]  }  ]  )
     The batch executed successfully
    

    The batch file also restarts the server.

Start the JBoss Server

If you do not have a running server:

  1. Open a command line and navigate to the root of the JBoss server directory.
  2. The following shows the command line to start the server:

     For Linux:   JBOSS_HOME/bin/standalone.sh
     For Windows: JBOSS_HOME\bin\standalone.bat
    

Build and Deploy the Quickstart

NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See Build and Deploy the Quickstarts for complete instructions and additional options.

  1. Make sure you have started the JBoss Server as described above.
  2. Open a command line and navigate to the root directory of this quickstart.
  3. Type this command to build and deploy the archive:

     mvn clean install jboss-as:deploy
    
  4. This deploys target/jboss-picketlink-sts.war to the running instance of the server.

Access the Application

You can test the service as follows:

  1. Open a command line and navigate to the root directory of this quickstart.
  2. Type the following command:

     mvn exec:java
    
  3. You should see a <saml:Assertion assertion from PicketLink STS along with a BUILD SUCCESS printed to the console.

     Invoking token service to get SAML assertion for user:UserA with password:PassA
     SAML assertion for user:UserA successfully obtained!
     <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="ID_79157aa6-38ab-4e5e-a562-78bade9ffb82" IssueInstant="2013-11-18T18:19:35.955Z" Version="2.0"><saml:Issuer>PicketLinkSTS</saml:Issuer><dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:SignedInfo><dsig:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#WithComments"/><dsig:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/><dsig:Reference URI="#ID_79157aa6-38ab-4e5e-a562-78bade9ffb82"><dsig:Transforms><dsig:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/><dsig:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></dsig:Transforms><dsig:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/><dsig:DigestValue>7LaVacKTsP6wnuNlsQ6KASNDgdE=</dsig:DigestValue></dsig:Reference></dsig:SignedInfo><dsig:SignatureValue>jiyC63KG65d019PY7ThZzyojiU6iJMAr9N39uqrPr3HBGPfW7JjwFH9tahsFKjgoQQH7ToRLKZJKvm12TmDured+s+5VyI+Py6TsDiaQCRnNSeARvYdXFwNCA1D8Sx0xDkXKWpgB3YZenBV6U0IZtmAa5CxXFKmdqxEzHweAPq0=</dsig:SignatureValue><dsig:KeyInfo><dsig:KeyValue><dsig:RSAKeyValue><dsig:Modulus>suGIyhVTbFvDwZdx8Av62zmP+aGOlsBN8WUE3eEEcDtOIZgO78SImMQGwB2C0eIVMhiLRzVPqoW1dCPAveTm653zHOmubaps1fY0lLJDSZbTbhjeYhoQmmaBro/tDpVw5lKJns2qVnMuRK19ju2dxpKwlYGGtrP5VQv00dfNPbs=</dsig:Modulus><dsig:Exponent>AQAB</dsig:Exponent></dsig:RSAKeyValue></dsig:KeyValue></dsig:KeyInfo></dsig:Signature><saml:Subject><saml:NameID NameQualifier="urn:picketlink:identity-federation">UserA</saml:NameID><saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"/></saml:Subject><saml:Conditions NotBefore="2013-11-18T18:19:35.955Z" NotOnOrAfter="2013-11-18T20:19:35.955Z"/><saml:AuthnStatement AuthnInstant="2013-11-18T18:19:35.955Z"><saml:AuthnContext><saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:cm:bearer</saml:AuthnContextClassRef></saml:AuthnContext></saml:AuthnStatement></saml:Assertion>
     [INFO] ------------------------------------------------------------------------
     [INFO] BUILD SUCCESS
     [INFO] ------------------------------------------------------------------------
     [INFO] Total time: 1.404s
     [INFO] Finished at: Mon Nov 18 13:19:36 EST 2013
     [INFO] Final Memory: 7M/146M
     [INFO] ------------------------------------------------------------------------
    

Undeploy and Remove the Security Domain Configuration

Undeploy and Remove the Security Domain Using the JBoss CLI

You can undeploy the quickstart and remove the security domain configuration in one easy step using the undeploy-and-remove-security-domain.cli script located in the root directory of this quickstart.

  1. Open a new command line, navigate to the root directory of this quickstart.
  2. Run the following command, replacing JBOSS_HOME with the path to your server:

     For Linux: JBOSS_HOME/bin/jboss-cli.sh --file=undeploy-and-remove-security-domain.cli
     For Windows: JBOSS_HOME\bin\jboss-cli.bat --file=undeploy-and-remove-security-domain.cli You should see the following result when you run the script:
       
     {"outcome" => "success"}
    

Undeploy the quickstart and Remove the Security Domain Manually

  1. Make sure you have started the JBoss Server as described above.
  2. Open a command line and navigate to the root directory of this quickstart.
  3. When you are finished testing, type this command to undeploy the archive:

     mvn jboss-as:undeploy
    
  4. Stop the JBoss server.
  5. Replace the JBOSS_HOME/standalone/configuration/standalone.xml file with the back-up copy of the file.

Run the Quickstart in JBoss Developer Studio or Eclipse

You can also start the server and deploy the quickstarts from Eclipse using JBoss tools. For more information, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts

Debug the Application

If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.

  mvn dependency:sources
  mvn dependency:resolve -Dclassifier=javadoc

Recent Changelog

  • Nov 25, 2013(Sande Gilda):picketlink sts README.md Removed ending forward slash in WSDL URL
  • Nov 18, 2013(Sande Gilda):Fix typos in picketlink sts README file
  • Nov 18, 2013(Peter Skopek):BZ 1030937 Adding proper testing example to check if PicketLink STS
  • Nov 8, 2013(Sande Gilda):Bz1028448 Add spaces to end of metadata so it renders with a line break in HTML
  • Nov 4, 2013(Sande Gilda):Bz10254987 Clarify instructions for picketlink sts quickstart
  • Oct 11, 2013(Peter Skopek):BZ 1011975 Adding picketlink sts.war as quickstart
Avg:
Your Rating: