Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java Systems Access Manager 6 2005Q1 Federation Management Guide 

Chapter 6  
Discovery Service

The Sun Java™ System Access Manager contains an implementation of the Discovery Service Specification from the Liberty Alliance Project. The Discovery Service instance 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 contains the following topics:

Overview

The initial step in accessing identity data is to determine where the information is located. (For example, which identity service holds the principal’s credit card information, or which server stores the principal’s calendar service.) Typically, there are one or more services on a network that allow other entities to perform an action on identity data. Because clients are not expected to keep track of these services or to know which can be trusted, they require a discovery service. The Liberty ID-WSF Discovery Service Specification (part of the Liberty Identity Web Services Framework) defines the framework that enables a client to locate the appropriate Web service for retrieving, updating, or modifying a specific piece of identity data.

Note

The Discovery Service Specification can be found on the Liberty Alliance Project Web site at http://www.projectliberty.org/specs/liberty-idwsf-disco-svc-v1.1.pdf.

A discovery service is essentially a Web service interface for discovery resources. A discovery resource is a registry of resource offerings. A resource offering defines an association between a piece of identity data and the service instance that provides access to that data. A resource identifier is a unique resource identifier (URI) registered with the discovery service that points to a particular discovery resource.

Note

A discoverable service is assigned a service type URI in the specification that defines it. This URI points to a Web Services Description Language (WSDL) file that describes the service’s data, the operations that can be perfomed on it, and a protocol detailing how to send it. The discoverable service specification itself adds the available ways the data can be exchanged.

When a client sends a request for some type of data, it includes a resource identifier that the discovery service uses to locate the Web services provider (WSP) for the requested attributes. The discovery service returns a resource offering that contains the information necessary to locate the data.

Tip

Because a provider hosting the Discovery Service may also be fulfilling other roles for an identity (such as a Policy Decision Point or an Authentication Authority), a query response also functions as a security token service, by providing a requester with the means of obtaining security tokens that can be used to invoke service instances returned.

Discovery Entries

One user account has one discovery resource. This discovery resource though can include zero or more resource offerings. Storing resource offerings within a user profile supports both entry lookups and updates. Another option is to store discovery entries within a service and assign that service to an organization or a roll. This scenario only supports entry lookups. For more information on discovery entries, see Discovery Entries and Resource Offerings.

XML Service Files

The Discovery Service is defined using the XML service file amDisco.xml. amDisco.xml 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

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).

A second XML file, amDisco_add.xml (found in /AccessManager_base/SUNWam/upgrade/services50_sunIdentityServerDiscoveryService/10_20/data), is used for upgrading Identity Server 6.2 to Access Manager 6.3. It lists the changes to the amDisco.xml file since 6.2.

Note

More information on upgading and migration can be found in the Java Enterprise System 2005Q1 Upgrade and Migration Guide located at (http://docs.sun.com/doc/817-7645).

Application Programming Interfaces

Access Manager contains several Java packages that are used by the Discovery Service. They include:

Additional information on these interfaces can be found in Discovery Service Interfaces and in the Javadocs.

com.sun.identity.liberty.ws.disco

The com.sun.identity.liberty.ws.disco package includes a client application programming interface (API) that provides interfaces to communicate with the Discovery Service.

com.sun.identity.liberty.ws.disco.plugins

The com.sun.identity.liberty.ws.disco.plugins package includes an interface that can be used to develop plugins.

com.sun.identity.liberty.ws.interfaces

The com.sun.identity.liberty.ws.interfaces package includes interfaces that can be used to implement functionality common to all Liberty-enabled identity services in Sun Java System Access Manager. Several implementations of these interfaces have been developed for the Discovery Service.

Discovery Service Architecture

The Access Manager Discovery Service includes Java and Web services-based interfaces. Java applications use the client API (discussed in Client APIs) to form requests sent to the Discovery Service and to parse the responses received back from it. Requests are received by the Access Manager SOAP receiver which constructs a SOAP message incorporating the client request.

Note

The Access Manager 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. Information on the SOAP Binding Service can be found in Chapter 7, “SOAP Binding Service.”

The SOAP message is then sent on to the Discovery Service which parses a discovery resource identifier from it. This identifier is used to find the matching user DN which is then used to process the request. 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. Figure 6-1 details this architecture.

Figure 6-1  Discovery Service Architecture

Image illustrating the implementation of the Discovery Service within Access Manager

Discovery Service Process

Figure 6-2 provides a high-level overview of the interaction between parties in a Liberty-enabled Web services environment using the Discovery Service.

Note

In Figure 6-2, the identity provider hosts the Discovery Service.

Figure 6-2  Liberty-enabled Discovery Service Process

Overview of the Discovery Service process flow between parties in a Liberty web services environment.

The following steps detail the process illustrated in Figure 6-2.

  1. The user logs onto a Liberty-enabled identity provider, is authenticated, and completes the introduction process, enabling single sign-on with other members of the authentication domain. More specifically:
    1. The user points their browser to a Liberty-enabled service provider.
    2. The service provider collects the user’s credentials and redirects the information to the identity provider for authentication.
    3. If the credentials pass muster, the user is authenticated.
    4. Assuming the identity provider is the center of an authentication domain, it will notify authenticated principals that they have the option to federate any local identities created with member organizations. The principal would then accept or decline this invitation to federate. By accepting the invitation, the principal will be introduced to the option of federation everytime they log on to a member organization’s Web site. If they accept this federation option, single sign-on is enabled.
  2. After authentication, the user now requests access to services hosted by another service provider in the authentication domain.

    3. Single sign-on authentication in this step requires contacting the user’s Personal Profile service via information from the Discovery Service.

  3. The service provider sends a lookup query to the Discovery Service.

    4. Information used by any client to contact Discovery Service is culled from the authentication statement returned in Step 1.

  4. The Discovery Service returns a discovery lookup response to the service provider.

    5. The lookup response contains the resource offering (defining an association between a piece of identity data and the service instance that provides access to it) for the user’s Personal Profile Service.

  5. The service provider then sends a query (using the Data Services Template Specification) to the Personal Profile Service instance.

    6. The required authentication mechanism specified in the Personal Profile Service resource offering must be followed.

  6. The Personal Profile Service instance returns a Data Services Template response after collecting all required data.

    7. The Personal Profile Service authenticates and validates authorization or policy, or both, for the requested user and service provider. If user interaction is required for some attributes, the Interaction Service will be invoked to query the user for consents or for attribute values.

  7. The service provider processes the Personal Profile Service response, and renders HTML pages based on the original request and user authorization.

    8. Users’ actual account information is not exchanged during federation. Thus, the identifier displayed on each provider site will be based on the 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:

Provider ID

This attribute takes as a value a URI that points to the Discovery Service. The value is written in the format:

http://host:port/amserver/Liberty/disco

Supported Authentication Mechanisms

This attribute specifies the authentication methods supported by the Discovery Service. By default, all available methods are selected. If an authentication method is not selected, and a Web services consumer (WSC) sends a request using that method, the request is rejected.

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. Table 6-1 details the available options.

Table 6-1  Policy-related Directives 

Directive

Purpose

AuthenticateRequester

The Discovery Service should include a SAML assertion (containing an AuthenticationStatement) in its 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 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.

Caution

The AuthorizeRequestor and EncryptResourceID directives can not be used together.

Enable Policy Evaluation for DiscoveryLookup

If selected, the service will perform a policy evaluation for the DiscoveryLookup operation. By default, the option is not selected.

Enable Policy Evaluation for DiscoveryUpdate

If selected, the service will perform a policy evaluation for the DiscoveryUpdate operation. By default, this option is not selected.

Authorizer Plugin Class

The value of this attribute is the name and path to the plugin class that implements the com.sun.identity.liberty.ws.interfaces.Authorizer interface used for policy evaluation of a WSC.

Entry Handler Plugin Class

The value of this attribute is the name and path to the plugin class that implements the DiscoEntryHandler interface used to set or retrieve a principal’s discovery entries. A default implementation is provided for the Access Manager Discovery Service. 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.

Classes For ResourceIDMapper Plugin

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:

Different implementations may be developed with the implementing class and added as a value of this attribute by clicking Add and using the following format:

providerid=providerID|class_name_and_path

The value of providerid is a key/value pair separated by a pipe (“|”).

Authenticate Response Message

If selected, the service will authenticate the response message. By default, the option is not selected.

Generate SessionContextStatement for Bootstrapping

If selected, the specifies whether to generate a SessionContextStatement for bootstrapping. SessionConxtext in the SessionContextStatement is needed by the Discovery Service to support the AuthenicateSessionContext directive. By default, this option is not selected.

Encrypt NameIdentifier in Session Context for Bootstrapping

If selected, the service will encrypt the name identifier in a SessionContextStatement. By default, the option is not selected.

Use Implied Resource; don't generate ResourceID for Bootstrapping

If selected, the service will not generate a resource identifier for bootstrapping. By default, the option is not selected.

Resource Offerings for Bootstrapping Resources

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; by default, this offering contains information regarding the Discovery Service. For more information defining on resource offerings, see Discovery Entries and Resource Offerings.

Caution

The value of the Resource Offerings for Bootstrapping Resources attribute is a default value configured during installation of Access Manager. If you wish to define a new resource offering, click New. If you wish to edit an existing resource offering, click Edit.

Discovery Entries and Resource Offerings

In Access Manager, a discovery entry can be stored as a user attribute or as a dynamic attribute. When storing a discovery entry as a user attribute, one user account has one discovery resource which can include zero or more resource offerings. Storing resource offerings within a user profile supports both entry lookups and updates. When storing a discovery entry as a dynamic attribute, the entry can be assigned to an organization or a role. This scenario only supports entry lookups. More information can be found in:

Storing Discovery Entries as User Attributes

Discovery entries can be stored as a user attribute under a user’s distinguished name (DN) using the Lightweight Directory Access Protocol (LDAP). Storing resource offerings within a user profile supports both entry lookups and updates. The following procedure details how to access and create a user’s resource offerings.

  1. Choose Users from the View menu in the Navigation pane of the Identity Management module.
  2. Click on the Properties arrow next to the user for whom you wish to create (or modify) a resource offering.
  3. Choose Resource Offering from the View menu in the Data pane.
  4. Click New to access the resource offering attributes.
  5. Enter a value for the Resource ID Attribute.

    6. This field defines an optional identifier for the resource offering.

  6. Enter the Resource ID Value.

    7. This required field defines the resource identifier. Resource identifiers are URIs registered with the Discovery Service that point to a particular discovery resource. 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 in circumstances where there is only one resource that 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.

  7. Enter a description of the resource offering in the Abstract field.

    8. This field is optional.

  8. Enter a URI for the value of the Service Type attribute.

    9. 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:id-sis-pp:2003-08

  9. Enter a URI for the value of the Provider ID attribute.

    10. 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://profile-provider.com

  10. Click New to define the Service Description.

    11. For each resource offering, at least one service description must be created.

    1. Select the values for the Security Mechanism ID attribute to define how a Web service client can authenticate to a Web service provider.

      2. 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.

    2. Define a value for the Conrete Service Description attributes by selecting either the Brief SoapHttp Description radio button or the WSDL Reference radio button.

      3. To configure Brief SoapHttp Description (selected by default):

      1. Select Brief SoapHttp Description to provide the information necessary to invoke basic SOAP-over-HTTP-based service instances without using WSDL.
      2. Enter a value for the SOAP-over-HTTP end point in the End Point attribute field.

        3. This field contains the URI of the SOAP-over-HTTP endpoint. The URI scheme must be HTTP or HTTPS as in:

        https://soap.profile-provider.com/soap

      3. Enter a value for the SOAP action in the SOAP Action attribute field.

        4. This field contains the equivalent of the wsdlsoap:soapAction attribute of the wsdlsoap:operation element in the service’s concrete WSDL-based description.

        To configure WSDL Reference:

      4. Select WSDL Reference to in order to reference a concrete WSDL service instance file.
      5. Enter a value for the Required Field WSDL URI attribute.

        6. This field contains the URI of the WSDL document.

      6. Enter a value for the Required Field Service Namespace attribute.

        7. This field references a wsdl:service element with the WSDL resource, such that ServiceNameRef is equal to the wsdl:name attribute of the proper wsdl:service element.

      7. Enter a value for the Service Local Part attribute.

        8. This field provides the local portion of the qualified name of the service namespace URI.

        Note

        WSDL Reference is not currently supported in the client.

  11. Add a URI to specify any options for the resource offering.

    12. This field lists the options available for the resource offering. Options provide hints to a potential requestor concerning the availability of certain data or operations to a particular offering. The set of possible URIs are defined by the service type and not the discovery service. If no option is specified, the service instance does not advertise any available options.

    Note

    The Liberty ID-SIS Personal Profile Service Specification standardizes a set of options. This specification can be found at http://www.projectliberty.org/specs/liberty-idsis-pp-v1.0.pdf.

  12. Select a directive for the resource offering.

    13. Directives are special entries defined in SOAP headers that can be used to enforce policy-related decisions. You can choose from the following:

    1. GenerateBearerToken. This directive specifies that a bearer token be generated.
    2. AuthenticateRequester. This directive must be used with any service description that use SAML for message authentication.
    3. EncryptResourceID. This directive specifies that the Discovery Service encrypt the resource ID.
    4. AuthenticateSessionContext. This directive is specified when a Discovery Service provider includes a SAML assertion containing a SessionContextStatement in any future QueryResponse messages.
    5. AuthorizeRequester. This directive is specified when a Discovery Service provider wants to include a SAML assertion containing a ResourceAccessStatement in any future QueryResponse messages.

      6. Note

      If you wish to associate a directive with one or more service descriptions, select the checkbox in front of that Description ID. If no service descriptions are selected, the directive is applied to all description elements in the resource offering.

  13. Click Save.

Storing Discovery Entries 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 an organization. The role or organization can then be assigned to an identity-related object making the entry available to all users within the object. To create a discovery entry as a dynamic attribute, the Discovery Service must first be added and a template for the service created.

Note

For more information on adding a service and creating a template, see the Sun Java System Access Manager Administration Guide (http://docs.sun.com/doc/817-7647).

After a service has been added and a template created, the procedure is the same as that detailed in Storing Discovery Entries as User Attributes except for the following:

  1. Select the Identity Management module in the Header frame.
  2. Choose Roles from the View menu in the Navigation pane.
  3. Click on the Properties arrow next to the role to which you want to add the discovery entry.
  4. Choose Services from the View menu in the Data pane.
  5. Click Edit next to the Discovery Service under the heading Service Configuration for this Role.
  6. Select a priority level to resolve conflicting resource offerings.

    7. The conflict resolution level sets a priority level for roles that may contain the same user. For example, if User1 is assigned to both Role1 and Role2, you can define a higher priority level for Role1 so the resource offering from Role1 will be dominant.

  7. Enter a description of the resource offering in the Abstract field.

    8. This field is optional.

  8. Enter a URI for the value of the Service Type attribute.

    9. 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:id-sis-pp:2003-08

  9. Enter a URI for the value of the Provider ID attribute.

    10. 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://profile-provider.com

  10. Click New to define the Service Description.

    11. For each resource offering, at least one service description must be created.

    1. Select the values for the Security Mechanism ID attribute to define how a Web service client can authenticate to a Web service provider.

      2. 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.

    2. Define a value for the Conrete Service Description attributes by selecting either the Brief SoapHttp Description radio button or the WSDL Reference radio button.

      3. To configure Brief SoapHttp Description (selected by default):

      1. Select Brief SoapHttp Description to provide the information necessary to invoke basic SOAP-over-HTTP-based service instances without using WSDL.
      2. Enter a value for the SOAP-over-HTTP end point in the End Point attribute field.

        3. This field contains the URI of the SOAP-over-HTTP endpoint. The URI scheme must be HTTP or HTTPS as in:

        https://soap.profile-provider.com/soap

      3. Enter a value for the SOAP action in the SOAP Action attribute field.

        4. This field contains the equivalent of the wsdlsoap:soapAction attribute of the wsdlsoap:operation element in the service’s concrete WSDL-based description.

        To configure WSDL Reference:

      4. Select WSDL Reference to in order to reference a concrete WSDL service instance file.
      5. Enter a value for the Required Field WSDL URI attribute.

        6. This field contains the URI of the WSDL document.

      6. Enter a value for the Required Field Service Namespace attribute.

        7. This field references a wsdl:service element with the WSDL resource, such that ServiceNameRef is equal to the wsdl:name attribute of the proper wsdl:service element.

      7. Enter a value for the Service Local Part attribute.

        8. This field provides the local portion of the qualified name of the service namespace URI.

        Note

        WSDL Reference is not currently supported in the client.

  11. Add a URI to specify any options for the resource offering.

    12. This field lists the options available for the resource offering. Options provide hints to a potential requestor concerning the availability of certain data or operations to a particular offering. The set of possible URIs are defined by the service type and not the discovery service. If no option is specified, the service instance does not advertise any available options.

    Note

    The Liberty ID-SIS Personal Profile Service Specification standardizes a set of possible option values. This specification can be found at http://www.projectliberty.org/specs/liberty-idsis-pp-v1.0.pdf.

  12. Select a directive for the resource offering.

    13. You can choose from the following:

    1. GenerateBearerToken. This directive specifies that a bearer token be generated.
    2. AuthenticateRequester. This directive must be used with any service description that use SAML for message authentication.
    3. EncryptResourceID. This directive specifies that the Discovery Service encrypt the resource ID.
    4. AuthenticateSessionContext. This directive is specified when a Discovery Service provider includes a SAML assertion containing a SessionContextStatement in any future QueryResponse messages.
    5. AuthorizeRequester. This directive is specified when a Discovery Service provider wants to include a SAML assertion containing a ResourceAccessStatement in any future QueryResponse messages.
  13. Click Save.

    14. Caution

    Unlike storing a discovery entry as a user attribute, this scenario only supports entry lookups, not updates.

Storing Discovery Entries for Bootstrapping

When a WSC contacts the Discovery Service for a resource offering, the WSC first needs to find the Discovery Service itself. Thus, an initial resource offering for locating the Discovery Service is sent back to the WSC in a single sign-on assertion. The following procedure details how to configure a global attribute for bootstrapping the Discovery Service itself.

  1. Select the Service Management module in the Header frame.
  2. Click on the Properties arrow next to the Discovery Service in the Navigation pane.
  3. Choose New under Resource Offerings for Bootstrapping Resources.

    4. 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.

  4. Enter a description of the resource offering in the Abstract field.

    5. This field is optional.

  5. Enter a URI for the value of the Service Type attribute.

    6. 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

  6. Enter a URI for the value of the Provider ID attribute.

    7. 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

  7. Click New to define the Service Description.

    8. For each resource offering, at least one service description must be created.

    1. Select the values for the Security Mechanism ID attribute to define how a Web service client can authenticate to a Web service provider.

      2. 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.

    2. Define a value for the Conrete Service Description attributes by selecting either the Brief SoapHttp Description radio button or the WSDL Reference radio button.

      3. To configure Brief SoapHttp Description (selected by default):

      1. Select Brief SoapHttp Description to provide the information necessary to invoke basic SOAP-over-HTTP-based service instances without using WSDL.
      2. Enter a value for the SOAP-over-HTTP end point in the End Point attribute field.

        3. This field contains the URI of the SOAP-over-HTTP endpoint. The URI scheme must be HTTP or HTTPS as in:

        https://soap.profile-provider.com/soap

      3. Enter a value for the SOAP action in the SOAP Action attribute field.

        4. This field contains the equivalent of the wsdlsoap:soapAction attribute of the wsdlsoap:operation element in the service’s concrete WSDL-based description.

        To configure WSDL Reference:

      4. Select WSDL Reference to in order to reference a concrete WSDL service instance file.
      5. Enter a value for the Required Field WSDL URI attribute.

        6. This field contains the URI of the WSDL document.

      6. Enter a value for the Required Field Service Namespace attribute.

        7. This field references a wsdl:service element with the WSDL resource, such that ServiceNameRef is equal to the wsdl:name attribute of the proper wsdl:service element.

      7. Enter a value for the Service Local Part attribute.

        8. This field provides the local portion of the qualified name of the service namespace URI.

        Note

        WSDL Reference is not currently supported in the client.

  8. Add a URI to specify any options for the resource offering.

    9. This field lists the options available for the resource offering. Options provide hints to a potential requestor concerning the availability of certain data or operations to a particular offering. The set of possible URIs are defined by the service type and not the discovery service. If no option is specified, the service instance does not advertise any available options.

    Note

    The Liberty ID-SIS Personal Profile Service Specification standardizes a set of possible option values. This specification can be found at http://www.projectliberty.org/specs/liberty-idsis-pp-v1.0.pdf.

  9. Select a directive for the resource offering.

    10. You can choose from the following:

    1. GenerateBearerToken. This directive specifies that a bearer token be generated.
    2. AuthenticateRequester. This directive must be used with any service description that use SAML for message authentication.
    3. EncryptResourceID. This directive specifies that the Discovery Service encrypt the resource ID.
    4. AuthenticateSessionContext. This directive is specified when a Discovery Service provider includes a SAML assertion containing a SessionContextStatement in any future QueryResponse messages.
    5. AuthorizeRequester. This directive is specified when a Discovery Service provider wants to include a SAML assertion containing a ResourceAccessStatement in any future QueryResponse messages.
  10. Click Save.

Discovery Service Interfaces

By default, a discovery service is implemented as one of the identity web services in Access Manager. The Discovery Service provides the following implementations and interfaces:

DefaultDiscoAuthorizer Implementation

The com.sun.identity.liberty.ws.interfaces.Authorizer is an interface used to enable an identity service to check the authorization of a WSC. The DefaultDiscoAuthorizer class is the default implementation of this interface. It uses the Access Manager Policy Service for creating and applying policy definitions.

Note

The Policy Service looks for an SSOToken defined for Authenticated Users or Web Service Clients. More information on this, and the Policy Service in general, can be found in the Sun Java System Identity Server 2004Q2 Administration Guide (http://docs.sun.com/doc/817-7647).

Policy definitions for the Discovery Service are configured using the Access Manager console. The procedure is as follows:

  1. Choose Services from the View menu in the Navigation pane of the Identity Management module.

    2. The Discovery Service must be added to the organization for which the Discovery Service policy is being created. Proceed to Step 5 if this has already been done.

  2. Click Add to add a new service to the organization.
  3. Choose Discovery Service from the list of services in the Data Pane.
  4. Click OK.
  5. Choose Policies from the View menu in the Navigation pane of the Identity Management module.
  6. Click New to create a new policy.
  7. Select the type of policy.
  8. Enter a name for the policy.
  9. Click OK.
  10. Choose Rules from the View menu in the Data pane for the created policy.
  11. Click New.
  12. Select Discovery Service for the rule type and click Next.
  13. Enter a name for the rule.
  14. Enter a resource on which the rule acts.

    15. The Resource Name field uses the form:

    ServiceType + RESOURCE_SEPARATOR + ProviderID

    For example:

    urn:liberty:id-sis-pp:2003-08;http://example.com

  15. Select an action for the rule.

    16. Discovery Service policies can only look up or update data.

  16. Click Finish.

    17. Note

    The com.sun.identity.liberty.ws.interfaces.Authorizer interface can be implemented by any Web service in Access Manager. More information can be found in Common Service Interfaces of Chapter 8, "Application Programming Interfaces" and in the Access Manager Javadocs (located in /AccessManager_base/SUNWam/docs.).

Default ResourceIDMapper Implementations

The com.sun.identity.liberty.ws.interfaces.ResourceIDMapper is an interface used to map a user ID to the resource identifier associated with it. Access Manager provides two implementations of this interface.

A different implementation of the interface may be developed. The implementation class should be given to the provider that hosts the Discovery Service. The mapping between the providerID and the implementation class can be configured through the Classes For ResourceIDMapper Plugin attribute.

Note

The com.sun.identity.liberty.ws.interfaces.ResourceIDMapper interface is common to all identity services in Access Manager not only the Discovery Service. More information can be found in Common Service Interfaces of Chapter 8, "Application Programming Interfaces" and in the Access Manager Javadocs (located in /AccessManager_base/SUNWam/docs.).

DiscoEntryHandler Interface

The com.sun.identity.liberty.ws.disco.plugins.DiscoEntryHandler is an interface 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 in the Discovery Service. The default implementations of this interface are:

UserDiscoEntryHandler.     This implementation 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 Personal Profile service.

DynamicDiscoEntryHandler.     This implementation 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 Employee Profile service.

UserDynamicDiscoEntryHandler.     This implementation 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.

Client APIs

Table 6-2 summarizes the client APIs in the package com.sun.identity.liberty.ws.disco. For detailed API reference, including methods and their syntax and parameters, see the Javadocs in /AccessManager_base/SUNWam/docs.

Table 6-2  Discovery Service Client APIs  

Class Name

Description

Description

Represents a Description Type of a service instance.

Directive

Represents a discovery service DirectiveType element.

DiscoveryClient

Provides methods to send Discovery Service query and modify.

EncryptedResourceID

Represents an Encryption Resource ID element for the Discovery Service.

InsertEntry

Represents a Insert Entry for Discovery Modify request.

Modify

Represents a discovery modify request.

ModifyResponse

Represents a discovery response for modify request.

Query

Represents a discovery Query object.

QueryResponse

Represents a response for 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 via a service instance complying with one of the specified service type.

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.

Discovery Service Sample

A sample outlining the process involved in querying and modifying the Discovery Service is included with Access Manager. It is located in the AccessManager_base/SUNWam/samples/phase2/wsc directory. The sample initally details how to deploy and run a WSC. The final portion queries the Discovery Service and modifies identity data in the Liberty Personal Profile Service. More information can be found in Appendix A, "Included Samples."



Previous      Contents      Index      Next     

Part No: 817-7648.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.