Chapter 5 Using the Web Services Client APIs

Sun ™ Java System Identity Server 2004Q2 provides a Federation Management framework for creating, discovering, and consuming identity services. This chapter provides engineering notes and summaries of Java classes and APIs that you can use to extend the framework. The SOAP-based invocation framework includes the following components and core identity services:

Federation Packages and Global Interfaces

Table Table 5-1 summarizes the public APIs you can use to deploy Liberty II components or extend the core services. For detailed API reference that includes classes, methods and their syntax and parameters, see the Javadocs at /opt/SUNWam/docs/am_public_javadocs.jar.

Table 5-1 Summary of Liberty II Web Services Packages
Package Name	Description
com.sun.identity.liberty.ws.common.wsse	Provides an interface for Web Service Security X.509 Certificate Token Profile. See Authorization.
com.sun.identity.liberty.ws.disco	Provides interfaces to manage liberty discovery service. See Discovery Service.
com.sun.identity.liberty.ws.disco.plugins	Provides interfaces to manage liberty discovery service. See Discovery Service.
com.sun.identity.liberty.ws.dst	Provides interface to manage liberty ID-WSF Data Service Template. See Data Services Template.
com.sun.identity.liberty.ws.interaction	Provides classes to support Liberty Interaction RequestRedirect Profile. See Interaction Service.
com.sun.identity.liberty.ws.interfaces	Provides interfaces common to all liberty services.
com.sun.identity.liberty.ws.paos	Provides classes for web application to construct and process PAOS request and response.PAOS.
com.sun.identity.liberty.ws.security	Provides interface to manage liberty ID-WSF security mechanisms.Security Token Manager.

Table 5-2 summarizes classes used by all Liberty service components, and interfaces common to all Liberty services. All of these are Included in package com.sun.identity.liberty.ws.common.

Table 5-2 Common Liberty II Classes and Interfaces
Class or Interface Name	Description
LogUtil	Included in package com.sun.identity.liberty.ws.common.
Status	Class that represents a common status object. Included in package com.sun.identity.liberty.ws.common.
Authorizer	Interface for identity service to check authorization of a WSC. Included in package com.sun.identity.liberty.ws.common.interfaces.
ResourceIDMapper	Interface Used to map between an userID and the ResourceID associated with it. Included in package com.sun.identity.liberty.ws.common.interfaces.

Trusted Authority

The Trust Authority component provides APIs for creating security tokens used for authentication and authorization in accordance with the ID-WSF Security Mechanisms Specification. Both WSS X509 and SAML tokens are supported.

Security Token Manager

This is the entry class for the security package com.sun.identity.liberty.ws.security. You can call methods in this class to generate X509 and SAML tokens for message authentication or authorization. It is designed as a provider model, so different implementations can be plugged in if the default implementation does not meet your requirements.

Table Table 5-3 summarizes the Liberty security APIs included in com.sun.identity.liberty.ws.security. For detailed API reference, including methods and their syntax and parameters, see the Javadocs at /opt/SUNWam/docs/am_public_javadocs.jar.

Table 5-3 Security APIs
Class Name	Description
SecurityTokenProvider	A provider interface for managing WSS security tokens.
ProxySubject	Represents the identity of a proxy, the confirmation key and confirmation obligation the proxy must possess and demonstrate for authentication purpose
ResourceAccessStatement	Conveys information regarding the accessing entities and the resource for which access is being attempted
SecurityAssertion	Provides an extension to Assertion class to support ID-WSF ResourceAccessStatement and SessionContextStatement
SecurityTokenManager	A final class that provides interfaces to manage Web Service Security (WSS) Tokens.
SessionContext	Represents session status of an entity to another system entity.
SessionContextStatement	An element that conveys session status of an entity to another system entity within the body of an <saml:assertion> element.
SessionSubject	Represents a liberty subject with associated session status.
BinarySecurityToken	The class BinarySecurityToken provides interface to parse and create X.509 Security Token depicted by Web Service Security: X.509
WSSEConstants	.

SOAP Binding

The SOAP Binding component is designed to be a generic transport layer for handling SOAP messages.

Table 5-4 Summarizes the APIs for SOAP binding. For detailed API reference, including methods and their syntax and parameters, see the Javadocs at /opt/SUNWam/docs/am_public_javadocs.jar.

Table 5-4 APIs for SOAP binding.
Class Name	Description
Message	Used by web service client and server to construct a request or response.
CorrelationHeader	Represents the Correlation element defined in the SOAP binding schema.
ConsentHeader	Represents the Consent element defined in the SOAP binding schema.
UsageDirectiveHeader	This is the default constructor.
Client	Provides web service clients with a method to send requests using a SOAP connection to web service servers.
SOAPReceiver	Defines a SOAP Receiver which supports SOAP over HTTP binding.
RequestHandler	This interface must be implemented by web service in order to receive requests from a client.

A client-side API is provided so that any web server client can talk to the server's SOAP end point. A server-side hook, the RequestHandler interface, is provided so that any web service provider can easily be plugged into the Liberty Identity web service framework.

Plugin a new Web Service Provider

The web service provider needs to implement the RequestHandler interface, which will be called to do service specific processing.

Code Example 5-1 New Web Service Provider


/**
* The RequestHandler interface needs to be implemented
* by web services in order to receive request from client.
*/
public interface RequestHandler {
/**
* Generates a response according to the request
* @param request request message object
* @return response message
*/
public Message
processRequest(
Message request
)
}

The web service provider need to register the RequestHandler in the SOAP service together with a second level URI. SOAP service registers the top level servlet mapping URI in web.xml: <servlet>


<servlet-name>WSSOAPReceiver</servlet-name>
<servlet-class>com.sun.identity.liberty.ws.soapbinding.SOAPReceiver</servl et-class>
</servlet>
<servlet-mapping>
<servlet-name>WSSOAPReceiver</servlet-name>
<url-pattern>/Liberty/*</url-pattern>
</servlet-mapping>

For example, a personal profile service provider could register idpp URI with the SOAP service. Registration is done through Identity Server administration console by adding the key/handler class mapping to the SOAP service Request Handler List field:

If the SOAP service receives any requests to the /Liberty/idpp URI, the registered ID-SIS-PP RequestHandler will be invoked to process the request, and return will be sent as response to the requester.

Authorization

When a web service consumer contacts a web service provider, the consumer may convey both sender identity and invocation identity. The web service provider must make an authorization decision based on one or both identities. Identity Server depends on the policy framework to perform access evaluation.

Creating an SSO Token

Identity Server framework requires an SSO token in order to perform policy evaluation. The SSO token is created in the SOAP layer. Any web service provider can use the SSO token to perform policy evaluation.

SOAP creates the SSO token after successful peer and/or message authentication. The subject of the certification used in peer or message authentication, or in both, will be set as the subject of the SSO token. An SPI interface is defined to create an SSO token based on the SOAP message and/or HTTP servlet request.The Sender Identity, Authentication Mechanism, and SOAP Message properties will be set in the SSO token.

Creating a Policy

You must create a policy for the identity service. See the Identity Server Administration Guide for detailed steps for creating a policy. Specify the policy subject, roles, and so forth that you want to use for authorization to be enforced.

Table 5-5 summarizes the Security Token APIs included in com.sun.identity.liberty.ws.common.wsse. For detailed API reference, including methods and their syntax and parameters, see the Javadocs at /opt/SUNWam/docs/am_public_javadocs.jar.

Table 5-5 Binary Security Token APIs
Class Name	Description
BinarySecurityToken	The class BinarySecurityToken provides interface to parse and create X.509 Security Token depicted by Web Service Security: X.509
WSSEConstants	.

Discovery Service

A Discovery Service describes and discovers identity services. By default, a Discovery service is implemented as one of the identity web services in Identity Server. Discovery Service provides four interfaces:

Authorizer

The class com.sun.identity.liberty.ws.interfaces.Authorizer is an interface to enable Identity service to check authorization of a Web Service Client.

DefaultDiscoAuthorizer

The com.sun.identity.liberty.ws.disco.plugins.DefaultDiscoAuthorizer is the Discovery Service default implementation. This implementation uses the policy service defined in sunIdentityServerDiscoveryService. In this policy definition, a policy resource uses the form:

Policy credentials are SSOToken for Authentication Users or Web Service Clients. The actions are DiscoConstants.ACTION_LOOKUP or DiscoConstants.ACTION_UPDATE.

You can write a policy plugin to process and use the information passed in through the environment variable. Or you can define a complete new policy service and implement your own Authorizer plugin.

ResourceIDMapper

The class com.sun.identity.liberty.ws.interfaces.ResourceIDMapper is an interface that is used to map a userID to the ResourceID associated with it.

A different implementation of the interface may be developed by different service provider. The implementation classes should be given to the provider that hosts Discovery Service. The mapping between the providerID and the implementation class can be configured through the "Class for ResourceID Mapper Plugin" field in Discovery Service.

Discovery Service provides two implementations for this interface. com.sun.identity.liberty.ws.disco.plugins.Default64ResourceIDMapper assumes the format of ResourceID is:

In this example, com.sun.identity.liberty.ws.disco.plugins.DefaultHexResourceIDMapper assumes the format of ResourceID is:

DiscoEntryHandler

The class com.sun.identity.liberty.ws.disco.plugins.DiscoEntryHandler is an interface that is used to get and set DiscoEntries for a user. A default implementation is provided for this Discovery Service. If you want to handle DiscoEntry differently, implement this interface and set the implementing class to DiscoEntryHandler Plugins Class field in Discovery Service.

UserDiscoEntryHandler. This implementation gets or modifies discovery entries stored at the user's entry in the attribute named sunIdentityServerDiscoEntries. The resource offering is saved in a user entry. UserDiscoEntryHandler is used in business-to-consumer scenarios such as the Personal Profile service.

DynamicDiscoEntryHandler. This implementation gets discovery entries stored at the dynamic template in attribute named sunIdentityServerDynamicDiscoEntries. Modification method is not supported and always returns false. The resource offering is saved in an organization or a role. DynamicDiscoEntryHandler is used in business-to-business scenarios such as the Employee Profile service.

This implementation gets a union of the discovery entries stored at the user entry in attribute named sunIdentityServerDiscoEntries and entries stored at the dynamic template in attribute named sunIdentityServerDynamicDiscoEntries. It modifies discovery entries stored at the user entry in the attribute named sunIdentityServerDiscoEntries. UserDynamicDiscoEntryHandler is used in both business-to-consumer and business-to-business scenarios.

Client APIs

Table 5-6 summarizes the Discovery Service client APIs included in com.sun.identity.liberty.ws.disco. For detailed API reference, including methods and their syntax and parameters, see the Javadocs at /opt/SUNWam/docs/am_public_javadocs.jar.

Table 5-6 Discovery Service Client APIs
Class Name	Description
Description	Represents a Description Type of a service instance.
Directive	Represents a discovery service DirectiveType element.
DiscoveryClient	Provides methods to send Discovery Service query and modify.
EncryptedResourceID	Represents an Encryption Resource ID element for the Discovery Service.
InsertEntry	Represents a Insert Entry for Discovery Modify request.
Modify	Represents a discovery modify request.
ModifyResponse	Represents a discovery response for modify request.
Query	Represents a discovery Query object.
QueryResponse	Represents a response for a discovery query request.
RemoveEntry	Represents a remove entry element for the discovery modify request.
RequestedService	Enables the requester to specify that all the resource offerings returned must be offered via a service instance complying with one of the specified service type.
ResourceID	Represents a discovery service resource ID
ResourceOffering	Associates a resource with a service instance that provides access to that resource
ServiceInstance	Describes a web service at a distinct protocol endpoint.
DiscoEntryHandler	An interface used to get and set DiscoEntries for a user. Contained in the com.sun.identity.liberty.ws.disco.plugins package.

Data Services Template

The Data Services Template is designed to be a base layer that can be extended by any data services instance. An example of a data service a personal profile service such as a online corporate directory. When you want to contact a colleague, you conduct a search based on the individual’s name, and the service returns information associated with your colleague’s identity. The information may include the individual’s office location and phone number, as well as other data such as his job title and department name.

The Data Services client APIs for the template provide the building blocks for implementing a data service on top of the Identity Services framework. The template defines how to query and modify data stored in a data service, and provides some common attributes for the data services. From the implementation point of view, all the data identity services must be built on top of the template. The Data Service Template provides the data model and the message interfaces for all data services.

Client APIs

Table 5-7 summarizes the Data Services client APIs included in com.sun.identity.liberty.ws.dst. For detailed API reference, including methods and their syntax and parameters, see the Javadocs at /opt/SUNWam/docs/am_public_javadocs.jar.

Table 5-7 Data Service Client APIs
Class Name	Description
DSTClient	Provides common functions for the Data Service Templates query and modify option.
DSTData	Provides a wrapper for any data entry.
DSTModification	Represents a Data Services Template modification operation.
DSTModify	Represents a Data Services Template modify request.
DSTModifyResponse	Represents a Data Services Template response for DST modify request.
DSTQuery	Represents a Data Services Template query request.
DSTQueryItem	The wrapper for one query item for Data service.
DSTQueryResponse	Represents a Data Services Template query response.
DSTException	Represents an error while processing Data Service Templates query or modify requests.

Personal Profile Service

A Personal Profile service (ID-PP) is a data-oriented identity web service hosted by an attribute provider for web service clients. It is designed to make public the user personal profiles in the World Wide Web. Examples of personal profile services used in a company are the corporate calendar or phone book which provide information associated with an employee’s individual identity.

Identity Server provides a framework for developing identity web services, and also provides a built-in personal profile service that you can deploy.

Before the Web Service Client posts a query or a modify request, the Personal Profile service for a specific resource must be registered with Discovery Service. This is done by updating a resource offering for a specific resource. The invocation of the personal profile starts when a web services client posts a query or a modify request to the Personal Profile service on behalf of the user.

How It Works

A web services consumer posts either a query or a modify request to the Personal Profile service by keeping appropriate credentials based on the security profile that it is using to communicate.

The client's SOAPRequest is received by the SOAPReceiver provided by the SOAP binding framework. The SOAP framework authenticates the web services client and invokes the corresponding service.

The Personal Profile service handler parses the request and evaluates the authorization for each item in the request. Policy enforcement is done by making use of Identity Server Policy framework. The processing of each request is subject to the processing rules specified by the Liberty Data Template specification.

The Personal Profile service responds to query and modify requests. For query requests, the service builds a personal profile container (as defined by the specification). This is an xml blob based on the Query Select expression. The Personal Profile attribute values are extracted from the data store by making use of the attribute mapper. The attribute mapper is defined by the service xml definition, and these values will be used while building the xml container.

The Personal Profile service then applies xpath queries on the xml blob and gives us the resultant xml data node. For modify requests, it parses the Modifiable Select expression and updates the new data from the new data node in the request.

Finally, the Personal Profile service builds a service response and adds credentials (if they are required), then sends it back to the web services client.

Notes on Customizing the Personal Profile Service

This Personal Profile service is completely customizable and provides multiple levels of customization that you can implement to meet your company’s needs. These include:

Attribute Mapping

Each Personal Profile attribute defined by the Liberty Personal Profile service has a one-to-one Identity Server Personal Profile service attribute. However, we do not need to use the same attributes, instead, we could specify attribute mappings with any other user attributes. These attribute mappings are defined as a global attribute in the personal profile service xml definition.

In the following example, Liberty informalName is mapped to a user's uid which is defined by IDService:


<AttributeSchema name="sunIdentityServerPPDSAttributeMapList"
type="list"
syntax="string"
i18nKey="p108">
<DefaultValues>
<Value>CN=sunIdentityServerPPCommonNameCN</Value>
<Value>FN=sunIdentityServerPPCommonNameFN</Value>
<Value>MN=sunIdentityServerPPCommonNameMN</Value>
<Value>SN=sunIdentityServerPPCommonNameSN</Value>
<Value>InformalName=uid</Value>
</AttributeSchema>

Authorization

The authorization component is a plug-in to the Personal Profile service and is defined by the service as a global attribute. The plug-in implementation must implement the Authorizer interface as defined by API.


<AttributeSchema name="sunIdentityServerPPDSAttributeMapList"
type="list"
syntax="string"
i18nKey="p108">
<DefaultValues>
<Value>CN=sunIdentityServerPPCommonNameCN</Value>
<Value>FN=sunIdentityServerPPCommonNameFN</Value>
<Value>MN=sunIdentityServerPPCommonNameMN</Value>
<Value>SN=sunIdentityServerPPCommonNameSN</Value>
<Value>InformalName=uid</Value>
</AttributeSchema>

The default authorization plug-in uses the Identity Server policy framework and defines four different policy action values for the query and modify operations:

The resource values for the rules are similar to x-path expressions defined by the Personal Profile service. For example, a rule can be defined as follows:

The policy enforcement can be turned off globally by a boolean flag defined by the service xml file.

Containers

The Liberty Personal Profile specification defines all the Personal Profile attributes as container leaf attributes so that they can be easily referencable. Identity Server defines each Personal Profile container as a pluggable entity. The service can also limit the number of personal profile containers that it would like to support by defining them as a global service attribute value.

Each container implements a container interface IDPPContainer. For example, CommonName is a Personal Profile container. The container is defined as follows.

Note that container implementations are not configurable through Service Configuration.

Extensions

The Liberty Personal Profile service allows you to specify extension attributes that are not defined by the Liberty specification. These extensions can be specified for any container or at the container leaf level. The Identity Server Personal Profile service, however, allows you to specify only the extension attributes at the container-level extension element. For example, all the extensions should be defined as follows:


/pp:PP/pp:Extension/ispp:PPISExtension[@name='creditcard']
Note: The prefix for the PPISExtension is different., and the schema for the PP extension is as follows:
<?xml version="1.0" encoding="UTF-8" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.sun.com/identity/liberty/pp"
targetNamespace="http://www.sun.com/identity/liberty/pp">
<xs:annotation>
<xs:documentation>
</xs:documentation>
</xs:annotation>

<xs:element name="PPISExtension">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="name" type="xs:string" use="required"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:schema>

Rewriting the whole service

Personal Profile Service is completely replacable by using the existing web services framework. Each web service needs to register with the SOAP service by specifying a handler. The handler extends from the SOAP's request handler.


<AttributeSchema name="RequestHandlerList"
type="list"
syntax="string"
uitype="name_value_list"
i18nKey="a101">
<DefaultValues>
<Value>key=disco\|class=com.sun.identity.liberty.ws.disco
.DiscoveryService</Value>
<Value>key=idpp\|class=com.sun.identity.liberty.ws.idpp.P
PRequestHandler</Value>
</DefaultValues>
</AttributeSchema>

Interaction Service

An identity service provider sometimes needs to interact with the owner of the exposed resources to get the owner's consent or to get additional data. Identity Server provides a framework to support interactions between web service providers and resource owners. The framework is based upon the Liberty ID-WSF Interaction Service.

The Interaction Service specifies two different mechanisms to facilitate interactions between an identity service provider and a resource owner:

com.sun.liberty.ws.interaction.wspredirecthandler. points to the URL at which WSPRedirectHandler servlet is deployed.

points to the URL at which the XSLT sheet used to format InteractionQuery is available.

Table 5-8 summarizes the Interaction Service APIs. For detailed API reference, including methods and their syntax and parameters, see the Javadocs at /opt/SUNWam/docs/am_public_javadocs.jar.

Table 5-8 Interaction Service APIs
Class Name	Description
InteractionManager	This class provides the interface and implementation for supporting resource owner interaction.
InteractionUtils	Provides some utility methods that work with objects related to interaction
JAXBObjectFactory

Metadata Specifications

Due to changes in Liberty Metadata specification, Liberty Service Management (SM) Configuration schema in Identity Server 6.2 is no longer compatible with that in Identity Server 6.1. SM versioning will be used to support coexistence of Identity Server 6.1 and 6.2 running against same Sun Java System directory Server. Metadata publication via queries through the DNS will not be supported in this release.

External component dependency

When upgrading from Identity Server 6.1 to 6.2, meta data migration is required to make it 6.2 compliant.

PAOS

Simple Object Access Protocol (SOAP) is a lightweight protocol for the exchange of information in a decentralized, distributed environment. SOAP enables the exchange of messages using a variety of underlying protocols. PAOS is another name for the implementation of the Liberty Reverse HTTP Binding for SOAP Specification. The use of PAOS makes possible the exchange of information between user agent hosted services and remote servers.

In a typical forward SOAP binding, an HTTP client exposes a service via a client request and a server response. For example, a cell phone user (the client) may contact his phone service provider (the service) in order to retrieve stocks quotes and weather information. The service verifies the user’s identity, and responds with the requested information.

In a reverse HTTP SOAP binding, the Service Provider server plays the client role, and the client plays the server role. Technically, the initial SOAP request from the server is bound to a server HTTP response. Then the subsequent response is bound to a client request. This is why Reversed HTTP Binding for SOAP is also known as PAOS (or “SOAP” spelled backwards).

PAOS APIs

Table 5-9 summarizes the PAOS APIs included in com.sun.identity.liberty.ws.pao. Note that these APIs are used by PAOS clients which are on the HTTP server side. For detailed API reference, including methods and their syntax and parameters, see the Javadocs at /opt/SUNWam/docs/am_public_javadocs.jar.

Table 5-9 Summary of PAOS APIs in com.sun.identity.liberty.ws.paos
Class Name	Description
PAOSHeader	The PAOSHeader class is used by a web application on HTTP server side to parse a PAOS header in an HTTP request from the user agent side.
PAOSRequest	The PAOSRequest class is used by a web application on HTTP server side to construct a PAOS request message and send it via an HTTPresponse to the user agent side.
PAOSResponse	The PAOSResponse class is used by a web application on HTTP server side to receive and parse a PAOS response via an HTTP request from the user agent side.

Note that PAOSRequest is made available from PAOSResponse to provide correlation if needed by API users.Code Example 5-2 illustrates how to use implement a PAOS client.

public class PAOSClientServlet extends HttpServlet {

public void doGet(HttpServletRequest req, HttpServletResponse res)

throws ServletException, IOException {

// use PAOSHeader class to parse the PAOS header

// to get at least service information

PAOSHeader paosHeader = null;

try {

paosHeader = new PAOSHeader(req);

} catch (PAOSException pe1) {

...

}

HashMap servicesAndOptions = paosHeader.getServicesAndOptions();

Set services = servicesAndOptions.keySet();

// construct PAOSRequest instance

String thisURL = req.getRequestURL().toString();

String[] queryItems = { “/IDPP/Demographics/Birthday” };

PAOSRequest paosReq = null;

try {

paosReq = new PAOSRequest(thisURL,

(String)(services.iterator().next()),

thisURL,

queryItems);

} catch (PAOSException pe2) {

...

}

// send PAOS request

paosReq.send(res, true);

}

public void doPost(HttpServletRequest req, HttpServletResponse res)

throws ServletException, IOException {

// construct a PAOSResponse instance from the HTTP request

PAOSResponse paosRes = null;

try {

paosRes = new PAOSResponse(req);

} catch (PAOSException pe) {

...

}

// get the data from the PAOSResponse

String dataStr = null;

try {

dataStr = paosRes.getPPResponseStr();

} catch (PAOSException paose) {

...

}

...

}

Previous Contents Index Next
Sun Java System Identity Server 2004Q2 Federation Management Guide