Part III Supported Web Services
Chapter 5 Liberty Alliance Project Web Services Framework
Sun Java™ System Access Manager implements the Liberty Identity Web Services Framework (Liberty ID-WSF) which defines a web services stack that can be used to support the Liberty Alliance Project business model. These web services leverage the Liberty ID-FF for principal authentication, federation, and privacy protections. This chapter covers the following topics:
Web Services
Web services are distributed applications developed using open technologies such as eXtensible Markup Language (XML), SOAP, and HyperText Transfer Protocol (HTTP). Enterprises use these technologies as a mechanism for allowing their applications to cross network boundaries and communicate with those of their partners, customers and suppliers. Access Manager implements the Liberty ID-WSF which is designed to operate in concert with a federated identity framework, such as the Liberty Identity Federation Framework (Liberty ID-FF). Previous releases of Access Manager implemented the Liberty ID-WSF version 1.0. This current release of Access Manager 7.1 extends the implementation to include version 1.1. Access Manager includes the following Liberty ID-WSF web services:
Authentication Web Service
The Authentication Web Service adds authentication functionality to the SOAP binding. It provides authentication to a WSC, allowing the WSC to obtain security tokens for further interactions with other services at the same provider. These other services may include a discovery service or single sign-on service. Upon successful authentication, the final Simple Authentication and Security Layer (SASL) response contains the resource offering for the Discovery Service. For more information, see Chapter 6, Authentication Web Service.
Caution – Do not confuse the Liberty-based Authentication Web Service with the proprietary Access Manager Authentication Service discussed in the Sun Java System Access Manager 7.1 Technical Overview.
Liberty Personal Profile Service
The Liberty Personal Profile Service is a data service that supports storing and modifying a principal's identity attributes. It maps attributes defined in a user's personal profile to LDAP attributes in a data store. These identity attributes might include the user's first name, last name, home address, or emergency contact information. The Liberty Personal Profile Service is queried or updated by a WSC acting on behalf of the principal. For more information, see Chapter 7, Data Services.
Discovery Service
The Discovery Service is a framework for describing and discovering identity web services. It allows a requesting entity, such as a service provider, to dynamically determine a principal's registered web services provider (WSP), such as an attribute provider. Typically, a service provider queries the Discovery Service, which responds by providing a resource offering that describes the requested WSP. (A resource offering defines associations between a piece of identity data and the service instance that provides access to the data.) The implementation of the Discovery Service includes Java and web-based interfaces. The service is bootstrapped using Liberty ID-FF single sign-on or the Liberty ID-WSF Authentication Web Service. For more information, see Chapter 8, Discovery Service.
Note –
By definition, a discoverable service is assigned a service type URI, allowing the service to be registered in Discovery Service instances. The service type URI is typically defined in the Web Service Definition Language (WSDL) file that defines the service.
SOAP Binding Service
The SOAP Binding Service is the method of transport used to convey identity data between web services. It includes a set of Java APIs used by the developer of a Liberty-enabled identity service. The APIs are used to send and receive identity-based messages using SOAP, an XML-based messaging protocol. The service invokes the correct request handler class (specified by a service endpoint) to handle the messages. For more information, see Chapter 9, SOAP Binding Service.
Liberty ID-WSF Architecture in Access Manager
The Liberty ID-WSF defines an architecture in which SOAP over HTTP(S) is used as the transport layer protocol. As well, custom web services can be plugged into it. All web services in Access Manager (whether proprietary or custom) are front-ended by a servlet endpoint called the SOAPReceiver. The SOAPReceiver validates digital signatures or encryptions from incoming SOAP request messages and authenticates the remote web services client. The following diagram shows the high level architecture of the Access Manager implementation of the Liberty ID-WSF.
In the high-level process between a WSC and an Access Manager WSP, a user requests a specific service on a WSC which passes the request to Access Manager. The request is received by the SOAPReceiver which, in turn, passes it to the corresponding WSP (for example, the Liberty Personal Profile Service or a custom web service). More detailed information can be found in SOAP Binding Process.
Web Services and Security
Access Manager defines a variety of security mechanisms for protecting web services. It includes security mechanisms from both the Liberty ID-WSF Security Mechanisms Specification and the WS-Security version 1.x specifications. The SOAP Binding Service is where security is configured. It can be configured globally for all the services hosted by Access Manager to limit the accepted security mechanisms or, each web service can define it's own security mechanisms for more fine-grained security. The primary advantage of deploying the web services using Access Manager is that web services security is handled by the Access Manager allowing application developers to concentrate on the business logic of their web service. There are blueprints available that present solutions for developing secure web services by enabling application-level or message-level security. They can be found on the open development web site for the Java BluePrints Project.
Note –
These blueprints require that Access Manager be deployed in an instance of Application Server 9 (which is not a supported container on Sun Java Enterprise System 5).
Developing New Web Services
Any web service that is plugged into the Access Manager Liberty ID-WSF framework must register a key, and an implementation of the com.sun.identity.liberty.ws.soapbinding.RequestHandler interface, with the SOAP Binding Service. (For example, the Liberty Personal Profile Service is registered with the key idpp, and the class com.sun.identity.liberty. ws.soapbinding.PPRequestHandler.) The Key value becomes part of the URL for the web service's endpoint (as in protocol://host:port/deploymenturi/Liberty/key). The implemented class allows the web service to retrieve the request (containing the authenticated principal and the authenticated security mechanism along with the entire SOAP message). The web service processes the request and generates a response. This section contains the process you would use to add a new Liberty ID-WSF web service to the Access Manager framework. Instructions for some of these steps are beyond the scope of this guide. The process has been divided into two tasks:
To Host a Custom Service
Before You Begin
The XML Schema Definition (XSD) file written to define the new service is the starting point for developing the service's server-side code. More information can be found in Schema Files and Service Definition Documents.
-
Write an XML service schema for the new web service and Java classes to parse and process the XML messages.
The following sample schema defines a stock quote web service. The QuoteRequest and QuoteResponse elements define the parameters for the request and response that are inserted in the SOAP Body of the request and response, respectively. You will need to have QuoteRequest.java and QuoteResponse.java to parse and process the XML messages.
<?xml version="1.0" encoding="UTF-8" ?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="urn:com:sun:liberty:sample:stockticker" targetNamespace="urn:com:sun:liberty:sample:stockticker"> <xs:annotation> <xs:documentation> This is a sample stock ticker web service protocol </xs:documentation> </xs:annotation> <xs:element name="QuoteRequest" type="QuoteRequestType"/> <xs:complexType name="QuoteRequestType"> <xs:sequence> <xs:element name = "ResourceID" type="xs:string" minOccurs="0"/> <xs:element name = "Symbol" type="xs:string" minOccours="1"/> </xs:sequence> </xs:complexType> <xs:complexType name="PriceType"> <xs:sequence> <xs:element name="Last" type="xs:integer"/> <xs:element name="Open" type="xs:integer"/> <xs:element name="DayRange" type="xs:string"/> <xs:element name="Change" type="xs:string"/> <xs:element name="PrevClose" type="xs:integer"/> </xs:sequence> </xs:complexType> <xs:element name="QuoteResponse" type="QuoteResponseType"/> <xs:complexType name="QuoteResponseType"> <xs:sequence> <xs:element name="Symbol" type="xs:string"/> <xs:element name="Time" type="xs:dateTime"/> <xs:element name="Delay" type="xs:dateTime" minOccurs="0"/> <xs:element name="Price" type="PriceType"/> <xs:element name="Volume" type="xs:integer"/> </xs:sequence> </xs:complexType> </xs:schema> -
Provide an implementation for one of the following interfaces based on the type of web service being developed:
-
com.sun.identity.liberty.ws.soapbinding.RequestHandler for developing and deploying a general web service.
-
com.sun.identity.liberty.ws.dst.service.DSTRequestHandler for developing and deploying an identity data service type web service based on the Liberty Alliance Project Identity Service Interface Specifications (Liberty ID-SIS).
In Access Manager, each web service must implement one of these interfaces to accept incoming message requests and return outgoing message responses. The following sample implements the com.sun.identity.liberty.ws.soapbinding.RequestHandler interface for the stock quote web service. com.sun.identity.liberty.ws.soapbinding.Message is the API used to construct requests and responses.
public class StockTickerService implements RequestHandler { : //implement business logic public Message processRequest(Message msg) throws SOAPFaultException, Exception { : SSOToken token = (SSOToken)msg.getToken(); List responseBody = processSOAPBody(msg.getBodies()); : Message response = new Message(); response.setBodies(responseBody); return response; } : //more business logic } -
-
Compile the Java source code.
Be sure to include /AccessManager-base/SUNWam/lib/am_services.jar in your classpath.
-
Add the previously created classes to the web container classpath and restart the web container.
-
Login to the Access Manager console as the top level administrator.
By default, amadmin.
-
Click the Web Services tab.
-
Under Web Services, click the SOAP Binding Service tab to register the new implementation with the SOAP Binding Service.
-
Click New under the Request Handler List global attribute.
-
Enter a name for the implementation in the Key field.
This value will be used as part of the service endpoint URL for the web service. For example, if the value is stock, the endpoint URL to access the stock quote web service will be:
http://SERVER_HOST:SERVER_PORT/SERVER_DEPLOY_URI/Liberty/stock
-
Enter the name of the implementation class previously created in the Class field.
-
(Optional) Enter a SOAP Action in the SOAP Action field.
-
Click Save to save the configuration.
The request handler will be displayed under the Request Handler List.
-
Click on the Access Control tab to begin the process of publishing the web service to the Discovery Service.
The Discovery Service is a registry of web services. It matches the properties in a request with the properties in its registry and returns the appropriate service location. See Chapter 8, Discovery Service.
-
Select the name of the realm to which you want to add the web service.
-
Select Services to access the realm's services.
-
Click Discovery Service.
If the Discovery Service has not yet been added, do the following.
-
Click Add to create a new resource offering.
-
(Optional) Enter a description of the resource offering in the Description field.
-
Type a URI for the value of the Service Type attribute.
This URI defines the type of service. It is recommended that the value of this attribute be the targetNamespace URI defined in the abstract WSDL description for the service. An example of a valid URI for the sample service is urn:com:sun:liberty:sample:stockticker.
-
Type a URI for the value of the Provider ID attribute.
The value of this attribute contains the URI of the provider of the service instance. This information is useful for resolving trust metadata needed to invoke the service instance. A single physical provider may have multiple provider IDs.
Note –The provider represented by the URI in the Provider ID attribute must also have an entry in the ResourceIDMapper attribute. For more information, see Classes For ResourceIDMapper Plug-in.
-
Click New Description to define the Service Description.
For each resource offering, at least one service description must be created.
-
Select the values for the Security Mechanism ID attribute to define how a web service client can authenticate to a web service provider.
This field lists the security mechanisms that the service instance supports. Select the security mechanisms that you want to add and click Add. To prioritize the list, select the mechanism and click Move Up or Move Down.
-
Type a value for the End Point URL.
This value is the URL to access the new web service. For this example, it should be:
http://SERVER_HOST:SERVER_PORT/SERVER_DEPLOY_URI/Liberty/stock
-
(Optional) Type a value for the SOAP Action.
This value is the equivalent of the wsdlsoap:soapAction attribute of the wsdlsoap:operation element in the service's concrete WSDL-based description.
-
Click OK to complete the configuration.
-
-
Check the Options box if there are no options or add a URI to specify options for the resource offering.
This field lists the options that are available for the resource offering. Options provide hints to a potential requestor about the availability of certain data or operations to a particular offering. The set of possible URIs are defined by the service type, not the Discovery Service. If no option is specified, the service instance does not display any available options. For a standard set of options, see the Liberty ID-SIS Personal Profile Service Specification.
-
Select a directive for the resource offering.
Directives are special entries defined in SOAP headers that can be used to enforce policy-related decisions. You can choose from the following:
-
GenerateBearerToken specifies that a bearer token be generated.
-
AuthenticateRequester must be used with any service description that use SAML for message authentication.
-
EncryptResourceID specifies that the Discovery Service encrypt the resource ID.
-
AuthenticateSessionContext is specified when a Discovery Service provider includes a SAML assertion containing a SessionContextStatement in any future QueryResponse messages.
-
AuthorizeRequester is specified when a Discovery Service provider wants to include a SAML assertion containing a ResourceAccessStatement in any future QueryResponse messages.
If you want to associate a directive with one or more service descriptions, select the check box for that Description ID. If no service descriptions are selected, the directive is applied to all description elements in the resource offering.
-
-
Click OK.
-
Logout from the console.
To Invoke the Custom Service
Web service clients can access the custom web service by discovering the web service's end point and using the required credentials. This information is stored by the Access Manager Discovery Service. There are two ways in which a client can authenticate to Access Manager in order to access the Discovery Service:
-
The Liberty ID-FF is generally used if it's a browser-based application and the web service client is a federation enabled service provider.
-
The Access Manager Authentication Web Service (based on the Liberty ID-WSF) is used for remote web services clients with pure SOAP-based authentication capabilities.
In the following procedure, we use the Liberty ID-WSF client API to invoke the web service.
Note –
The code in this procedure is used to demonstrate the usage of the Liberty ID-WSF client API. More information can be found in the Sun Java System Access Manager 7.1 Java API Reference.
-
Write code to authenticate the WSC to the Authentication Web Service of Access Manager.
The sample code below will allow access to the Discovery Service. It is a client-side program to be run inside the WSC application.
public class StockClient { : public SASLResponse authenticate( String userName, String password, String authurl) throws Exception { SASLRequest saslReq = new SASLRequest(AuthnSvcConstants.MECHANISM_PLAIN); saslReq.setAuthzID(userName); SASLResponse saslResp = AuthnSvcClient.sendRequest(saslReq, authurl); String statusCode = saslResp.getStatusCode(); if (!statusCode.equals(SASLResponse.CONTINUE)) { return null; } String serverMechanism = saslResp.getServerMechanism(); saslReq = new SASLRequest(serverMechanism); String dataStr = userName + "\0" + userName + "\0" + password; saslReq.setData(dataStr.getBytes("UTF-8")); saslReq.setRefToMessageID(saslResp.getMessageID()); saslResp = AuthnSvcClient.sendRequest(saslReq, authurl); statusCode = saslResp.getStatusCode(); if (!statusCode.equals(SASLResponse.OK)) { return null; } return saslResp; } : } -
Add code that will extract the Discovery Service information from the Authentication Response.
The following additional code would be added to what was developed in the previous step.
ResourceOffering discoro = saslResp.getResourceOffering(); List credentials = authnResponse.getCredentials(); -
Add code to query the Discovery Service for the web service's resource offering by using the Discovery Service resource offering and the credentials that are required to access it.
The following additional code would be added to what was previously developed.
RequestedService rs = new RequestedService(null, "urn:com:sun:liberty:sample:stockticker"); List rss = new ArrayList(); rss.add(rs); Query discoQuery = new Query(discoro.getResourceID(), rss); DiscoveryClient discoClient = null; discoClient = new DiscoveryClient(secAssertion, serviceURL, null); QueryResponse queryResponse = discoClient.getResourceOffering(discoQuery); -
The discovery response contains the service's resource offering and the credentials required to access the service.
quotes contains the response body (the stock quote). You would use the Access Manager SOAP API to get the body elements.
List offerings = discoResponse.getResourceOffering(); ResourceOffering stockro = (ResourceOffering)offerings.get(0); List credentials = discoResponse.getCredentials(); SecurityAssertion secAssertion = null; if(credentials != null && !credentials.isEmpty()) { secAssertion = (SecurityAssertion)credentials.get(0); } String serviceURL = ((Description)stockro.getServiceInstance(). getDescription().get(0)).getEndpoint(); QuoteRequest req = new QuoteRequest(symbol, stockro.getResourceID().getResourceID()); Element elem = XMLUtils.toDOMDocument( req.toString(), debug).getDocumentElement(); List list = new ArrayList(); list.add(elem); Message msg = new Message(null, secAssertion); msg.setSOAPBodies(list); Message response = Client.sendRequest(msg, serviceURL, null, null); List quotes = response.getBodies();
Setting Up Liberty ID-WSF 1.1 Profiles
Access Manager automatically detects which version of the Liberty ID-WSF profiles is being used. If Access Manager is the web services provider (WSP), it detects the version from the incoming SOAP message. If Access Manager is the WSC, it uses the version the WSP has registered with the Discovery Service. If the WSP can not detect the version from the incoming SOAP message or the WSC can not communicate with the Discovery Service, the version defined in the com.sun.identity.liberty.wsf.version property in AMConfig.properties will be used. Following are the steps to configure Access Manager to use Liberty ID-WSF 1.1 profiles.
To Configure Access Manager to Use Liberty ID-WSF 1.1 Profiles
-
Install Access Manager on two different machines.
Test the installation by logging in to the console at http://server:port/amserver/UI/Login.
-
Setup the two instances of Access Manager for communication using the Liberty ID-FF protocols.
This entails setting up one instance as the service provider (SP) and the other as the identity provider (IDP). Instructions for doing this can be found in Entities and Authentication Domains or in the README file located in the /AccessManager-base/samples/liberty/sample1 directory.
Note –This step also entails creating a keystore for each provider. Instructions for this procedure are located in /AccessManager-base/samples/saml/xmlsig/keytool.html or in Appendix B, Key Management in this guide. For testing purposes, you can copy the same keystore to each machine; if not, import the public keys from one machine to the other. Be sure to update the Key Alias attribute for each provider in AMConfig.properties and change the cookie name on one of the machines (in the same file) if both machines are in the same domain.
-
Using the Access Manager console on the SP side, change the value of the Protocol Support Enumeration attribute to urn:liberty:iff:2003-08 in both provider configurations.
The value of this attribute defines the supported release of the Liberty ID-FF; in this case, version 1.2.
-
Setup the two instances of Access Manager for communication with the Liberty ID-WSF web services.
This entails copying the files located in the /AccessManager-base/samples/phase2/wsc directory to your web container's doc root directory and making the changes specified in the sample README file. The relevant files and corresponding function are:
-
index.jsp: Retrieves boot strapping resource offering for Discovery Service.
-
discovery-modify.jsp: Adds resource offering for a user.
-
discovery-query.jsp: Sends query to Discovery Service for a resource offering.
-
id-sis-pp-modify.jsp: Sends Data Service Modify request to modify user attributes.
-
id-sis-pp-query.jsp: Sends Data Service Query request to retrieve user attributes.
-
-
Copy the discovery-modify.jsp reproduced below into the web container's doc root directory.
This JSP is configured to use the Liberty ID-WSF 1.1 Bearer token profile (<SecurityMechID>urn:liberty:security:2005-02:null:Bearer</SecurityMechID>) with appropriate directives and should replace the file already in the directory. You can modify this file to use other profiles if you know the defined URI of the particular Liberty ID-WSF 1.1 profile. (X509 or SAML token, for example.)
<%-- Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved Use is subject to license terms. --%> <%@page import="java.io.*,java.util.*,com.sun.identity.saml.common.*, com.sun.identity.liberty.ws.disco.*,com.sun.identity.liberty.ws.disco.common.*, javax.xml.transform.stream.*, com.sun.identity.liberty.ws.idpp.plugin.IDPPResourceIDMapper, com.iplanet.sso.*,com.sun.liberty.LibertyManager" %> <html xmlns="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <head><title>Discovery Service Modification</title></head> <body bgcolor="white"> <h1>Discovery Service Modification</h1> <% if (request.getMethod().equals("GET")) { String resourceOfferingFile = request.getParameter("discoveryResourceOffering"); if (resourceOfferingFile == null) { resourceOfferingFile= ""; } String entryID = request.getParameter("entryID"); if (entryID == null) { entryID= ""; } // The following three values need to be changed to register a personal // profile resource offering for a user. String ppProviderID = "http://shivalik.red.iplanet.com:58080/amserver/Liberty/idpp"; String userDN = "uid=amAdmin,ou=People,dc=iplanet,dc=com"; String ppEndPoint = "http://shivalik.red.iplanet.com:58080/amserver/Liberty/idpp"; String providerID = request.getParameter("providerID"); String ppResourceID = (new IDPPResourceIDMapper()).getResourceID( ppProviderID, userDN); String newPPRO = "<ResourceOffering xmlns=\"urn:liberty:disco:2003-08\">" + " <ResourceID>" + ppResourceID + "</ResourceID>\n" + " <ServiceInstance>\n" + " <ServiceType>urn:liberty:id-sis-pp:2003-08</ServiceType>\n" + " <ProviderID>" + ppProviderID + "</ProviderID>\n" + " <Description>" + " <SecurityMechID>urn:liberty:security:2005-02:null:Bearer" + "</SecurityMechID>\n" + " <Endpoint>" + ppEndPoint + "</Endpoint>\n" + " </Description>\n" + " </ServiceInstance>\n" + " <Abstract>This is xyz </Abstract>\n" + "</ResourceOffering>"; %> <form method="POST"> <table> <tr> <td>ResourceOffering (for discovery service itself)</td> <td> <textarea rows="2" cols="30" name="discoResourceOffering"> <%= resourceOfferingFile %> </textarea> </td> </tr> <tr> <td>PP ResourceOffering to add</td> <td> <textarea rows="20" cols="60" name="insertStr"><%= newPPRO %></textarea> </td> </tr> <tr> <td>AND/OR PP ResourceOffering to remove</td> <td> <textarea rows="2" cols="30" name="entryID"></textarea> </td> </tr> </table> <input type="hidden" name="providerID" value="<%= providerID %>" /> <input type="submit" value="Send Discovery Update Request" /> </form> <% } else { try { String resourceXMLFile = request.getParameter("discoResourceOffering"); String resourceXML = null; try { BufferedReader bir = new BufferedReader( new FileReader(resourceXMLFile)); StringBuffer buffer = new StringBuffer(2000); int b1; while ((b1=bir.read ())!= -1) { buffer.append((char) b1); } resourceXML = buffer.toString(); } catch (Exception e) { %>Warning: cannot read disco resource offering.<% } String insertString = request.getParameter("insertStr"); String entryID = request.getParameter("entryID"); String providerID = request.getParameter("providerID"); if (resourceXML == null || resourceXML.equals("")) { %>ERROR: resource offering missing<% } else { ResourceOffering offering; try { offering = new ResourceOffering(DiscoUtils.parseXML( resourceXML)); DiscoveryClient client = new DiscoveryClient( offering, SSOTokenManager.getInstance().createSSOToken(request), providerID); Modify mod = new Modify(); mod.setResourceID(offering.getResourceID()); mod.setEncryptedResourceID(offering.getEncryptedResourceID()); if ((insertString != null) && !(insertString.equals(""))) { InsertEntry insert = new InsertEntry( new ResourceOffering( DiscoUtils.parseXML(insertString)), null); // Uncommnent the following when it's required. List directives = new ArrayList(); Directive dir1 = new Directive( Directive.AUTHENTICATE_REQUESTER); directives.add(dir1); // Directive dir2 = new Directive( // Directive.AUTHORIZE_REQUESTER); // directives.add(dir2); Directive dir3 = new Directive( Directive.GENERATE_BEARER_TOKEN); directives.add(dir3); insert.setAny(directives); List inserts = new ArrayList(); inserts.add(insert); mod.setInsertEntry(inserts); } if ((entryID != null) && !(entryID.equals(""))) { RemoveEntry remove = new RemoveEntry( com.iplanet.am.util.XMLUtils.escapeSpecialCharacters( entryID)); List removes = new ArrayList(); removes.add(remove); mod.setRemoveEntry(removes); } if ((mod.getInsertEntry() == null) && (mod.getRemoveEntry() == null)) { %>ERROR: empty Modify<% } else { %> <h2>Formed Modify :</h2> <pre><%= SAMLUtils.displayXML(mod.toString()) %></pre> <% ModifyResponse resp2 = client.modify(mod); %> <h2>Got result:</h2> <pre><%= SAMLUtils.displayXML(resp2.toString()) %></pre> <% } } catch (Throwable t) { t.printStackTrace(); StringWriter buf = new StringWriter(); t.printStackTrace(new PrintWriter(buf)); %> ERROR: caught exception: <pre> <% out.println(buf.toString()); %> </pre> <% } } %> <p><a href="index.jsp">Return to index.jsp</a></p> <% } catch (Throwable e) { e.printStackTrace(); StringWriter buf = new StringWriter(); e.printStackTrace(new PrintWriter(buf)); %> ERROR: oocaught exception: <pre> <% out.println(buf.toString()); %> </pre> <% } } %> <hr/> </body> </html> -
Modify the values of the following properties in AMConfig.properties on the IDP side to reflect the key alias.
AMConfig.properties is located in /etc/opt/SUNWam/config. The following properties should be changed.
-
com.sun.identity.liberty.ws.wsc.certalias=wsc_certificate_alias
-
com.sun.identity.liberty.ws.ta.certalias=signing_trusted_authority_certificate_alias
-
com.sun.identity.liberty.ws.trustedca.certaliases=list_of_trusted_authority_certification_alias
-
-
Register the Liberty Personal Profile Service to the user defined by the userDN in discovery-modify.jsp.
Under the default top-level realm on the instance of Access Manager acting as an IDP, go to Subjects and click User. Select the user and click Services. Click Add and register the Liberty Personal Profile Service.
Note –In the discovery-modify.jsp reproduced above, the user is defined as the default administrator, amAdmin. See the line:
String userDN = "uid=amAdmin,ou=People,dc=iplanet,dc=com";
-
Restart both instances of Access Manager.
-
Test that the Liberty ID-WSF 1.1 profiles are working by following the Run the Sample section of the README located in /AccessManager-base/samples/phase2/wsc.
Chapter 6 Authentication Web Service
Sun Java™ System Access Manager contains the Authentication Web Service. It enables web service consumers and Liberty-enabled user agents to authenticate with identity providers using SOAP messages. This chapter covers the following topics:
Authentication Web Service Overview
The SOAP specifications define an XML-based messaging paradigm, but do not specify any particular security mechanisms. Particularly, they do not describe user authentication using SOAP messages. To rectify this, the Authentication Web Service was implemented based on the Liberty ID-WSF Authentication Service and Single Sign-On Service Specification. The specification defines a protocol that adds the Simple Authentication and Security Layer (SASL) authentication functionality to the SOAP binding described in the Liberty ID-WSF SOAP Binding Specification and, Chapter 9, SOAP Binding Service in this guide. The Authentication Web Service is for provider-to-provider authentication.
Note –
The specification also contains an XML schema that defines the authentication protocol. More information can be found in Schema Files and Service Definition Documents.
This overview contains the following sections:
XML Service File
The Authentication Web Service is configured using the XML service file amAuthnSvc.xml. This file defines the attribute for the Authentication Web Service which can be managed through the Access Manager console or the XML file.
Note –
For information about service files, see the Sun Java System Access Manager 7.1 Administration Guide.
Authentication Web Service APIs
The Access Manager Authentication Web Service includes the following Java programming packages:
-
com.sun.identity.liberty.ws.authnsvc
-
com.sun.identity.liberty.ws.authnsvc.mechanism
-
com.sun.identity.liberty.ws.authnsvc.protocol
The first package is a client API for external Java applications to send SASL requests and receive SASL responses. The second package defines an interface to handle different SASL mechanisms. The final package contains classes that represent the SASL request and response. Together, the packages are used to initiate the authentication process and communicate authentication credentials to the Authentication Web Service. For more information, see the Authentication Web Service API.
Which Authentication Service to Use?
The Liberty-based Authentication Web Service is not to be confused with the proprietary Authentication Service discussed in the Sun Java System Access Manager 7.1 Administration Guide. Architecturally, the Authentication Web Service sits on top of the Access Manager Authentication Service and the Liberty Alliance Project framework. You might use the Authentication Web Service if you are a service provider and want to use a standards-based mechanism to authenticate users.
Following are two use cases where the Authentication Web Service is preferable to the Access Manager Authentication Service:
-
A service provider relies on a remote identity provider (not necessarily using Access Manager) for authentication.
-
An enterprise in a service-oriented architecture (SOA) environment wants to use non-proprietary mechanisms to authenticate users and web services clients before accessing a protected web service.
In addition to providing an authentication service to verify credentials (for example, user ID and password), the Authentication Web Service provides the web services consumer (WSC) with bootstrap information that contains the endpoint and credentials needed to access the Discovery Service (as discussed in Chapter 8, Discovery Service). The WSC can ignore the bootstrap or use it to access other web services, such as the authenticated user's personal profile or calendar.
Note –
An authenticated enterprise might also use the bootstrap information to access a partner in a business-to-business environment.
Following is an example that shows how the Authentication Web Service interacts with the Access Manager Authentication Service. It assumes the following separate entities:
-
A user (principal)
-
A service provider (acting as a WSC)
-
An identity provider hosted by Access Manager where the Access Manager Authentication Service is configured for Certificate and LDAP authentication and the Authentication Web Service has mapped LDAP to its own PLAIN authentication mechanism
-
The user's personal profile (hosted by another product)
The WSC delegates all authentication to the identity provider and prefers PLAIN authentication which accepts a user identifier and password.
-
The user attempts access to a service provider (not necessarily hosted by Access Manager).
-
When the service provider finds that the user is not authenticated, it invokes the identity provider's Authentication Web Service by sending it a SOAP request.
-
After inspecting its configuration, the Authentication Web Service sends back a response indicating that it supports Certificate and PLAIN authentication.
-
The service provider decides on PLAIN authentication and prompts the user for an identifier and password.
-
Interactions based on the standard PLAIN authentication mapping ensues between the service provider and identity provider (hosted on Access Manager) using the Authentication Web Service.
-
The service provider receives the user identifier and password and sends it to the identity provider.
-
The identity provider passes the credentials to the locally hosted LDAP Authentication module using the proprietary Access Manager Authentication Service's Java API.
-
The LDAP Authentication module verifies the credentials.
-
The Authentication Web Service is notified of the verification and sends a response to the service provider indicating successful authentication. If configured to do so, it also includes bootstrap information formatted using XML and containing the Discovery Service endpoint and a token to invoke it.
-
-
The service provider parses the response, verifies that it is a successful authentication, and provides the service to the user.
At some point the service provider might need to access the user's personal profile. To do this, it will use the bootstrap information received during this process to contact the Discovery Service and find where the profile is stored. The Discovery Service returns a resource offering (containing a token and the location of an endpoint), and the service provider uses that to invoke the Liberty Personal Profile Service.
Authentication Web Service Process
The exchange of authentication information between a web service consumer (WSC) and the web service provider (WSP) is accomplished using SOAP-bound messages. The messages are a series of client requests and server responses specific to the defined SASL mechanism (or mode of authentication). The authentication exchange can involve an arbitrary number of round trips, dictated by the particular SASL mechanism employed. The WSC might have knowledge of the supported SASL mechanisms, or it might send the server its own list of mechanisms and allow the server to choose one. The list of supported mechanisms can be found at http://www.iana.org/assignments/sasl-mechanisms.
After receiving a request for authentication (or any response from the WSC), the WSP may issue additional challenges or indicate authentication failure or success. The sequence between the WSC and the Authentication Web Service (a WSP) is as follows.
-
The authentication exchange begins when a WSC sends an SASL authentication request to the Authentication Web Service on behalf of a principal.
The request message contains an identifier for the principal and indicates one or more SASL mechanisms from which the service can choose.
-
The Authentication Web Service responds by asserting the method to use and, if applicable, initiating a challenge.
If the Authentication Web Service does not support any of the cited methods, it responds by aborting the exchange.
-
The WSC responds with the necessary credentials for the chosen method of authentication.
-
The Authentication Web Service replies by approving or denying the authentication.
If approved, the response includes the credentials the WSC needs to invoke other web services, such as the Discovery Service.
Authentication Web Service Attribute
The Authentication Web Service attribute is a global attribute. The value of this attribute is carried across the Access Manager configuration and inherited by every organization.
Note –
For information about the types of attributes used in Access Manager, see the Sun Java System Access Manager 7.1 Technical Overview.
The attribute for the Authentication Web Service is defined in the amAuthnSvc.xml service file and is called the Mechanism Handlers List.
Mechanism Handlers List
The Mechanism Handler List attribute stores information about the SASL mechanisms that are supported by the Authentication Web Service.
key Parameter
The required key defines the SASL mechanism supported by the Authentication Web Service.
class Parameter
The required class specifies the name of the implemented class for the SASL mechanism. Two authentication mechanisms are supported by the following default implementations:
Table 6–1 Default Implementations for Authentication Mechanism|
Class |
Description |
|---|---|
|
com.sun.identity.liberty.ws.authnsvc.mechanism.PlainMechanismHandler |
This class is the default implementation for the PLAIN authentication mechanism. It maps user identifiers and passwords in the PLAIN mechanism to the user identifiers and passwords in the LDAP authentication module under the root organization. |
|
com.sun.identity.liberty.ws.authnsvc.mechanism.CramMD5MechanismHandler |
This class is the default implementation for the CRAM-MD5 authentication mechanism. |
Note –
The Authentication Web Service layer provides an interface that must be implemented for each SASL mechanism to process the requested message and return a response. For more information, see com.sun.identity.liberty.ws.authnsvc.mechanism Package.
Authentication Web Service API
The Authentication Web Service provides programmatic interfaces to allow clients to interact with it. The following sections provide short descriptions of these packages. For more detailed information, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com. The authentication-related packages include:
com.sun.identity.liberty.ws.authnsvc Package
This package provides web service clients with a method to request authentication credentials from the Authentication Web Service and receive responses back from it using the Simple Authentication and Security Layer (SASL).
com.sun.identity.liberty.ws.authnsvc.mechanism Package
This package provides an interface that must be implemented for each different SASL mechanism to enable authentication using them. Each SASL mechanism will correspond to one implementation that will process incoming SASL requests and generate outgoing SASL responses.
com.sun.identity.liberty.ws.authnsvc.protocol Package
This package provides classes that correspond to the request and response elements defined in the Liberty XSD schema that accompanies the Liberty ID-WSF Authentication Service Specification. More information about the XSD schemas can be found in Schema Files and Service Definition Documents.
Access the Authentication Web Service
The URL to gain access to the Authentication Web Service is:
http://SERVER_HOST:SERVER_PORT/SERVER_DEPLOY_URI/Liberty/authnsvc |
This URL is normally used by the Access Manager client API to access the service. For example, the Access Manager public client, com.sun.identity.liberty.ws.authnsvc.AuthnSvcClient uses this URL to authenticate principals with Access Manager.
Authentication Web Service Sample
A sample authentication client is included with Access Manager. It is located in the /AccessManager-base/SUNWam/samples/phase2/authnsvc directory. The client uses the PLAIN SASL authentication mechanism. It first authenticates against the Authentication Web Service, then extracts a resource offering to bootstrap the Discovery Service. It looks for a SAML Bearer token credential, issues a discovery query request with SAML assertion included, and receives a response.
Note –
This sample can be used by a Liberty User Agent Device WSC.
Chapter 7 Data Services
Sun Java™ System Access Manager contains implementations of the Liberty ID-WSF Data Services Template Specification in addition to instructions on how you can add a custom data service to your deployment. This chapter covers the following topics:
Data Services Overview
A data service is a web service that supports the query and modification of data regarding a principal. An example of a data service is a web service that hosts and exposes a principal's profile information, such as name, address and phone number. A query is when a web service consumer (WSC) requests and receives the data (in XML format). A modify is when a WSC sends new information to update the data. The Liberty Alliance Project has defined the Liberty ID-WSF Data Services Template Specification (Liberty ID-WSF-DST) as the standard protocol for the query and modification of data profiles exposed by a data service. Using this specification, the Liberty Alliance Project has developed additional specifications for other types of data services: personal profile service, geolocation service, contact service, and calendar service). Of these data services, Access Manager has implemented the Liberty Personal Profile Service and, using the included sample, the Liberty Employee Profile Service.
Note –
To develop your own data service see the instructions in Developing A New Data Service.
Liberty ID-WSF Data Services Template Specification
The Liberty ID-WSF-DST specifies a base layer that can be extended by any instance of a data service. An example of a data service is an identity service, such as an online corporate directory. When you want to contact a colleague, you conduct a search based on the individual’s name, and the data service returns information associated with that person's identity. The information might include the individual’s office location and phone number, as well as job title or department name. For proper implementation, all data services must be built on top of the Liberty ID-WSF-DST because it provides the data model and message interfaces. The following figure illustrates how Access Manager uses the Liberty ID-WSF-DST as the framework for data services.
Figure 7–1 Data Service Template as Building Block of Data Services
The Web Services framework in Access Manager uses the Liberty ID-WSF-DST to develop data services. The Access Manager Liberty Personal Profile Service and Liberty Employee Profile Service were developed on top of the Web Services framework, using the specification. Additional data services can also be developed by the customer.
Note –
For more information on the data services specification, see the Liberty ID-WSF Data Services Template Specification.
Liberty Personal Profile Service
The Liberty ID-SIS Personal Profile Service Specification (Liberty ID-SIS-PP) describes a data service that provides an identity’s basic profile information, such as full name, contact details, and financial information. This data service is intended to be the least common denominator for holding consumer-based information about a principal. Access Manager has implemented this specification and developed the Liberty Personal Profile Service.
For more information, see the Liberty ID-SIS Personal Profile Service Specification.
XML Service File
The Access Manager Liberty Personal Profile Service is configured using the XML service file amLibertyPersonalProfile.xml. This file defines attributes for the Liberty Personal Profile Service which can be managed through the Access Manager Console or the XML file itself.
Note –
For information about service files, see the Sun Java System Access Manager 7.1 Administration Guide.
XSD Schema Definition
The Liberty ID-SIS-PP also defines an XML schema for use in building a personal profile service. More information about the XSD schemas can be found in Schema Files and Service Definition Documents.
Liberty Employee Profile Service
The Liberty ID-SIS Employee Profile Service Specification (Liberty ID-SIS-EP) describes a data service that provides an identity’s profile information as it relates to employment. An example of a employee profile service might be a corporate calendar or phone book.
Access Manager has implemented this specification by developing a sample that includes the files needed to deploy and invoke a Liberty Employee Profile Service. The Liberty Employee Profile Service is not available when Access Manager is installed. It must first be deployed. For information about accessing the sample files and how to deploy them, see Liberty Employee Profile Service.
Note –
For more information, see the Liberty ID-SIS Employee Profile Service Specification.
XML Service File
Among the files included with the sample is the XML service file amLibertyEmployeeProfile.xml. This file defines the attributes for the Liberty Employee Profile Service which, once deployed, can be managed through the Access Manager Console or the XML file itself.
Note –
For information about service files, see the Sun Java System Access Manager 7.1 Administration Guide.
XSD Schema Definition
The Liberty ID-SIS-EP also defines an XML schema for use in building an employee profile service. More information about the XSD schemas can be found in Schema Files and Service Definition Documents.
Data Services API
Access Manager data services are built using a Java package called com.sun.identity.liberty.ws.dst. Access Manager provides this package for developing custom services based on the Liberty ID-WSF-DST. Additional information about these interfaces can be found in Data Services Template API and in the Java API Reference at /AccessManager-base/SUNWam/docs or on docs.sun.com.
Liberty Personal Profile Service
The Liberty Personal Profile Service is a default Access Manager identity service. It can be queried for identity data and its attributes can be updated.
For access to occur, the hosting provider of the Liberty Personal Profile Service needs to be registered with the Discovery Service on behalf of each identity principal. To register a service with the Discovery Service, update a resource offering for that service. For more information, see Chapter 8, Discovery Service. This section contains the following information:
Liberty Personal Profile Service Process
The invocation of a personal profile begins when a WSC posts a query or a modify request to the Liberty Personal Profile Service on behalf of a user. The following process is also illustrated in Figure 6–2.
-
A web services client uses the Data Services Template API to post a query or a modify request to the Liberty Personal Profile Service.
All the query or modify requests to any identity service are SOAP requests.
-
The client’s SOAP request is received by the SOAP receiver provided by the SOAP Binding Service.
The SOAP receiver invokes either the Discovery Service, the Authentication Web Service, or the Liberty Personal Profile Service, depending on the service key transmitted as part of the URL. The SOAP Binding Service might also authenticate the client identity.
-
The Liberty Personal Profile Service implements the DSTRequestHandler to process the request.
The request is processed based on the request type (query or modify) and the query expression. Processing might entail the authorization of a WSC using the Access Manager Policy Service, or it might entail using the Interaction Service for interacting with the user before sending data to the WSC.
-
The Liberty Personal Profile Service builds a service response, adds credentials (if they are required), and sends the response back to the WSC.
-
For a response to a query request, the Liberty Personal Profile Service builds a personal profile container (as defined by the specification). It is formatted in XML and based on the Query Select expression. The Personal Profile attribute values are extracted from the data store by making use of the attribute mapper. The attribute mapper is defined by the XML service file, and the attribute values will be used while building the XML container. The Personal Profile Service then applies xpath queries on the XML and provides us with the resultant XML data node.
-
For a response to a modify request, the Liberty Personal Profile Service parses the Modifiable Select expression and updates the new data from the new data node in the request.
-
The following diagram illustrates the Liberty Personal Profile Service process.
Figure 7–2 Liberty Personal Profile Service Process
Liberty Personal Profile Service Attributes
The Liberty Personal Profile Service attributes are global attributes. The values of these attributes are carried across the Access Manager configuration and inherited by each configured organization.
Note –
For information about the types of attributes used in Access Manager, see the Sun Java System Access Manager 7.1 Technical Overview.
Attributes for the Personal Profile Service are defined in the amLibertyPersonalProfile.xml service file. The attributes are:
ResourceID Mapper
The value of this attribute specifies the implementation of com.sun.identity.liberty.ws.interfaces.ResourceIDMapper. Although a new implementation can be developed, Access Manager provides the default com.sun.identity.liberty.ws.idpp.plugin.IDPPResourceIDMapper, which maps a discovery resource identifier to a user identifier.
Authorizer
Before processing a request, the Liberty Personal Profile Service verifies the authorization of the WSC making the request. There are two levels of authorization verification:
-
Is the requesting entity authorized to access the requested resource profile information?
-
Is the requested resource published to the requestor?
Authorization occurs through a plug-in to the Liberty Personal Profile Service, an implementation of the com.sun.identity.liberty.ws.interfaces.Authorizer interface. Although a new implementation can be developed, Access Manager provides the default class, com.sun.identity.liberty.ws.idpp.plugin.IDPPAuthorizer. This plug-in defines four policy action values for the query and modify operations:
-
Allow
-
Deny
-
Interact For Consent
-
Interact For Value
The resource values for the rules are similar to x-path expressions defined by the Liberty Personal Profile Service. For example, a rule can be defined like this:
/PP/CommonName/AnalyzedName/FN Query Interact for consent /PP/CommonName/* Modify Interact for value /PP/InformalName Query Deny |
Authorization can be turned off by deselecting one or both of the following attributes, which are also defined in the Liberty Personal Profile Service:
Attribute Mapper
The value of this attribute defines the class for mapping a Liberty Personal Profile Service attribute to an Access Manager user attribute. By default, the class is com.sun.identity.liberty.ws.idpp.plugin.IDPPAttributeMapper.
Note –
com.sun.identity.liberty.ws.idpp.plugin.IDPPAttributeMapper is not a public class.
Provider ID
The value of this attribute defines the unique identifier for this instance of the Liberty Personal Profile Service. Use the format protocol://hostname:port/deloy-uri/Liberty/idpp.
Name Scheme
The value of this attribute defines the naming scheme for the Liberty Personal Profile Service common name. Choose First Last or First Middle Last.
Namespace Prefix
The value of this attribute specifies the namespace prefix that is used for Liberty Personal Profile Service XML protocol messages. A namespace differentiates elements with the same name that come from different XML schemas. The Namespace Prefix is prepended to the element.
Supported Containers
The values of this attribute define a list of supported containers in the Liberty Personal Profile Service. A container, as used in this instance, is an attribute of the Liberty Personal Profile Service.
Note –
The term container as described in this section is not related to the Access Manager identity-related object that is also called container.
For example, Emergency Contact and Common Name are two default containers for the Liberty Personal Profile Service. To add a new container, click Add, enter values in the provided fields and click OK.
Note –
This functionality is not yet public.
PPLDAP Attribute Map List
Each identity attribute defined in the Liberty Personal Profile Service maps one-to-one with an Access Manager LDAP attribute. For example, JobTitle=sunIdentityServerPPEmploymentIdentityJobTitle maps the Liberty JobTitle attribute to the Access Manager sunIdentityServerPPEmploymentIdentityJobTitle attribute.
The value of this attribute is a list that specifies the mappings. The list is used by the attribute mapper defined in Attribute Mapper, by default, com.sun.identity.liberty.ws.idpp.plugin.IDPPAttributeMapper.
Note –
When adding new attributes to the Liberty Personal Profile Service or the LDAP data store, ensure that the new attribute mappings are configured as values of this attribute.
In the following code sample, the Liberty Personal Profile Service informalName attribute mapping to the LDAP attribute uid is added to the mappings already present in the Liberty Personal Profile Service XML service file, amLibertyPersonalProfile.xml.
Note –
Attribute mappings are defined as global attributes under the name sunIdentityServerPPDSAttributeMapList in amLibertyPersonalProfile.xml. This attribute corresponds to that sunIdentityServerPPDSAttributeMapList global attribute.
<AttributeSchema name="sunIdentityServerPPDSAttributeMapList"
type="list"
syntax="string"
i18nKey="p108">
<DefaultValues>
<Value>CN=sunIdentityServerPPCommonNameCN</Value>
<Value>FN=sunIdentityServerPPCommonNameFN</Value>
<Value>MN=sunIdentityServerPPCommonNameMN</Value>
<Value>SN=sunIdentityServerPPCommonNameSN</Value>
<Value>InformalName=uid</Value>
</DefaultValues>
</AttributeSchema>
|
Require Query PolicyEval
If selected, this option requires that a policy evaluation be performed for Liberty Personal Profile Service queries. For more information, see Authorizer.
Require Modify PolicyEval
If selected, this option requires that a policy evaluation be performed for Liberty Personal Profile Service modifications. For more information, see Authorizer.
Extension Container Attributes
The Liberty Personal Profile Service allows you to specify extension attributes that are not defined in the Liberty Alliance Project specifications. The values of this attribute specify a list of extension container attributes. All extensions should be defined as:
/PP/Extension/PPISExtension [@name=’extensionattribute’]
The following sample illustrates an extension query expression for creditcard, an extension attribute.
Example 7–1 Extension Query for creditcard
/pp:PP/pp:Extension/ispp:PPISExtension[@name=’creditcard’]
Note: The prefix for the PPISExtension is different,
and the schema for the PP extension is as follows:
<?xml version="1.0" encoding="UTF-8" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.sun.com/identity/liberty/pp"
targetNamespace="http://www.sun.com/identity/liberty/pp">
<xs:annotation>
<xs:documentation>
</xs:documentation>
</xs:annotation>
<xs:element name="PPISExtension">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="name" type="xs:string"
use="required"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:schema>
|
Type the new attribute and click Add.
Extension Attributes Namespace Prefix
The value of this attribute specifies the namespace prefix for the extensions defined in the Extension Container Attributes. This prefix is prepended to the element and helps to distinguish metadata from different XML schema namespaces.
Service Update
The SOAP Binding Service allows a service to indicate that requesters should contact it on a different endpoint or use a different security mechanism and credentials to access the requested resource. If selected, this attribute affirms that there is an update to the service instance.
Service Instance Update Class
The value of this attribute specifies the default implementation class com.sun.identity.liberty.ws.idpp.plugin.IDPPServiceInstanceUpdate. This class is used to update the information for the service instance.
Alternate Endpoint
The value of this attribute specifies an alternate SOAP endpoint to which a SOAP request can be sent.
Alternate Security Mechanisms
This attribute allows you to choose a security mechanism. For more information about this functionality and the mechanisms, see the Liberty ID-WSF Security Mechanisms specification.
Access the Liberty Personal Profile Service
The URL to gain access to the Liberty Personal Profile Service is:
http://SERVER_HOST:SERVER_PORT/SERVER_DEPLOY_URI/Liberty/idpp |
This URL is normally used by the Access Manager client API to access the service. For example, the Access Manager public Data Service Template client, com.sun.identity.liberty.ws.dst.DSTClient uses this URL to query and modify an identity's personal profile attributes stored in Access Manager.
Liberty Employee Profile Service
The Liberty Employee Profile Service sample provides a collection of files that can be used to deploy and invoke a corporate-based data service. The files are located in the /AccessManager-base/SUNWam/samples/phase2/sis-ep directory.
Note –
Before implementing this sample, you must have two instances of Access Manager installed, running, and Liberty-enabled. Completing the steps in sample1 Directory will accomplish this.
The Liberty Employee Profile Service is a deployment of the ID-SIS-EP specification as discussed in Liberty Employee Profile Service. The Readme.html file in the sample directory provides detailed steps on how to deploy and configure this sample for use as a data service. See also Appendix A, Liberty-based and SAML Samples.
Data Services Template API
Access Manager contains two packages based on the Liberty ID-WSF-DST. They are:
For more detailed API documentation, 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.dst Package
The following table summarizes the classes in the Data Services Template client API that are included in the com.sun.identity.liberty.ws.dst package.
Table 7–1 Data Service Client APIs|
Class |
Description |
|---|---|
|
DSTClient |
Provides common functions for the Data Services Templates query and modify options. |
|
DSTData |
Provides a wrapper for any data entry. |
|
DSTModification |
Represents a Data Services Template modification operation. |
|
DSTModify |
Represents a Data Services Template modify request. |
|
DSTModifyResponse |
Represents a Data Services Template response to a DST modify request. |
|
DSTQuery |
Represents a Data Services Template query request. |
|
DSTQueryItem |
Wrapper for one query item. |
|
DSTQueryResponse |
Represents a Data Services Template query response. |
|
DSTUtils |
Provides utility methods used by the DST layer. |
com.sun.identity.liberty.ws.dst.service Package
This package provides a handler class that can be used by any generic identity data service that is built using the Liberty Alliance ID-SIS Specifications.
Note –
The Liberty Personal Profile Service is built using the Liberty ID-SIS Personal Profile Service Specification, based on the Liberty Alliance ID-SIS Specifications.
The DSTRequestHandler class is used to process query or modify requests sent to an identity data service. It is an implementation of the interface com.sun.identity.liberty.ws.soapbinding.RequestHandler. For more detailed API documentation, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.
Note –
Access Manager provides a sample that makes use of the DSTRequestHandler class. The sis-ep sample illustrates how to implement the DSTRequestHandler and deploy a new identity data service instance. The sample is located in the /AccessManager-base/SUNWam/samples/phase2/sis-ep directory. For more information, see sis-ep Directory.
Developing A New Data Service
In addition to deploying an employee profile service, the Liberty Employee Profile Service sample can be used as a guide to develop other custom data services based on the Liberty ID-WSF-DST. Sections 2 and 3 in the Readme.html file in the /AccessManager-base/SUNWam/samples/phase2/sis-ep directory has detailed steps on how to deploy and configure data services. To use those instructions for a new data service, you need to write a new data service schema. This schema [an XML Schema Definition (XSD) document that is described in Schema Files and Service Definition Documents] defines the service’s data and data structure. After you write a new XSD file, use the sample Readme.html to deploy your new data service instead of the lib-id-sis-ep.xsd file referred to in the instructions.
Note –
Instructions on writing an XSD file are beyond the scope of this guide.
Chapter 8 Discovery Service
Sun Java™ System Access Manager contains a Discovery Service defined by the Liberty Alliance Project. The Discovery Service allows a requesting entity to dynamically determine a principal’s registered identity service. It might also function as a security token service, issuing security tokens to the requester that can then be used in the request to the discovered identity service.
This chapter covers the following topics:
Discovery Service Overview
All web services are defined by a Web Services Description Language (WSDL) file that describes the type of data the service contains, the available ways said data can be exchanged, the operations that can be performed using the data, a protocol that can be used to perform the operations, and a URL (or endpoint) for access to the service. Additionally, the WSDL file itself is assigned a unique resource identifier (URI) that is used to locate it. The file is then published and the URI is placed in a Universal Description, Discovery and Integration (UDDI) repository so it can be found by potential users. Thus, the web service can now be discovered. According to the Web Services Glossary, discovery of a web service is the act of locating a WSDL file for it. Typically, there are one or more web services on a network so, a discovery service is required to keep track of them.
Access Manager implements the Liberty ID-WSF Discovery Service Specification for its Discovery Service. The Discovery Service is a registry for identity-based web services. An identity-based web service presents an interface to access a type of data that is considered a part of a principal's online identity. For example, a payment web service might contain an individual's credit card information and would allow payments to be made using this information. When a web service consumer (WSC) queries the Discovery Service for a web service provider that allows access to a particular user's credit card information, the Discovery Service matches the properties in the request against the properties of it's registered services and returns the appropriate resource offering.
Note –
A resource offering defines an association between a type of identity data and a URI to the WSDL definition that provides information about obtaining access to the data. For more information on resource offerings, see Storing Resource Offerings.
This overview contains the following sections:
Discovery Service WSDL
A WSDL document is written in the eXtensible Markup Language (XML) and describes a web service. It specifies the location of the service and the operations the service exposes.
Note –
The WSDL specification can be found at http://www.w3.org/TR/wsdl.
The portType property in the Liberty ID-WSF Discovery Service WSDL file defines the Discovery Service operations.
-
DiscoveryLookup allows the Discovery Service to be queried. Using a Query, a WSC can find out which web service provider (WSP) stores the identity data relevant to the principal's request. The Discovery Service responds with QueryResponse that includes the necessary information for that identity.
-
DiscoveryUpdate enables maintenance of resource offerings already defined for the Discovery Service. Using a Modify, a WSC can add and remove resources, or change existing ones. The Discovery Service responds with ModifyResponse.
Following is a reproduction of liberty-idwsf-disco-svc-v1.2.wsdl, the Liberty ID-WSF Discovery Service WSDL file.
Example 8–1 Abstract WSDL for Liberty ID-WSF Discovery Service Specification
<?xml version="1.0"?>
<definitions name="disco-svc"
targetNamespace="urn:liberty:disco:2003-08"
xmlns:typens="urn:liberty:disco:2003-08"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:sb="urn:liberty:sb:2003-08"
xmlns:disco="urn:liberty:disco:2003-08">
<!-- Abstract WSDL for Liberty Discovery Service Specification -->
<xsd:documentation>
XML Schema from Liberty Discovery Service Specification.
### NOTICE ###
Copyright (c) 2004-2005 Liberty Alliance participants, see
http://www.projectliberty.org/specs/idwsf_1_1_copyrights.php
</xsd:documentation>
<types>
<xsd:schema>
<xsd:import schemaLocation="liberty-idwsf-disco-svc-exts-v1.2.xsd"/>
<xsd:import schemaLocation="liberty-idwsf-soap-binding-exts-v1.2.xsd"/>
<xsd:import schemaLocation="liberty-idwsf-soap-binding-v1.2.xsd"/>
</xsd:schema>
</types>
<message name="Query">
<part name="body" element="disco:Query"/>
</message>
<message name="QueryResponse">
<part name="body" element="disco:QueryResponse"/>
</message>
<message name="Modify">
<part name="body" element="disco:Modify"/>
</message>
<message name="ModifyResponse">
<part name="body" element="disco:ModifyResponse"/>
</message>
<message name="CorrelationHeader">
<part name="Correlation" element="typens:Correlation"/>
</message>
<portType name="DiscoveryPort">
<operation name="DiscoveryLookup">
<input message="typens:Query"/>
<output message="typens:QueryResponse"/>
</operation>
<operation name="DiscoveryUpdate">
<input message="typens:Modify"/>
<output message="typens:ModifyResponse"/>
</operation>
</portType>
<!--
An example of a binding and service that can be used with this
abstract service description is provided below.
-->
<binding name="DiscoveryBinding" type="typens:DiscoveryPort">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="DiscoveryLookup">
<soap:operation soapAction="http://example.com/DiscoveryLookup"/>
<input>
<soap:header message="typens:CorrelationHeader" part="Correlation" use="literal"/>
<soap:body use="literal"/>
</input>
<output>
<soap:header message="typens:CorrelationHeader" part="Correlation" use="literal"/>
<soap:body use="literal"/>
</output>
</operation>
<operation name="DiscoveryUpdate">
<soap:operation soapAction="http://example.com/DiscoveryUpdate"/>
<input>
<soap:header message="typens:CorrelationHeader" part="Correlation" use="literal"/>
<soap:body use="literal"/>
</input>
<output>
<soap:header message="typens:CorrelationHeader" part="Correlation" use="literal"/>
<soap:body use="literal"/>
</output>
</operation>
</binding>
<service name="DiscoveryService">
<port name="DiscoveryPort" binding="typens:DiscoveryBinding">
<!-- Modify with the REAL SOAP endpoint -->
<soap:address location="http://example.com/discovery"/>
</port>
</service>
</definitions>
|
amDisco XML Service Files
The Discovery Service is defined by the XML service file amDisco.xml. This file defines the attributes for the Discovery Service. All of the attributes in the Discovery Service can be managed through either the Access Manager Console or this file.
Note –
For more information about service files, see the Sun Java System Access Manager 7.1 Administration Guide. For more information about Discovery Service attributes, see Discovery Service Attributes.
A second XML file, amDisco_add.xml is in /AccessManager-base/SUNWam/upgrade/services50_sunIdentityServerDiscoveryService/10_20/data. This file is used for upgrading Identity Server 6.2 to Access Manager 7.1. It lists the changes to the amDisco.xml file since the earlier release.
Discovery Service Architecture
Java applications use the client API (discussed in Client APIs in com.sun.identity.liberty.ws.disco) to form requests sent to the Discovery Service and to parse the responses received back from it. Requests are initially received by a SOAP receiver which constructs the SOAP message that incorporates the client request.
Note –
The SOAP Binding Service defines how to send and receive messages using SOAP, an XML-based messaging protocol. The SOAP receiver is a servlet that constructs the message using these definitions. For more information, see Chapter 9, SOAP Binding Service.
The SOAP message is then routed to the Discovery Service which parses the resource identifier from it. This identifier is used to find a matching user distinguished name (DN). The necessary information is then culled from the corresponding profile, a response is generated, and the response is sent back to the SOAP receiver. The SOAP receiver then sends the response back to the client. The following figure illustrates this architecture. The Discovery Service Process has more information on how the Discovery Service works.
Figure 8–1 Discovery Service Architecture
Discovery Service Process
This figure provides a high-level overview of the interaction between parties in a web services environment using the Discovery Service. In this scenario, the identity provider hosts the Discovery Service. The process assumes that the Discovery Service is not generating security tokens. The individual steps are written up in more detail following the figure.
Figure 8–2 Participants in, and Process of, the Discovery Service
-
The user logs in to a Liberty-enabled identity provider, is authenticated, and completes the federation process, enabling single sign-on with other members of the authentication domain. More specifically:
-
Within a browser, the user types the URL for a Liberty-enabled service provider.
-
The service provider collects the user’s credentials and redirects the information to the identity provider for authentication.
-
If the credentials are verified, the user is authenticated.
-
Assuming the identity provider is the center of an authentication domain, that provider will notify the authenticated user of the option to federate any local identities created with member organizations. The user would then accept or decline this invitation to federate. By accepting the invitation, the user will be given the option to federate to a member organization’s web site at each login. If the user accepts this option to federate, single sign-on is enabled.
-
-
After authentication, the user now requests access to services hosted by another service provider in the authentication domain.
-
The service provider, acting as a web service consumer (WSC), sends a DiscoveryLookup query to the Discovery Service looking for a pointer to the user's identity provider.
The service provider is able to bootstrap the Discovery Service using the end point reference culled from the authentication statement.
-
The Discovery Service returns a DiscoveryLookup response to the service provider that points to the instance of the requested identity provider.
The response contains the resource offering for the user’s Personal Profile Service.
-
The service provider then sends a query (using the Data Services Template Specification) to the Personal Profile Service.
The required authentication mechanism specified in the Personal Profile Service resource offering must be followed.
-
The Personal Profile Service authenticates and validates authorization, or policy, or both for the requested user and service provider, and returns a Data Services Template response.
If user interaction is required for some attributes, the Interaction Service will be invoked to query the user for consents or attribute values. The Data Services Template would then be returned after all required data is collected.
-
The service provider processes the Personal Profile Service response and renders HTML pages based on the original request and user authorization.
A user's actual account information is not exchanged during federation. Thus, the identifier displayed on each provider site will be based on the respective local identity profile.
Discovery Service Attributes
The Discovery Service attributes are global attributes whose values are applied across the Access Manager configuration and inherited by every configured organization. The Discovery Service attributes are:
Note –
For information about the types of attributes used in Access Manager, see the Sun Java System Access Manager 7.1 Technical Overview.
Provider ID
This attribute takes a URI that points to the Discovery Service. Use the format protocol://host:port/amserver/Liberty/disco. This value can be changed only if other relevant attributes values are changed to match the new pointer.
Supported Authentication Mechanisms
This attribute specifies the authentication methods supported by the Discovery Service. These security mechanisms refer to the way a web service consumer authenticates to the web service provider or provides message-level security. By default, all available methods are selected. If an authentication method is not selected and a WSC sends a request using that method, the request is rejected. For more information, see the Liberty ID-WSF Security Mechanisms specification.
Supported Directives
This attribute allows you to specify a policy-related directive for a resource. If a service provider wants to use an unsupported directive, the request will fail. The following table describes the available options. More information can be found in the Liberty ID-WSF Discovery Service Specification.
Table 8–1 Policy-Related Directives|
Directive |
Purpose |
|---|---|
|
AuthenticateRequester |
The Discovery Service should include a SAML assertion containing an AuthenticationStatement in its query responses to enable the client to authenticate to the service instance hosting the resource. |
|
AuthenticateSessionContext |
The Discovery Service should include a SAML assertion containing a SessionContextStatement in its query responses that indicate the status of the session. |
|
AuthorizeRequestor |
The Discovery Service should include a SAML assertion containing a ResourceAccessStatement in its responses that indicate whether the client is allowed to access the resource. |
|
EncryptResourceID |
The Discovery Service should encrypt the resource identifier in responses to all clients. |
|
GenerateBearerToken |
For use with Bearer Token Authentication, the Discovery Service should generate a token that grants the bearer permission to access the resource. |
Policy Evaluation for Discovery Lookup
If enabled, the service will perform a policy evaluation for the DiscoveryLookup operation. By default, the check box is not selected.
Policy Evaluation for Discovery Update
If enabled, the service will perform a policy evaluation for the DiscoveryUpdate operation. By default, the check box is not selected.
Authorizer Plug-in Class
The value of this attribute is the name and path to the class that implements the com.sun.identity.liberty.ws.interfaces.Authorizer interface used for policy evaluation of a WSC. The default class is com.sun.identity.liberty.ws.disco.plugins.DefaultDiscoAuthorizer. See com.sun.identity.liberty.ws.interfaces.Authorizer Interface.
Entry Handler Plug-in Class
The value of this attribute is the name and path to the class that implements the com.sun.identity.liberty.ws.disco.plugins.DiscoEntryHandler interface. This interface is used to set or retrieve a principal’s discovery entries. To handle discovery entries differently, implement the com.sun.identity.liberty.ws.disco.plugins.DiscoEntryHandler interface and set the implementing class as the value for this attribute. The default implementation for the Discovery Service is com.sun.identity.liberty.ws.disco.plugins.UserDiscoEntryHandler. See com.sun.identity.liberty.ws.disco.plugins.DiscoEntryHandler Interface.
Classes For ResourceIDMapper Plug-in
The value of this attribute is a list of classes that generate identifiers for a resource offering configured for an organization or role. com.sun.identity.liberty.ws.interfaces.ResourceIDMapper is an interface used to map a user identifier to the resource identifier associated with it. The Discovery Service provides two implementations for this interface:
-
com.sun.identity.liberty.ws.disco.plugins.Default64ResourceIDMapper assumes the format to be providerID + "/" + the Base64 encoded userIDs
-
com.sun.identity.liberty.ws.disco.plugins.DefaultHexResourceIDMapper assumes the format to be providerID + "/" + the hex string of userIDs
Different implementations may also be developed with the interface and added as a value of this attribute by clicking New and defining the following attributes:
-
Provider ID takes as a value a URI that points to the Discovery Service. Use the format http://host:port/amserver/Liberty/disco. See Provider ID.
-
ID Mapper takes as a value the class name and path of the implementing class.
See com.sun.identity.liberty.ws.interfaces.ResourceIDMapper Interface.
Authenticate Response Message
If enabled, the service authenticates the response message. By default, the function is not enabled.
SessionContextStatement for Bootstrapping
If enabled, this attribute specifies whether to generate a SessionContextStatement for bootstrapping. A SessionContextStatement conveys the session status of an entity. By default, this function is not enabled.
Encrypt NameIdentifier in Session Context for Bootstrapping
If enabled, the service encrypts the name identifier in a SessionContextStatement. By default, this function is not enabled.
Implied Resource
If enabled, the service does not generate a resource identifier for bootstrapping. By default, this function is not enabled.
Resource Offerings for Bootstrapping
This attribute defines a resource offering for bootstrapping a service. After single sign-on (SSO), this resource offering and its associated credentials will be sent to the client in the SSO assertion. Only one resource offering is allowed for bootstrapping. The value of the Resource Offerings for Bootstrapping attribute is a default value configured during installation. If you want to define a new resource offering, you must first delete the existing resource offering, then click New to define the attributes for a new resource offering. If you want to edit an existing resource offering, click the name of the existing Service Type to modify the attributes. For more information, see Storing a Resource Offering for Discovery Service Bootstrapping.
Storing Resource Offerings
A resource offering defines an association between a type of identity data and a URI to the WSDL file that provides information about obtaining access to the data. In Access Manager, a resource offering can be stored as a user attribute or as a dynamic attribute. Storing resource offerings within a user profile supports both DiscoveryLookup and DiscoveryUpdate operations. Storing resource offerings within a service and assigning that service to a realm or role supports only the DiscoveryLookup operation using the discovery protocol. (Updates can still be done using the Access Manager Console.) More information is provided in the following sections:
Storing Resource Offerings as User Attributes
Resource offerings can be stored as an attribute under a user’s profile using the Lightweight Directory Access Protocol (LDAP). Storing resource offerings within a user profile supports both DiscoveryLookup and DiscoveryUpdate operations. The following procedure explains how to access and create a user’s resource offerings.
To Store a Resource Offering as a User Attribute
-
In the Access Manager Console, click the Access Control tab.
-
Select the name of the realm that contains the user profile you want to modify.
-
Select Subjects to access user information.
-
Select the name of the user profile that you want to modify.
-
Select Services to access the user's services.
-
Click Add to configure the Discovery Service for this user.
-
Select Discovery Service and click Next.
The Discovery Service is added to the user's services.
-
Select General to access the user's User Discovery Resource Offering attribute.
-
Click Edit.
A User Discovery Resource Offering window opens.
-
Click Add in the User Discovery Resource Offering window.
-
(Optional) Type a value for the Resource ID Attribute.
This field defines an identifier for the resource offering.
-
Type the Resource ID Value.
This field defines the resource identifier. A resource identifier is a URI registered with the Discovery Service that point to a particular discovery resource. It is generated by the profile provider. The value of this attribute must not be a relative URI and should contain a domain name that is owned by the provider hosting the resource. If a discovery resource is exposed in multiple Resource Offerings, the Resource ID Value for all of those resource offerings would be the same. An example of a valid Resource ID value is http://profile-provider.com/profiles/14m0B82k15csaUxs.
Tip –urn:libery:isf:implied-resource can be used as a Resource ID Value when only one resource can be operated upon at the service instance being contacted. The URI only implicitly identifies the resource in question. In some circumstances, the use of this resource identifier can eliminate the need for contacting the discovery service to access the resource.
-
(Optional) Enter a description of the resource offering in the Description field.
-
Type a URI for the value of the Service Type attribute.
This URI defines the type of service.
Tip –It is recommended that the value of this attribute be the targetNamespace URI defined in the abstract WSDL description for the service. An example of a valid URI is urn:liberty:id-sis-pp:2003-08.
-
Type a URI for the value of the Provider ID attribute.
This attribute contains the URI of the provider of the service instance. This information is useful for resolving trust metadata needed to invoke the service instance. A single physical provider may have multiple provider IDs. An example of a valid URI is http://profile-provider.com.
Note –The provider represented by the URI in the Provider ID attribute must also have a class entry in the ResourceIDMapper attribute. For more information, see Classes For ResourceIDMapper Plug-in.
-
Click Add Description to define the Service Description.
For each resource offering, at least one service description must be created.
-
Select the values for the Security Mechanism ID attribute to define how a web service client can authenticate to a web service provider.
This field lists the security mechanisms that the service instance supports. Select the security mechanisms that you want to add and click Add. To prioritize the list, select the mechanism and click Move Up or Move Down.
-
Type a value for the End Point URL.
This value is the URL of the SOAP-over-HTTP endpoint. The URI scheme must be HTTP or HTTPS as in https://soap.profile-provider.com/soap.
-
(Optional) Type a value for the SOAP Action.
This value is the equivalent of the wsdlsoap:soapAction attribute of the wsdlsoap:operation element in the service's concrete WSDL-based description.
-
Click OK to complete the configuration.
-
-
Check the Options box if there are no options or add a URI to specify options for the resource offering.
This field lists the options that are available for the resource offering. Options provide hints to a potential requestor about the availability of certain data or operations to a particular offering. The set of possible URIs are defined by the service type, not the Discovery Service. If no option is specified, the service instance does not display any available options. For a standard set of options, see the Liberty ID-SIS Personal Profile Service Specification.
-
Select a directive for the resource offering.
Directives are special entries defined in SOAP headers that can be used to enforce policy-related decisions. You can choose from the following:
-
GenerateBearerToken specifies that a bearer token be generated.
-
AuthenticateRequester must be used with any service description that use SAML for message authentication.
-
EncryptResourceID specifies that the Discovery Service encrypt the resource ID.
-
AuthenticateSessionContext is specified when a Discovery Service provider includes a SAML assertion containing a SessionContextStatement in any future QueryResponse messages.
-
AuthorizeRequester is specified when a Discovery Service provider wants to include a SAML assertion containing a ResourceAccessStatement in any future QueryResponse messages.
If you want to associate a directive with one or more service descriptions, select the check box for that Description ID. If no service descriptions are selected, the directive is applied to all description elements in the resource offering.
-
-
Click OK.
-
Click Close to close the User Discovery Resource Offering window.
-
Click Save to save the configuration.
Storing Resource Offerings as Dynamic Attributes
Due to the repetition inherent in storing discovery entries as user attributes, Access Manager has established the option of storing a discovery entry as a dynamic attribute within a role or a realm. The role or realm can then be assigned to an identity-related object, making the entry available to all users within the object. Unlike storing a discovery entry as a user attribute, this scenario only supports the DiscoveryLookup operation.
There are two ways in which you can store discovery entries as dynamic attributes. You can store them in a realm or in a role. The following sections describe the procedures:
To Store Resource Offerings as Dynamic Attributes
in a Realm
To create a discovery entry as a dynamic attribute in a realm, the Discovery Service must first be added and a template created.
-
In the Access Manager Console, click the Access Control tab.
-
Select the name of the realm you want to modify.
-
Select Services to access the realm's services.
-
Click Add to add the Discovery Service to the realm.
A list of available services is displayed.
-
Select Discovery Service and click Next to add the service.
A list of added services is displayed including the Discovery Service.
-
Select Subjects to access user information.
-
Select the name of the user you want to modify.
-
Select Services to add the Discovery Service to the user.
-
Click Add to add the Discovery Service to the user.
A list of available services is displayed.
-
Select Discovery Service and click Next to add the service.
A list of added services is displayed including the Discovery Service.
-
Using the path displayed on top of the Access Manager Console, click the name of the realm.
-
Click Services to access the realm's services.
-
Click Add.
-
Select Discovery Service and click Next to add the service.
-
Click Discovery Service to add a resource offering to the service.
-
Click Add to add a resource offering.
-
(Optional) Enter a description of the resource offering in the Description field.
-
Type a URI for the value of the Service Type attribute.
This URI defines the type of service. It is recommended that the value of this attribute be the targetNamespace URI defined in the abstract WSDL description for the service. An example of a valid URI is urn:liberty:id-sis-pp:2003-08.
-
Type a URI for the value of the Provider ID attribute.
The value of this attribute contains the URI of the provider of the service instance. This information is useful for resolving trust metadata needed to invoke the service instance. A single physical provider may have multiple provider IDs. An example of a valid URI is http://profile-provider.com.
Note –The provider represented by the URI in the Provider ID attribute must also have an entry in the ResourceIDMapper attribute. For more information, see Classes For ResourceIDMapper Plug-in.
-
Click Add Description to define the Service Description.
For each resource offering, at least one service description must be created.
-
Select the values for the Security Mechanism ID attribute to define how a web service client can authenticate to a web service provider.
This field lists the security mechanisms that the service instance supports. Select the security mechanisms that you want to add and click Add. To prioritize the list, select the mechanism and click Move Up or Move Down.
-
Type a value for the End Point URL.
This value is the URL of the SOAP-over-HTTP endpoint. The URI scheme must be HTTP or HTTPS as in https://soap.profile-provider.com/soap.
-
(Optional) Type a value for the SOAP Action.
This value is the equivalent of the wsdlsoap:soapAction attribute of the wsdlsoap:operation element in the service's concrete WSDL-based description.
-
Click OK to complete the configuration.
-
-
Check the Options box if there are no options or add a URI to specify options for the resource offering.
This field lists the options that are available for the resource offering. Options provide hints to a potential requestor about the availability of certain data or operations to a particular offering. The set of possible URIs are defined by the service type, not the Discovery Service. If no option is specified, the service instance does not display any available options. For a standard set of options, see the Liberty ID-SIS Personal Profile Service Specification.
-
Select a directive for the resource offering.
Directives are special entries defined in SOAP headers that can be used to enforce policy-related decisions. You can choose from the following:
-
GenerateBearerToken specifies that a bearer token be generated.
-
AuthenticateRequester must be used with any service description that use SAML for message authentication.
-
EncryptResourceID specifies that the Discovery Service encrypt the resource ID.
-
AuthenticateSessionContext is specified when a Discovery Service provider includes a SAML assertion containing a SessionContextStatement in any future QueryResponse messages.
-
AuthorizeRequester is specified when a Discovery Service provider wants to include a SAML assertion containing a ResourceAccessStatement in any future QueryResponse messages.
If you want to associate a directive with one or more service descriptions, select the check box for that Description ID. If no service descriptions are selected, the directive is applied to all description elements in the resource offering.
-
-
Click OK.
-
Click Close to close the Discovery Resource Offering window.
-
Click Save to save the configuration.
To Store Resource Offerings as Dynamic Attributes
in a Role
To create a discovery entry as a dynamic attribute in a role, the Discovery Service must first be added and a template created.
-
In the Access Manager Console, click the Access Control tab.
-
Select the name of the realm you want to modify.
-
Select Subjects to access the realm's identity information.
-
Select Role to access the realm's role information.
-
Select the name of the role you want to modify.
Alternately, you can create a new role and then select the name of this new role.
-
Under Services, click Add to add the Discovery Service to the role.
A list of available services is displayed.
-
Select Discovery Service and click Next to add the service.
A list of added services is displayed including the Discovery Service.
-
Click Discovery Service to add a resource offering to the service.
-
Click Add.
-
(Optional) Enter a description of the resource offering in the Description field.
-
Type a URI for the value of the Service Type attribute.
This URI defines the type of service. It is recommended that the value of this attribute be the targetNamespace URI defined in the abstract WSDL description for the service. An example of a valid URI is urn:liberty:id-sis-pp:2003-08.
-
Type a URI for the value of the Provider ID attribute.
The value of this attribute contains the URI of the provider of the service instance. This information is useful for resolving trust metadata needed to invoke the service instance. A single physical provider may have multiple provider IDs. An example of a valid URI is http://profile-provider.com.
Note –The provider represented by the URI in the Provider ID attribute must also have an entry in the ResourceIDMapper attribute. For more information, see Classes For ResourceIDMapper Plug-in.
-
Click Add Description to define the Service Description.
For each resource offering, at least one service description must be created.
-
Select the values for the Security Mechanism ID attribute to define how a web service client can authenticate to a web service provider.
This field lists the security mechanisms that the service instance supports. Select the security mechanisms that you want to add and click Add. To prioritize the list, select the mechanism and click Move Up or Move Down.
-
Type a value for the End Point URL.
This value is the URL of the SOAP-over-HTTP endpoint. The URI scheme must be HTTP or HTTPS as in https://soap.profile-provider.com/soap.
-
(Optional) Type a value for the SOAP Action.
This value is the equivalent of the wsdlsoap:soapAction attribute of the wsdlsoap:operation element in the service's concrete WSDL-based description.
-
Click OK to complete the configuration.
-
-
Check the Options box if there are no options or add a URI to specify options for the resource offering.
This field lists the options that are available for the resource offering. Options provide hints to a potential requestor about the availability of certain data or operations to a particular offering. The set of possible URIs are defined by the service type, not the Discovery Service. If no option is specified, the service instance does not display any available options. For a standard set of options, see the Liberty ID-SIS Personal Profile Service Specification.
-
Select a directive for the resource offering.
Directives are special entries defined in SOAP headers that can be used to enforce policy-related decisions. You can choose from the following:
-
GenerateBearerToken specifies that a bearer token be generated.
-
AuthenticateRequester must be used with any service description that use SAML for message authentication.
-
EncryptResourceID specifies that the Discovery Service encrypt the resource ID.
-
AuthenticateSessionContext is specified when a Discovery Service provider includes a SAML assertion containing a SessionContextStatement in any future QueryResponse messages.
-
AuthorizeRequester is specified when a Discovery Service provider wants to include a SAML assertion containing a ResourceAccessStatement in any future QueryResponse messages.
If you want to associate a directive with one or more service descriptions, select the check box for that Description ID. If no service descriptions are selected, the directive is applied to all description elements in the resource offering.
-
-
Click OK.
-
Click Close to close the Discovery Resource Offering window.
-
Click Save to save the configuration.
Storing a Resource Offering for Discovery Service Bootstrapping
Before a WSC can contact the Discovery Service to obtain a resource offering, the WSC needs to discover the Discovery Service. Thus, an initial resource offering for locating the Discovery Service is sent back to the WSC in a SAML assertion generated during authentication. The following procedure describes how to configure a global attribute for bootstrapping the Discovery Service. For more information on bootstrapping the Discovery Service, see Resource Offerings for Bootstrapping.
To Store a Resource Offering for Discovery Service Bootstrapping
-
In the Access Manager Console, select the Web Services tab.
-
Under Web Services, click the Discovery Service tab.
-
Choose New under the Resource Offerings for Bootstrapping Resources attribute.
By default, the resource offering for bootstrapping the Discovery Service is already configured. In order to create a new resource offering, you must first delete the default resource offering.
-
(Optional) Type a description of the resource offering.
-
Enter a URI for the value of the Service Type attribute.
This field defines the type of service. It is recommended that the value of this attribute be the targetNamespace URI defined in the abstract WSDL description for the service. An example of a valid URI is urn:liberty:disco:2003-08.
-
Enter a URI for the value of the Provider ID attribute.
This attribute contains the URI of the provider of the service instance. This is useful for resolving trust metadata needed to invoke the service instance. A single physical provider may have multiple provider IDs. An example of a valid URI is http://sample_disco.com.
Note –The provider represented by the URI in the Provider ID attribute must also have an entry in the Classes for ResourceIDMapper Plugin attribute. For more information, see Classes For ResourceIDMapper Plug-in.
-
Click Add Description to define a security mechanism ID.
For each resource offering, at least one service description must be created.
-
Select the values for the Security Mechanism ID attribute to define how a web service client can authenticate to a web service provider.
This field lists the security mechanisms that the service instance supports. Select the security mechanisms you wish to add and click the Add button. To arrange the priority of the list, select the mechanism and use the Move Up or Move Down buttons.
-
Type a value for the End Point URL.
This value is the URL of the SOAP-over-HTTP endpoint. The URI scheme must be HTTP or HTTPS as in https://soap.profile-provider.com/soap.
-
(Optional) Type a value for the SOAP action.
This field contains the equivalent of the wsdlsoap:soapAction attribute of the wsdlsoap:operation element in the service's concrete WSDL-based description.
-
Click OK to save the configuration.
-
-
Check the Options box if there are no options or add a URI to specify options for the resource offering.
This field lists the options that are available for the resource offering. Options provide hints to a potential requestor about the availability of certain data or operations to a particular offering. The set of possible URIs are defined by the service type, not the Discovery Service. If no option is specified, the service instance does not display any available options. For a standard set of options, see the Liberty ID-SIS Personal Profile Service Specification.
-
Select a directive for the resource offering.
Directives are special entries defined in SOAP headers that can be used to enforce policy-related decisions. You can choose from the following:
-
GenerateBearerToken specifies that a bearer token be generated.
-
AuthenticateRequester must be used with any service description that use SAML for message authentication.
-
EncryptResourceID specifies that the Discovery Service encrypt the resource ID.
-
AuthenticateSessionContext is specified when a Discovery Service provider includes a SAML assertion containing a SessionContextStatement in any future QueryResponse messages.
-
AuthorizeRequester is specified when a Discovery Service provider wants to include a SAML assertion containing a ResourceAccessStatement in any future QueryResponse messages.
If you want to associate a directive with one or more service descriptions, select the check box for that Description ID. If no service descriptions are selected, the directive is applied to all description elements in the resource offering.
-
-
Click OK to complete the configuration.
Generating Security Tokens
In general, a discovery service and an identity provider are hosted on the same machine. Because the identity provider hosting the Discovery Service might be fulfilling other roles for an identity (such as a Policy Decision Point or an Authentication Authority), it can be configured to provide the requesting entity with security tokens. The Discovery Service can include a security token (inserted into a SOAP message header) in a DiscoveryLookup response. The token can then be used as a credential to invoke the service returned with it.
To Configure the Discovery Service to Generate Security
Tokens
After completing the following procedure, you can test the functionality by running the samples. See Web Services Framework Samples for information.
-
Generate the keystore and certificate aliases for the machines that are hosting the Discovery Service, the WSP and the WSC.
Access Manager uses a Java keystore for storing the public and private keys so, if this is a new deployment, you might need to generate one. keystore.html in AccessManager-base/SUNWam/samples/saml/xmlsig/ has information on accomplishing this using keytool, the key and certificate management utility supplied with the Java Platform, Standard Edition. In short, keytool generates key pairs as separate key entries (one for a public key and the other for its associated private key). It wraps the public key into an X.509 self-signed certificate (one for which the issuer/signer is the same as the subject), and stores it as a single-element certificate chain. Additionally, the private key is stored separately, protected by a password, and associated with the certificate chain for the corresponding public key. All public and private keystore entries are accessed via unique aliases.
-
Update the values of the following key-related properties in the AMConfig.properties files of the appropriate deployed instances of Access Manager.
AMConfig.properties is located in /etc/opt/SUNWam/config/.
Note –The same property might have already been edited depending on the deployment scenario.
-
Update the values of the following key-related properties in the AMConfig.properties files on the machine that hosts the Discovery Service.
-
com.sun.identity.saml.xmlsig.keystore defines the location of the keystore file.
-
com.sun.identity.saml.xmlsig.storepass defines the location of the file that contains the password used to access the keystore file.
-
com.sun.identity.saml.xmlsig.keypass defines the location of the file that contains the password used to protect the private key of a generated key pair.
-
com.sun.identity.liberty.ws.ta.certalias defines the certificate alias used by the Discovery Service to sign SAML assertions.
-
com.sun.identity.liberty.ws.wsc.certalias defines the certificate alias used by the Discovery Service to sign the protocol response.
-
-
Update the values of the following key-related properties in the AMConfig.properties files on the machines that acts as the WSP.
-
com.sun.identity.saml.xmlsig.keystore defines the location of the keystore file.
-
com.sun.identity.saml.xmlsig.storepass defines the location of the file that contains the password used to access the keystore file.
-
com.sun.identity.saml.xmlsig.keypass defines the location of the file that contains the password used to protect the private key of a generated key pair.
-
com.sun.identity.liberty.ws.wsc.certalias defines the certificate alias used for signing the WSP protocol responses.
-
com.sun.identity.liberty.ws.trustedca.certaliases defines the certificate alias and the Provider ID list on which the WSP is trusting.
-
-
Update the values of the following key-related properties in the AMConfig.properties files on the machine that acts as the WSC.
-
com.sun.identity.saml.xmlsig.keystore defines the location of the keystore file.
-
com.sun.identity.saml.xmlsig.storepass defines the location of the file that contains the password used to access the keystore file.
-
com.sun.identity.saml.xmlsig.keypass defines the location of the file that contains the password used to protect the private key of a generated key pair.
-
com.sun.identity.liberty.ws.wsc.certalias defines the certificate alias used by web service clients for signing protocol requests.
Note –The com.sun.identity.liberty.ws.wsc.certalias property must be added to the AMConfig.properties file.
-
-
-
Configure each identity provider and service provider as an entity using the Access Manager Federation module.
This entails configuring a entity for each provider using the Access Manager Console or loading an XML metadata file using amadmin. See Entities for information on the former and Chapter 1, The amadmin Command Line Tool, in Sun Java System Access Manager 7.1 Administration Reference for information on the latter.
Note –Be sure to configure each provider's entity so that all providers in the scenario are defined as Trusted Providers.
-
Establish provider trust between the entities by creating an authentication domain using the Access Manager Federation module.
-
Change the default value of the Provider ID for the Discovery Service on the machine where the Discovery Service is hosted to the value that reflects the previously loaded metadata.
-
Click the Web Services tab from the Access Manager Console.
-
Click the Discovery Service tab under Web Services.
-
Change the default value of the Provider ID from protocol://host:port/deployuri/Liberty/disco.
Note –If using the samples, make sure that the value of Provider ID in discovery-modify.jsp is changed, if necessary, before the WSP registers with the Discovery Service.
-
-
Change the default value of the Provider ID for the Liberty Personal Profile Service on the machine where the Liberty Personal Profile Service is hosted to the value that reflects the previously loaded metadata.
-
Register a resource offering for the WSP using either of the following methods.
-
Access Manager Console
See Storing Resource Offerings for information on registering a resource offering using the Access Manager Console.
-
Client API
See discovery-modify.jsp in AccessManager-base/samples/phase2/wsc which calls the API for registering a resource offering.
Also, make sure that the appropriate directives are chosen.
-
For SAML Bearer token use GenerateBearerToken or AuthenticateRequester.
-
For SAML Token (Holder of key) use AuthenticateRequester or AuthorizeRequester.
-
Discovery Service APIs
Access Manager contains several Java packages that are used by the Discovery Service. They include:
-
com.sun.identity.liberty.ws.disco includes a client API that provides interfaces to communicate with the Discovery Service. See Client APIs in com.sun.identity.liberty.ws.disco.
-
com.sun.identity.liberty.ws.disco.plugins includes an interface that can be used to develop plug-ins. The package also contains some default plug-ins. See com.sun.identity.liberty.ws.disco.plugins.DiscoEntryHandler Interface.
-
com.sun.identity.liberty.ws.interfaces includes interfaces that can be used to implement functionality common to all Liberty-enabled identity services. Several implementations of these interfaces have been developed for the Discovery Service. See com.sun.identity.liberty.ws.interfaces.Authorizer Interface and com.sun.identity.liberty.ws.interfaces.ResourceIDMapper Interface.
Note –
Additional information is in the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com. Information about the com.sun.identity.liberty.ws.common package is in Common Service Interfaces in Chapter 11, Application Programming Interfaces.
Client APIs in com.sun.identity.liberty.ws.disco
The following table summarizes the client APIs in the package com.sun.identity.liberty.ws.disco. 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 8–2 Discovery Service Client APIs|
Class |
Description |
|---|---|
|
Description |
Represents a DescriptionType element of a service instance. |
|
Directive |
Represents a discovery service DirectiveType element. |
|
DiscoveryClient |
Provides methods to send Discovery Service queries and modifications. |
|
EncryptedResourceID |
Represents an EncryptionResourceID element for the Discovery Service. |
|
InsertEntry |
Represents an Insert Entry for Discovery Modify request. |
|
Modify |
Represents a discovery modify request. |
|
ModifyResponse |
Represents a discovery response to a modify request. |
|
Query |
Represents a discovery Query object. |
|
QueryResponse |
Represents a response to a discovery query request. |
|
RemoveEntry |
Represents a remove entry element for the discovery modify request. |
|
RequestedService |
Enables the requester to specify that all the resource offerings returned must be offered through a service instance that complys with one of the specified service types. |
|
ResourceID |
Represents a Discovery Service Resource ID. |
|
ResourceOffering |
Associates a resource with a service instance that provides access to that resource. |
|
ServiceInstance |
Describes a web service at a distinct protocol endpoint. |
com.sun.identity.liberty.ws.disco.plugins.DiscoEntryHandler Interface
This interface is used to get and set discovery entries for a user. A number of default implementations are provided, but if you want to handle this function differently, implement this interface and set the implementing class as the value of the Entry Handler Plugin Class attribute as discussed in Entry Handler Plug-in Class. The default implementations of this interface are described in the following table.
Table 8–3 Implementations of com.sun.identity.liberty.ws.disco.plugins.DiscoEntryHandler|
Class |
Description |
|---|---|
|
UserDiscoEntryHandler |
Gets or modifies discovery entries stored in the user’s entry as a value of the sunIdentityServerDiscoEntries attribute. The UserDiscoEntryHandler implementation is used in business-to-consumer scenarios such as the Liberty Personal Profile Service. |
|
DynamicDiscoEntryHandler |
Gets discovery entries stored as a value of the sunIdentityServerDynamicDiscoEntries dynamic attribute in the Discovery Service. Modification of these entries is not supported and always returns false. The resource offering is saved in an organization or a role. The DynamicDiscoEntryHandler implementation is used in business-to-business scenarios such as the Liberty Employee Profile service. |
|
UserDynamicDiscoEntryHandler |
Gets a union of the discovery entries stored in the user entry sunIdentityServerDiscoEntries attribute and discovery entries stored in the Discovery Service sunIdentityServerDynamicDiscoEntries attribute. It modifies only discovery entries stored in the user entry. The UserDynamicDiscoEntryHandler implementation can be used in both business-to-consumer and business-to-business scenarios. |
com.sun.identity.liberty.ws.interfaces.Authorizer Interface
This interface is used to enable an identity service to check the authorization of a WSC. The DefaultDiscoAuthorizer class is the default implementation of this interface. The class uses the Access Manager Policy Service for creating and applying policy definitions. Policy definitions for the Discovery Service are configured using the Access Manager Console.
Note –
The Policy Service looks for an SSOToken defined for Authenticated Users or Web Service Clients. For more information on this and the Policy Service in general, see the Sun Java System Access Manager 7.1 Administration Guide.
To Configure Discovery Service Policy Definitions
-
In the Access Manager Console, click the Access Control tab.
-
Select the name of the realm in which the policy definitions will be configured.
-
Select Policies to access policy configurations.
-
Click New Policy to add a new policy definition.
-
Type a name for the policy.
-
(Optional) Enter a description for the policy.
-
(Optional) Select the check box next to Active.
-
Click New to add rules to the policy definition.
-
Select Discovery Service for the rule type and click Next.
-
Type a name for the rule.
-
Type a resource on which the rule acts.
The Resource Name field uses the form ServiceType + RESOURCE_SEPARATOR + ProviderID. For example, urn:liberty:id-sis-pp:2003-08;http://example.com.
-
Select an action and appropriate value for the rule.
Discovery Service policies can only look up or update data.
-
Click Finish to configure the rule.
The com.sun.identity.liberty.ws.interfaces.Authorizer interface can be implemented by any web service in Access Manager. For more information, see Common Service Interfaces and the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.
-
Click New to add subjects to the policy definition.
-
Select the subject type and click Next.
-
Type a name for the group of subjects.
-
(Optional) Click the check box if this is an exclusive group.
-
Select the users and click to add them to the group.
-
Click Finish to return to the policy definition screen.
-
Click New to add conditions to the policy definition.
-
Select the condition type and click Next.
-
Type values for the displayed attributes.
For more information, see the Sun Java System Access Manager 7.1 Administration Guide.
-
Click Finish to return to the policy definition screen.
-
Click New to add response providers to the policy definition.
-
Type a name for the response provider.
-
(Optional) Add values for the StaticAttribute.
-
(Optional) Add values for the DynamicAttribute.
-
Click Finish to return to the policy definition screen.
-
Click Create to finish the policy configuration.
com.sun.identity.liberty.ws.interfaces.ResourceIDMapper Interface
This interface is used to map a user ID to the resource identifier associated with it. Access Manager provides two implementations of this interface.
-
com.sun.identity.liberty.ws.disco.plugins.Default64ResourceIDMapper assumes the format to be providerID + "/" + the Base64 encoded userIDs
-
com.sun.identity.liberty.ws.disco.plugins.DefaultHexResourceIDMapper assumes the format to be providerID + "/" + the hex string of 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 Plug-in attribute.
Note –
The com.sun.identity.liberty.ws.interfaces.ResourceIDMapper interface is common to all identity services in Access Manager not only the Discovery Service. For more information, see Common Service Interfaces and the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.
Access the Discovery Service
The URL to gain access to the Discovery Service is:
http://SERVER_HOST:SERVER_PORT/SERVER_DEPLOY_URI/Liberty/disco |
This URL is normally used by the Access Manager client API to access the service. For example, the Access Manager public Discovery Service client, com.sun.identity.liberty.ws.disco.DiscoveryClient uses this URL to query and modify the resource offerings of an identity.
Discovery Service Sample
A sample that shows the process for querying and modifying the Discovery Service is included with Access Manager in the /AccessManager-base/SUNWam/samples/phase2/wsc directory. The sample initially shows how to deploy and run a WSC. The final portion queries the Discovery Service and modifies identity data in the Liberty Personal Profile Service. For more information, see Appendix A, Liberty-based and SAML Samples.
Chapter 9 SOAP Binding Service
Sun™ Java System Access Manager contains an implementation of the Liberty ID-WSF SOAP Binding Specification from the Liberty Alliance Project. The specification defines a transport layer for sending and receiving SOAP messages.
This chapter covers the following topics:
SOAP Binding Service Overview
The Liberty Identity Web Services Framework (Liberty ID-WSF) and Liberty Identity Service Interface Specifications (Liberty ID-SIS) components of the Liberty Alliance Project specifications use messages to convey identity data between providers. Access Manager has implemented the Liberty ID-WSF SOAP Binding Specification (Liberty ID-WSF-SBS) as the method of transport for this purpose. The specification defines SOAP as the binding to the Hypertext Transport Protocol (HTTP), which is itself layered onto the TCP/IP stack.
Note –
For more information, see the Liberty ID-WSF SOAP Binding Specification.
The following sections contain additional information about the SOAP Binding Service.
XML Service File
The Access Manager SOAP Binding Service is defined using the XML service file amSOAPBinding.xml. This file defines the attributes for the SOAP Binding Service which can be managed through the Access Manager Console or the XML file.
Note –
For more information on service files, see the Sun Java System Access Manager 7.1 Administration Guide.
The Liberty ID-WSF-SBS also defines an XML schema for use in building the SOAP messages. More information about the XSD schemas can be found in Schema Files and Service Definition Documents.
SOAPReceiver Servlet
The SOAPReceiver servlet receives a Message object from a web service client (WSC), verifies the signature, and constructs its own Message object for processing by Access Manager. The SOAPReceiver then invokes the correct request handler class to pass this second Message object on to the appropriate Access Manager service for a response. When the response is generated, the SOAPReceiver returns this Message object back to the WSC. More information can be found in the SOAP Binding Process.
SOAP Binding Service APIs
The Access Manager SOAP Binding Service includes a Java package named com.sun.identity.liberty.ws.soapbinding. For more information, see SOAP Binding Service Package.
SOAP Binding Process
In the SOAP Binding process, an identity service invokes the Message class (contained in the client-side API) to construct a request. (As clients of the SOAP Binding Service, the Access Manager Discovery Service, implemented Data Services Template services (including the Liberty Personal Profile Service and the sample Employee Profile Service), and the Authentication Web Service all use the SOAP Binding Service client-side API.) The Message object will contain any default or non-default SOAP headers as well as the SOAP body containing the request(s). Once generated, the WSC invokes the sendRequest method and sends the Message object to the SOAP endpoint URL on the server side. The URL is, in effect, a servlet called the SOAPReceiver. The SOAPReceiver receives the Message, verifies the signature, and constructs its own Message object. The SOAPReceiver then invokes the appropriate Request Handler class to send this second message to the corresponding service for a response.
Note –
com.sun.identity.liberty.ws.soapbinding.RequestHandler is an interface that must be implemented on the server side by any Liberty-based web service using the SOAP Binding Service. For more information, see Request Handler List.
The web service processes the second message, generates a response, and sends that response back to the SOAPReceiver which, in turn, returns the response back to the WSC for processing.
Note –
Before invoking a corresponding service, the SOAP framework might also do the following:
-
Authenticate the sender identity to verify the credentials of a WSC peer, probably by verifying its client certificate.
-
Authenticate the invoking identity to verify the credentials of a WSC on behalf of a user to verify whether the user has been authenticated. This depends on the security authentication profile.
-
Granular authorization to authorize the WSC before processing a service request.
SOAP Binding Service Attributes
The SOAP Binding Service attributes are global attributes. The values of these attributes are carried across the Access Manager configuration and inherited by every organization.
Note –
For information about the types of attributes used in Access Manager, see the Sun Java System Access Manager 7.1 Technical Overview.
Attributes for the SOAP Binding Service are defined in the amSOAPBinding.xml service file. The SOAP Binding Service attributes are as follows:
Request Handler List
The Request Handler List stores information about the classes implemented from the com.sun.identity.liberty.ws.soapbinding.RequestHandler interface. The SOAP Binding Service provides the interface to process requests and return responses. The interface must be implemented on the server side for each Liberty-based web service that uses the SOAP Binding Service.
To add a new implementation, click New and define values for the following parameters.
Key Parameter
The Key parameter is the last part of the URI path to a SOAP endpoint. The SOAP endpoint in Access Manager is the SOAPReceiver servlet. The URI to the SOAPReceiver uses the format protocol://host:port/deloy-uri/Liberty/key. If you define disco as the Key, the URI path to the SOAPReceiver for the corresponding Discovery Service would be protocol://host:port/amserver/Liberty/disco.
Note –
Different service clients must use different keys when connecting to the SOAPReceiver.
Class Parameter
The Class parameter specifies the name of the class implemented from com.sun.identity.liberty.ws.soapbinding.RequestHandler for the particular web service. For example, class=com.example.identity.liberty.ws.disco.DiscoveryService.
SOAP Action Parameter
The optional SOAP Action can be used to indicate the intent of the SOAP HTTP request. The SOAP processor on the receiving system can use this information to determine the ultimate destination for the service. The value is a URI. No defined value indicates no intent.
Note –
SOAP places no restrictions on the format or specificity of the URI or that it is resolvable.
Web Service Authenticator
This attribute takes as a value the implementation class for the Web Service Authenticator interface. This class authenticates a request and generates a credential for a WSC.
Note –
This interface is not public. The value of the attribute is configured during installation.
Supported Authentication Mechanisms
This attribute specifies the authentication mechanisms supported by the SOAP Receiver. Authentication mechanisms offer user authentication as well as data integrity and encryption. By default, all available authentication mechanisms are selected. If a mechanism is not selected and a WSC sends a request using it, the request is rejected. Following is a list of the supported authentication mechanisms:
-
urn:liberty:security:2003-08:ClientTLS:SAML
-
urn:liberty:security:2003-08:ClientTLS:X509
-
urn:liberty:security:2003-08:ClientTLS:null
-
urn:liberty:security:2003-08:TLS:SAML
-
urn:liberty:security:2003-08:TLS:X509
-
urn:liberty:security:2003-08:TLS:null
-
urn:liberty:security:2003-08:null:SAML
-
urn:liberty:security:2003-08:null:X509
-
urn:liberty:security:2003-08:null:null
-
urn:liberty:security:2004-04:ClientTLS:Bearer
-
urn:liberty:security:2004-04:TLS:Bearer
-
urn:liberty:security:2004-04:null:Bearer
-
urn:liberty:security:2005-02:ClientTLS:Bearer
-
urn:liberty:security:2005-02:ClientTLS:SAML
-
urn:liberty:security:2005-02:ClientTLS:X509
-
urn:liberty:security:2005-02:TLS:Bearer
-
urn:liberty:security:2005-02:TLS:SAML
-
urn:liberty:security:2005-02:TLS:X509
-
urn:liberty:security:2005-02:null:Bearer
-
urn:liberty:security:2005-02:null:SAML
-
urn:liberty:security:2005-02:null:X509
Note –
For more complete information about authentication mechanisms and their level of security, see the Liberty ID-WSF Security Mechanisms specification.
SOAP Binding Service Package
The Access Manager SOAP Binding Service includes a Java package named com.sun.identity.liberty.ws.soapbinding. This package provides classes to construct SOAP requests and responses and to change the contact point for the SOAP binding. The following table describes some of the available classes. For more detailed information, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.
Table 9–1 SOAP Binding Service API|
Class |
Description |
|---|---|
|
Client |
Provides a method with which a WSC can send a request to a WSP using a SOAP connection. It also returns the response. |
|
ConsentHeader |
Represents the SOAP element named Consent. |
|
CorrelationHeader |
Represents the SOAP element named Correlation. By default, CorrelationHeader will always be signed. |
|
ProcessingContextHeader |
Represents the SOAP element named ProcessingContext. |
|
ProviderHeader |
Represents the SOAP element named Provider. |
|
RequestHandler |
Defines an interface that needs to be implemented on the server side by each web service in order to receive a request from a WSC and generate a response. After implementing the class, it must be registered in the SOAP Binding Service so the SOAP framework knows where to forward incoming requests. |
|
Message |
Represents a SOAP message and is used by both the web service client and server to construct SOAP requests and responses. Each SOAP message has multiple headers and bodies. It may contain a certificate for client authentication, the IP address of a remote endpoint, and a SAML assertion used for signing. |
|
ServiceInstanceUpdateHeader |
Allows a service to change the endpoint on which requesters will contact it. |
|
ServiceInstanceUpdateHeader.Credential |
Allows a service to use a different security mechanism and credentials to access the requested resource. |
|
SOAPFault |
Represents the SOAP element named SOAP Fault. |
|
SOAPFaultDetail |
Represents the SOAP element named Detail, a child element of SOAP Fault. |
|
UsageDirectiveHeader |
Defines the SOAP element named UsageDirective. |
See Appendix A, Liberty-based and SAML Samples for sample code and files to help you understand the implementation of the Liberty Alliance Project specifications.
See PAOS Binding for information on this reverse HTTP binding for SOAP.
- © 2010, Oracle Corporation and/or its affiliates