Sun™ Java System Access Manager contains an implementation of the Liberty ID-WSF SOAP Binding Specification from the Liberty Alliance Project. The specification defines a transport layer for sending and receiving SOAP messages.
This chapter covers the following topics:
The Liberty Identity Web Services Framework (Liberty ID-WSF) and Liberty Identity Service Interface Specifications (Liberty ID-SIS) components of the Liberty Alliance Project specifications use messages to convey identity data between providers. Access Manager has implemented the Liberty ID-WSF SOAP Binding Specification (Liberty ID-WSF-SBS) as the method of transport 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.
For more information, see the Liberty ID-WSF SOAP Binding Specification.
The following sections contain additional information about the SOAP Binding Service.
The Access Manager SOAP Binding Service is defined using the XML service file amSOAPBinding.xml. This file defines the attributes for the SOAP Binding Service which can be managed through the Access Manager Console or the XML file.
For more information on service files, see the Sun Java System Access Manager 7.1 Administration Guide.
The Liberty ID-WSF-SBS also defines an XML schema for use in building the SOAP messages. More information about the XSD schemas can be found in Schema Files and Service Definition Documents.
The SOAPReceiver servlet receives a Message object from a web service client (WSC), verifies the signature, and constructs its own Message object for processing by Access Manager. The SOAPReceiver then invokes the correct request handler class to pass this second Message object on to the appropriate Access Manager service for a response. When the response is generated, the SOAPReceiver returns this Message object back to the WSC. More information can be found in the SOAP Binding Process.
The Access Manager SOAP Binding Service includes a Java package named com.sun.identity.liberty.ws.soapbinding. For more information, see SOAP Binding Service Package.
In the SOAP Binding process, an identity service invokes the Message class (contained in the client-side API) to construct a request. (As clients of the SOAP Binding Service, the Access Manager Discovery Service, implemented Data Services Template services (including the Liberty Personal Profile Service and the sample Employee Profile Service), and the Authentication Web Service all use the SOAP Binding Service client-side API.) The Message object will contain any default or non-default SOAP headers as well as the SOAP body containing the request(s). Once generated, the WSC invokes the sendRequest method and sends the Message object to the SOAP endpoint URL on the server side. The URL is, in effect, a servlet called the SOAPReceiver. The SOAPReceiver receives the Message, verifies the signature, and constructs its own Message object. The SOAPReceiver then invokes the appropriate Request Handler class to send this second message to the corresponding service for a response.
com.sun.identity.liberty.ws.soapbinding.RequestHandler is an interface that must be implemented on the server side by any Liberty-based web service using the SOAP Binding Service. For more information, see Request Handler List.
The web service processes the second message, generates a response, and sends that response back to the SOAPReceiver which, in turn, returns the response back to the WSC for processing.
Before invoking a corresponding service, the SOAP framework might also do the following:
Authenticate the sender identity to verify the credentials of a WSC peer, probably by verifying its client certificate.
Authenticate the invoking identity to verify 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 to authorize the WSC before processing a service request.
The SOAP Binding Service attributes are global attributes. The values of these attributes are carried across the Access Manager configuration and inherited by every organization.
For information about the types of attributes used in Access Manager, see the Sun Java System Access Manager 7.1 Technical Overview.
Attributes for the SOAP Binding Service are defined in the amSOAPBinding.xml service file. The SOAP Binding Service attributes are as follows:
The Request Handler List stores information about the classes implemented from the com.sun.identity.liberty.ws.soapbinding.RequestHandler interface. The SOAP Binding Service provides the interface to process requests and return responses. The interface must be implemented on the server side for each Liberty-based web service that uses the SOAP Binding Service.
To add a new implementation, click New and define values for the following parameters.
The Key parameter is the last part of the URI path to a SOAP endpoint. The SOAP endpoint in Access Manager is the SOAPReceiver servlet. The URI to the SOAPReceiver uses the format protocol://host:port/deloy-uri/Liberty/key. If you define disco as the Key, the URI path to the SOAPReceiver for the corresponding Discovery Service would be protocol://host:port/amserver/Liberty/disco.
Different service clients must use different keys when connecting to the SOAPReceiver.
The Class parameter specifies the name of the class implemented from com.sun.identity.liberty.ws.soapbinding.RequestHandler for the particular web service. For example, class=com.example.identity.liberty.ws.disco.DiscoveryService.
The optional SOAP Action can be used to indicate the intent of the SOAP HTTP request. The SOAP processor on the receiving system can use this information to determine the ultimate destination for the service. The value is a URI. No defined value indicates no intent.
SOAP places no restrictions on the format or specificity of the URI or that it is resolvable.
This attribute takes as a value the implementation class for the Web Service Authenticator interface. This class authenticates a request and generates a credential for a WSC.
This interface is not public. The value of the attribute is configured during installation.
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 a mechanism is not selected and a WSC sends a request using it, the request is rejected. Following is a list of the supported authentication mechanisms:
urn:liberty:security:2003-08:ClientTLS:SAML
urn:liberty:security:2003-08:ClientTLS:X509
urn:liberty:security:2003-08:ClientTLS:null
urn:liberty:security:2003-08:TLS:SAML
urn:liberty:security:2003-08:TLS:X509
urn:liberty:security:2003-08:TLS:null
urn:liberty:security:2003-08:null:SAML
urn:liberty:security:2003-08:null:X509
urn:liberty:security:2003-08:null:null
urn:liberty:security:2004-04:ClientTLS:Bearer
urn:liberty:security:2004-04:TLS:Bearer
urn:liberty:security:2004-04:null:Bearer
urn:liberty:security:2005-02:ClientTLS:Bearer
urn:liberty:security:2005-02:ClientTLS:SAML
urn:liberty:security:2005-02:ClientTLS:X509
urn:liberty:security:2005-02:TLS:Bearer
urn:liberty:security:2005-02:TLS:SAML
urn:liberty:security:2005-02:TLS:X509
urn:liberty:security:2005-02:null:Bearer
urn:liberty:security:2005-02:null:SAML
urn:liberty:security:2005-02:null:X509
For more complete information about authentication mechanisms and their level of security, see the Liberty ID-WSF Security Mechanisms specification.
The Access Manager SOAP Binding Service includes a Java package named com.sun.identity.liberty.ws.soapbinding. This package provides classes to construct SOAP requests and responses and to change the contact point for the SOAP binding. The following table describes some of the available classes. For more detailed information, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.
Table 9–1 SOAP Binding Service API
Class |
Description |
---|---|
Client |
Provides a method with which a WSC can send a request to a WSP using a SOAP connection. It also returns the response. |
ConsentHeader |
Represents the SOAP element named Consent. |
CorrelationHeader |
Represents the SOAP element named Correlation. By default, CorrelationHeader will always be signed. |
ProcessingContextHeader |
Represents the SOAP element named ProcessingContext. |
ProviderHeader |
Represents the SOAP element named Provider. |
RequestHandler |
Defines an interface that needs to be implemented on the server side by each web service in order to receive a request from a WSC and generate a response. After implementing the class, it must be registered in the SOAP Binding Service so the SOAP framework knows where to forward incoming requests. |
Message |
Represents a SOAP message and is used by both the web service client and server to construct SOAP requests and responses. Each SOAP message has multiple headers and bodies. It may contain a certificate for client authentication, the IP address of a remote endpoint, and a SAML assertion used for signing. |
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. |
SOAPFault |
Represents the SOAP element named SOAP Fault. |
SOAPFaultDetail |
Represents the SOAP element named Detail, a child element of SOAP Fault. |
UsageDirectiveHeader |
Defines the SOAP element named UsageDirective. |
See Appendix A, Liberty-based and SAML Samples for sample code and files to help you understand the implementation of the Liberty Alliance Project specifications.
See PAOS Binding for information on this reverse HTTP binding for SOAP.