test

Sun OpenSSO Enterprise 8.0 Developer's Guide

Discovery Service

OpenSSO Enterprise contains a Discovery Service defined by the Liberty Alliance Project specifications. 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. The following sections contain more information.

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.

Note –

For information regarding the deployment of the Client SDK, see Chapter 14, Using the Client SDK.

ProcedureTo Configure the Discovery Service to Generate Security Tokens

  1. Generate the keystore and certificate aliases for the machines that are hosting the Discovery Service, the WSP and the WSC.

    OpenSSO Enterprise uses a Java keystore for storing the public and private keys so, if this is a new deployment, you might need to generate one 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 key-related properties for the appropriate deployed instances of OpenSSO Enterprise.

    Note –

    The same property might have already been edited depending on the deployment scenario.

    1. For the web services provider and web services client deployed on OpenSSO Enterprise:

      1. Login to the OpenSSO Enterprise console.

      2. Click the Configuration tab.

      3. Click the Global tab.

      4. Click the Liberty ID-WSF Security Service link.

        The Liberty ID-WSF Security Service page is displayed.

      5. Enter test as the value for the following attributes and click Save.

        • Default WSC Certificate alias

        • Trusted Authority signing certificate alias

        • Trusted CA signing certificate aliases

        Note –

        test is the default self-signed certificate shipped with OpenSSO Enterprise. Use your own key and CA name for your customized deployment. If you want to use a different keystore location, under the Configuration tab click Servers and Sites. Click the link of the appropriate server instance. Under the Security tab click Inheritance Settings and do the following:

        • Uncheck the Keystore File box.

        • Optionally, uncheck the Private Key Password File box and the Keystore Password File box.

        Click Save and Back to Server Profile. Click the Keystore link and enter the location of the Keystore File. (If you change the password for the Private Key or Keystore, you need to encode the new password using the ampassword command or encode.jsp before putting it into the corresponding password file.)

      6. Log out of the console and restart the instance to allow the changes to take effect.

    2. For the web services provider and web services client deployed on the same machine as the OpenSSO Enterprise Client SDK update the values of the following key-related properties in the AMConfig.properties:

      • 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. Configure each identity provider and service provider as an entity using the Federation module.

    This entails configuring each provider as an entity in a circle of trust.

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

    See Part II, Federation, Web Services, and SAML Administration, in Sun OpenSSO Enterprise 8.0 Administration Guide.

  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 OpenSSO Enterprise 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 to the Entity ID of the identity provider.

  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 OpenSSO Enterprise 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 to the Entity ID of the identity provider.

  7. Register a resource offering for the WSP using either of the following methods.

    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 Packages

OpenSSO Enterprise contains several Java packages that are used by the Discovery Service. They include:

Note –

Additional information is in the Sun OpenSSO Enterprise 8.0 Java API Reference.

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 Sun OpenSSO Enterprise 8.0 Java API Reference.

Table 9–5 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 complies 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 in Sun OpenSSO Enterprise 8.0 Administration Guide. The default implementations of this interface are described in the following table.

Table 9–6 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 OpenSSO Enterprise Policy Service for creating and applying policy definitions. Policy definitions for the Discovery Service are configured using the OpenSSO Enterprise 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 OpenSSO Enterprise 8.0 Administration Guide.

ProcedureTo Configure Discovery Service Policy Definitions

  1. In the OpenSSO Enterprise 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 OpenSSO Enterprise. For more information, see XXXXXCommon Service Interfaces and the Java API Reference in //OpenSSO-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 OpenSSO Enterprise 8.0 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. OpenSSO Enterprise 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 XXXXXClasses For ResourceIDMapper Plug-in attribute.

Note –

The com.sun.identity.liberty.ws.interfaces.ResourceIDMapper interface is common to all identity services in OpenSSO Enterprise not only the Discovery Service. For more information, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

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 OpenSSO Enterprise client API to access the service. For example, the public Discovery Service client, com.sun.identity.liberty.ws.disco.DiscoveryClient uses this URL to query and modify the resource offerings of an identity.