Index Changes

Using the SAML Sender Vouches with Certificates Security Mechanism with the HTTP BC

Introduction

The HTTP Binding Component (HTTP BC) is a component in the JBI environment that is used as a provider proxy to provide connectivity to services in the JBI environment, or as consumer proxy to invoke services.

The SAML Sender Vouches with Certificates Security mechanism uses mutual certificates to sign and encrypt messages, for integrity and confidentiality. The "SAML Sender Vouches" in its name refers to the fact that a SAML assertion is included as part of the message signature as an authorization token.

Prerequisites

Sample

The examples implemented on this page can be downloaded as NetBeans projects:

Known Issues

  • An issue exists in the NetBeans/CASA Editor tool that prevents Composite Applications from deploying successfully when a CallbackHandler class is included in the project. At this time, to work around the problem, such Composite Applications need to be deployed either from the Admin web console, or from the command-line (via the asadmin tool).
  • The Java Application project described in the section below, titled, Enabling SAML Sender Vouches with Certificates Security for HTTP BC-based Service Clients, may not build successful due to unresolved class references, especially those classes defined in the javax.security.auth package. If compile time errors are experienced, resolve them by:
    • Defining a Class Library using the NetBeans Library Manager. Include in the library the files j2ee.jar and webservices-rt.jar from the Glassfish installation's lib directory.
    • Referencing the above Class Library in the Java Application project.

Enabling SAML Sender Vouches with Certificates Security for HTTP BC-exposed Services

In this scenario, the HTTP BC is utilized as a provider proxy, providing a HTTP-based communication endpoint through which consumers can access the service. The following instructions describe the implementation of a basic "echo" service using the JBI environment's BPEL service engine, and the utilization of the Composite Application Service Assembly (CASA) editor to secure the service using the SAML Sender Vouches with Certificates security mechanism.

Implement the service

1. Create a NetBeans BPEL Module project.

2. Define (create the WSDL) of the service. This example accepts the defaults to create a SOAP binding-based service consisting of a request-response operation that uses single-part input and output messages.

3. Compose a BPEL process that implements the "echo" operation. This example composes a simple workflow that receives the message and replies with a response whose payload is identical to the request.

4. Build the BPEL project.

5. Create a NetBeans Composite Application project and include the BPEL project into it.

6. Build the Composite Application project. This step is mandatory before WSIT options can be configured, because the building process generates the required service assembly information.

Secure the service

1. Access the Service Assembly node in the Composite Application project, to load the project's assembly information into the Composite Application Service Assembly (CASA) editor.

The object of interest for assigning WSIT options is the "inbound" WSDL port, which represents the consuming endpoint to the service. To configure WSIT options for this port, first clone the port so that the CASA editor will permit the modification of the port.

The assembly graph displayed by the CASA editor is obtained from information culled from the BPEL project, which the Composite Application project does not modify. The act of cloning a port creates a local, modifiable copy of the BPEL project information, in the Composite Application project.

2. Once the port is cloned, access its context menu again and choose to Edit Web Service Attributes / Server Configuration.

3. The WS-Policy Attachment dialog appears.

  • Check the Security check box.
  • Choose SAML Sender Vouches with Certificates for the security mechanism
  • As this specific security mechanism requires requires keystore and truststore information for message signing and encryption purposes, click on the Keystore... and Truststore..._ buttons and provide the required parameters.

4. Save changes.

5. Build the Composite Application project again, and then deploy it. The service is now secured and deployed.

Enabling SAML Sender Vouches with Certificates Security for HTTP BC-based Service Clients

This example uses the HTTP BC to create a WS Security-enabled client to talk to the service (also WS Security-enabled) created in the previous section.

The following instructions create a project that uses the service-invocation mechanism available to BPEL processes. By using BPEL (and thus the JBI environment) to implement the "client" that talks to the service, the HTTP BC can be used as a consumer proxy to demonstrate how WSIT options are configured for JBI clients.

Implement a SAML CallbackHandler

A client that intends to access a service secured with SAML security mechanisms (there are several, not just SAML Sender Vouches with Certificates), must implement a SAML CallbackHandler.

  • Generally speaking, a Callback Handler is an opaque object exchanged between two entities, that the receiver of which can manipulate, through known interfaces, to obtain information belonging or pertinent to the giver. A "real-life" example is a security token card, provided by a company to an employee as a means to access company network resources, that generates random passwords every 60 seconds. The employee "calls back" the company site thru the token card (the callback handler), to obtain a necessary piece of information (a usable password) to gain entry to the network.
  • A SAML CallbackHandler is a callback handler passed by an application to underlying security services so that these services may interact with the application to retrieve SAML authentication/authorization assertions.

Designing and implementing a particular CallbackHandler is beyond the scope of this document. The sample CallbackHandler provided in The WSIT Tutorial can be used for the purpose of this example.

1. Create a NetBeans Java Application project.

2. Create a Java class, and copy the sample CallbackHandler code into this class.

3. Build the project. Reminder: Please review the Known Issues section, above, for Class Library dependencies that may have to be fulfilled in order for this project to compile successfully.

Implement the service client

Note In creating a client in this fashion, these instructions create, essentially, a second service. There is the target service defined in the previous section, and there is this triggering service that starts a BPEL process that, in turn, calls the target service.

1. Ensure that the target service, created in the previous section, has been built and deployed before continuing.

2. Create a BPEL project. This project will implement the triggering service.

3. Import the description of the target service into the BPEL project.

4. Define (create the WSDL) of the trigger service. The SOAP binding is utilized here so that the trigger service can be executed from the SOAP tester available to JBI Composite Application projects.

5. Compose a BPEL process that invokes the target service.

For diagnostic purposes, the BPEL process will concatenate the service call's response with a fixed string literal. The presence of this string literal in the test output serves as verification that the service call was conducted by the BPEL process.

Create the JBI service assembly for the client

1. Build the BPEL project.

2. Create a JBI Composite Application project. Add the BPEL project to it.

3. Build the JBI Composite Application project. This step is mandatory before WSIT options can be configured, because the building process generates the required service assembly information.

Secure the client

1. Access the Service Assembly node in the Composite Application project, to load the project's assembly information into the Composite Application Service Assembly (CASA) editor.

Note that the "inbound" WSDL port (upper port in the diagram) represents a consumer endpoint for the triggering service, not the target service.

The actual object of interest for assigning WSIT options is the "outbound" WSDL port, which represents the provisioning endpoint to the target service. To configure WSIT options for this port, first clone the port so that the CASA editor will permit the modification of the port.

The assembly graph displayed by the CASA editor is obtained from information culled from the BPEL project, which the Composite Application project does not modify. The act of cloning a port creates a local, modifiable copy of the BPEL project information, in the Composite Application project.

2. Once the port is cloned, access its context menu again, and choose to edit its Properties.

3. Edit the CallbackProject property, and point it to the Java Application project created earlier.

2. Access the port's context menu again and choose to Edit Web Service Attributes / Client Configuration.

3. The WS-Policy Attachment dialog appears. Since SAML Sender Vouches with Certificates is the security mechanism used by the service, three security parameters are required:

  • Keystore and Truststore information: Click on the Keystore... and Truststore..._ buttons and provide these parameters
  • SAML Callback Handler: Click on the Browse... button for the SAML Callback Handler field, and find and select the previously created Java class that implements javax.security.auth.callback.CallbackHandler.

4. Save changes.

Deploy and test the service and client

1. If the target service needs to be deployed, do so now.

2. Build and deploy the client Composite Application project. Due to an existing issue in NetBeans, Composite Applications that include CallbackHandler classes must be deployed via the Admin web console or the command-line asadmin tool (shown below):

%AS_HOME%\bin\asadmin deploy-jbi-service-assembly

e.g., deploy-jbi-service-assembly C:\WSIT\MutualCerts_CompApp_Project\dist\MutualCerts_CompApp_Project.zip

3. Navigate to the Test node of the Composite Application project, access its context menu, and choose to create a New Test Case.

Note When prompted for the WSDL document, provide the WSDL document for the triggering service. The intent is to invoke the triggering service, which in turns uses the BPEL process (and the HTTP BC) to invoke the target service, thus causing the WSIT options configured on the outbound port to be utilized. If, instead, the WSDL document for the target service is provided, then the tester will access the target service directly, bypassing the use of the BPEL process and the secured HTTP port, and causing a security exception or fault.

4. Once the Test Case is created, its input file is shown. Populate it with data.

5. Access the Composite Application project's context menu and choose to Test. Since this is the first time the test is run, the test will fail because there is no prior output against which to compare the test result. Answering No to the prompt(s) will deposit the test result into a subnode in the Test Case subtree. Edit the node to see the result.

The output of this test instance was (reformatted for readability):

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/ http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Body>
    <m:TriggerResponse xmlns:m="http://j2ee.netbeans.org/wsdl/TriggerService">
      <part1
          xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
          xmlns:exc14n="http://www.w3.org/2001/10/xml-exc-c14n#"
          xmlns:m="http://j2ee.netbeans.org/wsdl/EchoService"
          xmlns:msgns="http://j2ee.netbeans.org/wsdl/TriggerService"
          xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
          xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
          xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" xmlns="">Response___TestMessage</part1>
    </m:TriggerResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

JSPWiki v2.4.100
[RSS]
« Home Index Changes Prefs
This page (revision-7) was last changed on 04-Jun-08 17:12 PM, -0700 by NoelDAng