Introduction
The following article describes how to enforce authentication with SAML and authorization with XACML on a JAX-WS Web Service on JBoss Enterprise Application Platform with Picketlink. I combined several articles listed in the References section to make this one demonstration. The source code is on github.Products
JBoss Enterprise Application Platform 5.2.0
Picketlink 2.0.1
JDK 1.7
JBoss Developer Studio 6
Note: Future updates will the latest versions of EAP/Picketlink/Fuse and moving the projects to maven.
Server Project
Contains the Web Service to take the assertion out of the wsse, validate it, verify authorization and process the request. The files contained in the project are the SAML2ServerHandler.java, WSTest.java, WSTestBean.java, jboss.xml, jbossxacml-config.xml,standard-jaxws-endpoint-config.xml,xacml-policy.xml,sts-config.properties,sts-roles.properties,sts-security-domain-jboss-beans.xml,sts-users.properties. All the XML is displayed to the console.
Client Project
Contains the Client to get an assertion from the STS, add it to the wsse in the SOAP header and call the test web service. The files contained in the project are the STSWSClient.java, SAML2ClientHandler.java and standard-jaxws-client-config.xml. All the XML is displayed to the console.
Architecture Overview
Web Service (Server Side)
In our sample we created a simple EJB3 stateless session bean called WSTest. The implementation class in our sample is WSTestBean.
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. The security domain is within the deployment for authentication and authorization. The application-policy defines two (SAML2STSLoginModule and UsersRolesLoginModules) login modules and one (XACMLAuthorizationModule) authorization module. 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, etc. Setup the sts-config property 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.properties is just an empty file as authentication is handled by PicketLink's login module. sts-roles.properties contains the sts roles.
The endpoint definition is included in the /META-INF/standard-jaxws-endpoint-config.xml. This will contain the jax-ws handler class, webservice.jaxws.server.handler.SAML2ServerHandler, which contains the handleMessage method.
The jbossxacml-config.xml file contains the policy locators and policy location. In our example we used JBossPolicySetLocator and JBossPolicyLocator. We put our XACML policy in xacml-policy.xml. The authorization module acts as a Policy Enforcement Point (PEP) to setup the XACML request to send to the Policy Decision Point (PDP) for evaluation.
STS (Server Side)
The STS has a new security domain for the STS in the jboss-web.xml, includes an application policy for the new domain that uses the UsersRolesLoginModule to authenticate STS clients, includes the users and roles properties files, and the required role in web.xml to STSClient.
The STS accept only stsclient roles which is in the web.xml. In the jboss-web.xml the application domain should point to the sts-users and roles properties files located within the login-config.xml. 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. JBoss and UserA from our sample are both STSClient roles.
Web Service (Client Side)
The STSWSClient acquires a SAML assertion from the PicketLink STS and invokes the echo method of the WS.
The assertion is first obtained using the WSTrustClient API. Notice the client then adds the SAML assertion in the SAML2Constants.SAML2_ASSERTION_PROPERTY ("org.picketlink.trust.saml.assertion") 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. The SAML2ClientHandler defined in the client config inserts the assertion into the WSSE in the SOAP Header.
To run the project the classpath should contain the classes similar to below if run from command line (this is for EAP 5.0) or similar to the ones in the project if running the project from JBDS 6 with EAP 5.2.
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.jaxws.client.STSWSClient
References for JAX-WS
Integration with PicketLink STS - http://community.jboss.org/wiki/SAMLWSIntegrationwithPicketLinkSTSSOAP Web Service Authorization - Protecting EJB web services with XACML, A beginners tutorial - http://community.jboss.org/wiki/ProtectingEJBwebserviceswithXACMLAbeginnerstutorial
SOAP Web Service Authentication - This example is using SAML but similar for X509. It shows how to use the JAX-WS handler with the STS. SAML WS
SOAP Web Service Authentication - This example is a specific X509 with policy http://www.jroller.com/gmazza/entry/cxf_x509_profile_secpol
JAX-WS Handler Tutorial - http://www.jroller.com/gmazza/entry/jaxws_handler_tutorial
