Oracle Technology Network

Role-based Federations with Oracle Identity Federation (OIF)

<Do not delete this text because it is a placeholder for the generated list of "main" topics when run in a browser>

Purpose

In this tutorial, you learn how to configure a role-based federation across security domains between one Service Provider and one Identity Provider.

Time to Complete

Approximately 1 hour.

Overview

OIF supports several different use cases for federations. Previous tutorials covered configuring transient federations (one-sided), mapped federations (two-sided symmetrical), and linked federations (two-sided asymmetrical). This tutorial explains how to configure role-based federations. In a role-based federation, the Identity Provider may have hundreds of users that fall into a few broad roles such as manager, clerk, contractor, executive, and so on. If there are a dozen contractors that all need access to an application on a Service Provider, all dozen users might have the same privileges. Compare those contractor users with another half-dozen executives. All half-dozen executives might have the same privileges as each other, but the executives' privileges are different than the contractors' privileges. In this scenario, it does not matter which executive signs on, any and all executives are treated the same. Similarly, any and all contractors are treated the same. To configure this role-based federation, all individual users are added to the Identity Provider (IdP) directory, but only a few pseudo-users are added to the Service Provider (SP) directory. A pseudo-user is an ordinary user as far as LDAP is concerned, but their "name" might be Manager or Executive with an employeeType of Mgr or Exec. No one would ever sign on as Manager, but would sign on as themselves, for example, as Joe Smith. All of the managers (Joe Smith and Mary Doe, and so on) all have an employeeType = Mgr and the pseudo-user named Manager also has an employeeType = Mgr. A linked federation is established just like the one done for telephoneNumber, except that in the role-based case, it is a 1-to-many relationship (the one pseudo-user Manager with an employeeType = Mgr matches a dozen or so regular users who also have an employeeType = Mgr), whereas in the previous linked federation with telephoneNumber it was a 1-to-1 relationship (the one user Jim exactly matches only one other user James where his mobile = cell = telephoneNumber).

Scenario

Background: Your company's users have access to a Web-based application that runs on a separate server in a separate company. Your company and the other company are considered separate security domains. For purposes of naming, assume that your company is MyCorp and the application is a life insurance benefits package hosted by MyLife Inc. The security for the benefits application requires authentication for a group of manager users whose privileges are not necessarily the same as the privileges for a group of clerk users. The SP does not care about the individual names of the managers, only that there are managers distinct from clerks. You must configure OIF on both your company's computer and the insurance company's computer. Your company's computer will be the Identity Provider (IdP) and the insurance company's computer will be the Service Provider (SP).

A group of managers that needs to use the application exists on the IdP system. A pseudo-user named Manager needs to be created on the SP. Privileges will be assigned to the pseudo-user and real manager users will come and go, each signing on to the IdP as themselves but being treated by the SP as the one pseudo-user Manager. You will configure a linked federation based on the employeeType.

Hardware and Software Requirements

The following is a list of hardware and software requirements:

Prerequisites

Before starting this tutorial, you should:

.

Verify that OIF is installed and configured as per the OBE Installing Oracle Identity Federation

.

Verify that OIF partners are registered and configured as per the OBE Transient and Mapping Federations with Oracle Identity Federation

Adding Role-based Users

There are two kinds of users: the real users (who have job roles such as manager and clerk), and the pseudo-users (who also have job roles such as manager and clerk, but are named Manager and Clerk.) The users sign on as themselves, no one ever signs on as the pseudo-users. From an LDAP standpoint, there is no difference between a real user and a pseudo-user. The real users exist on the IdP and the pseudo-users exist on the SP. To add the users to the IdP and the SP, perform the following steps:

Adding Role-based Users to the Identity Provider (IdP)


The users Ira and Isabella already exist from previous tutorials. The schema for the users already includes hundreds of attributes, only about a dozen of which are currently being used. Using ODSM, you will make the existing attribute employeeType indexed and therefore searchable. You will add employeeType to the short-list of visible attributes. You will add data (employee roles such as Mgr or Clerk) to that attribute for a few users.

.

Connect to the Oracle Directory Services Manager (ODSM) for the IdP.

There are three equally valid ways to bring up the ODSM Connect page. You can pick any one of the three:

  • Go to URL http://hostidp:7005/odsm.
  • If you have a connection from any ODSM (for example the SP's) you can go to the IdP ODSM by pulling down the "Connect to a directory" menu.
  • In the Enterprise Manager, under Identity and Access (far left) right-click "oid1" and select Directory Services Manager > Data Browser.

Enter a User Name of cn=orcladmin and a Password of Welcome1 (the password will display as a series of dots). Click Connect.

The main page for ODSM shows five tabs:

  • Home is just a summary of the other four tabs (and LDAP statistics).
  • Data Browser is used to add and modify (among other things) users. This is where you will add Ira and Isabella's data.
  • Schema is used to add and modify (among other things) attributes or fields for each user. This is where you will make employeeType indexed.
  • Security controls passwords and is not used in this tutorial.
  • Advanced configures plug-ins, chaining, garbage collection, and is not used in this tutorial.
Notice that the URL indicates that you are talking to the ODSM of the IdP through the SP. This is because the pull-down menu that says "OID - OID-hostidp" allows multiple destination configurations.

 

.

Index the employeeType attribute (column, field) so that it will be searchable. You have to do this before you add any data to it.

Click on the Schema tab. Scroll down the Attributes until you see employeeType. Right-click on employeeType and click Modify Index.

Click Confirm to create the index.

The Indexed field should now be checked. This is a reported option box, you cannot select it. Not all columns are initially indexed (for example, employeeType was not). Creating and maintaining an index takes up time and space, but gives you the option to search on that column. Unlike a regular relational database, adding the index only makes future data searchable, not current or previous data in that attribute. Because of this behavior, you must create the index before adding any data to that attribute.

 

.

Edit user Bob.

Click on the [+] to expand Root > dc=com > dc=example > cn=users > cn=Bob.

There are several different tabbed views available of Bob's attributes, such as Person, Attributes, Subtree Access, and Local Access.

 

.

On the Attributes tab, under Optional Attributes, click the Add icon [+] to add the employeeType attribute.

The attribute already exists in the schema, all this does is to display it in the list for easy editing and viewing.

 

.

Add employeeType to the list of Shown Attributes.

Select employeeType from the list of All Attributes on the left.

Click Move, click Add Attributes.

 

.

Make Bob a clerk.

Change the employeeType to Clerk. The schema has this column as case-insensitive, but other columns may be case-sensitive, so it is always a good habit to find out the "right" way to code it.

Click Apply. Note that the Modified time has changed. This is the only confirmation that the Apply was accepted successfully. You may have to click away from this panel and come back to see the date/time change.

 

.

Make Ira and Isabella both managers.

Go through the same process you did for Bob (screens not shown) but this time as manager instead of clerk:

  1. Click the Add icon.
  2. Add employeeType.
  3. Change employeeType to Mgr. Note that it is "Mgr," not "Manager." This will have to match the pseudo-user created later.
  4. Click Apply.

 

.

Optionally add another user Igor as a clerk.

In order to demonstrate the 1:many relationship, it would be more interesting to have more clerks than just Bob. OIF and LDAP will work fine with only one clerk, but that is not typically how a business organization is set up. To really make a thorough demonstration, you may want to optionally create a user with no employeeType, an employeeType (pseudo-user) with no real user, and so on. The process of creating users like an existing one was covered in detail in earlier OIF tutorials. For review of how to do that, look at tutorial (xxxxxxxxxx) Installing Oracle Identity Federation (OIF) and then return to here. Or, add the pseudo-users to the SP first (the next section) and that will review the steps for creating a user like another user, then come back here.

 

.

Test the directory to see if any Managers come back from an LDAP search.

Click the Data Browser tab, then click Advanced.

In the Search Criteria, select employeeType from the pull-down list, and type M (for Manager) in the field next to Beginning With. Optionally, select "Show LDAP filter" to display the LDAP Query. Click Search. Optionally, you can repeat the search with C (for Clerk) and you should see Bob (and Igor) as clerks.

Verify that Ira and Isabella show up in the Search Result. If they don't show up here, then the rest of the exercise will not work. Possible reasons for them not showing up in the Search are that you made the index after entering data, or that you forgot to Apply some change. If this is the case, then delete the users and re-enter them.

 

Adding Role-based Pseudo-Users to the Service Provider (SP)


There is nothing special about these users as far as OIF is concerned. They have all the same attributes as regular users. You need to add one pseudo-user for each role you use. For this exercise, add a Manager and a ShopClerk pseudo-user. Their employeeType must match the employeeType found in the real users.

.

Connect to the SP ODSM using the same techniques you used to connect to the IdP ODSM.

User Name is cn=orcladmin, Password is Welcome1. Click Connect. Note that the URL shown on the Connect dialog box is not the URL used for Web browsing the ODSM, in fact it is not even http; but rather it is the URL used for secure LDAP communications which is used internally by applications.

 

.

Index the employeeType column so that it will be searchable. This is the identical process you performed on the IdP earlier. It must be done before you add any employeeType information to the SP directory.

Click on the Schema tab. Scroll down the Attributes until you see employeeType. Right-click on employeeType and click Modify Index.

Click Confirm to create the index.

The Indexed field should now be checked. This is a reported option box, you cannot select it. Not all columns are initially indexed (for example, employeeType was not). Creating and maintaining an index takes up time and space, but gives you the option to search on that column.

 

.

Create a new user like orcladmin.

Expand the users until you can right-click on orcladmin, then select Create Like.

 

.

Accept the default Entry Properties.

Click Next.

 

.

Enter the Mandatory Properties for the new user Manager.

Enter the following values:

  • cn: Manager ("cn" for common name)
  • sn: Manager ("sn" for surname)
  • Relative Distinguished Name: cn
Click Next.

 

.

There is nothing to configure for this step.

Click Finish.

 

.

Select the new user Manager you just created, and add Optional Attributes.

On the Attributes tab, under Optional Attributes, click the Add icon [+] to add the employeeType attribute.

 

.

Add the employeeType and the userPassword Attributes to the Shown panel.

Scroll down the list of All Attributes and select employeeType and userPassword.

Click Move, then Add Attributes.

 

.

Change most Optional Attribute fields to Manager as shown, change employeeType to Mgr, change userPassword to Welcome1. In real life it would be important to make the password for the pseudo-users not match the real users' password. You don't want people signing on as the pseudo-user because that would violate audit principles. The passwords matching here is only for your convenience to make it easy to remember everything.

So now three users, Ira, Isabella, and the pseudo-user Manager, all have the employeeType = Mgr. In the same way that Jim = James based on cell number, now Ira=Manager based on role, but it is also true that Isabella = Manager based on role. There could be zero, one, or many users who "equal" the pseudo-user Manager based on role (employeeType).

 

.

Add the pseudo-user StockClerk in the same way you added Manager.

Go through the same process you did for Manager (screens not shown) but this time as a role of Clerk instead of Mgr:

  1. Click the Add icon.
  2. Add employeeType and userPassword.
  3. Change employeeType to Clerk. Note that it is "Clerk," not "StockClerk."
  4. Click Apply.

 

.

Complete the user's Optional Attribute values.

Change most Optional Attribute fields to StockClerk as shown, change employeeType to Clerk to match Bob (and optionally Igor), change userPassword to Welcome1.

 

.

Test the directory to see if any Clerks come back from an LDAP search.

Click the Data Browser tab, then click Advanced.

In the Search Criteria, select employeeType from the pull-down list, and type C (for Clerk) in the field next to Beginning With. Optionally, select "Show LDAP filter" to display the LDAP Query. Click Search.

Verify that pseudo-user StockClerk shows up in the Search Result. Repeat the search with M (for Manager) to make sure that pseudo-user Manager shows up. If either of the pseudo-users don't show up here, then the rest of the exercise will not work. Possible reasons for them not showing up in the Search are that you made the index after entering data, or that you forgot to Apply some change. If this is the case, then delete the users and re-enter them.

 

.

Close the ODSM session.

Click the blue X (not the red X). You can optionally close or reuse that Web browser tab.

 

Configuring the Identity Provider


Most of the preparation for the IdP was done when you configured the IdP to support linked federations in the previous tutorial (the prerequisite for this tutorial). First verify that the users were added correctly in the previous steps. Then modify the IdP configuration to support a mapping of employeeType to role. This configuration supports any number of roles, manager just happens to be an example. It will work for clerks and any other roles you define (for example, contractors, executives, and so on). To configure the IdP to support role-based federations for multiple users (for example Ira and Isabella) mapping to a single role (for example, manager), perform the following steps:

Verifying the Users


You added Ira and Isabella using ODSM. Now using OIF menus, verify that they are visible to the IdP.

.

Log in to the Enterprise Manager for the IdP.

Go to URL http://hostidp:7001/em and enter User Name: weblogic and Password: Welcome1. Click Login.

 

.

Navigate to configure the Identities to verify that the users Ira and Isabella were added correctly.

Make sure you are configuring the IdP (not the SP). On the left panel, click OIF(11.1.1.1.0). On the pull-down menu at the top, navigate to Oracle Identity Federation > Administration > Identities.

 

.

Search the local users for Ira and Isabella.

Click the Local Users tab. Click Search.

 

.

Verify that Ira, Isabella, and optionally Igor are there.

You cannot see the other attributes such as phone and employeeType from this display.

 

Configuring Roles on the Identity Provider


Configure the SAML parameters and Federations to associate (that is, map or link) the schema User Attribute Name employeeType with a made-up Assertion Attribute Name role.

.

Configure the IdP parameters.

On the pull-down menu at the top, navigate to Oracle Identity Federation > Administration > Identity Provider.

 

.

Specify that SAML pass the employeeType from the LDAP directory along with the user's normal assertion information (for example, name, password, email).

On the SAML 2.0 tab, configure the Unspecified NameID Format as follows:

  • Enabled: selected (there can be many)
  • Default: selected (there can only be one)
  • Get Value from User Session: deselected
  • User Attribute Mapping: employeeType
If you are modifying the previous configuration from the previous linked federation tutorial, then the previous Unspecified was mobile.

Click Apply. The Confirmation should say that "Changes have been applied."

 

.

Configure the Federation parameters.

On the pull-down menu at the top, navigate to Oracle Identity Federation > Administration > Federations.

 

.

Edit the configuration for the SP (stored on the IdP).

Select the SP Provider ID. It should be the only one listed there. In real world scenarios, there may be several SPs. It indicates "selected" by the gray box at the left, there is no check mark or any other indication. Click Edit.

 

.

Edit the Attribute Mappings.

Notice that Unspecified is selected. That will carry the role in it in the assertion. On the Oracle Identity Federation Settings tab, click Edit.

 

.

Add a mapping entry.

On the Name Mappings, click Add. You could simply edit the existing one (mobile), but it is a good exercise to see the creation panels. They are slightly different than the editing panels.

 

.

Add the mapping entry for employeeType.

Configure the Attribute Name Mapping as follows:

  • User Attribute Name: employeeType (must match the SP schema)
  • Assertion Attribute Name: role (must match the Attribute Query defined later)
  • Get Value from User Session: deselected
  • Send with SSO Assertion: selected
  • Require from Infocard: deselected
Click OK.

 

.

Clean up any mappings that will not be used in this example.

Select mobile and click Delete.

Confirm Yes that you want to delete "mobile". You could leave mobile there, it does not hurt anything. Since mobile will not be passed in the assertion, there is nothing to map it to. You are just tidying up.

 

.

Click OK.

The Confirmation should indicate that "mobile has been deleted successfully."

 

Configuring the Service Provider

Most of the preparation for the SP was done when you configured the SP to support linked federations in the previous tutorial (the prerequisite for this tutorial). First verify that the pseudo-users were created correctly, one for each role you expect to use. Then configure the parameters to map the role to the assertion values passed in the SSO.

To configure the role-based federation on the SP side, perform the following steps:

Verifying the Pseudo-Users


Make sure that two pseudo-users are visible to OIF: Manager and Shopclerk.

.

Log in to the Enterprise Manager on the SP.

Go to URL http://hostsp:7001/em and enter User Name: weblogic and Password: Welcome1. Click Login.

 

.

Navigate to configure the Identities to verify that the pseudo-users Manager and ShopClerk were added correctly.

Make sure you are configuring the SP (not the IdP). On the left panel, click OIF(11.1.1.1.0). On the pull-down menu at the top, navigate to Oracle Identity Federation > Administration > Identities.

 

.

Search the local users for pseudo-users Manager and ShopClerk.

Click the Local Users tab. Click Search. You cannot see the other attributes such as phone and employeeType from this display.

 

Configuring Roles on the Service Provider


Configure the SAML assertion settings to specify the query mapping role to a real attribute.

.

Configure the SP parameters.

On the pull-down menu at the top, navigate to Oracle Identity Federation > Administration > Service Provider.

 

.

Configure the SAML Assertion Settings. Based on the check boxes, it appears as if you can select more than one kind of mapping. In fact, these should be radio buttons. You can only pick to Map User via either:

  • Federated Identity or
  • Attribute Query or
  • NameID
Select only one! The GUI interface will let you wrongly select multiple mappings, but then unpredictable results may occur.

On the SAML 2.0 tab, configure the Assertion Settings as follows:

  • Map User via Federated Identity: deselected
  • Enable Auto Account Linking: deselected (but it doesn't matter since this is a subset of the disabled option above)
  • Map User via Attribute Query: selected
  • Attribute Query: (&(employeeType=%role%)) (the "role" must match the Assertion Attribute Name)
  • Map User via NameID: deselected
All of the NameID Formats and User Attribute Mapping fields are ignored since the mapping is via Attribute Query, not NameID.

 

.

Click Apply.

The Confirmation should say that "Changes have been applied."

 

Testing the Role-based Federation

This sample application makes no distinction between what a clerk can see and what a manager can see, but at least it knows that the user is a clerk versus a manager. To test the role-based federation, perform the following steps:

.

Open a separate Web browser window to test the SP Single Sign On (SSO).

Most of these values should be set as defaults in the configuration of earlier tutorials. Just to be sure, set the options as follows:

  • IdP Provider ID: http://hostidp.example.com:7499/fed/idp (it should be the only one in the pull-down list)
  • Authn Request Binding: HTTP POST
  • Allow Federation Creation: selected
  • SSO Response Binding: HTTP POST
  • Name ID Format: does not matter since you are mapping by query attribute, not Name ID.
Click Start SSO.

 

.

Try logging in as someone on the IdP who is not a manager.

Enter a User Name of orcladmin and Password of Welcome1. Click Sign In.

Since there is no employeeType data for orcladmin, there is nothing to match that user to on the SP side. It is important to note that even though there is a user orcladmin on the SP side, and the data is identical between orcladmin on the IdP and on the SP, you cannot match null to null, so orcladmin is denied access to the system using a role-based federation.
WARNING: The administrator is now locked out of the hypothetical MyLife benefits system. Had this been a real system, that would be an issue. You can fix this from ODSM by either making orcladmin a clerk or mgr, or making a new pseudo-user Administrator with employeeType=Admin and making orcladmin employeeType=Admin.

 

.

Try logging in as someone on the IdP who has a matching role (pseudo-user) on the SP.

Enter a User Name of Ira and Password of Welcome1. Click Sign In. It should work equally well for Isabella.

The role shows a value of Mgr. If you try the same experiment for Bob or Igor, it should show a value of Clerk.

 

Summary

The two computers at MyCorp and MyLife trust each other and can establish federations. These federations allow the employees at MyCorp to access the life insurance benefits application hosted at MyLife. The security can be based on two IDs (one on the SP and one on the IdP) linked to each other. Users on the SP need not match users on the IdP only based on email, they could match on any arbitrary field. In this tutorial they matched 1:many on employeeType.

In this tutorial, you have learned how to:

Resources

Credits

Oracle Is The Information Company About Oracle | Oracle RSS Feeds | Careers | Contact Us | Site Maps | Legal Notices | Terms of Use | Your Privacy Rights