test

Sun Java System Access Manager 7.1 Federation and SAML Administration 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.

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

Illustration depicting the architecture of the Discovery Service.

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

Process of the Discovery Service

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

    1. Within a browser, the user types the URL for 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 are verified, the user is authenticated.

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

  2. After authentication, the user now requests access to services hosted by another service provider in the authentication domain.

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

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

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

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

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

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:

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.

ProcedureTo Store a Resource Offering as a User Attribute

  1. In the Access Manager Console, click the Access Control tab.

  2. Select the name of the realm that contains the user profile you want to modify.

  3. Select Subjects to access user information.

  4. Select the name of the user profile that you want to modify.

  5. Select Services to access the user's services.

  6. Click Add to configure the Discovery Service for this user.

  7. Select Discovery Service and click Next.

    The Discovery Service is added to the user's services.

  8. Select General to access the user's User Discovery Resource Offering attribute.

  9. Click Edit.

    A User Discovery Resource Offering window opens.

  10. Click Add in the User Discovery Resource Offering window.

  11. (Optional) Type a value for the Resource ID Attribute.

    This field defines an identifier for the resource offering.

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

  13. (Optional) Enter a description of the resource offering in the Description field.

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

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

  16. Click Add Description to define the Service Description.

    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.

      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.

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

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

    4. Click OK to complete the configuration.

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

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

  19. Click OK.

  20. Click Close to close the User Discovery Resource Offering window.

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

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

  1. In the Access Manager Console, click the Access Control tab.

  2. Select the name of the realm you want to modify.

  3. Select Services to access the realm's services.

  4. Click Add to add the Discovery Service to the realm.

    A list of available services is displayed.

  5. Select Discovery Service and click Next to add the service.

    A list of added services is displayed including the Discovery Service.

  6. Select Subjects to access user information.

  7. Select the name of the user you want to modify.

  8. Select Services to add the Discovery Service to the user.

  9. Click Add to add the Discovery Service to the user.

    A list of available services is displayed.

  10. Select Discovery Service and click Next to add the service.

    A list of added services is displayed including the Discovery Service.

  11. Using the path displayed on top of the Access Manager Console, click the name of the realm.

  12. Click Services to access the realm's services.

  13. Click Add.

  14. Select Discovery Service and click Next to add the service.

  15. Click Discovery Service to add a resource offering to the service.

  16. Click Add to add a resource offering.

  17. (Optional) Enter a description of the resource offering in the Description field.

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

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

  20. Click Add Description to define the Service Description.

    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.

      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.

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

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

    4. Click OK to complete the configuration.

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

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

  23. Click OK.

  24. Click Close to close the Discovery Resource Offering window.

  25. Click Save to save the configuration.

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

  1. In the Access Manager Console, click the Access Control tab.

  2. Select the name of the realm you want to modify.

  3. Select Subjects to access the realm's identity information.

  4. Select Role to access the realm's role information.

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

  6. Under Services, click Add to add the Discovery Service to the role.

    A list of available services is displayed.

  7. Select Discovery Service and click Next to add the service.

    A list of added services is displayed including the Discovery Service.

  8. Click Discovery Service to add a resource offering to the service.

  9. Click Add.

  10. (Optional) Enter a description of the resource offering in the Description field.

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

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

  13. Click Add Description to define the Service Description.

    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.

      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.

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

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

    4. Click OK to complete the configuration.

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

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

  16. Click OK.

  17. Click Close to close the Discovery Resource Offering window.

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

ProcedureTo Store a Resource Offering for Discovery Service Bootstrapping

  1. In the Access Manager Console, select the Web Services tab.

  2. Under Web Services, click the Discovery Service tab.

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

  4. (Optional) Type a description of the resource offering.

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

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

  7. Click Add Description to define a security mechanism ID.

    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.

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

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

    4. Click OK to save the configuration.

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

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

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

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

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

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

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

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

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

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

  4. Establish provider trust between the entities by creating an authentication domain using the Access Manager Federation module.

    See Authentication Domains.

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

    1. Click the Web Services tab from the Access Manager Console.

    2. Click the Discovery Service tab under Web Services.

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

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

    1. Click the Web Services tab from the Access Manager Console.

    2. Click the Liberty Personal Profile Service tab under Web Services.

    3. Change the default value of the Provider ID from protocol://host:port/deployuri/Liberty/idpp.

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

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.

ProcedureTo Configure Discovery Service Policy Definitions

  1. In the Access Manager Console, click the Access Control tab.

  2. Select the name of the realm in which the policy definitions will be configured.

  3. Select Policies to access policy configurations.

  4. Click New Policy to add a new policy definition.

  5. Type a name for the policy.

  6. (Optional) Enter a description for the policy.

  7. (Optional) Select the check box next to Active.

  8. Click New to add rules to the policy definition.

  9. Select Discovery Service for the rule type and click Next.

  10. Type a name for the rule.

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

  12. Select an action and appropriate value for the rule.

    Discovery Service policies can only look up or update data.

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

  14. Click New to add subjects to the policy definition.

  15. Select the subject type and click Next.

  16. Type a name for the group of subjects.

  17. (Optional) Click the check box if this is an exclusive group.

  18. Select the users and click to add them to the group.

  19. Click Finish to return to the policy definition screen.

  20. Click New to add conditions to the policy definition.

  21. Select the condition type and click Next.

  22. Type values for the displayed attributes.

    For more information, see the Sun Java System Access Manager 7.1 Administration Guide.

  23. Click Finish to return to the policy definition screen.

  24. Click New to add response providers to the policy definition.

  25. Type a name for the response provider.

  26. (Optional) Add values for the StaticAttribute.

  27. (Optional) Add values for the DynamicAttribute.

  28. Click Finish to return to the policy definition screen.

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

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.