test

Sun Java System Access Manager 7.1 Federation and SAML Administration Guide

Chapter 9 SOAP Binding Service

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:

SOAP Binding Service Overview

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.

Note –

For more information, see the Liberty ID-WSF SOAP Binding Specification.

The following sections contain additional information about the SOAP Binding Service.

XML Service File

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.

Note –

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.

SOAPReceiver Servlet

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.

SOAP Binding Service APIs

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.

SOAP Binding Process

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.

Note –

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.

Note –

Before invoking a corresponding service, the SOAP framework might also do the following:

SOAP Binding Service Attributes

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.

Note –

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:

Request Handler List

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.

Key Parameter

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.

Note –

Different service clients must use different keys when connecting to the SOAPReceiver.

Class Parameter

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.

SOAP Action Parameter

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.

Note –

SOAP places no restrictions on the format or specificity of the URI or that it is resolvable.

Web Service Authenticator

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.

Note –

This interface is not 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 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:

Note –

For more complete information about authentication mechanisms and their level of security, see the Liberty ID-WSF Security Mechanisms specification.

SOAP Binding Service Package

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.