Sun Java System Identity Server 2004Q2 Federation Management Guide |
Chapter 5
Using the Web Services Client APIsSun 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 InterfacesTable 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.
Trusted AuthorityThe 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.
SOAP BindingThe 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.
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.
- 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>
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:
key=idpp|class=com.sun.identity.liberty.ws.idpp.PPRequestHandler
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.
AuthorizationWhen 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 ServiceA 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:
ServiceType + RESOURCE_SEPERATOR + ProviderID.
Example:
urn:liberty:id-sis-pp:2003-08;http://example.com.
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:
providerID + "/" + the Base64 encoded userIDs
In this example, com.sun.identity.liberty.ws.disco.plugins.DefaultHexResourceIDMapper assumes the format of ResourceID is:
providerID + "/" + the hex string of userID.
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.
Discovery Service provides three implementations for this interface.
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 TemplateThe 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 ServiceA 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.
The following the default plug-in implementation:
<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:
/PP/CommonName/AnalyzedName/FN Query Interact for consent
/PP/CommonName/* Modify Interact for value
/PP/InformalName Query Deny
Here, the subjects can be defined as web services clients.
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/Extension/PPISExtension [@name='extensionattribute']
A typical extension query expression for an extension attribute is 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.
The default Personal Profile Service is registered as follows:
<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 ServiceAn 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:
- The identity service provider and web service consumer can cooperate to redirect the resource owner to the identity service provider and back to the web service consumer.
- Interaction Service can be hosted as a web service. This service can be offered by a trusted web service consumer as well as by a dedicated provider that has a reliable means of communication with the resource owner. The identity service provider would interact with this interaction service by exchanging SOAP messages.
Interaction Service provides interfaces:
com.sun.liberty.ws.interaction.wspredirecthandler. points to the URL at which WSPRedirectHandler servlet is deployed.
com.sun.liberty.ws.interaction.wspstylesheet.
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 SpecificationsDue 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.
PAOSSimple 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.
Code Example 5-2 Sample PAOSClientServlet
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) {
...
}
...
}
}