Version 9

    In this document we show how to use PicketLink STS to validate SAML assertions and authenticate WS clients.

    Required software: JDK 6, PicketLink 1.0.3 or superior and PicketLink Trust JBossWS 1.0.0.CR3 or superior.

    Process Overview

    The following picture illustrates the process of using SAML assertions to authenticate clients of EJB applications:


    The client must first obtain the SAML assertion from PicketLink STS by sending a WS-Trust request to the token service. This process usually involves authentication of the client. After obtaining the SAML assertion from the STS, the client includes the assertion in the context of the WS request before invoking any operation. The client side WS handler will take care of including the assertion in the SOAP payload. Upon receiving the invocation, the server side WS handler extracts the assertion and validates it by sending a WS-Trust validate message to the  STS. If the assertion is considered valid by the STS (and the proof of  possession token has been verified if needed), the client is  authenticated.


    On JBoss, the SAML assertion validation process is handled by the SAML2STSLoginModule. It reads properties from a configurable file (specified by the configFile option) and establishes communication with the STS based on these  properties. We will see how a configuration file looks like later on. If  the assertion is valid, a Principal is created using the assertion subject name and if the assertion contains roles, these roles are also extracted and associated with the caller's Subject.

    WS Integration Example

    In this section we present a sample WS application that authenticates  clients by validating their SAML assertions with PicketLink STS. The  deployments for both the WS application and the STS can be found  attached in this document.

    WS Sample App

    Our WS application consists of a simple EJB3 stateless session bean. The session interface can be seen bellow:


    package webservice.test;
    import javax.ejb.Remote;
    import javax.jws.WebService;
    public interface WSTest {
        public void echo(String echo);

    And this is the implementation class:


    package webservice.test;
    import javax.annotation.Resource;
    import javax.ejb.Stateless;
    import javax.jws.WebMethod;
    import javax.jws.WebService;
    import org.jboss.ejb3.annotation.SecurityDomain;
    @EndpointConfig(configName = "SAML WSSecurity Endpoint")
    public class WSTestBean implements WSTest {
        WebServiceContext wsCtx;
        public void echo(String echo) {
            System.out.println("WSTest: " + echo);
            System.out.println("Principal: " + wsCtx.getUserPrincipal());
            System.out.println("Principal.getName(): " + wsCtx.getUserPrincipal().getName());
            System.out.println("isUserInRole('testRole'): " + wsCtx.isUserInRole("testRole"));

    The session requires authentication using the sts security domain and just prints whatever string the client sent and also the Principal on the server side.


    This sts security domain is deployed along with the example wstest.jar file attached here but here is:


    <?xml version="1.0" encoding="UTF-8"?>
    <deployment xmlns="urn:jboss:bean-deployer:2.0">
       <!-- ejb3 test application-policy definition -->
       <application-policy xmlns="urn:jboss:security-beans:1.0" name="sts">
             <login-module code="org.picketlink.identity.federation.bindings.jboss.auth.SAML2STSLoginModule" flag="required">
                <module-option name="configFile"></module-option>
                <module-option name="password-stacking">useFirstPass</module-option>
             <login-module code="" flag="required">
                <module-option name="usersProperties"></module-option>
                <module-option name="rolesProperties"></module-option>
                <module-option name="password-stacking">useFirstPass</module-option>

    The policy defines two login modules: SAML2STSLoginModule and UsersRolesLoginModule. The former will be responsible for validating the assertion with the STS in order to authenticate the client and the latter is responsible for adding roles. To validate the SAML assertions the login module needs information about the STS, like its endpoint URL, service name, port name, etc. This information is supplied by the file:



    The last two properties specify the username and password that will be  used to authenticate the JBoss server to the STS when the WS-Trust  validate message is dispatched. In other words, SAML2STSLoginModule needs to authenticate to the STS when validating the SAML assertions  and these properties specify the username and password that will be used  for that.

    The deployment wstest.jar also contains the files to map roles to the Subject. The file sts-users.properies is just an empty file as authentication is handled by PicketLink's login module. looks like this:




    Notice also that the WS uses a custom endpoint (SAML WSSecurity Endpoint). This endpoint definition must be included in .../deployers/jbossws.deployer/META-INF/standard-jaxws-endpoint-config.xml:


        <config-name>SAML WSSecurity Endpoint</config-name>
            <javaee:protocol-bindings>##SOAP11_HTTP ##SOAP11_HTTP_MTOM</javaee:protocol-bindings>
              <javaee:handler-name>SAML WSSecurity Handler</javaee:handler-name>
              <javaee:handler-name>Recording Handler</javaee:handler-name>


    For this endpoint to work, the library picketlink-trust-jbossws-1.0.0.CR3.jar must be included in .../deployers/jbossws.deployer/. This library is also attached here at the end of the article.

    PicketLink STS

    Our PicketLink STS application is a tweaked version of the picketink-sts.war  file that is available in the PicketLink project downloads page. More  specifically, we created a new security domain for the STS in jboss-web.xml, included an application policy for the new domain that uses the UsersRolesLoginModule to authenticate STS clients, included the users and roles properties files,  and changed the required role in web.xml to STSClient.


    This is the content of the STS web.xml:


    <?xml version="1.0"?>
    <!DOCTYPE web-app PUBLIC
       -//Sun Microsystems, Inc.//DTD Web Application 2.3//EN>







    STS callers must all have the STSClient role in order to send a WS-Trust request to the STS.


    The STS security domain is specified by the jboss-web.xml file:


    <?xml version="1.0" encoding="UTF-8"?>



    The application policy for the sts-domain is defined in the sts-jboss-beans.xml file:


    <?xml version="1.0" encoding="UTF-8"?>

    <deployment xmlns="urn:jboss:bean-deployer:2.0">

       <!-- ejb3 test application-policy definition -->
       <application-policy xmlns="urn:jboss:security-beans:1.0" name="sts-domain">
             <login-module code="" flag="required">
                <module-option name="usersProperties"></module-option>
                <module-option name="rolesProperties"></module-option>



    The specify the username/passwords of the STS callers:




    The specify the roles of the STS callers:




    Notice that the JBoss user represents the JBoss server during the SAML validation process. All other users are the clients of the WS sample  application - they send a message to the STS to acquire a SAML assertion before calling the methods on the WS application.

    Client Application

    STSWSClient just acquires a SAML assertion from PicketLink STS and invokes the echo method of the WS:


    package webservice.test;
    import org.w3c.dom.Element;
    import javax.xml.namespace.QName;
    import org.picketlink.identity.federation.api.wstrust.WSTrustClient.SecurityInfo;
    import org.picketlink.identity.federation.api.wstrust.WSTrustClient;
    import org.picketlink.identity.federation.core.wstrust.WSTrustException;
    import org.picketlink.identity.federation.core.wstrust.plugins.saml.SAMLUtil;
    public class STSWSClient {
        private static String username = "UserA";
        private static String password = "PassA";
        public static void main(String[] args) throws Exception {
            WSTrustClient client = new WSTrustClient("PicketLinkSTS", "PicketLinkSTSPort",
                    new SecurityInfo(username, password));
            Element assertion = null;
            try {
                System.out.println("Invoking token service to get SAML assertion for " + username);
                assertion = client.issueToken(SAMLUtil.SAML2_TOKEN_TYPE);
                System.out.println("SAML assertion for " + username + " successfully obtained!");
            } catch (WSTrustException wse) {
                System.out.println("Unable to issue assertion: " + wse.getMessage());
            URL wsdl = new URL("");
            QName serviceName = new QName("http://test.webservice/", "WSTestBeanService");
            Service service = Service.create(wsdl, serviceName);
            WSTest port = service.getPort(new QName("http://test.webservice/", "WSTestBeanPort"), WSTest.class);
            ((StubExt) port).setConfigName("SAML WSSecurity Client");
            ((BindingProvider) port).getRequestContext().put(SAML2Constants.SAML2_ASSERTION_PROPERTY, assertion);

    As we can see, the assertion is first obtained using the WSTrustClient API. Notice the client then adds the SAML assertion in the SAML2Constants.SAML2_ASSERTION_PROPERTY ("") property in the request context before invoking the echo method.


    The client also uses a custom endpoint configuration (SAML WSSecurity Client) that must be included in the client's META-INF/standard-jaxws-client-config.xml:


    <?xml version="1.0" encoding="UTF-8"?>
    <jaxws-config xmlns="urn:jboss:jaxws-config:2.0" xmlns:xsi="" xmlns:javaee=""
      xsi:schemaLocation="urn:jboss:jaxws-config:2.0 schema/jaxws-config_2_0.xsd">
        <config-name>SAML WSSecurity Client</config-name>
            <javaee:protocol-bindings>##SOAP11_HTTP ##SOAP11_HTTP_MTOM</javaee:protocol-bindings>
              <javaee:handler-name>SAML WSSecurity Client Handler</javaee:handler-name>

    Deploying and Running the EJB3 Sample Application on JBoss AS5

    In  order to get the sample application running you must first install the  PicketLink jar files on JBoss. This is accomplished by copying picketlink-fed-2.0.0-SNAPSHOT.jar and picketlink-bindings-jboss-2.0.0-SNAPSHOT.jar (both attached in this document) files to the $JBOSS_HOME/server/<config>/lib folder. After installing the required PicketLink libs you must copy the wstest.jar and picketlink-sts-1.0.0.war to $JBOSS_HOME/server/<config>/deploy.


    After  copying the required PicketLink jars and deploying the sample  application and the STS war, start your JBoss instance. If everything  is ok, you should see something like the following in the log:


    16:36:30,062 INFO  [JBossASKernel] Created KernelDeployment for: wstest.jar
    16:36:30,069 INFO  [JBossASKernel] installing bean: jboss.j2ee:jar=wstest.jar,name=WSTestBean,service=EJB3
    16:36:30,069 INFO  [JBossASKernel]   with dependencies:
    16:36:30,069 INFO  [JBossASKernel]   and demands:
    16:36:30,069 INFO  [JBossASKernel]      jboss.ejb:service=EJBTimerService
    16:36:30,070 INFO  [JBossASKernel]   and supplies:
    16:36:30,070 INFO  [JBossASKernel]      Class:webservice.test.WSTest
    16:36:30,070 INFO  [JBossASKernel]      jndi:WSTestBean/remote
    16:36:30,070 INFO  [JBossASKernel]      jndi:WSTestBean/remote-webservice.test.WSTest
    16:36:30,070 INFO  [JBossASKernel] Added bean(jboss.j2ee:jar=wstest.jar,name=WSTestBean,service=EJB3) to KernelDeployment of: wstest.jar
    16:36:30,214 INFO  [SessionSpecContainer] Starting jboss.j2ee:jar=wstest.jar,name=WSTestBean,service=EJB3
    16:36:30,227 INFO  [EJBContainer] STARTED EJB: webservice.test.WSTestBean ejbName: WSTestBean
    16:36:30,354 INFO  [JndiSessionRegistrarBase] Binding the following Entries in Global JNDI:
            WSTestBean/remote - EJB3.x Default Remote Business Interface
            WSTestBean/remote-webservice.test.WSTest - EJB3.x Remote Business Interface
    16:36:30,687 INFO  [DefaultEndpointRegistry] register:,endpoint=WSTestBean
    16:36:31,924 INFO  [WSDLFilePublisher] WSDL published to: file:/opt/jboss-eap-5.0/jboss-as/server/wstest/data/wsdl/wstest.jar/WSTestBeanService7960307186338997650.wsdl
    16:36:32,048 INFO  [TomcatDeployment] deploy, ctxPath=/wstest
    16:36:32,102 WARNING [config] Unable to process deployment descriptor for context '/wstest'
    16:36:32,136 INFO  [config] Initializing Mojarra (1.2_13-b01-FCS) for context '/wstest'
    16:36:35,856 INFO  [DefaultEndpointRegistry] register:,endpoint=PicketLinkSTS
    16:36:35,936 INFO  [TomcatDeployment] deploy, ctxPath=/picketlink-sts-1.0.0
    16:36:36,120 INFO  [WSDLFilePublisher] WSDL published to: file:/opt/jboss-eap-5.0/jboss-as/server/wstest/data/wsdl/picketlink-sts-1.0.0.war/PicketLinkSTS.wsdl

    To run the client application some JBoss' libraries must be included in the classpath:


    java -Djava.endorsed.dirs=/opt/jboss-eap-5.0/jboss-as/lib/endorsed -classpath /opt/jboss-eap-5.0/jboss-as/client/jbossall-client.jar:/opt/jboss-eap-5.0/jboss-as/client/jbossws-native-core.jar:/opt/jboss-eap-5.0/jboss-as/client/jbossws-spi.jar:/opt/jboss-eap-5.0/jboss-as/client/jbossws-common.jar:/opt/jboss-eap-5.0/jboss-as/client/jbossws-native-jaxrpc.jar:/opt/jboss-eap-5.0/jboss-as/client/mail.jar:../lib/picketlink-bindings-jboss-2.0.0-SNAPSHOT.jar:../lib/picketlink-fed-2.0.0-SNAPSHOT.jar:../lib/picketlink-trust-jbossws-1.0.0.CR3.jar:/opt/jboss-eap-5.0/jboss-as/client/jboss-xml-binding.jar:/opt/jboss-eap-5.0/jboss-as/client/jaxb-impl.jar:/opt/jboss-eap-5.0/jboss-as/client/wsdl4j.jar:../lib/wstest.jar:. webservice.test.STSWSClient

    If everything has been configured and deployed correctly, you should see this output in the client's side:


    Invoking token service to get SAML assertion for UserA
    SAML assertion for UserA successfully obtained!

    And this in the server's side:


    15:56:19,040 INFO  [PicketLinkSTS] Loading STS configuration
    15:56:19,145 INFO  [PicketLinkSTS] picketlink-sts.xml configuration file loaded
    15:56:21,648 INFO  [STDOUT] WSTest: Test
    15:56:21,658 INFO  [STDOUT] Principal: org.picketlink.identity.federation.bindings.jboss.subject.PicketLinkPrincipal@4e39dd5
    15:56:21,658 INFO  [STDOUT] Principal.getName(): UserA
    15:56:21,669 INFO  [STDOUT] isUserInRole('testRole'): true

    As we can see, the echo method was invoked and the Principal is an instance of PicketLinkPrincipal (meaning the authentication was successful). Invocation of the web service was successful and also WebServiceContext.isUserInRole("testRole") returns true meaning authorization was also successful.


    Special thanks to David Boeren for helping out with the WS client part.