Sun Java System Access Manager 7 2005Q4 Federation and SAML Administration Guide

Chapter 6 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 6–1 Data Service Template as Building Block of Data Services

Illustration showing how data service template is framework
for 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 2005Q4 Administration Guide.

XSD Schema Definition

The Liberty ID-SIS-PP also defines an XML schema for use in building a personal profile service. This XML Schema Definition (XSD) file is on the Liberty Alliance Project web site. Version 1.0 is also reproduced in Appendix B, Service Schema Files.

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 2005Q4 Administration Guide.

XSD Schema Definition

The Liberty ID-SIS-EP also defines an XML schema for use in building an employee profile service. This XSD file is on the Liberty Alliance Project web site. Version 1.0 is also reproduced in Appendix B, Service Schema Files.

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 7, Discovery Service.

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 6–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 2005Q4 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 6–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>

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.

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.

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.

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 6–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 to deploy other custom data services that are 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 XML Schema Definition (XSD) document (as discussed in Appendix B, Service Schema Files) defines the service’s data and data structure. After you write a new XSD file, use it to deploy your new data service instead of the lib-id-sis-ep.xsd file.

Note –

Instructions on writing the XSD file are beyond the scope of this guide.

Chapter 6 Data Services

Data Services Overview

Liberty ID-WSF Data Services Template Specification

Figure 6–1 Data Service Template as Building Block of Data Services

Liberty Personal Profile Service

XML Service File

XSD Schema Definition

Liberty Employee Profile Service

XML Service File

XSD Schema Definition

Data Services API

Liberty Personal Profile Service

Liberty Personal Profile Service Process

Figure 6–2 Liberty Personal Profile Service Process

Liberty Personal Profile Service Attributes

ResourceID Mapper

Authorizer

Attribute Mapper

Provider ID

Name Scheme

Namespace Prefix

Supported Containers

PPLDAP Attribute Map List

Require Query PolicyEval

Require Modify PolicyEval

Extension Container Attributes

Example 6–1 Extension Query for creditcard

Extension Attributes Namespace Prefix

Is ServiceUpdate Enabled

Service Instance Update Class

Alternate Endpoint

Alternate Security Mechanisms

Liberty Employee Profile Service

Data Services Template API

com.sun.identity.liberty.ws.dst Package

com.sun.identity.liberty.ws.dst.service Package

Developing A New Data Service

Example 6–1 Extension Query for `creditcard`

`com.sun.identity.liberty.ws.dst` Package

`com.sun.identity.liberty.ws.dst.service` Package