ESB Examples - Using BPELInvoke to call a BPEL process using SAML to authenticate process participants
======================================================================================================

This is a somewhat complex example. Its goal is to show how SAML, WS-Trust, and WS-BPEL can be used to help a composite service allow access to an authenticated user from trusted party. The business requirement is fairly simple: A service provided by one party (call them PartyB) that is consumed by another party (call them PartyA) requires the invoking party first authenticate the user and send a claim with the message that asserts the authenticity of the user. PartyB requires the use of SAML Assertions for making this claim. 

Riftsaw, JBossESB, PicketLink, and JBossAS JAAS can together meet this requirement in the context of a business process performed by PartyA. The PicketLink project provides a component, PicketLinkSTS, that provides a WS-Trust SecureTokenService. This quickstart uses PicketLinkSTS to issue a SAML Token with an Authentication assertion (as PartyA). PicketLinkSTS is also used by the invoked service (PartyB) to validated the SAML Token. Riftsaw is responsible for passing the SAML token to the linked service.

The quickstart is executed using ant runtest, which invokes a Web service which is really an ESB service exposed as a Web service using EBWS. The client request includes a WS-Security header element with a UsernameToken. The EBWS generated Web service extracts the UsernameToken making it available to the ESB Service. The ESB Service is configured with a security element that specifies a JBoss JASS application policy that uses the PicketLinkSTS TokenIssuing login module. This login module authenticates the user using the UsernameToken and requests PicketLinkSTS to issue a SAMLToken for this user. Once the user is authenticated and the SAMLToken issues, the ESB Service action processing pipeline is entered, where a BPELInvoke action is called that starts a Riftsaw
BPEL process and copies the SAML Token wrapped in a Security element into the process receive variable. The BPEL process then copies the Security element along with the data into another variable (this is specified in the BPEL process design), which is then used to populate the message sent to the invoke activity (PartyB's Web service). The invoke activity consumes a JaxWS Web service, which is proxied by another ESB service using the SOAPProxy action. SOAPProxy uses an HTTP Gateway, which does not process WS-Security elements. Therefore a custom message composer was added to the listener configuration of this second service. This second ESB service also uses PicketLinkSTS to validate the SAML Token.

To deploy the example, open a command line window in the example's folder, and simply type 'ant deploy'. To undeploy, use the command 'ant undeploy'.

To test the example, for example using the SOAPUI client, an example message can be found in the messages sub-folder, with the relevant WSDL being located in the server/default/data/wsdl/Quickstart_bpel_hello_world_saml/BPELESBSecurity folder.

Alternatively, use the 'ant runtest' command (from a command line window) to send the example message directly to the Web service.

NOTE: The "ant deploy" command will by default deploy version 1 of the example to the server. If you wish to change the example, and redeploy, then you should either undeploy, or else you will need to update the version number in the build.xml, or override the version property, e.g. "ant -Dversion=2 deploy" (and similarly when undeploying "ant -Dversion=2 undeploy").

Some handy URLs:
http://localhost:8080/bpel-console is the BPEL console

The quickstart bpel_helloworld_saml folder has several files and folders in it. 


/bpelcontent contains the bpel process definition, bpel-deploy.xml, and associated WSDL files for the services

/esbcontent contains the definitions and sample code for the two ESB services. the hello.xsd is used to expose the ESB Service as a Web service, and HelloWorldWS.wsdl is used to define the service being proxied by the second ESBService. login-config.xml defines the PicketLink application policies / login modules, as well as an application policy to perform the initial authentication of the user (this uses the UsersRolesLoginModule). login-config.xml is generated from the login-config-unfiltered.xml at the root of the quickstart. Make any changes to this file. The jboss-service.xml is used to define an MBean to add these application policies dynamically. sts-client.properties is used by the STS login module to describe how to connect to the PicketLinkSTS service (this could be on another server) and to provide the TokenValidating login module with some credentials (since when it is invoked it has a SAML Token but no user credentials).

/picketlink-sts contains files to create a Web application, picketlink-sts.war, which is also provided. Should changes be required to this Web application, run jar cvf ../picketlink-sts.war ** from a command line to re-create the war.

/props contains an sts-users.properties and an sts-roles.properties. These are copied to the server/default/conf directory and referenced by the sts application policy. Additional users can be added to sts users.

/src contains source code for DisplaySubjectAction, which is used in the first ESB Service to display the SAML token after it is issued, as well as HttpGatewayMessageComposer, which extracts the SAML Assertion from the SOAPHeader for processing by the ESB security component.

/war contains the files for the Web service that is invoked by the BPEL process.



Future work: Currently this quickstart only uses Authentication. Future versions hope to add authorization information to the SAML Token (in the form of AttributeStatements and / or AuthorizationDecisionStatements).



