Contained WithinFind More DocumentationFeatured Support Resources |  Scarica il manuale in formato PDF (1996 KB)
Part IV SAML Administration and Application Programming InterfacesChapter 10 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. It covers the following topics: SAML OverviewSAML is an XML-based standard for communicating authentication, authorization and attribute information amongst online partners. It allows businesses to securely send assertions between partnered organizations regarding the identity and entitlements of a principal. The Organization for the Advancement of Structured Information Standards (OASIS) Security Services Technical Committee is in charge of defining, enhancing, and maintaining the SAML specifications. SAML standardizes queries for, and responses that contain, user authentication, entitlements, and attribute information in an XML format. This format can then be used by a relying party to request security information about a principal from a SAML authority. A SAML authority, sometimes called the asserting party, is a platform or application that can relay security information. The relying party (or assertion consumer or requesting party) is a partner site that receives the security information. The exchanged information 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. Note – All parties in a SAML interaction 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 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 compares the benefits of the two. Table 10–1 Comparison of the SAML and Liberty Alliance Project Specifications
Note – The Organization for the Advancement of Structured Information Standards (OASIS) drives the development of SAML. For information and specifications, see the OASIS Security Services (SAML) Technical Committee home page. 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 10–1 SAML Interaction in Access Manager
SAML allows Access Manager to work in the following ways:
Using the SAML ServiceThe SAML Service 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, attempts to access URLs on trusted partner sites. Developers, who have integrated the SAML API into their applications, are then able 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 SAMLSAML defines message formats in XML for queries and responses. SAML queries are sent to a SAML authority and responses, in the form of SAML assertions, are returned via SOAP over HTTP, the request-response protocol used to carry SAML messages. The following sections describe these and other elements of SAML. Queries and ResponsesAn entity can interact with a SAML authority using requests containing queries and responses containing assertions. AuthenticationQuery, AttributeQuery, and AuthorizationDecisionQuery XML tags containing requests for security information are wrapped within a <samlp:Request> XML tag and sent to a SAML authority. AuthenticationStatement, AttributeStatement, and AuthorizationDecisionStatement XML tags containing assertions of security information are wrapped within a <samlp:Response> XML tag and returned to the assertion consumer. See the following sections for more information. QueriesA requesting party uses AuthenticationQuery, AttributeQuery, and AuthorizationDecisionQuery tags within a <samlp:Request> to ask for assertions about a particular entity from a SAML authority. Following is an example request containing an attribute query.
ResponsesA SAML authority uses AuthenticationStatement, AttributeStatement, and AuthorizationDecisionStatement tags within a <samlp:Response> to return information about an entity to the requesting party. Following is an example response containing an assertion. See Assertions for more information.
AssertionsSAML 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 PartnerSiteAttributeMapper Interface. Note – One assertion can contain many different statements made by the authority. The SAML specification provides for different types of assertions:
ProfilesA 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 the Web Browser Artifact Profile and the Web Browser POST Profile. Both profiles use HTTP. The profile methods can be initiated through a web browser or the SAML API. (For more information about the API method, see SAML API.) Either profile 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:
More information can be found in the following sections: Web Browser Artifact ProfileThe Web Browser Artifact Profile is used when there is a back channel available to process an artifact. (An artifact is carried as part of the URL and points to an assertion which contains the security information regarding the requestor.) The 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 artifact is sent via a browser and processed using SOAP. The SOAP communication should be either Basic Authentication or Client Certificate Authentication over SSL although XML signing is a stronger alternative. The Web Browser Artifact Profile is considered more secure than the Web Browser POST Profile (as discussed in Web Browser POST Profile).
Figure 10–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 is a front-channel profile that sends responses via the browser. It 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. The Web Browser POST Profile is simpler than the Web Browser Artifact Profile (as discussed in Web Browser Artifact Profile). Note – The POST profile function is provided by either of two
means: an HTTP request using
Figure 10–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 10–1 SOAP Request for Authentication Assertion Using Web Browser Artifact Profile
In response to the request, Example 10–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
|
// 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:
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.
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.
NameIdentifierMapper Interface
NameIdentifierMapper is an interface that can be implemented by a site to map a user account to a name identifier in the subject of a SAML assertion. The implementation class is specified when configuring the site's Trusted Partners.
PartnerAccountMapper Interface
Caution – The AccountMapper interface has been deprecated. Use the PartnerAccountMapper interface.
The PartnerAccountMapper interface needs 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 sub-attribute 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. The PartnerAccountMapper takes the whole assertion as a parameter, enabling the partner to define user account mapping based on attributes inside the assertion. 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.1 Developer’s Guide.
PartnerSiteAttributeMapper Interface
Caution – The SiteAttributeMapper interface has been deprecated. Use the PartnerSiteAttributeMapper interface.
The PartnerSiteAttributeMapper interface needs 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 this mapper which would be used to obtain attributes, create the attribute statement, and insert the statement inside the assertion.
How to Set Up a PartnerSiteAttributeMapper
-
Implement a customized class based on the PartnerSiteAttributeMapper interface.
This class will include user attributes in the SAML authentication assertion.
-
Log in to the Access Manager console to configure the class in the Site Attribute Mapper attribute of the Trusted Partner configuration.
See Trusted Partners for more information.
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 10–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.1 Developer’s Guide. For details on how to use the signature functionality, see SAML Samples.
SAML Operations
This section contains procedures illustrating how to use the Access Manager SAML Service. They are:
Setting Up SAML Single Sign-on
The following procedures explain how to configure and access instances of Access Manager for single sign-on using SAML 1.x assertions. Machine A (exampleA.com) is the source site which authenticates the user and creates the SAML authentication assertion. Machine B (exampleB.com) is the destination site which consumes the assertion and generates a SSOToken for the user.
Note –
If both machines are in the same domain, the cookie names must be different. You can change the cookie name by modifying the com.iplanet.am.cookie.name property in AMConfig.properties, located in /etc/opt/SUNWam/config/.
This section contains the following procedures:
To Set Up SAML Single Sign-on
This procedure assumes the following values:
|
Deployment URI |
amserver |
|
Port |
58080 |
|
Protocol |
http |
-
Write down or copy the value of the Site ID attribute from the destination site (machine B).
-
Login to the Access Manager console running at exampleB.com as the default administrator, amadmin.
-
Click the Federation tab.
-
Click the SAML tab.
-
Click the sole entry listed under Site Identifiers.
This takes you to the Edit site identifier page.
-
Write down or copy the value of the Site ID attribute.
-
Click Cancel.
-
Log out of this instance of Access Manager.
-
-
Configure the source site (machine A) to trust the destination site (machine B) AND write down or copy the value of the Site ID attribute from the source site.
-
Login to the Access Manager console running at exampleA.com as the default administrator, amadmin.
-
Click the Federation tab.
-
Click the SAML tab.
-
Click New under Trusted Partners.
This takes you to the Select trusted partner type and profile page.
-
Check Artifact and Post under Destination and click Next.
This takes you to the Add New Trusted Partner page.
-
Set the values of the following attributes to configure machine B as a trusted partner of machine A:
Source ID
Type the Site ID copied from the destination site, machine B, in the previous step.
Target
The value of this attribute contains the host's domain or domain with port. Do not include the accompanying protocol. For example, exampleB.com and exampleB.com:58080 are valid but, http://exampleB.com:58080.
SAML URL
http://exampleB.com:58080/amserver/SAMLAwareServlet
HOST LIST
exampleB.com
POST URL
http://exampleB.com:58080/amserver/SAMLPOSTProfileServlet
-
Click Finish.
-
Click Save.
-
Click the sole entry listed under Site Identifiers.
This takes you to the Edit site identifier page.
-
Write down or copy the value of the Site ID attribute.
-
Click Cancel to go to previous page.
-
Log out of Access Manager.
-
-
Configure the destination site (machine B) to trust the source site (machine A).
-
Login to the Access Manager console running at exampleB.com as the default administrator, amadmin.
-
Click the top-level realm under Access Control.
-
Click the Authentication tab.
-
Click New under Module Instances.
-
Type a value in the Name field.
-
Select the SAML radio button and click OK.
-
Click Save.
-
Click Access Control in the upper left corner.
-
Click the Federation tab.
-
Click the SAML tab.
-
Click New under Trusted Partners.
This takes you to the Select trusted partner type and profile page.
-
Check Artifact and Post under Source and click Next.
This takes you to the Add New Trusted Partner page.
-
Set the values of the following attributes to configure machine A as a trusted partner of machine B:
Source ID
Type the Site ID you copied from the source site, machine A, in the previous step.
SOAP URL
http://exampleA.com:58080/amserver/SAMLSOAPReceiver
Issuer
exampleA.com:58080
Note –If machine B uses https, check SSL under Authentication Type. Be sure to modify the protocol in the other attributes as necessary.
-
Click Finish.
-
Click Save.
-
Log out of Access Manager.
-
To Verify the SAML Single Sign-on Configurations
-
Login to the Access Manager console running at exampleA.com as the default administrator, amadmin.
-
To initialize single sign-on from machine A, do one of the following:
-
Access the following URL to use the SAML Artifact profile:
http://exampleA.com:58080/amserver/SAMLAwareServlet?TARGET=exampleB.com_Target_URL
-
Access the following URL to use the SAML POST profile:
http://exampleA.com:58080/amserver/SAMPOSTProfileServlet?TARGET=exampleB.com_Target_URL
Note –XML signing must be enabled before running the SAML POST profile. See Signing Liberty ID-FF Requests and Responses for details.
exampleB.com_Target_URL is any URL on the exampleB.com site to which the user will be redirected after a successful single sign-on. For testing purpose, this could be the login page as in TARGET=http://exampleB.com:58080/amserver/UI/Login. If the administrator successfully accesses the Access Manager console on the destination site without manual authentication, we know that an SSOtoken has been created for the principal on the destination site and single sign-on has been properly established.
-
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 11 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 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 11–1 Access Manager Public APIs|
Package Name |
Description |
|---|---|
|
com.sun.identity.federation.plugins |
Provides interfaces which can be implemented to allow applications to customize their actions before and after invoking the federation protocols. See Chapter 3, Federation. |
|
com.sun.identity.federation.services |
Provides interfaces for writing custom plug-ins that can be used during the federation or single sign-on process. See Chapter 3, Federation. |
|
com.sun.identity.liberty.ws.authnsvc |
Provides classes to manage the Authentication Web Service. See Chapter 6, 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 6, Authentication Web Service. |
|
com.sun.identity.liberty.ws.authnsvc.protocol |
Provides classes to manage the Authentication Web Service protocol. See Chapter 6, 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 8, Discovery Service. |
|
com.sun.identity.liberty.ws.disco.plugins |
Provides a plug-in interface for the Discovery Service. See Chapter 8, Discovery Service. |
|
com.sun.identity.liberty.ws.dst |
Provides classes to implement an identity service on top of the Access Manager framework. See Chapter 7, 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 7, Data Services for information on data services. |
|
com.sun.identity.liberty.ws.idpp.plugin |
Defines plug-in interfaces for the Liberty Personal Profile Service. |
|
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 7, Data Services and Chapter 8, 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 9, SOAP Binding Service. |
|
com.sun.identity.saml |
Provides an SPI in which proprietary XML signature implementations can be plugged in. See Chapter 10, SAML Administration. |
|
com.sun.identity.saml.assertion |
Provides classes that manage assertions and profiles. See Chapter 10, SAML Administration. |
|
com.sun.identity.saml.common |
Provides classes common to all SAML elements. See Chapter 10, SAML Administration. |
|
com.sun.identity.saml.plugins |
Provides SPIs to integrate SAML into custom services. See Chapter 10, SAML Administration. |
|
com.sun.identity.saml.protocol |
Provides classes that parse the XML messages used to exchange assertions and information. See Chapter 10, SAML Administration. |
|
com.sun.identity.saml.xmlsig |
Provides an SPI in which proprietary XML signature implementations can be plugged in. See Chapter 10, 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 11–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 11–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 8, 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 7, 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.1 Technical Overview for more information about policy management, single sign-on, and user sessions. See the Sun Java System Access Manager 7.1 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 and the SecurityAttributePlugin interface for inserting security attributes, via an AttributeStatement, into the assertion during the Discovery Service token generation. The following table describes the classes used to manage Liberty-based security mechanisms.
Table 11–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 11–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 11–6 Interaction Service Properties in AMConfig.properties|
Property |
Description |
|---|---|
|
com.sun.identity.liberty.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 11–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 11–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 11–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.