Using the Fedlet with Oracle Identity Federation (OIF)

The Fedlet was first introduced in Sun's OpenSSO product. In a nutshell the Fedlet is a light weight SAML relying party implementation that is "pre-baked" with all of the right meta data needed to join a federation.

Typically a large Identity Provider creates a Fedlets for smaller partners that wish to leverage the providers identity infrastructure. These partners do not need to know the intricacies of SAML as the Fedlet is pre-configured. The Identity provider packages a Fedlet as a Java .war file or a .Net assembly that the partner can deploy.

The Fedlet has a simple API that is used to log the user in at the Identity provider and obtain information about the federated user that the provider has chosen to share.

As a prerequisite OIF must be installed, and the Fedlet distribution downloaded and unzipped.  The latest version of the Fedlet is 11.1.1.3 and can be downloaded from Oracle EDelivery (look under Fusion Middleware).

You also need a servlet container to deploy the sample fedlet war file. Any container with JSP support will do the trick (Tomcat, Glassfish, Weblogic, etc.).

The Fedlet Deployment Process

The high level steps to deploy a Fedlet are:

1. Export OIF's IdP SAML meta data to a file. This meta-data is used by the Fedlet  generation script to parameterize the Fedlet (part of the "pre-baking" process").
2. Run the Fedlet script to create a custom Java war file and additional meta-data. 
3. The Fedlet script outputs the relying party meta-data to a file called sp.xml. This is the partner half of the federation. This meta data is imported into OIF to configure the partner link. You could do this manually - but importing the SP data will save time.
4. Deploy the generated Fedlet war file to a servlet container
5. Profit!

Getting Ready

• Unzip the Fedlet distribution to a base directory (example ~/fedlet-install). The distribution contains templates for Java and .Net. 

Update OIF IdP Settings

Log in to your OIF EM Admin console (for example at  http://oif:7001/em).


Navigate to OIF -> Administration -> Identity Provider -> SAML 2.0

• In “Assertion Settings” section: Set “Transient/One-Time Identifier” as default Name ID Format
• In “Protocol Settings” check “Enable Attribute Query Responder” flag, and “Use Identity Federation for Attribute Response” flag.
• In “Protocol Settings” section, “Messages to Send/Require Signed” table: 
• Uncheck the flag “Require Signed” for “Requester- HTTP Redirect” 
• Apply the changes.

Export OIF Idp Meta Data

You can export OIF meta in two ways - from the EM Console and from a meta data URL presented by OIF.  The fedlet configuration script shown later uses the URL. Below is the procedure for using the EM console:

• Navigate to  OIF->Administration->Security and Trust
• Select Identity Provider and SAML 2.0 
• Press Generate

A screen shot is show below:

Run the Fedlet Configuration Script

The next step is to run the Fedlet configuration program to generate the custom war file.  The Fedlet distribution does not come with a shell script to invoke the program. Below is sample that you can modify for your environment (link for non JS browsers https://gist.github.com/1340523#file_configfedlet.sh)



The shell script demonstrates how to get the IdP meta data from OIF. The Fedlet configurator will prompt for the meta data location.

Importing SP meta data

The Fedlet configurator generates the Fedlet configuration files to the target directory you specified. The generated file sp.xml is the meta data for OIF that describes the partner relationship. Import this file into OIF using the OIF Enterprise Manager console:

• Navigate to Admin -> Federations
• Select the "+ Add" button
• Select the "Browse" button and import the generated sp.xml file

Mapping Attributes

The Fedlet can pass along attributes from the IdP along with the SSO assertion. These are useful for the service provider to identify the user and offer personalized service.

• Navigate to Admin->Federations and select your newly added partner, and click on “Edit”.
• Under the tab “Oracle Identity Federation Settings”, Click on “Edit” next to “Attribute Mappings and Filters”
• This  panel will allow you to add mappings from the IdPs attributes  (ldap attributes for the authenticated user) to attribute names to be passed to the partner. 

The following screen shot shows an example:

The above example shows passing on the ldap attribute "giveName" in the SAML assertion. It will be called "firstName" when the partner gets the assertion.

To complete the SP configuration you must perform the following steps:

• Under “Enable Attributes in Single Sign=On(SSO)”, make sure “Transient/One-Time Identifier” is selected
• Under “Protocol Settings”, “Messages to Send/Require Signed” table, enable the check mark under “Send Signed” for “Response with Assertion – SOAP”

Deploy and Test the Fedlet 

The generated war file is deployed to your container.  For example copy~/fedlet/fedletsample.war to ~/tomcat/webapps

When you bring up the fedlet page you should see this:

This is the sample Fedlet home page that is meant to serve as a starting point for your partner. Have a look through the various JSP files  to see the how the Fedlet API works.

If you click on any of the sample "Initiate SSO links" you will be redirected to OIF for authentication.

In this example we have OIF integrated with Oracle Access Manager (OAM) to perform the SSO session creation, so the login screen is from OAM:

Upon succesfull Federation you will be redirected back to the Fedlet.

The mapped attributes returned from the IdP are displayed:

Only the attributes mapped for this partner will be returned.

You can initiate Single Logout at the IdP by clicking on any of the "Logout" links at the bottom.

Trouble Shooting

The fedlet will log information to the "debug" directory under the fedlet configuration directory. Unless you override it, the Fedlet configuration directory is:

• ${user.home}/fedlet 

So the log files will be in ~/fedlet/debug

The file FederationConfig.properties can be used to adjust the behavior of the Fedlet:

• The property ${com.sun.identity.fedlet.home} sets the default config file location. 
• You can also increase the logging verbosity to "message" by setting the com.iplanet.services.debug.level property.