Chapter 8 Application Programming Interfaces

Sun ™ Java System Access Manager provides a framework for identity federation and creating, discovering, and consuming identity Web services. This framework includes exposed graphical user interfaces for Liberty-based Web services (discussed in the Web services section of this book) as well as application programming interfaces (APIs). This chapter details information on the APIs that do not have a corresponding graphical user interface (GUI) and contains the following sections:

Overview of Public Interfaces

Table 8-1 lists all of the public APIs you can use to deploy Liberty-enabled components or extend the core services. Packages that are part of a Web service with a GUI are described in the corresponding chapters of this book; links to those chapters are provided in the Description column. Packages that are used in the back-end are described in this chapter; links to those sections are also provided in the Description column. For detailed API reference, including methods and their syntax and parameters, see the Javadocs in /AccessManager_base/SUNWam/docs.

Table 8-1 Summary of Liberty-based Packages
Package Name	Description
com.sun.identity.liberty.ws.authnsvc	Provides classes to manage the Authentication Web Service. See Chapter 4, "Authentication Web Service".
com.sun.identity.liberty.ws.authnsvc.protocol	Provides classes to manage Authentication Web Service protocol. See Chapter 4, "Authentication Web Service".
com.sun.identity.liberty.ws.common	Defines common classes used by many of the Access Manager Liberty-based Web service components. See Common Service Interfaces of this chapter.
com.sun.identity.liberty.ws.common.wsse	Provides an interface to parse and create a X.509 Certificate Token Profile. See Interaction Service API of this chapter.
com.sun.identity.liberty.ws.disco	Provides interfaces to manage the Discovery Service. See Chapter 6, "Discovery Service".
com.sun.identity.liberty.ws.disco.plugins	Provides a plugin interface for the Discovery Service. See Chapter 6, "Discovery Service".
com.sun.identity.liberty.ws.dst	Provides classes to implement an identity service on top of the Access Manager framework. See Chapter 5, "Data Services" for information on a service built using this API and for more general information.
com.sun.identity.liberty.ws.dst.service	Provides a handler class that can be used by any generic identity data service. See Chapter 5, "Data Services" for information on data services and for more general information.
com.sun.identity.liberty.ws.interaction	Provides classes to support the Interaction RequestRedirect Profile. See Interaction Service API of this chapter.
com.sun.identity.liberty.ws.interfaces	Provides interfaces common to all Access Manager Liberty-based Web service components.See Chapter 6, "Discovery Service" and Chapter 5, "Data Services" for information on default implementations. See Common Service Interfaces of this chapter for more general information.
com.sun.identity.liberty.ws.paos	Provides classes for Web applications to construct and process PAOS requests and responses. See PAOS Binding of this chapter.
com.sun.identity.liberty.ws.security	Provides interface to manage Liberty-based Web service security mechanisms. See Common Security API of this chapter.
com.sun.identity.liberty.ws.soapbinding	Provides classes to construct SOAP requests and responses and to change the contact point for the SOAP binding. See Chapter 7, “SOAP Binding Service” on page 147.
com.sun.liberty	Provides interfaces common to the Access Manager Federation Management module. See Chapter 3, "Federation Management".

Common Service Interfaces

This section summarizes classes that can be used by all Liberty-based Access Manager service components, as well as interfaces common to all Liberty-based Access Manager services. The packages are:

com.sun.identity.liberty.ws.common

The com.sun.identity.liberty.ws.common package includes classes common to all Liberty-based Access Manager service components.

Table 8-2 Common Liberty Classes
Class	Description
LogUtil	Class that defines methods which are used by the Liberty component of Access Manager to write logs.
Status	Class that represents a common status object.

For more detailed API reference information, see the Javadocs in /AccessManager_base/SUNWam/docs.

com.sun.identity.liberty.ws.interfaces

The com.sun.identity.liberty.ws.interfaces package includes interfaces that can be implemented to add their corresponding functionality to each Liberty-based Access Manager Web service.

Authorizer

Table 8-3 Common Liberty Interfaces
Interface	Description
Authorizer	Interface for identity service to check authorization of a WSC.
ResourceIDMapper	Interface used to map between a userID and the ResourceID associated with it.

The com.sun.identity.liberty.ws.interfaces.Authorizer is an interface that, once implemented, can be used by each Liberty-based Web service component for access control.


Note	The DefaultDiscoAuthorizer class is the implementation of this interface for the Discovery Service. For more information, see Chapter 6, "Discovery Service." The com.sun.identity.liberty.ws.idpp.plugin.IDPPAuthorizer class is the implementation for the Liberty Personal Profile Service. For more information, see Chapter 5, "Data Services."

The Authorizer interface enables the Web service to check for the authorization of a Web service consumer (WSC) to access the requested resource. When a WSC contacts a Web service provider (WSP), the WSC conveys a sender identity and an invocation identity. (The invocation identity is always the subject of the SAML assertion.) These conveyances allow the WSP to make an authorization decision based on one or both identities. The Access Manager Policy Service performs the authorization based on defined policies.

ResourceIDMapper


Note	See the Sun Java System Access Manager 6 2005Q1 Developer’s Guide (http://docs.sun.com/doc/817-7649) for more information on policy management, single sign-on and sessions. See the Sun Java System Access Manager 6 2005Q1 Administration Guide (http://docs.sun.com/doc/817-7647) for information on creating policy.

The com.sun.identity.liberty.ws.interfaces.ResourceIDMapper is an interface used to map a user DN to the resource identifier associated with it. Access Manager provides two implementations of this interface.

A different implementation of the interface may be developed. The implementation class should be given to the provider that hosts the Discovery Service. The mapping between the providerID and the implementation class can be configured through the “Classes For ResourceIDMapper Plugin” attribute.

Common Security API

The Liberty-based security APIs are included in the com.sun.identity.liberty.ws.security package and the com.sun.identity.liberty.ws.common.wsse package.

com.sun.identity.liberty.ws.security

The com.sun.identity.liberty.ws.security package includes an interface and classes to manage Liberty-based security mechanisms.

Table 8-4 com.sun.identity.liberty.ws.security
Class Name	Description
SecurityTokenProvider	A provider interface for managing Web Service Security (WSS) type 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 the Assertion class to support ID-WSF ResourceAccessStatement and SessionContextStatement
SecurityTokenManager	This is the entry class for the security package com.sun.identity.liberty.ws.security. You can call its methods 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.
SecurityUtils	Class that defines methods which are used to get certificates and sign messages.
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.

For more detailed API reference information, see the Javadocs in /AccessManager_base/SUNWam/docs.

com.sun.identity.liberty.ws.common.wsse

The com.sun.identity.liberty.ws.common.wsse package includes APIs for creating security tokens used for authentication and authorization in accordance with the Liberty ID-WSF Security Mechanisms specification. This document can be found at the Liberty Alliance Project (LAP) Web site at http://www.projectliberty.org/specs/liberty-idwsf-security-mechanisms-v1.1.pdf. Both WSS X509 and SAML tokens are supported.

Table 8-5 Security 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

For more detailed API reference information, see the Javadocs in /AccessManager_base/SUNWam/docs.

Interaction Service API

It is often necessary for providers of identity services to interact with the owner of a reosurce to get the resource owner’s consent to expose data, or to get additional data from the resource owner. The Liberty Alliance Project (LAP) has defined the Liberty ID-WSF Interaction Service Specification to specify how these interactions can be carried out. Of the options for this interaction defined in the specification, Access Manager has implemented one of them: the RedirectRequest. In this profile, the Web service provider (WSP) requests the connecting Web service consumer (WSC) to redirect the user agent (principal) to an interaction resource (URL) at the WSP. Once the user agent sends an HTTP request to fetch the URL, the WSP has the opportunity to present one or more pages to the principal with questions for other information. When the WSP obtains the information it requires to serve the WSC, it redirects the user agent back to the WSC which can now reissue its original request to the WSP.

Configuring the Interaction Service

There is no XML service file for the Interaction Service. There are two properties, though, that are configured upon installation in the AMConfig.properties file located in /AccessManager_base/SUNWam/lib.

com.sun.liberty.ws.interaction.wspRedirectHandler —This property points to the URL at which the WSPRedirectHandler servlet is deployed. The servlet handles the service provider side of interactions for user redirects.

com.sun.identity.liberty.interaction.wscSpecifiedInteractionChoice —This property indicates the level of interaction in which the WSC will participate if they participate in user redirects. Possible values include interactIfNeeded, doNotInteract, and doNotInteractForData. The affirmative interactIfNeeded is the default.

com.sun.identity.liberty.interaction.wscWillIncludeUserInteractionHeader —This property indicates whether the WSC will include a SOAP header to indicate certain preferences for interaction based on the LAP specifications. The default value is yes.

com.sun.identity.liberty.interaction.wscWillRedirect —This property indicates whether the WSC will participate in user redirections. The default value is yes.

com.sun.identity.liberty.interaction.wscSpecifiedMaxInteractionTime —This property indicates the maximum length of time (in seconds) the WSC is willing to wait for the WSP to complete their portion of the interaction. The WSP would not then initiate an interaction if the interaction is likely to take more than the time specified. For example, if the WSP receives a request where this property is set to a maximum 30 seconds and their own property com.sun.identity.liberty.interaction.wspRedirectTime (see below) is set to 40 seconds, the WSP will return a SOAP fault (timeNotSufficient) indicating that the time is not sufficient for interaction.

com.sun.identity.liberty.interaction.wscWillEnforceHttpsCheck—This property indicates whether the WSC will enforce HTTPS in redirected URLs. The default value, yes, indicates that the WSC will not redirect the user when the value of redirectURL (specified by the WSP) is not an HTTPS URL.

com.sun.identity.liberty.interaction.wspWillRedirect—The WSP can initiate an interaction to get user consent for something or to collect additional data. This property indicates whether the WSP will redirect the user for consent. The default value is yes.

com.sun.identity.liberty.interaction.wspWillRedirectForData—The WSP can initiate interaction to get user consent for something or to collect additional data. This property indicates whether the WSP will redirect the user to collect additional data. The default value is yes.

com.sun.identity.liberty.interaction.wspRedirectTime—This property indicates the length of time (in seconds) the WSP expects to take to complete an interaction and return control back to the WSC. For example, if the WSP receives a request indicating that the WSC will wait a maximum 30 seconds (set in com.sun.identity.liberty.interaction.wscSpecifiedMaxInteractionTime) for interaction and wspRedirectTime is set to 40 seconds, the WSP will return a SOAP fault (timeNotSufficient) indicating that the time is not sufficient for interaction.

com.sun.identity.liberty.interaction.wspWillEnforceHttpsCheck—This property indicates whether the WSP will enforce a HTTPS returnToURL specified by the WSC. The default value is yes.

com.sun.identity.liberty.interaction.wspWillEnforceReturnToHostEqualsRequestHost—This property indicates whether the WSP would enforce the address values of returnToHost and requestHost if they are the same. Per the LAP specifications, the value of this property is always yes.

com.sun.identity.liberty.interaction.htmlStyleSheetLocation—This property points to the location of the style sheet used to render the interaction page in HTML.

com.sun.identity.liberty.interaction.wmlStyleSheetLocation—This property points to the location of the style sheet used to render the interaction page in WML.

Interaction Service API

The Access Manager Interaction Service includes a Java package named com.sun.identity.liberty.ws.interaction. WSCs and WSPs use these classes to interact with a resource owner. Table 8-6 details the API.

Table 8-6 Interaction Service API
Class	Description
InteractionManager	This class provides the interface and implementation for resource owner interaction.
InteractionUtils	This class provides some utility methods related to resoource owner interaction.
JAXBObjectFactory	This object contains factory methods. An ObjectFactory allows you to programatically construct new instances of the Java representation for XML content.

For more detailed API reference information, including methods and their syntax and parameters, see the Javadocs in /AccessManager_base/SUNWam/docs.

PAOS Binding

Access Manager has implemented the optional Liberty Alliance Project (LAP) Liberty Reverse HTTP Binding for SOAP Specification. It defines a message exchange protocol that permits a HTTP client to be a SOAP responder. HTTP clients are no longer necessarily equipped with HTTP servers. For example, mobile terminals and personal computers contain Web browsers yet they do not operate HTTP servers. These clients, though, can use their browsers to interact with an identity service (possibly a personal profile service or a calendar service). These identity services could also be valuable when the client devices interact with an HTTP server. The use of PAOS makes it possible to exchange information between user agent hosted services and remote servers.

PAOS vs. SOAP

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

In a reverse HTTP for SOAP binding, the phone service provider plays the client role, and the cell phone client plays the server role. The initial SOAP request from the server is actually bound to a HTTP response. The subsequent response from the client is bound to a request. This is why the reverse HTTP for SOAP binding is also known as PAOS; the spelling of SOAP is reversed.

PAOS Binding API

The Access Manager implementation of PAOS binding includes a Java package named com.sun.identity.liberty.ws.paos. It provides classes to parse a PAOS header, make a PAOS request, and receive a PAOS response.


Note	These APIs are used by PAOS clients on the HTTP server side. APIs for PAOS servers on the HTTP client side would be developed by the manufacturers of the HTTP client side products, for example, cell phone manufacturers.

Table 8-7 details the available classes in com.sun.identity.liberty.ws.paos. For more detailed information, including methods and their syntax and parameters, see the Javadocs in /AccessManager_base/SUNWam/docs.

Table 8-7 Summary of PAOS APIs
Class Name	Description
PAOSHeader	The PAOSHeader class is used by a web application on the 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 the 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 the 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 in PAOSResponse to provide correlation if needed by API users.

PAOS Binding Sample

A sample demonstrating PAOS service interaction between a HTTP client and server is provided in the /AccessManager_base/SUNWam/samples/phase2/paos directory. The PAOS client is a servlet, and the PAOS server is a stand-alone Java program. Instructions on how to run the sample can be found in the Readme.html or Readme.txt both included in the paos directory. Code Example 8-1 is the PAOS client servlet also included.

Code Example 8-1 PAOS Client Servlet from PAOS Sample


import java.util.*;
import java.io.*;

import javax.servlet.*;
import javax.servlet.http.*;

import com.sun.identity.liberty.ws.paos.*;

import com.sun.identity.liberty.ws.idpp.jaxb.*;

public class PAOSClientServlet extends HttpServlet {

public void doGet(HttpServletRequest req, HttpServletResponse res)
throws ServletException, IOException {

PAOSHeader paosHeader = null;
try {
paosHeader = new PAOSHeader(req);
} catch (PAOSException pe1) {
pe1.printStackTrace();

String msg = "No PAOS header\n";
res.setContentType("text/plain");
res.setContentLength(1+msg.length());
PrintWriter out = new PrintWriter(res.getOutputStream());
out.println(msg);
out.close();

throw new ServletException(pe1.getMessage());
}

HashMap servicesAndOptions = paosHeader.getServicesAndOptions();

Set services = servicesAndOptions.keySet();

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) {
pe2.printStackTrace();
throw new ServletException(pe2.getMessage());
}
System.out.println("PAOS request to User Agent side --------------->");
System.out.println(paosReq.toString());
paosReq.send(res, true);
}

public void doPost(HttpServletRequest req, HttpServletResponse res)
throws ServletException, IOException {

PAOSResponse paosRes = null;
try {
paosRes = new PAOSResponse(req);
} catch (PAOSException pe) {
pe.printStackTrace();
throw new ServletException(pe.getMessage());
}

System.out.println("PAOS response from User Agent side -------------->");
System.out.println(paosRes.toString());

System.out.println("Data output after parsing -------------->");

String dataStr = null;
try {
dataStr = paosRes.getPPResponseStr();
} catch (PAOSException paose) {
paose.printStackTrace();
throw new ServletException(paose.getMessage());
}
System.out.println(dataStr);

String msg = "Got the data: \n" + dataStr;

res.setContentType("text/plain");
res.setContentLength(1+msg.length());

PrintWriter out = new PrintWriter(res.getOutputStream());

out.println(msg);

out.close();
}
}

Previous Contents Index Next
Sun Java Systems Access Manager 6 2005Q1 Federation Management Guide


Note	Be sure to check out Appendix A, "Included Samples" for information on all the sample code and files included with Access Manager.