test

Sun Java System Access Manager 7 2005Q4 Federation and SAML Administration Guide

Chapter 8 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.

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 2005Q4 Administration Guide.

The Liberty ID-WSF-SBS also defines an XML schema for use in building the SOAP messages. This XML Schema Definition (XSD) file is on the Liberty Alliance Project web site. Version 1.0 is also reproduced in Appendix B, Service Schema Files.

SOAP Binding Service APIs

The Access Manager SOAP Binding Service includes a Java package named com.sun.identity.liberty.ws.soapbinding. For more information about these interfaces, see SOAP Binding Service Package.

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. The URL is, in effect, a servlet that receives and processes SOAP messages.

Note –

The Discovery Service, implemented Data Services Template services (including the Liberty Personal Profile Service and the sample Employee Profile Service), and the Authentication Web Service use the SOAP Binding Service client API.

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 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 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 service 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 2005Q4 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. It must be implemented on the server side for each Liberty-based web service that uses the SOAP Binding Service.

Note –

The Discovery Service, implemented Data Services Template (DST) services (including the Liberty Personal Profile Service and the sample Employee Profile Service, if deployed), and the Authentication Web Service use the SOAP Binding Service client API.

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 SOAP Receiver servlet. The URI to the SOAP Receiver uses the format protocol://host:port/deloy-uri/Liberty/key. If you define disco as the Key, the URI path to the SOAP endpoint for the corresponding Discovery Service would be protocol://host:port/amserver/Liberty/disco.

Note –

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

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 8–1 SOAP Binding Service Classes

Class 

Description 

Client

Provides a WSC with a method to send requests using a SOAP connection with a WSP. 

ConsentHeader

Defines the SOAP element named Consent.

CorrelationHeader

Defines the SOAP element named Correlation.

ProcessingContextHeader

Defines the SOAP element named ProcessingContext.

ProviderHeader

Defines the SOAP element named Provider.

RequestHandler

Defines an interface that needs to be implemented by each web service in order to receive a request from your web service client. After implementing the handler class, the user must register the class in the SOAP Binding Service so the SOAP layer knows where to forward incoming WSC requests. 

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. 

SOAPBindingException

Represents an error that has occurred while processing a SOAP request and response. 

SOAPFault

Defines the SOAP element named Fault.

SOAPFaultDetail

Defines the SOAP element named Consent.

SOAPFaultException

Represents a SOAP fault while processing a SOAP request. 

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.