Chapter 3 Federation Management

Chapter 3
Federation Management

Once you’ve created a Liberty web service environment, you can modify service configurations or add new services to the system. This chapter provides instructions for modifying authentication domains, entity descriptors, and resource offerings. An Employee Profile Service sample is included to illustrate how you use the Federation APIs to create a new service and enable it for federation management.

Topics in this chapter include:

Overview of Authentication Domains and Providers

Managing Authentication Domains

Managing Entity Descriptors

Managing Resource Offerings

Adding a New Liberty Web Service

Constructing a PAOS Request and Response

Overview of Authentication Domains and Providers

The Federation Management module provides an interface for creating, modifying, and deleting authentication domains, remote providers and hosted providers. The following steps demonstrate a basic Federation Management model:

Create an authentication domain.

Create one or more hosted providers that belong to the created authentication domain.

Create one or more remote providers that belong to the created authentication domain. You must also include the metadata for the remote providers.

Establish a trusted relationship between the providers. A hosted provider can choose to trust a subset of providers, either hosted or remote, that belong to the same authentication domain.

The following sections explain how to create and configure authentication domains, remote providers, and hosted providers.

Managing Authentication Domains

This section describes how to create, modify, and delete authentication domains.

To Create An Authentication Domain

Choose Authentication Domain from the View menu in the Federation Management module.

Click New in the Navigation pane.

The Create Authentication Domain is displayed in the Data pane.

In the Create Authentication Domain window, enter the name of the Authentication Domain.

Enter a value for the description of the Authentication Domain.

Enter a value for the Writer Service URL.

Writer Service URL specifies the location of the Writer service that writes the cookie from the Common Domain. For example, if example.com is the common domain, the URL could be:

http://example.com:8080/common/writer

Enter a value for the Reader Service URL.

The Reader Service URL specifies the location of the service that reads the cookie from the Common Domain. For example, if example.com is the common domain, the URL could be:

http://example.com:8080/common/transfer

Choose a status of active or inactive.

The default is active. This can be changed at any time during the life of the Authentication Domain by selecting the Properties icon. Choosing inactive disables Liberty communication within authentication domain, with respect to the current installation of Identity Server.

Click OK.

The new Authentication Domain displays in the Navigation pane.

To Modify An Authentication Domain

Click on the Properties arrow next to the Authentication Domain you wish to modify.

The properties of the Authentication Domain display in the Data pane.

Modify the properties of the Authentication Domain.

Click Save.

To Delete An Authentication Domain

Deleting an authentication domain does not delete the providers that belong to it. If providers belong to an authentication domain that has been deleted, they remain part of the authentication domain until they are explicitly removed. Additional providers can not be added to an authentication domain that has been deleted.

Choose Authentication Domains from the View menu in the Federation Management module.

All created Authentication Domains display in the Navigation pane.

Check the box next to the name of the Authentication Domain to be deleted.

Click Delete.



Note	There is no warning message when performing a delete.

Managing Entity Descriptors

This section describes how to create, modify and delete entity descriptors. There are two types of entity descriptors you can define; a container entity (which can contain identity and service provider descriptors) and affiliate entities.

Once you have created an entity descriptor (of either type), you can add information for a contact person for that entity and a description of the organization to which the person belongs. The contact person is generally responsible for technical details concerning federation within his or her organization.



Note	The contact person and organization concepts only exist within Federation Management, and have no correlation to the organization and user Identity Server object types.

Creating and Managing Providers

Creating a provider descriptor through the Identity Server console is a two-step process. First, you create an container entity. Next, you create the provider descriptor associated with that entity.

Once the provider descriptor is defined, you can modify any of the provider’s attributes by selecting Provider from the View menu located in the Navigation pane.

To Create a Container Entity

Choose Entity Descriptors from the View menu in the Federation Management module.

Click New. The Create Provider window is displayed.

Enter a value for the Entity ID.

The Entity ID should specify the URL identifier of the entity. It must be unique across all entities.

Enter a description of the entity.

Select Provider from the Type option.

Click OK.

To Create and Manage a Provider Descriptor

Choose Entity Descriptors from the View menu in the Federation Management module.

Select the Entity that will contain the provider.

Select Provider from the View menu in the Navigation pane.

Click the New Provider button to display the first page of the New Provider Wizard.

Select the provider type and enter information into the common provider attribute fields. The fields are as follows:

Provider ID. The Provider ID should specify the URL identifier of the provider. It must be unique across all remote and hosted providers.

Description. Enter a description of the provider.

Provider is of Type Identity. Decide if the provider is to be defined as an identity provider. By default, all providers are service providers. If selected, the Identity Provider option will additionally define the provider as an identity provider.

Provider is Hosted (Local). If selected, the provider is a hosted provider. By default (not selected), the provider is a remote provider.

Valid Until. This field allows you to enter the expiration date for the metadata pertaining to the provider. Use the following format:

yyyy-mm-dd hh:mm:ss.SZ

For example, 2004-12-31 12:30:00.0-0800

Cache Duration. This field defines the duration period for the metadata to be cached and uses the xs:duration format.

Protocol Support Enum. This field defines the protocol release supported by the entity. urn:liberty:iff:2003-08 refers to Identity Federation Framework (ID-FF) 1.2 and urn:liberty:iff:2002-12 refers to Federation Identity Framework (ID-FF) 1.1.

Security Key. The Security Key defines the Security Certificate alias. The certificates are stored in the JKS keystore against an alias. This alias (the Security Key) is used to fetch the required certificate.

Key Use.This field defines allowed key usage. You can choose encryption or signing.

Key Size. This field constrains the length of keys used by the consumer when interacting with another entity.

Encryption Method. This field defines the encryption preferences URI.

Server Name Identifier Mapping Binding. This field defines the SAML authority binding at the identity provider to which identifier mapping queries are sent.

Additional Meta Locations. This field specifies the location of other relevant metedata about the provider.

Click Next.

Enter the information for the communications and service provider attributes. The fields are as follows:

Communication URLs

SOAP Endpoint URL. This field specifies the location for the receiver of SOAP requests. This is used to communicate on the back-channel (non-browser communication) through SOAP.

Single Logout Service URL. The Single Logout Service URL is used by a service provider or identity provider to send and receive logout requests.

Single Logout Return URL. This specifies the URL to which logout requests are redirected after processing.

Federation Termination Service URL. This field specifies the URL to which federation termination requests are sent.

Federation Termination Return URL. This field specifies the URL to which federation termination requests are redirected after processing.

Name Registration Service URL. This field uses the Name Registration protocol that is used by a service provider to register its own Name Identifier while communicating to an identity provider. Registration occurs only after a federation session is established. This field defines the service URL used by a service provider to register a Name Identifier with an identity provider.

Name Registration Return URL. This field uses the Name Registration protocol that is used by a service provider to register its own Name Identifier while communicating to an identity provider. Registration occurs only after a federation session is established. The Name Registration Return URL is the URL to which the identity provider sends back the status of the registration.

Communication Profiles

Federation Termination Profile. You can choose SOAP or HTTP/Redirect. This field specifies if the SOAP or HTTP/Redirect profile is to be used to notify of federation termination. This can be changed at any time during the life of the provider.

Single Logout Profile. You can choose SOAP or HTTP Redirect. This field specifies if SOAP or HTTP Redirect is to be used to notify a logout event. This can be changed at any time during the life of the provider.

Name Registration Profile. You can choose SOAP or HTTP/Redirect. This field specifies if the SOAP or HTTP/Redirect profile is to be used for name registration. This can be changed at any time during the life of the provider.

Server Relationship Term Notification URL. This field defines a URI describing the profiles that the entity supports for relationship termination.

Single Sign-on/Federation Profile. This field specifies the profile used by the hosted provider for sending authentication requests. Identity Server provides the following protocols:

Browser Post - specifies a front-channel (http POST-based) protocol.

Browser Artifact - Backchannel (non-browser) SOAP-based protocol.

LECP - Liberty Enabled Client Proxy.

Assertion Consumer URL. This field defines the provider end-point to which a provider will send SAML assertions.

Assertion Consumer URL ID. This ID is required if Protocol Support Enum is urn:liberty:iff:2002-12.

Set Assertion Consumer Service URL as Default. This option sets the Assertion Consumer URL as the default.

Sign Authentication Request. This option, if enabled, specifies that the provider send signed authentication and federation requests. The identity provider will not process unsigned requests originated from the service provider.

Name Registration After Federation. If enabled, this option allows for a service provider to participate in name registration after it has been federated. Name registration is a profile by which service providers specify a principal’s name identifier that an identity provider will use when communicating to the service provider.

If the provider you are creating is a local provider, enter data for the Identity Server Configuration. If the provider is not local, skip this step. The fields are:

Provider URL. This field defines the URL of the local provider.

Alias. This field allows you to enter an alias name for the local provider.

Authentication Type. Remote/Local - This field specifies if the hosted provider should contact an identity provider for authentication upon receiving an authentication request (Remote), or if authentication should be done by the hosted provider itself (Local).

Default Authentication Context. This field specifies the authentication context to be used if the identity provider does not receive it as part of a service provider request. It also specifies the authentication context used by the service provider when an unknown user tries to access a protected resource. The default values are:

Previous-Session

Time-Sync-Token

Smartcard

MobileUnregistered

Smartcard-PKI

MobileContract

Password

Password-ProtectedTransport

MobileDigitalID

Software-PKI

Force Authentication at Identity Provider. This option indicates if the identity provider must reauthenticate (even during a live session) when an authentication request is received.

Request Identity Provider to be Passive. If selected, this option specifies that the identity provider must not interact with the principal and must interact with the user

Organization DN. This field specifies the storage location of the DN of the organization if each hosted provider chooses to manage users across different organizations leading to a hosted model.

Liberty Version URI. This field specifies the version of the Liberty specification.

Name Identifier Implementation. This field allows the option for a service provider to participate in name registration. Name registration is a profile by which service providers specify a principal’s name identifier that an identity provider will use when communicating to the service provider.

Provider Home Page URL. This field specifies the home page of the provider.

Single Sign-on Failure Redirect URL. This field specifies the home page of the provider.

Assertion Interval. This field specifies the validity interval for the assertion issued by an identity provider. A principal will remain authenticated by the identity provider until the assertion interval expires.

Cleanup Interval. This field specifies the interval of time to clear assertions that are stored in the identity provider.

Artifact Timeout. This field specifies the timeout of a identity provider for assertion artifacts.

Assertion Limit. This field specifies the number of assertions an identity provider can issue, or the number of assertions that can be stored.

Click Next.

Enter the values for the organization and contact person. For more information, see To Add a Contact Person and Organization.

Click Next.

Select the authentication domains to which the provider will belong.

Use the direction arrows to move a selected authentication domain into the Available list. Click Save. This will assign the provider to the authentication domain. A provider can belong to one or more authentication domains, however a provider without any authentication domains specified can not participate in Liberty communications. Click Save.

Click Finish.

Creating and Managing Affiliates

In the Identity Server console, you create an affiliate through the New Entity page. Once the affiliate descriptor is defined, you can modify any of the affiliate’s attributes and manage the members of the affiliation by selecting Affiliates from the View menu located in the Navigation pane.

To Create an Affiliate Entity

Choose Entity Descriptors from the View menu in the Federation Management module.

Click New.

Enter a value for the Entity ID.

The Entity ID should specify the URL identifier of the entity. It must be unique across all entities.

Enter a description of the entity.

Select Affiliate from the Type option.

Enter the Affiliate ID.

The Affiliate ID should specify the URL identifier of the affiliate. It must be unique across all entities. This field is required.

Enter the Affiliate Owner ID.

The Affiliate OwnerID is the Provider ID of the owner or parent operator of the affiliate, from which additional metadata can be received. This field is required.

Click OK.

To Manage an Affiliate Descriptor

Choose Entity Descriptors from the View menu in the Federation Management module.

Select the Entity that will contain the Affiliate.

Select Affiliates from the View menu in the Navigation pane.

Modify the affiliate attribute fields. The fields are as follows:

Valid Until. This field allows you to enter the expiration date for the metadata pertaining to the affiliate in the following format:

yyyy-mm-dd hh:mm:ss.SZ

For example, 2004-12-31 12:30:00.0-0800

Cache Duration. This field defines the duration period for the metadata to be cached and uses the xs:duration format.

Key Use.This field defines allowed key usage. You can choose encryption or signing.

Key Size. This field constrains the length of keys used by the consumer when interacting with another entity.

Encryption Method. This field defines the encryption preferences URI.

Affiliate Members. This field allows you to define one or more providers that will be members of the affiliation. The providers that are displayed are pre-defined in existing container entity descriptors.

Use the direction arrows to move a selected provider into the Available list. Click Save. This will assign the provider to the authentication domain. A provider can belong to one or more affiliates.

Click Save.

To Add a Contact Person and Organization

Choose Entity Descriptors from the View menu in the Federation Management module.

Click the Properties arrow next to the entity you wish to modify.

In the Data pane, choose General from the View menu (this is the default view).

Enter a general description of the contact person and organization.

Enter a date in the Valid Until field.

This field allows you to enter the expiration date for the metadata pertaining to the contact person. Use the following format:

yyyy-mm-dd hh:mm:ss.SZ

For example, 2004-12-31 12:30:00.0-0800

Enter a value for the Cache Duration.

This field defines the duration period for the metadata to be cached and uses the xs:duration format.

Enter the following fields in the Contact Person section:

First Name. The first name of the contact person.

Last Name. The last name of the contact person.

Type. The contact type. This can be one of the following:

Technical

Administrative

Billing

Other

Company. The contact person’s company name.

Liberty Principal Identifier. The name identifier that points to an online instance of the contact person’s personal information profile (PIP).

Email. The email address of the contact person.

Telephone.The telephone number of the contact person.

Enter the following fields in the Organization section (all fields are mandatory):

Name. The name of the entity’s organization.

Display Name. The name of the organization that is displayed to the principal.

URL. The URL of the organization. This URL is used by a user agent to direct a principal for additional information on the entity.

Click Save.

Deleting Entity Descriptors

Choose Entity Descriptors from the View menu in Federation Management.

All created entities display in the Navigation pane.

Check the boxes of the entity descriptor you want to delete.

Click Delete.



Note	There is no warning message when performing a delete.

Managing Resource Offerings

A resource offering is the association of a resource and a service instance. Typically, a single service instance will serve many resources. For example, a personal profile service provider will serve multiple profiles to a single service instance. It would be impractical to have a separate protocol endpoint for each profile.

The Discovery Service is an identity service that allows requestors to discover resource offerings. In Identity Server, resource offerings can be stored and managed in three different ways:

User Discovery Resource Offering - This is a resource offering associated with particular user. To access the User Discovery Resource offering, select Users in the Identity Management module, and choose Resource Offerings from the View menu in the Navigation pane.

Dynamic Resource Offering - This is a resource offering associated with and organization or role.

Resource Offering for Bootstrapping Mode - This resource offering is accessed through the Discovery Service in the Service Configuration module. The resource offering is sent to the service provider or web service client (WSC) in the Single Sign-on assertion during Single Sign-on.

To Define Resource Offering



Note	Steps 1 and 2 only apply to User Discover Resource Offering.

Enter a value for the Resource ID Attribute.

This field defines an identifier for a Resource ID value.

Enter the Resource ID Value.

This field defines the URI used to identify a particular resource. It must not be a relative URI and should contain a domain name which is owned by the provider that is hosting the resource. If a resource is exposed through multiple Resource Offering elements, all of those resource offering elements should have the same Resource ID value.

Example of a Resource ID value:

http://profile-provider.com/profiles/14m0B82k15csaUxs

urn:libery:isf:implied-resource



Note	The following steps apply to all resource offering mechanisms.

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

Enter the Service Instance.

This field defines an active web service at a distinct endpoint.

Enter the Service Type.

This field contains the URI that defines the type of service that service instance implements. For example:

urn:liberty:id-sis-pp:2003-08

Enter the Provider ID.

This field contains the URI of the provider of this service instance. For example:

http://profile-provider.com

Define the Service Description.

For each resource offering profile, at least one service description must be defined. The service description fields are as follows:

Security Mechanism ID.This field lists all available security mechanisms that the service instance supports, which define how a web service client authenticates to the web service provider. 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 and Move Down buttons.

Brief SoapHttp Description. If selected (default), this provides inline the information necessary to invoke basic SOAP-over-HTTP-based service instances, without using Web Service Description Language (WSDL).

End Point. This field contains the URI of the SOAP-over-HTTP endpoint. The URI scheme must be HTTP or HTTPS. For example:

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

SOAP Action. This field contains the equivalent of the wsdlsoap:soapAction attribute of the wsdlsoap:operation element in a WSDL-based description.

WSDL Reference. This field references an external concrete WSDL resource.

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

Service Local Part. This field provides the local part of the qualified name of the service namespace URI.

Enter the Resource Offering Options.

This field lists the options available for the resource offering to provide hints to a potential requestor whether certain data or operations are available to a particular offering. If no option is specified, the service instance does not advertise any available options.

Choose the resource offering Directives. The directives are as follows:

Authorize Requester. This directive is specified for discovery service provider to include a SAML assertion containing a ResourceAccessStatement in any future QueryResponse message.

Authenticate Session Context. This directive is specified for discovery service provider to include a SAML assertion containing a SessionContextStatement in any future QueryResponse message.

AuthenticateRequester. This directive must be used with any descriptions, including the security mechanisms from LibertySecMech which uses SAML for message authentication.

EncryptResourceID. This directive specifies that the discovery service must not reveal the unencrypted resource ID to the clients. Currently, this directive is not supported, so the resource ID will not be encrypted when this directive is selected. If you wish to associate a directive with one or more description elements in the resource offering, select the checkbox in front of that Description ID. If none of the Description IDs are selected, the directive is applied to all description elements provided in the resource offering.

Click Save.

Adding a New Liberty Web Service

Adding a Liberty web service to Identity Server entails the following:

Developing the Server-Side Code

Configuring the Service Schema

Setting Up the Back-End Data Store

Deploying the Service on the Identity Provider

Deploying the Client on the Service Provider

Running the Web Service Client

Sample code for an Employee Profile service is provided with Identity Server to illustrate how to implement and deploy a new data service instance in Identity Server. The sample implements a Liberty Employee Profile service.

An Employee Profile Service Example

For deploying and running of this sample, you will need two Identity Server installations. One serves as Liberty Service Provider (SP), and one serves as Liberty Identity Provider (IDP). The Employee Profile service will be located in Identity Provider, and client code in the forms of jsp files will be located in SP.

Table 3-1 Two machines required for this sample
Variable Placeholder	Host Name	Deployed on this host
machine1	www.sp1.com	Service Provider Web Service Client (.jsp files)
machine2	www.idp1.com	Identity Provider Discovery Service Employee Profile Service

The sample provides five .jsp files.

Table 3-2 JSPs provided in this sample
Name	Description
index.jsp	Retrieves boot strapping resource offering for discovery service.
discovery-modify.jsp	Adds Resource Offering for a user.
discovery-query.jsp	Sends query to discovery service for service resource offering.
id-sis-ep-modify.jsp	Sends Data Service Modify request to modify user attributes.
id-sis-ep-query.jsp	Sends Data Service Query Request to retrieve user attributes

Developing the Server-Side Code

Since the Employee Profile service is a data service, when you develop its server-side code, you must extend DSTRequestHandler and implement its processDSTRequest() method to process query and modify requests.

Identity Server provides sample code to demonstrate how you would develop and deploy a new service. The Employee Profile service sample code is already written and resides in the following directory:

IdentityServer_base/samples/phase2/sis-ep/src/ep



Note	This sample does not provide instructions for implementing every aspect of a complete service. For this example, note the following: Authorization is not enabled. The only authentication mechanism supported is urn:liberty:security:2003-08:null:null SSL/X509 and SAML tokens are not supported. Uses simple-minded select string parsing instead of using XPATH API A few attributes such as LInternalJobTitle, LOU, LCN, LAltCN and LLegalName not supported.

Identity Server's back-end data store is used in this sample to store the requested Employee Profile data. The code for getting and setting the data is included in the Service Management APIs. See “Defining A Custom Service” in the Identity Server Developer’s Guide.

Configuring the Service Schema

The xsd file which defines the Employee Profile service schema is the starting point for developing the Employee Profile service server-side code.

Invoke the jaxb compiler on xsd files.

The Employee Profile service and the related schema files are gathered under IdentityServer_base/SUNWam/samples/phase2/sis-ep/xsd.

Be sure that the jaxb compiler xjc is available somewhere in your environment. If it is not available, download JWSDP 1.3 from Sun's web site.

http://java.sun.com

To make sure your are using the correct xjc.sh path inside the script invoke_xjc.sh (which is under IdentityServer_base/SUNWam/samples/phase2/sis-ep/bin), run the following command:

# jar tvf install_dir/SUNWam/lib/am_services.jar | grep "impl/runtime"

Based on the result, in the script invoke_xjc.sh, replace the package name behind the option -use-runtime.

Be sure that JAVA_HOME environment variable in xjc.sh is set; it should point to a JDK version equal to or higher than 1.4.

Invoke the script invoke_xjc.sh:

# IdentityServer_base/SUNWam/samples/phase2/sis-ep/bin/
invoke_xjc.sh

A number of Java files are generated from the xsd files and are placed under IdentityServer_base/SUNWam/samples/phase2/sis-ep/xsd/gen.

Compile the generated Java files.

If necessary, modify the INSTALL_DIR variable in script IdentityServer_base/SUNWam/samples/phase2/sis-ep/
bin/compile_gen.sh.

Run the following command:

# IdentityServer_base/SUNWam/samples/phase2/sis-ep/
bin/compile_gen.sh

A number of class files are generated and placed under IdentityServer_base/SUNWam/samples/phase2/sis-ep/classes. The IdentityServer_base/SUNWam/samples/phase2/sis-ep/classes directory is soft-linked from install_dir/SUNWam/lib which is already on the web container's class path.

Develop the Employee Profile service code. (See the introduction to Developing the Server-Side Code.)

Compile the EP service code.

# cd IdentityServer_base/SUNWam/samples/phase2/sis-ep/src
# make

The generated class files are placed under IdentityServer_base/SUNWam/samples/phase2/sis-ep/classes, together with the class files compiled from the generated jaxb Java files.

Set up the back-end data store.

See the following section.

Setting Up the Back-End Data Store

For more information about the back end data store and service management, see the Identity Server Administration Guide.

To Set up the Back-End Data Store

Load the Employee Profile LDIF file. This is the Directory Server schema.

# cd IdentityServer_base/SUNWam/samples/phase2/sis-ep/bin

Modify load_ldif.sh.

Provide the values that are appropriate for your deployment for the following parameters: installation directory, host name, directory server port and password.

Run the load_ldif.sh script:

# ./load_ldif.sh

This loads the Directory Server schema defined in IdentityServer_base/SUNWam/samples/phase2/sis-ep/ldif/ep.ldif into the Directory Server. The attribute names used in ep.ldif are the ones used in EmployeeProfile.java in IdentityServer_base/SUNWam/samples/phase2/sis-ep/src/ep.

Load the Employee Profile service management schema.

In IdentityServer_base/SUNWam/samples/phase2/sis-ep/
bin, modify load_xml.sh.

Change the amadmin password. Change the installation directory, if necessary.

Run the following command:

# ./load_xml.sh

This loads the Identity Server service management schema that is defined in IdentityServer_base/SUNWam/samples/phase2/sis-ep/
xml/amLibertyEmployeeProfile.xml into the Identity Server and ultimately into Directory Server.

Note that the attribute names in amLibertyEmployeeProfile.xml are the same as those in ep.ldif.

Deploying the Service on the Identity Provider

To Deploy the Service

Configure the SOAP Receiver to recognize EPRequestHandler.

Click the Service Configuration tab, and then select SOAP Binding.

In the right pane, add key=idep|class=ep.EPRequestHandler to the RequestHandler List.

Note that ep.EPRequestHandler is the class name for IdentityServer_base/SUNWam/samples/phase2/sis-ep/
src/ep/EPRequestHandler.java which extends DSTRequestHandler. Also note that idep will be part of the URI used to invoke the Employee Profile service.

In /etc/opt/SUNWam/config/AMConfig.properties, add ep.jaxb to the property com.sun.identity.liberty.ws.jaxb.packageList.

This is to let the SOAP binding layer knows about the Employee Profile service jaxb package which is new to the Identity Server platform.

In the Identity Management tab, in the View menu, choose Services.

Click Add.

In the right pane, select "Liberty Employee Profile Service,” and then click OK.

Create a user. For this example, name the user idpUser.

Select "Liberty Employee Profile Service" in the "Available Services" list creating idpUser (otherwise EP modify will fail).

If idpUser exists already (from deploying the Web Service Client sample, for example), then just add the "Liberty Employee Profile Service" for this user.

This user will be used as the federated user on the Identity Provider side, also for storage of Discovery Service resource offering and Employee Profile service attributes. Deploy liberty sample1 IDP to set up a runnable liberty scenario.

Deploy the Identity Provider.

Follow the instructions in the section Deploying the Identity Provider. If this is done already, when running the Web Service Client sample, for example, then skip this step.

Restart the web container in which Identity Server is running.

Deploying the Client on the Service Provider

To Deploy the Client

Deploy the Service Provider.

Follow the instruction in the section Deploying the Identity Provider. If this is already done, for example if you have already run the Web Service Client sample, then skip this step.

Change protocol support of the remote Identity Provider to ID-FF 1.2.

Click the Federation Management tab, and then in the View menu choose Entity Descriptors.

Click the remoteIDP entity ID from the list.

In the right pane, in the view menu, choose Provider.

Click the Edit link under Provider.

In the "Protocol Support Enum" field, choose urn:liberty:iff:2003-08.

Click Save.

Replace the tags and hosts in discovery-modify.jsp and index.jsp.

All the JSP files are under IdentityServer_base/SUNWam/samples/phase2/sis-ep/
jsp/. Use the Data Services Template client API and Discovery client API for sending query or modify requests and for receiving query or modify responses.

Replace IDP_SERVER_PORT with the server port of Identity Provider host.

Replace SERVICE_DEPLOY_URI with the service deployment URI of the Identity Provider host.

Replace www.sp1.com with host name of the Service Provider host if necessary.

Replace www.idp1.com with host name of Identity Provider host if necessary.

Deploy the JSP files.

Copy all the five JSP files to a sub directory of the document root of the web container.

For example, if you are using Sun Java System Web Server 6.1, run following command:

# mkdir webserber_install_dir/docs/wsc

# cp is_install_dir/SUNWam/samples/phase2/ep/*.jsp webserber_install_dir/docs/ep/

Create a user named spUser.

This user will be used as federated user on the Service Provider side.

Restart the web container in which Identity Server is running.

Running the Web Service Client

Before you can run the Web Service Client, you must deploy a Service Provider and an Identity Provider. If you have not done this yet, see Creating a Liberty Web Services Environment for detailed instructions.

Federate users spUser and idpUser.

See Creating a Liberty Web Services Environment. Follow the instructions for federating user accounts, performing single sign-on, and performing single logout.

As idpUser, perform a single sign-on again from the Service Provider to the Identity Provider.

In a browser, connect to http://machine1:sever_port/ep/index.jsp.

You will see the bootstrapping resource offering for Discovery Service and two two buttons: "Send Discovery Lookup" and "Add PP Resource Offering."

Click "Add PP Resource Offering."

The discovery-modify.jsp page is displayed. The Employee Service resource offering has been computed based on the bootstrapped Discovery Service Resource Offering.

Click "Send Discovery Update Request.",

The user's Employee Profile resource offering will be registered in idpUser on machine2.

Click the "Return to index.jsp" link.

This will bring you back to the index.jsp page with the bootstrapped resource offering.

Click "Send Discovery Lookup."

The discovery-query.jsp page is displayed.

(Optional) If you leave the “ServiceType to look for” field blank, all service instances will be returned.

You can enter a value in the "ServiceType to look for" field. Values are defined in the Liberty Web Service Consumer specification.

Click "Send Discovery Lookup Request."

The Employee Profile resource offering added in Step 4 will be displayed. Choose one of the following two options:

To query Employee Profile Service in machine2 for user attributes, click "Send EP Query."

The id-sis-ep-query.jsp page is displayed.

In the Authentication Mechanism field, choose urn:liberty:security:2003-08:null:null. You can change the "XPath Expression" field to a different XPath expression for attribute selection. The default is /EP/EmployeeID.

To modify the user's employee profile attributes, click "Send PP Modify." The id-sis-ep-modify.jsp page is displayed. The modify request is sent to the Employee Profile Service in machine2.

In the Authentication Mechanism field, choose urn:liberty:security:2003-08:null:null. You can modify the "XPath Expression" field for attribute selection. The default is /EP/EmployeeID. You can modify the Value field with new values for the attribute.

Constructing a PAOS Request and Response

Identity Server provides client PAOS APIs and a sample stand-alone Java application to demonstrate how to set up and invoke a PAOS service interaction between a client and a server. In a real-world deployment, the server-side code would be developed by a service provider.

All the files required to use the sample are located here:

IdentityServer_base/SUNWam/samples/phase2/paos

The sample is based on the following scenario: a cell phone user subscribes to a news service offered by his cell phone’s manufacturer. The news service automatically pushes stocks and weather information to the user’s cell phone at regular intervals. In this scenario, the manufacturer is the news service provider and the individual cell phone user is the client or consumer.

To Run the Sample PAOS Program

Set the environment variables.

These environment variables will be used for running the make and gmake commands, and for using the run command. The Makefile and run command are in the same directory where the sample files are located:

IdentitySever_base/SUNWam/samples/phase2/paos

Set the JAVA_HOME variable to your installation of JDK. The JDK version should be newer than JDK 1.3.1

In the directory IdentityServer_base/SUNWam/samples/phase2/paos, run gmake or make.

Copy the PAOSClientServlet.class file to the IdentityServer_base/SUNWam/lib directory. Alternatively, you can make a soft-link in that directory back to this class.

In the file IdentityServer_base/SUNWam/web-apps/services/WEB-INF/web.xml, insert these lines just after the last /servlet tag:


<servlet>
<servlet-name>PAOSClientServlet</servlet-name>
<description>PAOSClientServlet</description>
<servlet-class>PAOSClientServlet</servlet-class>
</servlet>

Insert the following lines just after the last </servlet-mapping> tag:


<servlet-mapping>
<servlet-name>PAOSClientServlet</servlet-name>
<url-pattern>/PAOSClientServlet</url-pattern>
</servlet-mapping>

Restart the server.

Modify the run script to reflect your particular installation.

Run PAOSServer:

./run

You will see the output from the PAOSServer program. You can also see the output from PAOSClientServlet program in the Web Server's log file. For example, for Sun Java System Web Server, in the Web Server instance directory, look in the log subdirectory for the errors file.

Previous Contents Index Next

Previous Contents Index Next
Sun Java System Identity Server 2004Q2 Federation Management Guide