Chapter 7 SOAP Binding Service

The Sun Java™ System Access Manager contains an implementation of the Liberty ID-WSF SOAP Binding Specification from the Liberty Alliance Project. SOAP Binding is a transport layer for sending and receiving SOAP messages. This chapter contains the following topics:

Overview

The Liberty Identity Web Services Framework (ID-WSF) and Liberty Identity Service Interface Specification (ID-SIS) components of the Liberty Alliance Project (LAP) specifications use messages to convey identity data between providers. These identity messages themselves do not address a specific method of transport so Access Manager has implemented the Liberty ID-WSF SOAP Binding Specification (ID-WSF-SBS) for this purpose. The specification defines SOAP as the binding to the HyperText Transport Protocol (HTTP), which is itself layered onto the TCP/IP stack.



Note	The Liberty ID-WSF SOAP Binding Specification can be found on the Liberty Alliance Project Web site at http://www.projectliberty.org/specs/liberty-idwsf-soap-binding-v1.1.pdf.

XML Service File

The Access Manager SOAP Binding service is defined using the XML service file amSOAPBinding.xml. amSOAPBinding.xml defines the attributes for the SOAP Binding service which can be managed through the Access Manager console or the XML file itself.



Note	More information on XML service files can be found in the section on XML Service Files in the Sun Java System Access Manager 6 2005Q1 Developer’s Guide (http://docs.sun.com/doc/817-7649).

The ID-WSF-SBS also defines an XML schema for use in building the SOAP messages. This XML Schema Defintion (XSD) file can be found on the LAP Web site. Version 1.0 is also reproduced in Appendix B, "Service Schema Files."

Application Programming Interfaces

The Access Manager SOAP Binding service includes a Java package named com.sun.identity.liberty.ws.soapbinding. Additional information on these interfaces can be found in SOAP Binding Interfaces.

SOAP Binding Process

In the SOAP Binding process, an identity service calls the client side application programming interface (API) to construct a message and send it to the SOAP endpoint URL; in effect, a SOAP Receiver servlet.



Note	Currently, only the Discovery Service, the Liberty Personal Profile Service and the Authentication Web Service use the SOAP Binding Service client API. Additionally, the Liberty Employee Profile sample uses them. They are not yet public.

The SOAP Receiver servlet receives the message, verifies the signature, and constructs a second message. The SOAP Receiver servlet then invokes the correct Request Handler to send this second message to the corresponding identity service for a response.



Note	The Request Handler is an interface that must be implemented on the server side by any Liberty-based identity Web service using the SOAP Binding Service. More information on this interface can be found in the Request Handler List.

The identity service processes the second message, generates a response, and sends that response back to the SOAP Receiver servlet. The SOAP receiver, in turn, sends the response back to the identity service for processing.



Note	Before invoking a corresponding service, the SOAP framework might also do the following: Authenticate sender identity: This is to verify the credentials of a WSC peer, probably by verifying it's client certificate. Authenticate invoking identity: This verifies the credentials of a WSC on behalf of a user to verify whether the user has been authenticated. This depends on the security authentication profile. Granular authorization: This is to authorize the WSC itself before processing a service request.

SOAP Binding Attributes

The SOAP Binding service attributes are global attributes. The values of these attributes are carried across the Sun Java System Access Manager configuration and inherited by every organization.



Note	For information on the types of attributes used in Access Manager, see the Service Management chapter of the Sun Java System Access Manager Developer’s Guide (http://docs.sun.com/doc/817-7649).

Attributes for the SOAP Binding service are defined in the amSOAPBinding.xml service file. The SOAP Binding attributes are:

Request Handler List

Web Service Authenticator

Supported Authentication Mechanisms

Request Handler List

The SOAP Binding Service provides the RequestHandler interface to process the request message and return a response. This interface must be implemented on the server side by each Liberty-based identity service that uses the SOAP Binding Service. The Request Handler List attribute stores information about the implementation classes of the Web services that implement the Request Handler.



Note	Currently, only the Discovery Service, the Liberty Personal Profile Service and the Authentication Web Service use the SOAP Binding Service RequestHandler interface. Additionally, the Liberty Employee Profile Service sample uses it. The interface itself is not yet public.

The Request Handler List displays entries that contain key/value pairs separated by a pipe (“|”) as in:

key Parameter

The required key parameter is the last part of the URI path to a SOAP endpoint. The SOAP endpoint in Access Manager is the SOAP Receiver servlet. The URI to the SOAP Receiver is:

If you define disco as the key, the URI path to the SOAP endpoint for the corresponding Discovery Service would be:

Different service clients use different keys when connecting to the SOAP Receiver.

class Parameter

The required class parameter specifies the name of the Request Handler implementation class for the particular identity service. For example:

Web Service Authenticator

This attribute takes as a value the implementation class for the Web Service Authenicator interface. This class authenticates a request and generates a credential for a Web service consumer (WSC).



Note	This interface is not currently public. The value of the attribute is configured during installation.

Supported Authentication Mechanisms

This attribute specifies the authentication mechanisms supported by the SOAP Receiver. Authentication mechanisms offer user authentication, as well as data integrity and encryption. By default, all available authentication mechanisms are selected. If one is not selected, and a Web services consumer (WSC) sends a request using it, the request is rejected. Following is a list of the supported authentication mechanisms:

urn:liberty:security:2003-08:null:null

urn:liberty:security:2003-08:null:X509

urn:liberty:security:2003-08:null:SAML

urn:liberty:security:2004-04:null:Bearer

urn:liberty:security:2003-08:TLS:null

urn:liberty:security:2003-08:TLS:X509

urn:liberty:security:2003-08:TLS:SAML

urn:liberty:security:2004-04:TLS:Bearer

urn:liberty:security:2003-08:ClientTLS:null

urn:liberty:security:2003-08:ClientTLS:X509

urn:liberty:security:2003-08:ClientTLS:SAML

urn:liberty:security:2004-04:ClientTLS:Bearer



Note	More complete information on authentication mechanisms and their level of security can be found in the Liberty ID-WSF Security Mechanisms document on the Liberty Alliance Project Web site at http://www.projectliberty.org/specs/liberty-idwsf-security-mechanisms-v1.1.pdf.

SOAP Binding Interfaces

The Access Manager SOAP Binding Service includes a Java package named com.sun.identity.liberty.ws.soapbinding. It provides classes to construct SOAP requests and responses and to change the contact point for the SOAP binding. Table 7-1 details the available classes.

Table 7-1 SOAP Binding API Classes
Class	Description
Message	Used by both the Web service client and server to construct SOAP requests and responses.
ServiceInstanceUpdateHeader	Allows a service to change the endpoint on which requesters will contact it.
ServiceInstanceUpdateHeader.Credential	Allows a service to use a different security mechanism and credentials to access the requested resource.

The package also includes a RequestHandler interface. The implementation of this interface is discussed further in Interaction Service API of Chapter 8, "Application Programming Interfaces." For more detailed API reference information, see the Javadocs in /AccessManager_base/SUNWam/docs.



Note	Be sure to check out Appendix A, "Included Samples" for sample code and files to help you understand the implementation of the Liberty Alliance Project’s specifications in Access Manager.

Previous Contents Index Next
Sun Java Systems Access Manager 6 2005Q1 Federation Management Guide