Contained WithinFind More DocumentationFeatured Support Resources |  PDF로 이 문서 다운로드 (1272 KB)
Part IV SAML Administration and Application Programming InterfacesChapter 9 SAML AdministrationSun Java™ System Access Manager uses the Security Assertion Markup Language (SAML) as the means for exchanging security information. SAML uses an eXtensible Markup Language (XML) framework to achieve interoperability between vendor platforms that provide SAML assertions. This chapter explains SAML and defines how it is used within Access Manager. This chapter covers the following topics: SAML OverviewSAML is an open-standard protocol that defines user authentication, entitlements, and attribute information in XML documents. The Organization for the Advancement of Structured Information Standards (OASIS) drives the development of SAML 1.0 and 1.1, the versions supported in Access Manager 7 2005Q4. Note – For information and specifications, see the OASIS Security Services (SAML) Technical Committee web site. The SAML documents can be used to exchange security information between an authority and a trusted partner site. The security information that is exchanged deals with a subject’s authentication status, access authorization, and attribute information. A subject is an entity in a particular domain. A person identified by an email address is a subject, as might be a printer. A SAML authority, sometimes called the asserting party, is a platform or application that has been integrated with the SAML API, allowing it to relay security information. Trusted partner sites receive the security information and rely on its authenticity. Note – All domains need to form a trust relationship before they can share information about a subject’s identity. How this is accomplished is beyond the scope of this guide. Comparison of SAML and Liberty SpecificationsSAML was designed by vendors to address the issue of cross-domain single sign-on. The Liberty Alliance Project was formed to develop technical specifications that would solve business process problems. These issues include single sign-on, but also incorporate protocols for account linking and consent, among others. SAML, on the other hand, does not solve issues such as privacy, single logout, and federation termination. The SAML 1.0 and 1.1 specifications and the Liberty Alliance Project specifications do not compete with one another. They are complementary. In fact, the Liberty Alliance Project specifications leverage profiles from the SAML specifications. The decision of whether to use SAML or the Liberty specifications depends on your goal. In general, SAML should suffice for single sign-on basics. The Liberty Alliance Project specifications can be used for more sophisticated functions and capabilities, such as global sign-out, attribute sharing, web services. The following table lists the benefits of the two. Table 9–1 Benefits of the SAML and the Liberty Alliance Project Specifications
Note – SAML Version 2.0 has been integrated into the Liberty Alliance Project specifications. This version is planned for implementation in an upcoming release of Access Manager. SAML Architecture in Access ManagerSAML security information is expressed in the form of an assertion about a subject. An assertion is a package of verified security information that supplies one or more statements concerning a subject’s authentication status, access authorization decisions, or identity attributes. Assertions are issued by the SAML authority, and received by partner sites defined by the authority as trusted. SAML authorities use different sources to configure the assertion information, including external data stores or assertions that have already been received and verified. The following figure illustrates how SAML interacts with the other components in Access Manager. Note – Although Federation (as described in Chapter 3, Federation) integrates aspects of the SAML specifications, its usage of SAML is independent of the SAML component as described in this chapter. Figure 9–1 SAML Interaction in Access Manager
SAML allows Access Manager to work in the following ways:
Using SAMLThe SAML can be accessed using a web browser or the SAML API. An end user authenticates to Access Manager using a web browser and, once authorized to do so, accesses URLs from trusted partner sites. Developers integrate the API into their applications to exchange security information with Access Manager. For example, a Java application can use the SAML API to achieve single sign-on. After obtaining a SSOToken from Access Manager, the application can call the doWebArtifact() method of the SAMLClient class, which will send a SOAP request for authorization information to Access Manager and, if applicable, redirect the application to the destination site. For more information, see SAML API. Elements of SAMLThe following sections describe the elements of the SAML component: Assertion TypesSAML assertions are a declaration of facts about a principal. For example, an assertion can be made that a particular client was granted update privileges to a specific database resource at a certain time. Assertions are constructed in XML based on the SAML assertion schema. Assertions are built from the user’s session information and optional attribute information using the siteAttributeMapper class. For more information, see SiteAttributeMapper and PartnerSiteAttributeMapper Interfaces. Note – One assertion can contain many different statements made by the authority. The SAML specification provides for different types of assertions:
Profile TypesA profile is a set of rules that defines how to embed and extract SAML assertions. The profile describes how the assertions are combined with other objects by an authority, transported from the authority, and subsequently processed at the trusted partner site. Access Manager supports two profiles: the Web Browser Artifact Profile and the Web Browser POST Profile. Both profiles use HTTP. Either can be used in single sign-on between two SAML-enabled entities, allowing an authenticated user to access resources from a trusted partner site. Each profile has its benefits:
The profile methods can be initiated through a web browser or the SAML API. For more information about the API method, see SAML API. Web Browser Artifact ProfileThe Web Browser Artifact Profile defines interaction between three parties: a user equipped with a web browser, an authority site, and a trusted partner site. The SOAP communication should be either Basic Authentication or Client Certificate Authentication over SSL. Note that XML signing is a stronger alternative.
Figure 9–2 Web Browser Artifact Profile Interactions
A sample has been provided to test the Web Browser Artifact Profile function. See SAML Samples for more information. Web Browser POST ProfileThe Web Browser POST Profile allows security information to be supplied to a trusted partner site using the HTTP POST method (without the use of an artifact). This interaction consists of two parts. The first part is between a user with a web browser and Access Manager. The second part is between the same user and the trusted partner site. The content of the POST should be signed to ensure message integrity, and the method of transport should be SSL. Note – The POST profile function is provided by either of two means:
an HTTP request using
Figure 9–3 Web Browser POST Profile Interactions
A sample has been provided to test the Web Browser POST Profile function. See SAML Samples. Single-Use Policy With POST ProfileAccording to the SAML specifications, the trusted partner site must ensure a single-use policy for SSO assertions that are communicated
using the Web Browser POST Profile. SAML SOAP ReceiverAssertions are exchanged between Access Manager and inquiring parties using the <Request> and <Response> XML constructs defined in the SAML specification. These SAML constructs are then integrated into SOAP messages for transport. Note – A SAML <Request> can contain queries for authentication status, authorization decisions, attribute information, and one or more assertion identifier references or artifacts. Access Manager uses SOAP, a message communications specification that integrates
XML and HTTPS, to transport the SAML constructs. The request is received by Note –
SOAP MessagesSOAP messages consist of three parts: an envelope, header data, and a message body. The SAML <Request> and <Response> elements are enclosed in the message body. A client transmits a SAML <Request> element within the body of a SOAP message to an entity. Note – The SAML API and the Java API for XML Messaging (JAXM) are used
to construct SOAP messages and send them to The following two samples illustrate a SOAP exchange for the Web Browser Artifact Profile. The first is a request for an authentication assertion. Example 9–1 SOAP Request for Authentication Assertion Using Web Browser Artifact Profile
In response to the request, Example 9–2 SOAP Response to SOAP Request for Web Browser Artifact Profile
Note – The entities requesting and responding with SAML must not include more than one SAML request or response per SOAP message. They must also not include any additional XML elements in the SOAP body. Protecting
|
To Configure Access Manager for Basic Authentication
Caution –
// get statement in the assertion Set set = assertion.getStatement(); //assume there is one AttributeStatement //should check null& instanceof AttributeStatement statement = (AttributeStatement) set.iterator().next(); List attributes = statement.getAttribute(); // assume there is at least one Attribute Attribute attribute = (Attribute) attributes.get(0); List values = attribute.getAttributeValue(); |
com.sun.identity.saml.common Package
This package defines classes common to all SAML elements, including site ID, issuer name, and server host. The package also contains all SAML-related exceptions.
com.sun.identity.saml.plugins Package
Access Manager provides service provider interfaces (SPIs), three of which have default implementations. The default implementations of these SPIs can be altered, or brand new ones written, based on the specifications of a particular customized service. The implementations are then used to integrate SAML into the custom service. Currently, the package includes the following interfaces:
AccountMapper and PartnerAccountMapper Interfaces
AccountMapper and PartnerAccountMapper are interfaces that need to be implemented by each partner site. The implemented class maps the partner site's user accounts to user accounts configured in Access Manager for purposes of single sign-on. For example, if single sign-on is configured from site A to site B, a site-specific account mapper can be developed and defined in the Trusted Partners subattribute of site B's Trusted Partners profile. When site B processes the assertion received, it locates the corresponding account mapper by retrieving the source ID of the originating site. Either SPI can be implemented although PartnerAccountMapper has one benefit over AccountMapper: it takes the whole assertion as a parameter, enabling the partner to define user account mapping based on attributes inside the assertion. The AccountMapper interface uses only the subject of the assertion as a parameter. The default implementation is com.sun.identity.saml.plugin.DefaultAccountMapper. If a site-specific account mapper is not configured, this default mapper is used.
Note –
Turning on the Debug Service in the AMConfig.properties file logs additional information about the account mapper, for example, the user name and organization to which the mapper has been mapped. For more information about the AMConfig.properties file, see the Sun Java System Access Manager 7 2005Q4 Developer’s Guide.
SiteAttributeMapper and PartnerSiteAttributeMapper Interfaces
SiteAttributeMapper and PartnerSiteAttributeMapper are interfaces that need to be implemented by each partner site. The implemented class defines a list of attributes to be returned as elements of the AttributeStatements in an authentication assertion. By default, when Access Manager creates an assertion and no mapper is specified, the authentication assertion only contains authentication statements. If a partner site wants to include attribute statements, it needs to implement one of these mappers. This class would be used to obtain attributes, create the attribute statement, and insert the statement inside the assertion. Either SPI can be implemented although PartnerSiteAttributeMapper has one benefit over SiteAttributeMapper: there is an additional targetURL parameter that enables the partner to include different sets of attributes to target different applications.
Note –
The default behavior is that no attribute statements are returned unless specified by the plug-in.
AttributeMapper Interface
AttributeMapper is an interface used in conjunction with an AttributeQuery class When a site receives an attribute query, this mapper obtains the SSOToken or an assertion (containing an authentication statement) from the query. The retrieved information is used to convert the attributes in the query to the corresponding Access Manager attributes. A default attribute mapper is provided if no other implementation is defined.
For more information, see AttributeQuery Class.
ActionMapper Interface
ActionMapper is an interface used to obtain single sign-on information and to map partner actions to Access Manager authorization decisions. A default action mapper is provided if no other implementation is defined.
com.sun.identity.saml.protocol Package
This package contains classes that parse the request and response XML messages used to exchange assertions and their authentication, attribute, or authorization information.
AuthenticationQuery Class
The AuthenticationQuery class represents a query for an authentication assertion. When an identity attempts to access a trusted partner web site, a SAML request with an AuthenticationQuery inside is directed to the authority site.
The Subject of the AuthenticationQuery must contain a SubjectConfirmation element. In this element, ConfirmationMethod needs to be set to urn:com:sun:identity, and SubjectConfirmationData needs to be set to the SSOToken ID of the Subject. If the Subject contains a NameIdentifier, the value of the NameIdentifier should be the same as the one in the SSOToken.
AttributeQuery Class
The AttributeQuery class represents a query for an identity’s attributes. When an identity attempts to access a trusted partner web site, a SAML request with an AttributeQuery is directed to the authority site.
You can develop an attribute mapper to obtain an SSOToken, or an assertion that contains an AuthenticationStatement from the query. If no attribute mapper for the querying site is defined, the DefaultAttributeMapper will be used. To use the DefaultAttributeMapper, the query should have either the SSOToken or an assertion that contains an AuthenticationStatement in the SubjectConfirmationData element. If an SSOToken is used, the ConfirmationMethod must be set to urn:com:sun:identity:. If an assertion is used, the assertion should be issued by the Access Manager instance processing the query or a server that is trusted by the Access Manager instance processing the query.
Note –
In the DefaultAttributeMapper, a subject’s attributes can be queried using another subject’s SSOToken if the SSOToken has the privilege to retrieve the attributes.
For a query using the DefaultAttributeMapper, any matching attributes found will be returned. If no AttributeDesignator is specified in the AttributeQuery, all attributes from the services defined under the userServiceNameList in amSAML.properties will be returned. The value of the userServiceNameList property is user service names separated by a comma.
AuthorizationDecisionQuery Class
The AuthorizationDecisionQuery class represents a query about a principal’s authority to access protected resources. When an identity attempts to access a trusted partner web site, a SAML request with an AuthorizationDecisionQuery is directed to the authority site.
You can develop an ActionMapper to obtain the SSOToken ID and retrieve the authentication decisions for the actions defined in the query. If no ActionMapper for the querying site is defined, the DefaultActionMapper will be used. To use the DefaultActionMapper, the query should have the SSOToken ID in the SubjectConfirmationData element of the Subject. If the SSOToken ID is used, the ConfirmationMethod must be set to urn:com:sun:identity:. If a NameIdentifier is present, the information in the SSOToken must be the same as the information in the NameIdentifier.
Note –
When using web agents, the DefaultActionMapper handles actions in the namespace urn:oasis:names:tc:SAML:1.0:ghpp only. Web agents serve the policy decisions for this action namespace.
The authentication information can also be passed through the Evidence element in the query. Evidence can contain an AssertionIDReference, an assertion containing an AuthenticationStatement issued by the Access Manager instance processing the query, or an assertion issued by a server that is trusted by the Access Manager instance processing the query. The Subject in the AuthenticationStatement of the Evidence element should be the same as the one in the query.
Note –
Policy conditions can be passed through AttributeStatements of assertion(s) inside the Evidence of a query. If the value of an attribute contains a TEXT node only, the condition is set as attributeName=attributeValueString. Otherwise, the condition is set as attributename=attributeValueElement.
The following example illustrates one of many ways to form an authorization decision query that will return a decision.
Example 9–4 AuthorizationDecisionQuery Code Sample
// testing getAssertion(authZQuery): no SC, with ni, with
// evidence(AssertionIDRef, authN, for this ni):
String nameQualifier = "dc=iplanet,dc=com";
String pName = "uid=amadmin,ou=people,dc=iplanet,dc=com";
NameIdentifier ni = new NameIdentifier(pName, nameQualifier);
Subject subject = new Subject(ni);
String actionNamespace = "urn:test";
// policy should be added to this resource with these
// actions for the subject
Action action1 = new Action(actionNamespace, "GET");
Action action2 = new Action(actionNamespace, "POST");
List actions = new ArrayList();
actions.add(action1);
actions.add(action2);
String resource = "http://www.sun.com:80";
eviSet = new HashSet();
// this assertion should contain authentication assertion for
// this subject and should be created by a trusted server
eviSet.add(eviAssertionIDRef3);
evidence = new Evidence(eviSet);
authzQuery = new AuthorizationDecisionQuery(eviSubject1, actions,
evidence, resource);
try {
assertion = am.getAssertion(authzQuery, destID);
} catch (SAMLException e) {
out.println("--failed. Exception:" + e);
}
|
com.sun.identity.saml.xmlsig Package
All SAML assertions, requests, and responses can be signed using this signature package. It contains SPI that are implemented to plug in proprietary XML signatures. This package contains classes needed to sign and verify using XML signatures. By default, the keystore provided with the Java Development Kit is used and the key type is DSA. The configuration properties for this functionality are in the AMConfig.properties file. For information about these properties, see the Sun Java System Access Manager 7 2005Q4 Developer’s Guide. For details on how to use the signature functionality, see SAML Samples.
SAML Samples
You can access several SAML-based samples from the Access Manager installation in /AccessManager-base/SUNWam/samples/saml. These samples illustrate how the SAML service can be used in different ways, including the following:
-
A sample that serves as the basis for using the SAML client API. This sample is located in /AccessManager-base/SUNWam/samples/saml/client.
-
A sample that illustrates how to form a Query, write an AttributeMapper, and send and process a SOAP message using the SAML SDK. This sample is located in /AccessManager-base/SUNWam/samples/saml/query.
-
A sample application for achieving SSO using either the Web Browser Artifact Profile or the Web Browser POST Profile. This sample is located in /AccessManager-base/SUNWam/samples/saml/sso.
-
A sample that illustrates how to use the XMLSIG API and explains how to configure for XML signing. This sample is located in /AccessManager-base/SUNWam/samples/saml/xmlsig.
Each sample includes a README file with information and instructions on how to use it.
Chapter 10 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 a graphical user interface for Liberty-based web services as well as application programming interfaces (APIs). This chapter provides information on the APIs that do not have a corresponding graphical user interface (GUI).
This chapter covers the following topics:
Public Interfaces
The following list describes 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 that has a GUI are described in the corresponding chapters of this book. Packages that are used solely on the back end are described in this chapter. Links to those sections are also provided. For more information, including methods and their syntax and parameters, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.
Table 10–1 Access Manager Public APIs|
Package Name |
Description |
|---|---|
|
com.sun.identity.liberty.ws.authnsvc |
Provides classes to manage the Authentication Web Service. See Chapter 5, Authentication Web Service. |
|
com.sun.identity.liberty.ws.authnsvc.mechanism |
Provides an interface to process incoming Simple Authentication and Security Layer (SASL) requests and generate SASL responses for the different SASL mechanisms. See Chapter 5, Authentication Web Service. |
|
com.sun.identity.liberty.ws.authnsvc.protocol |
Provides classes to manage the Authentication Web Service protocol. See Chapter 5, 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. |
|
com.sun.identity.liberty.ws.common.wsse |
Provides an interface to parse and create an X.509 Certificate Token Profile. See Common Service Interfaces. |
|
com.sun.identity.liberty.ws.disco |
Provides interfaces to manage the Discovery Service. See Chapter 7, Discovery Service. |
|
com.sun.identity.liberty.ws.disco.plugins |
Provides a plug-in interface for the Discovery Service. See Chapter 7, Discovery Service. |
|
com.sun.identity.liberty.ws.dst |
Provides classes to implement an identity service on top of the Access Manager framework. See Chapter 6, Data Services for information about a service built using this API. |
|
com.sun.identity.liberty.ws.dst.service |
Provides a handler class that can be used by any generic identity data service. See Chapter 6, Data Services for information on data services. |
|
com.sun.identity.liberty.ws.interaction |
Provides classes to support the Liberty-based Interaction RequestRedirect Profile. See Interaction Service. |
|
com.sun.identity.liberty.ws.interfaces |
Provides interfaces common to all Access Manager Liberty-based web service components. See Chapter 6, Data Services and Chapter 7, Discovery Service for information about default implementations. See Common Service Interfaces 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. |
|
com.sun.identity.liberty.ws.security |
Provides an interface to manage Liberty-based web service security mechanisms. See Common Security API. |
|
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 8, SOAP Binding Service. |
|
com.sun.identity.saml |
Provides an SPI in which proprietary XML signature implementations can be plugged in. See Chapter 9, SAML Administration. |
|
com.sun.identity.saml.assertion |
Provides classes that manage assertions and profiles. See Chapter 9, SAML Administration. |
|
com.sun.identity.saml.common |
Provides classes common to all SAML elements. See Chapter 9, SAML Administration. |
|
com.sun.identity.saml.plugins |
Provides SPIs to integrate SAML into custom services. See Chapter 9, SAML Administration. |
|
com.sun.identity.saml.protocol |
Provides classes that parse the XML messages used to exchange assertions and information. See Chapter 9, SAML Administration. |
|
com.sun.identity.saml.xmlsig |
Provides an SPI in which proprietary XML signature implementations can be plugged in. See Chapter 9, SAML Administration. |
|
com.sun.liberty |
Provides interfaces common to the Access Manager Federation Management module. See Chapter 3, Federation. |
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 that contain the classes and interfaces are:
com.sun.identity.liberty.ws.common Package
This package includes classes common to all Liberty-based Access Manager service components.
Table 10–2 com.sun.identity.liberty.ws.common Classes|
Class |
Description |
|---|---|
|
LogUtil |
Defines methods that are used by the Liberty component of Access Manager to write logs. |
|
Status |
Represents a common status object. |
For more information, including methods and their syntax and parameters, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.
com.sun.identity.liberty.ws.interfaces Package
This package includes interfaces that can be implemented to add their corresponding functionality to each Liberty-based Access Manager web service.
Table 10–3 com.sun.identity.liberty.ws.interfaces Interfaces|
Interface |
Description |
|---|---|
|
Authorizer |
Interface for identity service to check authorization of a WSC. |
|
ResourceIDMapper |
Interface used to map between a user ID and the Resource ID associated with it. |
|
ServiceInstanceUpdate |
Interface used to include a SOAP header (ServiceInstanceUpdateHeader) when sending a SOAP response. |
com.sun.identity.liberty.ws.interfaces.Authorizer Interface
This interface, once implemented, can be used by each Liberty-based web service component for access control.
Note –
The com.sun.identity.liberty.ws.disco.plugins.DefaultDiscoAuthorizer class is the implementation of this interface for the Discovery Service. For more information, see Chapter 7, 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 6, Data Services.
The Authorizer interface enables a web service to check whether a web service consumer (WSC) is allowed to access the requested resource. When a WSC contacts a web service provider (WSP), the WSC conveys a sender identity and an invocation identity. Note that the invocation identity is always the subject of the SAML assertion. These conveyances enable 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 7 2005Q4 Technical Overview for more information about policy management, single sign-on, and user sessions. See the Sun Java System Access Manager 7 2005Q4 Administration Guide for information about creating policy.
com.sun.identity.liberty.ws.interfaces.ResourceIDMapper Interface
This interface is used to map a user DN to the resource identifier associated with it. Access Manager provides implementations of this interface.
-
com.sun.identity.liberty.ws.disco.plugins.Default64ResourceIDMapper assumes the Resource ID format to be: providerID + "/" + the Base64 encoded userIDs.
-
com.sun.identity.liberty.ws.disco.plugins.DefaultHexResourceIDMapper assumes the Resource ID format to be: providerID + "/" + the hex string of userID.
-
com.sun.identity.liberty.ws.idpp.plugin.IDPPResourceIDMapper assumes the Resource ID format to be: providerID + "/" + the Base64 encoded userIDs.
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 Package
The com.sun.identity.liberty.ws.security package includes the SecurityTokenProvider interface for managing Web Service Security (WSS) type tokens. The following table describes the classes used to manage Liberty-based security mechanisms.
Table 10–4 com.sun.identity.liberty.ws.security Classes|
Class |
Description |
|---|---|
|
ProxySubject |
Represents the identity of a proxy, the confirmation key, and confirmation obligation the proxy must possess and demonstrate for authentication purposes. |
|
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 |
An entry class for the security package com.sun.identity.liberty.ws.security. You can call its methods to generate X.509 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 |
Defines methods that are used to get certificates and sign messages. |
|
SessionContext |
Represents the session status of an entity to another system entity. |
|
SessionContextStatement |
Conveys the session status of an entity to another system entity within the body of an <saml:assertion> element. |
|
SessionSubject |
Represents a Liberty subject with its associated session status. |
For more information, including methods and their syntax and parameters, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.
com.sun.identity.liberty.ws.common.wsse Package
This package includes classes for creating security tokens used for authentication and authorization in accordance with the Liberty ID-WSF Security Mechanisms. Both WSS X.509 and SAML tokens are supported.
Table 10–5 com.sun.identity.liberty.ws.common.wsse Classes|
Class |
Description |
|---|---|
|
BinarySecurityToken |
Provides an interface to parse and create the X.509 Security Token depicted by Web Service Security: X.509 |
|
WSSEConstants |
Defines constants used in security packages. |
For more information, including methods and their syntax and parameters, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.
Interaction Service
Providers of identity services often need to interact with the owner of a resource to get additional information, or to get their consent to expose data. The Liberty Alliance Project has defined the Liberty ID-WSF Interaction Service Specification to specify how these interactions can be carried out. Of the options defined in the specification, Access Manager has implemented the Interaction RequestRedirect Profile. In this profile, the WSP requests the connecting WSC to redirect the user agent (principal) to an interaction resource (URL) at the WSP. When the user agent sends an HTTP request to get the URL, the WSP has the opportunity to present one or more pages to the principal with questions for other information. After the WSP obtains the information it needs 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
While there is no XML service file for the Interaction Service, this service does have properties. The properties are configured upon installation in the AMConfig.properties file located in /AccessManager-base/SUNWam/lib and are described in the following table.
Table 10–6 Interaction Service Properties in AMConfig.properties|
Property |
Description |
|---|---|
|
com.sun.liberty.ws.interaction.wspRedirectHandler |
Points to the URL where the WSPRedirectHandler servlet is deployed. The servlet handles the service provider side of interactions for user redirects. |
|
com.sun.identity.liberty.interaction.wscSpecifiedInteractionChoice |
Indicates the level of interaction in which the WSC will participate if the WSC participates in user redirects. Possible values include interactIfNeeded, doNotInteract, and doNotInteractForData. The affirmative interactIfNeeded is the default. |
|
com.sun.identity.liberty.interaction.wscWillIncludeUserInteractionHeader |
Indicates whether the WSC will include a SOAP header to indicate certain preferences for interaction based on the Liberty specifications. The default value is yes. |
|
com.sun.identity.liberty.interaction.wscWillRedirect |
Indicates whether the WSC will participate in user redirections. The default value is yes. |
|
com.sun.identity.liberty.interaction.wscSpecifiedMaxInteractionTime |
Indicates the maximum length of time (in seconds) the WSC is willing to wait for the WSP to complete its portion of the interaction. The WSP will not initiate an interaction if the interaction is likely to take more time than . For example, the WSP receives a request where this property is set to a maximum 30 seconds. If the WSP property com.sun.identity.liberty.interaction.wspRedirectTime is set to 40 seconds, the WSP returns a SOAP fault (timeNotSufficient), indicating that the time is insufficient for interaction. |
|
com.sun.identity.liberty.interaction.wscWillEnforceHttpsCheck |
Indicates whether the WSC will enforce HTTPS in redirected URLs. The Liberty Alliance Project specifications state that, the value of this property is always yes, which indicates that the WSP will not redirect the user when the value of redirectURL (specified by the WSP) is not an HTTPS URL. The false value is primarily meant for ease of deployment in a phased manner. |
|
com.sun.identity.liberty.interaction.wspWillRedirect |
Initiates 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 |
Initiates an 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 |
Indicates the length of time (in seconds) that the WSP expects to take to complete an interaction and return control back to the WSC. For example, 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. If the wspRedirectTime is set to 40 seconds, the WSP returns a SOAP fault (timeNotSufficient), indicating that the time is insufficient for interaction. |
|
com.sun.identity.liberty.interaction.wspWillEnforceHttpsCheck |
Indicates whether the WSP will enforce a HTTPS returnToURL specified by the WSC. The Liberty Alliance Project specifications state that the value of this property is always yes. The false value is primarily meant for ease of deployment in a phased manner. |
|
com.sun.identity.liberty.interaction.wspWillEnforceReturnToHostEqualsRequestHost |
Indicates whether the WSP would enforce the address values of returnToHost and requestHost if they are the same. The Liberty Alliance Project specifications state that the value of this property is always yes. The false value is primarily meant for ease of deployment in a phased manner. |
|
com.sun.identity.liberty.interaction.htmlStyleSheetLocation |
Points to the location of the style sheet that is used to render the interaction page in HTML. |
|
com.sun.identity.liberty.interaction.wmlStyleSheetLocation |
Points to the location of the style sheet that is 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 the classes in this package to interact with a resource owner. The following table describes the classes.
Table 10–7 Interaction Service Classes|
Class |
Description |
|---|---|
|
InteractionManager |
Provides the interface and implementation for resource owner interaction. |
|
InteractionUtils |
Provides some utility methods related to resource owner interaction. |
|
JAXBObjectFactory |
Contains factory methods that enable you to construct new instances of the Java representation for XML content. |
For more information, including methods and their syntax and parameters, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.
PAOS Binding
Access Manager has implemented the optional Liberty Reverse HTTP Binding for SOAP Specification. This specification defines a message exchange protocol that permits an 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 beneficial 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. This is why the reverse HTTP for SOAP binding is also known as PAOS; the spelling of SOAP is reversed.
Comparison of PAOS and SOAP
In a typical SOAP binding, an HTTP client interacts with an identity service through a client request and a server response. For example, a cell phone user (client) can contact the phone service provider (service) 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 an HTTP response. The subsequent response from the client is bound to a request.
PAOS Binding API
The Access Manager implementation of PAOS binding includes a Java package named com.sun.identity.liberty.ws.paos. This package provides classes to parse a PAOS header, make a PAOS request, and receive a PAOS response.
Note –
This API is used by PAOS clients on the HTTP server side. An API 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.
The following table describes the available classes in com.sun.identity.liberty.ws.paos. For more detailed API documentation, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.
Table 10–8 PAOS Binding Classes|
Class |
Description |
|---|---|
|
PAOSHeader |
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 |
Used by a web application on the HTTP server side to construct a PAOS request message and send it via an HTTP response to the user agent side. Note – PAOSRequest is made available in PAOSResponse to provide correlation, if needed, by API users. |
|
PAOSResponse |
Used by a web application on the HTTP server side to receive and parse a PAOS response using an HTTP request from the user agent side. |
|
PAOSException |
Represents an error occurring while processing a SOAP request and response. |
For more information, including methods and their syntax and parameters, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.
PAOS Binding Sample
A sample that demonstrates PAOS service interaction between an 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 file. Both files are included in the paos directory. The following code example is the PAOS client servlet.
Example 10–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();
}
}
|
See Appendix A, Liberty-based and SAML Samples for information about all the sample code and files included with Access Manager.