Chapter 5 Using the OpenSSO Enterprise Fedlet to Enable Identity Federation

The OpenSSO Enterprise Fedlet is a streamlined Service Provider implementation of SAMLv2 single sign-on (SSO) protocols. The OpenSSO Enterprise Fedlet is designed to be used by Service Providers when a full-featured federation solution is not required, and when the primary goals are to achieve single sign-on with an Identity Provider while also retrieving some user attributes from the Identity Provider.

The following topics are contained in this chapter:

• About the OpenSSO Enterprise Fedlet

• Analyzing the Deployment Architecture

• Considering Deployment Assumptions, Dependencies, and Constraints

• Understanding Typical Business Use Cases

• Setting Up and Configuring the Fedlet

• Evaluating Benefits and Tradeoffs

• Finding More Information

About the OpenSSO Enterprise Fedlet

The OpenSSO Enterprise Fedlet is compliant with SAMLv2 standards so you can embed the Fedlet in a J2EE web application. You can embed the Fedlet SDK into a Service Provider application, and enable the application to accept SAML POSTs from an Identity Provider. The application can then use the Fedlet SDK to pull user attributes into the Service Provider application. The user attributes become part of the SAML Response from the Identity Provider. After the user has successfully authenticated to the Identity Provider, the Identity Provider sends the SAML Response to the Fedlet .

The following figures illustrates how OpenSSO Enterprise, as the Identity Provider, determines which user attributes to include in the SAMLv2 Response to the Service Provider.

Figure 5–1 OpenSSO Enterprise Determines Which User Attributes to Include in the SAML Response

Using The Fedlet with Multiple Identity Providers

You can install multiple Fedlet instances at the Service Provider so that each Fedlet instance talks to a different Identity Provider. Or you can deploy a single OpenSSO Enterprise instance at the Service Provider.

If you want to install multiple Fedlet instances so that each Fedlet instance talks to a different Identity Provider, use caution with this approach. Consider the following example. A ringtone provider acts as a Service Provider and conducts business with multiple telecommunications companies. Each telecommunications company acts as its own Identity Provider. The Service Provider might have to deploy multiple instances of its Ringtone Application, each with its own Fedlet instance. Each Fedlet instance would communicate with a different telecommunications company Identity Provider. The result is that each Identity Provider would be using a different instance of the Ringtone Application.

Consider another example. The Fedlet is deployed on Sun Application Server, and the Fedlet home-directory is configured in the Application Server domain configuration file, domain.xml. So for each new Fedlet instance, a new Application Server domain must be set up, and an instance of the Ringtone Application must be deployed on this new Application Server domain. Now the Service Provider has to maintain two Application Server domains for the same Ringtone Application. This presents two possibilities. One possibility is that the same Ringtone Application is run on different ports for different Identity Providers. The second possibility is that the same Ringtone Application is run on the same port on different machines. This could also translate into different Ringtone Application URLs that each Identity Provider will use with the Service Provider. Or the Service Provider would have to implement some logic to route to the correct Ringtone Application based on the particular Identity Provider requesting it.

Using an Identity Provider Discovery Service with Multiple Identity Providers

The Fedlet supports multiple Identity Providers. Additionally, the Fedlet supports the use of a separate Identity Provider Discovery Service to allow the user to select a preferred Identity Provider to authenticate against. When configured this way, the Identity Provider Discovery Service will remember the user's preferred Identity Provider, and communicate this to the Fedlet. The Fedlet will then be able to determine which Identity Provider to have the user authenticate to. You can deploy an OpenSSO Enterprise instance as an Identity Provider Discovery Service. However, the Fedlet can work with any Identity Provider Discovery Service. The figure below illustrates the process flow in a Fedlet deployment when the Identity Provider Discovery Service is used to set the user's preferred Identity Provider.

Figure 5–2 Identity Provider Discover Services is Set to User's Preferred Identity Provider

The following figure illustrates the process flow in a Fedlet deployment when the Identity Provider Discovery Service is used to retrieve the user's preferred Identity Provider.

Figure 5–3 Identity Provider Discovery Service Retrieves the User's Preferred Identity Provider

Analyzing the Deployment Architecture

The main components of the circle of trust described in this chapter are the telecommunications company which acts as and Identity Provider, and a ringtone Service Provider. The following two use cases are supported by the Fedlet:

• Identity Provider-Initiated Single Sign-On

• Fedlet Service Provider-Initiated Single Sign-On

The following table provides a simple comparison of the two use cases.

Table 5–1 Comparison of Fedlet Use Cases

Identity Provider-Initiated Single Sign-On	Service Provider-Initiated Single Sign-On
1. Mobile phone user authenticates with Telecommunications Company.	1. Mobile phone user attempts to access the ringtone Service Provider portal.
2. Upon authentication, mobile phone user accesses the ringtone Service Provider portal.	2. Ringtone Service Provider detects whether or not the mobile phone user has been authenticated by the Telecommunications Company. If not, then the ringtone Service Provider redirects the mobile phone user to the Telecommunications Identity Provider.
	3. Telecommunications Company challenges mobile phone user's credentials. Mobile user presents credentials.
	4. Upon authentication, mobile phone user accesses the ringtone Service Provider portal.

Identity Provider-Initiated Single Sign-On

The following illustrates the flow of communication in a federation scenario between a telecommunications company acting as the Identity Provider, and a ringtone provider company acting as the Service Provider.

Figure 5–4 Process Flow for the Fedlet in Identity Provider-initiated Single Sign-On

In an Identity Provider-initiated single sign-on scenario, the Identity Provider is configured with specialized links to specific Service Providers. These links actually refer to the local Identity Provider single sign-on service and pass parameters to the service identifying the remote Service Provider. So instead of directly visiting the Service Provider, the user goes to the Identity Provider site and clicks on one of the links to gain access to the remote Service Provider. This triggers the creation of a SAML assertion that is subsequently transported to the Service Provider.

Fedlet Service Provider-Initiated Single Sign-On

In a Service Provider-initiated single sign-on scenario, the user attempts to access a resource on the Service Provider. However the user does not have a current logon session on this site, and the user's federated identity is managed by the Identity Provider. The user is sent to the Identity Provider to log on. The Identity Provider creates a SAML assertion for the user's federated identity and sends it back to the Service Provider. The following figure illustrates the process flow.

Figure 5–5 Process Flow for Fedlet Service Provider-initiated Single Sign-On

Considering Deployment Assumptions, Dependencies, and Constraints

As you plan your deployment, consider the following assumptions, dependencies, and constraints to determine if your environment is appropriate for using the Fedlet.

Assumptions and Dependencies

• The configuration file and the metadata for the Fedlet is stored in a flat-file repository at the Service Provider.

• This solution uses the HTTP POST bindings for transport between the Identity Provider and the Service Provider.

• The Fedlet supports the verification of the XML signature carried in the SAML Assertion from Identity Provider. XML signature verification is done using the Identity Provider public certificate included in the Identity Provider metadata XML file. If the Identity Provider signing certificate is changed, the Identity Provider metadata in the Fedlet configuration directory must be updated to include the new signing certificate information. Otherwise XML signature verification will fail on the Fedlet side. At this time, the Fedlet does not support XML encryption, XML decryption, or XML signing such as signing the AuthnRequest on the Fedlet side.

Constraints

• The Fedlet supports Identity Provider-initiated single sign-on using only HTTP POST bindings.

• The Fedlet supports Fedlet Service Provider-initiated single sign-on using only HTTP POST bindings.

• In this deployment, no keystore exists to store certificates used for encrypting and signing SAMLv2 message elements. The Fedlet does not support the encryption and signing of SAMLv2 message elements. This capability may be implemented in a future release of OpenSSO Enterprise. This constraint has implications about ensuring the confidentiality and integrity of messages. Until the Fedlet can support the encryption and signing of SAMLv2 message elements, you are encouraged to use SSL/TLS at the message transport layer to secure exchanges between browser and server. The ensures that exchanges are secured at least while the SAML messages are in-transit. The Fedlet does support the verification of XML signature in the SAMLv2 Response from Identity Provider.

Understanding Typical Business Use Cases

The following use cases illustrate why companies might choose to use the Fedlet in their environment.

Saving Time and Reducing Overhead

In this use case, the Service Provider needs to single sign-on with an Identity Provider that has OpenSSO Enterprise installed in the Identity Provider environment. But the Service Provider does not want to install the full-featured OpenSSO Enterprise just to enable federation. The Service Provider cites one or more of the following reasons for not installing OpenSSO Enterprise:

• The Service Provider is small company that provides one application as only part of their service.

• The Service Provider wants identity federation at minimum cost.

• Installing OpenSSO Enterprise would require investments in hardware, services, and human resources that the Service Provider does not want to make.

• Installing OpenSSO Enterprise would require the Service Provider system administrators to be proficient in implementing identity federation protocols in order to configure and maintain the OpenSSO Enterprise federation deployment.

• The Service Provider wants to quickly enable federation in their environment in a very short timeframe.

• The Service Provider wants only to implement single sign-on with the Identity Provider and retrieve some user attributes for customizing the service to the user. The Service Provider does not want to install a full-featured federation solution and just to use two features.

Customizing Content Based on User Attributes

In this use case, a telecommunications company acts as an Identity Provider. The telecommunications company subscribers use the custom telecommunications company user portal to receive personalized content. The content is received by the telecommunications company from its business partners such as StockService.com, Weather.com, and so forth. OnCast, a new partner of the telecommunications company, uses Fedlets for its portal user single sign-on. Through the Fedlets, OnCast retrieves specific user attributes over SAML from the telecommunications company. OnCast then uses the user attribute data to customize its content deliver.

Figure 5–6 Fedlet Service Provider Customizes Content Based on User Attributes

See the demonstration of this business use case at http://blogs.sun.com/sid/resource/fedlet.html .

Setting Up and Configuring the Fedlet

This section describes the high-level tasks to setup the Fedlet at the Service Provider. For more detailed instructions, see the README file contained in the Fedlet.zip and Fedlet-unconfigured.zip files.

Technical Requirements

• Any J2EE-complaint server on which to deploy the Fedlet

• JDK 1.5 or higher

Obtaining and Deploying the OpenSSO Fedlet Bundle

You can choose one of two methods for obtaining and deploying the Fedlet Bundle.

If OpenSSO is deployed as an Identity Provider, then use the OpenSSO Enterprise console to create the Fedlet bundle. In this scenario, using the console is the faster and easier method because the Identity Provider follows the same workflow to integrate with any Service Provider.

If multiple Identity Providers exist in the Service Provider circle of trust, and not all Identity Providers use OpenSSO Enterprise, then use the Fedlet Demo. The Fedlet Demo contains a sample JSP is packaged in the fedlet.war. The fedlet.war file emulates the Service Provider web application. Using the fedlet.war file makes it easy to demonstrate a simple JSP receiving the SAMLv2 POST from the Identity Provider.

To Use the OpenSSO Enterprise Console to Create the Fedlet bundle

In the OpenSSO Enterprise console, navigate through a taskflow and provide the following:

1. Name of the Service Provider

2. Destination URL of the Service Provider that will include the Fedlet

3. The circle of trust in which to place the Service Provider

At the end of the taskflow, a Fedlet.zip bundle is automatically created. The bundle consists of the fedlet.war file and a README file that contains instructions for deploying the Fedlet. Follow the instructions to deploy the Fedlet.

To Use the Pre-Built Fedlet

As the Service Provider, download the opensso_enterprise_80.zip file. Then follow the instructions in the README file contained in the Fedlet-unconfigured.zip file to deploy and configure the Fedlet. The Fedlet-unconfigured.zip file is bundled into the opensso_enterprise_80.zip.

To Set Up the Workflow-based Fedlet

1. Install and Configure OpenSSO Enterprise on the Identity Provider.

2. On the Identity Provider, navigate through the Workflow on the OpenSSO Enterprise console to create the Fedlet.zip file.

   The Fedlet.zip file contains:

   • README.txt: A text file that contains instructions for deploying the fedlet.war and for integrating the Fedlet into an existing application.

   • fedlet.war: The Fedlet ready-to-deploy WAR file.

3. Send the Fedlet.zip file to the Service Provider.

4. Deploy and configure the fedlet.war file, on the Service Provider.

5. Verify that the Fedlet was successfully installed.

   1. Access the index.jsp file on the Fedlet deployment.

   2. Click the link to create the Fedlet configuration automatically.

   3. Follow the two links in the page to test the following use-cases :

   • (Fedlet) Service Provider-initiated single sign-on

   • Identity Provider-initiated single sign-on through the hyperlinks present on the page.

To Use the Pre-Built Fedlet

1. Download the Fedlet-unconfigured.zip.

   Fedlet-unconfigured.zip is contained in the opensso_enterprise_80.zip distribution. The Fedlet-unconfigured.zip file contains:

   • fedlet.war

     The Fedlet ready-to-deploy WAR file

   • conf

     A directory containing the Fedlet metadata template, circle of trust template, and various configuration files

   • README.txt

     A text file that provides instructions for using the \conf files to configure the Fedlet

2. Extract the Fedlet-unconfigured.zip file.

   Follow the instructions in the README file to set local configuration files for the Fedlet.

3. Send tag-swapped Service Provider metadata files to the Identity Provider, and request the Identity Provider metadata files from the Identity Provider.

4. Verify that the Fedlet is successfully installed.

   Access the index.jsp file on the Fedlet deployment, and test the following use-cases : Fedlet (SP)-initiated SSO IDP-initiated SSO through the hyperlinks present on the page.

   • (Fedlet) Service Provider-initiated single sign-on

   • Identity Provider-initiated single sign-on through the hyperlinks present on the page

To Use the Fedlet with Multiple Identity Providers

1. The Service Provider installs and configures the Fedlet and sets up the Fedlet with one Identity Provider.

   Install and configure the Fedlet using instructions in either To Set Up the Workflow-based Fedlet or To Use the Pre-Built Fedlet.

2. To use a second Identity Provider with the Fedlet, the Service Provider requests the Identity Provider metadata files from the second Identity Provider.

3. Update the Fedlet configuration directory with the Identity Provider metadata files, and update the Fedlet's configuration with the Identity Provider entity ID.

4. The second Identity Provider registers the Fedlet in its configuration.

5. To add more Identity Providers to the Fedlet, repeat steps 2 through 4.

6. Access the index.jsp file on the Fedlet deployment where you are presented a list of registered multiple Identity Providers. Choose an Identity Provider.

7. For the selected Identity Provider, you are presented the option to test the following use cases through the hyperlinks on the page:

   • Fedlet Service Provider-initiated single sign-on

   • Identity Provider-initiated single sign-on

8. The README file included in the Fedlet.zipand the Fedlet-unconfigured.zip contains instructions for setting up the Fedlet with multiple Identity Providers.

To Use the Fedlet with an Identity Discovery Service

1. The Service Provider configures the Fedlet with multiple Identity Providers.

   See “Using the Fedlet with Multiple Identity Providers.”

2. Deploy and configure an Identity Provider Discovery Service.

3. Set the SAML2 Reader and Writer Service URLs on each of the configured Identity Providers.

4. Set the SAML2 Reader and Writer Service URLs in the Fedlet configuration.

5. Access the index.jsp file on the Fedlet deployment where you will be presented with a list of the registered multiple Identity Providers. Choose your preferred Identity Provider.

6. You will be directed to your selected Identity Provider for login.

   A cookie _saml_idp that identifies your preferred Identity Provider will be written by your browser.

7. From this point on, you can elect to use the Identity Provider Discovery service after you access the index.jsp on the Fedlet deployment.

8. The Identity provider Discovery Service will remember your preferred Identity Provider and will automatically redirect you to that Identity Provider for login.

9. The README file included in the Fedlet.zip and the Fedlet-unconfigured.zip contains instructions on how to set up the Fedlet with an Identity Provider Discovery Service.

Embedding the Fedlet into Service Provider Applications

The README file contained in the Fedlet.zip and the Fedlet-unconfigured.zip files provides instructions for integrating the Fedlet demo into the Service Provider application. You need to embed all the properties/jars/JSPs/images and so forth in the demo fedlet.war into your existing application WAR. Merge the fedlet.war with your existing application WAR. The Fedlet provides a default Assertion Consumer endpoint named fedletSampleApp.jsp to process the SAMLv2 Assertion from the Identity Provider.

Use one of the following approaches to embed the Fedlet into the Service Provider applications:

• Use fedletSampleApp.jsp as the endpoint on Fedlet side, and modify fedletSampleApp.jsp to add the Service Provider application logic.

  

• Use fedletSampleApp.jsp as the endpoint on Fedlet side, and modify fedletSampleApp.jsp to forward the request to the Service Provider application URL.

  

• Create a new endpoint, for example servlet.jsp URL, on the Fedlet side to replace the fedletSampleApp.jsp or to embed the Fedlet into the Service Provider application. You can copy some of the code in the fedletSampleApp.jsp to the new endpoint code. Details of the actual code you can transfer are described in the README file.

  

Evaluating Benefits and Tradeoffs

As you design your deployment architecture, be sure to consider the benefits, tradeoffs. The following lists may help you determine if the Fedlet is appropriate to meet your business needs.

Benefits

• The Fedlet does not require additional hardware, thus reducing the cost to the Service Provider and increasing the return on investment on existing hardware.

• The Fedlet is easy to deploy and to embed into the Service Provider application. Configuration on the Fedlet, if needed at all, requires modifying only three to four parameters. This enables you to go live with the application much more quickly than deploying a full-featured federation solution.

• The Fedlet enables the Service Provider to quickly enable federation into their applications, resulting in shorter time-to-market for their applications with the Identity Provider.

• The Fedlet does not require the Service Provider to install any full-featured federation software. This reduces the amount of training required, thus reducing training costs for the Service Provider.

• The Fedlet is ideal for a Service Provider that wants only to achieve single sign-on with an Identity Provider, and to be able to retrieve user attributes from the Identity Provider.

• The Fedlet is compliant with SAMLv2 standards.

• A single instance of the Fedlet can be set up to work with more than one Identity Provider.

• The Fedlet can be configured to use an Identity Provider Discovery Service to set and find the user's preferred Identity Provider.

Tradeoffs

• The Fedlet will not perform session management on the Service Provider. The application or container must perform session management.

• The Fedlet supports single sign-on using the SAMLv2 protocol only. Other federation protocols such as Liberty ID-FF, WS-Federation, and SAML 1.x, are not supported.

• The Fedlet solution enables only single sign-on with an IDP and retrieval of user attributes. Advanced features, typically available in a full-featured federation product such as OpenSSO Enterprise, are not available in the Fedlet:

  • IDP Proxying

  • Single Logout

  • Auto Federation

  • Account Linking Auto-creation of users on the SP

  • Declarative policy integration with roles asserted from the IDP

Finding More Information

• OpenSSO Homepage

  http://opensso.org

• SAML v2.0 Technical Overview

  http://www.oasis-open.org/committees/download.php/27819/sstc-saml-tech-overview-2.0-cd-02.pdf

• Identity Provider Discovery Service Protocol and Profile

  http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-idp-discovery.pdf