Sun Java Systems Access Manager 6 2005Q1 Federation Management Guide |
Chapter 8
Application Programming InterfacesSun 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 InterfacesTable 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 InterfacesThis 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.
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
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.
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.
ResourceIDMapper
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 APIThe 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.
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.
For more detailed API reference information, see the Javadocs in /AccessManager_base/SUNWam/docs.
Interaction Service APIIt 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.
For more detailed API reference information, including methods and their syntax and parameters, see the Javadocs in /AccessManager_base/SUNWam/docs.
PAOS BindingAccess 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.
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.
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.
Note
Be sure to check out Appendix A, "Included Samples" for information on all the sample code and files included with Access Manager.