|
| |
| Sun Java Systems Access Manager 6 2005Q1 Federation Management Guide | |
Chapter 5
Data ServicesThe Sun Java™ System Access Manager contains implementations of the Liberty ID-WSF Data Services Template Specification (ID-WSF-DST) in addition to instructions on how you can add your own data service to the deployment. This chapter contains the following topics:
OverviewA data service is a Web service that supports the query and modification of identity data. Identity data includes, but is not limited to, attributes that define first name, last name, home address, business address, and emergency contact. A data service allows this data to be queried or modified. A query is when a Web service consumer (WSC) requests data (in an XML format) from a user’s profile. A modify is when a WSC sends new data to update a user’s profile. The Liberty Alliance Project (LAP) has defined the Liberty ID-WSF Data Services Template Specification (ID-WSF-DST) as the standard protocol used for the query and modification of identity data profiles comprised of attributes exposed by a data service.
Data Services Template Specifications
The 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 their identity. The information may include the individual’s office location and phone number, as well as job title or department name. From the implementation point of view, all data services must be built on top of the ID-WSF-DST which provides the data model and message interfaces. Figure 5-1 illustrates how Access Manager uses the ID-WSF-DST as the framework for its data services.
Figure 5-1 Data Service Template as Building Block for Data Services
The Liberty-defined Web Services Layer uses the ID-WSF-DST (and other Web services that allow data services to be discovered and invoked) for the development of data services. Access Manager has developed both the Liberty Personal Profile Service and the Liberty Employee Profile Service on top of the Liberty-defined Web Services Layer. Additional data services can also be developed by the customer. (More information on developing other data services can be found in Data Services Template API.)
Note
The Liberty ID-WSF Data Services Template Specification can be found at http://www.projectliberty.org/specs/draft-liberty-idwsf-dst-1.0-errata-v1.0.pdf.
Liberty Personal Profile Service
The Liberty ID-SIS Personal Profile Service Specification (ID-SIS-PP) of the LAP describes a data service which provides an identity’s basic profile information (full name, contact details, financials, etc.). It 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.
XML Service File
The Access Manager Liberty Personal Profile Service is configured using the XML service file amLibertyPersonalProfile.xml. amLibertyPersonalProfile.xml defines the attributes for the Liberty Personal Profile Service which can be managed through the Access Manager console or the XML file itself.
Note
More information on XML service files can be found in the section on XML Service Files in the Sun Java System Access Manager 6 2005Q1 Developer’s Guide (http://docs.sun.com/doc/817-7649).
XSD Schema Definition
The ID-SIS-PP also defines an XML schema for use in building the service itself. This XML Schema Defintion (XSD) file can be found on the LAP Web site. Version 1.0 is also reproduced in Appendix B, "Service Schema Files."
Note
The Liberty ID-SIS Personal Profile Service Specification can be found at http://www.projectliberty.org/specs/liberty-idsis-pp-v1.0.pdf.
Liberty Employee Profile Service
The Liberty ID-SIS Employee Profile Service Specification (ID-SIS-EP) describes a data service which provides an identity’s profile information in regards to their 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.
Tip
The Liberty Employee Profile Service is not available when Access Manager is installed. It must first be deployed. Information on accessing the sample files and how to deploy them can be found in Liberty Employee Profile Service.
XML Service File
Among the files included with the sample is the XML service file amLibertyEmployeeProfile.xml. amLibertyEmployeeProfile.xml 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
More information on XML service files can be found in the section on XML Service Files in the Sun Java System Access Manager 6 2005Q1 Developer’s Guide (http://docs.sun.com/doc/817-7649).
XSD Schema Definition
The ID-SIS-EP also defines an XML schema for use in building the service itself. This XSD file can be found on the LAP Web site. Version 1.0 is also reproduced in Appendix B, "Service Schema Files."
Note
The Liberty ID-SIS Employee Profile Service Specification can be found at http://www.projectliberty.org/specs/liberty-idsis-ep-v1.0.pdf.
Data Services Template 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 ID-WSF-DST. Additional information on these interfaces can be found in Data Services Template API and in the Javadocs at /AccessManager_base/SUNWam/docs.
Liberty Personal Profile ServiceThe Liberty Personal Profile Service is a default Access Manager identity service. The Service can be queried for identity data or its attributes can be updated. In order 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.
Note
Registering a service with the Discovery Service is done by updating a resource offering for that service. For more information, see Chapter 6, "Discovery Service."
The 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 the user. The following steps detail the system process for the Liberty Personal Profile Service.
- 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 SOAP Request handler to process the request.
The PersonalProfile RequestHandler processes the request based on the request type (either query or modify) and the query expression. This might entail the authorization of a WSC using Access Manager Policy Service. It might also make use of 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 it 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). This is an XML blob 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 these values will be used while building the XML container. The Personal Profile Service then applies xpath queries on the XML blob and gives us the resultant XML data node.
- For a response to a modify request, it parses the Modifiable Select expression and updates the new data from the new data node in the request.
Liberty Personal Profile Service Attributes
The Liberty Personal Profile Service attributes are global attributes. The values of these attributes are carried across the Sun Java System Access Manager configuration and inherited by every organization.
Note
For information on the types of attributes used in Access Manager, see the Service Management chapter of the Sun Java System Access Manager 6 2005Q1 Developer’s Guide (http://docs.sun.com/doc/817-7649).
Attributes for the SOAP Binding service are defined in the amLibertyPersonalProfile.xml service file. The Liberty Personal Profile Service 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 ID.
Authorizer
Before processing a request, the Liberty Personal Profile Service will verify the authorization of the WSC making the request. There are two levels of authorization check that can be done:
Authorization occurs via 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: com.sun.identity.liberty.ws.idpp.plugin.IDPPAuthorizer. This plug-in defines four policy action values for the query and modify operations:
The resource values for the rules are similar to x-path expressions defined by the Personal Profile service. For example, a rule can be defined as follows:
Code Example 5-1 Authorization Rules
/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 also defined in the Liberty Personal Profile Service:
Attribute Mapper
This 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.
Provider ID
The value of this attribute defines the unique identifier for this instance of the Liberty Personal Profile Service. The format is:
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. You can choose from First Last, or First Middle Last.
Namespace Prefix
The value of this attribute specifies the namespace prefix 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 and is useful to distinguish metadata from different XML schema namespaces.
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 Service.
Note
The term container as described here is not related to the Access Manager identity-related object also named 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.
PPLDAP Attribute Map List
Each identity attribute defined by the Liberty Personal Profile Service has a one-to-one match to an Access Manager User service attribute. The value of this attribute is a list that specifies those mappings. For example, JobTitle=sunIdentityServerPPEmploymentIdentityJobTitle maps the Liberty JobTitle attribute to the Access Manager sunIdentityServerPPEmploymentIdentityJobTitle attribute. When adding new attributes to either side of this equation, ensure that any new attribute mappings are configured in this attribute.
Note
Attribute mappings are defined as global attributes under the name sunIdentityServerPPDSAttributeMapList in the Liberty Personal Profile Service XML service file definition. This PPLDAP Attribute Map List attribute corresponds to that sunIdentityServerPPDSAttributeMapList global attribute.
In Code Example 5-2, the Liberty Personal Profile Service informalName attribute mapping to the User service attribute uid is added to the mappings already present in the amLibertyPersonalProfile.xml.
Require Query PolicyEval
If selected, this option requires a policy evaluation to be performed for Liberty Personal Profile Service queries.
Require Modify PolicyEval
If selected, this option requires a policy evaluation to be performed for Liberty Personal Profile Service modifications.
Extension Container Attributes
The Liberty Personal Profile Service allows you to specify extension attributes that are not defined in the LAP specification. The values of this attribute specify a list of extension container attributes. All extensions should be defined as:
/PP/Extension/PPISExtension [@name='extensionattribute']
Code Example 5-3 illsutrates an extension query expression for creditcard, an extension attribute.
Code Example 5-3 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>
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 is useful to distinguish metadata from different XML schema namespaces.
Is ServiceUpdate Enabled
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.
Liberty Employee Profile ServiceThe Liberty Employee Profile Service sample provides a collection of files, located in the /AccessManager_base/SUNWam/samples/phase2/sis-ep directory, that can be used to deploy and invoke a corporate-based data service.
Note
Before implementing this example, you must have two instances of Access Manager installed, running, and Liberty-enabled. Completing the steps in sample1 of Appendix A, "Included Samples" 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 in the sample directory provides detailed steps on how to deploy and configure this sample for use as a data service. More information can be found in Appendix A, "Included Samples."
Data Services Template APIThe ID-WSF-DST specifies a base layer that can be extended by any instance of a data service. It defines how to query and modify data stored in a data service, and provides some common attributes that might be used in 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 service returns information associated with their identity. The information may include the individual’s office location and phone number, as well as other data such as job title and department name. From the implementation point of view, all identity services must be built on top of the ID-WSF-DST which provides the data model and message interfaces.
Note
Figure 5-1 illustrates how Access Manager uses the ID-WSF-DST as the framework for identity data services. The Liberty Web Services layer is the framework for creating, discovering and consuming identity data services, including a SOAP-based transport binding that allows identity services to be discovered and invoked. Other Liberty Web Services include the Discovery Service, and Interaction Service.
Access Manager contains two packages based on the ID-WSF-DST. They are:
com.sun.identity.liberty.ws.dst
Table 5-1 summarizes the Data Services Template client APIs included in the com.sun.identity.liberty.ws.dst package.
Table 5-1 Data Service Client APIs
Class Name
Description
DSTClient
Provides common functions for the Data Service Templates query and modify option.
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 for DST modify request.
DSTQuery
Represents a Data Services Template query request.
DSTQueryItem
The wrapper for one query item for Data service.
DSTQueryResponse
Represents a Data Services Template query response.
DSTUtils
Provides utility methods used by the DST layer.
For more detailed API reference information, including methods and their syntax and parameters, see the Javadocs in /AccessManager_base/SUNWam/docs.
com.sun.identity.liberty.ws.dst.service
The com.sun.identity.liberty.ws.dst.services package provides a handler class that can be used by any generic identity data service built using the Liberty Alliance ID-SIS 1.0 Specifications.
Note
The Data Services is built using the Liberty ID-SIS Personal Profile Service Specification, based on the Liberty Alliance ID-SIS 1.0 Specifications.
The DSTRequestHandler 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 reference information, see the Javadocs in /AccessManager_base/SUNWam/docs.
Note
Access Manager provides a sample which makes use of the DSTRequestHandler interface. The sis-ep sample illustrates how to implement the DSTRequestHandler and deploy a new identity data service instance. It is located in the /AccessManager_base/SUNWam/samples/phase2/sis-ep directory. sis-ep of the Appendix A, "Included Samples" further discusses this sample.
Developing A New Data ServiceIn addition to deploying an employee profile service, the Liberty Employee Profile Service sample can be used to deploy other custom data services based on the ID-WSF-DST. Sections 2 and 3 in the Readme.html provided in the /AccessManager_base/SUNWam/samples/phase2/sis-ep directory have detailed steps on how to deploy and configure data services. But, in order to use those instructions for a new data service, you need to write a new data service schema. This XSD file (as discussed in Appendix B, "Service Schema Files") defines the service’s data and data structure. Once this new XSD file is written, it can be used in place of the lib-id-sis-ep.xsd in the sample instructions to deploy your new data service.
