New Features in OAM 11g R2 PS2: Using IDP Federation and Token Issuance Policies

Starting with OAM 11.1.2, the features from Oracle Identity Federation have begun to be merged into the OAM Suite itself to unify the product stack. The first piece was the Service Provider (SP) functionality, which allowed OAM to act as an SP without requiring a separate OIF installation. With the latest OAM release, 11.1.2.2 (PS2), the Identity Provider (IDP) functionality is now available as well.

In this post, we will cover the basics such as creating a Service Provider Partner in OAM, as well as creating a Token Issuance Policy, which allows you to authorize (or not authorize) certain users to generate a SAML assertion for a particular partner.

 

Create a Service Provider Partner and Attribute Profile

From the Launch Pad, click Identity Provider Administration. You will see two tabs: one for Service Provider Partners, and one for Service Provider Attribute Profiles. An Attribute Profile is basically a collection of attribute mappings that will take user attributes and map them to SAML attributes. This is a new feature in PS2 and enables you to customize the SAML assertion going to the Service Provider.

To get started, click the Service Provider Partners tab, and then click Create Service Provider Partner. Specify a name for your SP partner, and import the appropriate SAML 2.0 Metadata. You will also need to specify a NameID format and value, for example Email Address and mail.

Next, click the green plus next to Attribute Profile to create a new Attribute Profile. A new tab will appear. Here you will specify a name for your new Attribute Profile along with the Attribute Mappings. You can add as many mappings as needed for your SAML assertion. Click the New icon in the Attribute Mappings table and the new Attribute Mapping box will appear.

 

The Message Attribute Name is what attribute name will be used in the SAML assertion, and the Value is what you will populate in that attribute. In the above example, we have a SAML assertion attribute named UserDesc mapped to the user’s description attribute. Note that if you check Always Send, the attribute will be included in the SAML assertion even if it was not requested, for example in the case of IDP-initiated SSO.

After adding all of your Attribute Mappings, click Save. Your new Attribute Profile will be available for use with your SP. Click back to the Create Service Provider Partner tab, and select the Attribute Profile you just created. Finally, click Save to finish adding the Service Provider Partner.

 


Be sure to note the name you provided for the SP Partner (in our case, oifsme SP). This will be needed later when you create the TokenServiceRP Resource.

 

Create Token Issuance Policy

Under your Application Domain, click the Token Issuance Policies tab, and then click Create Token Issuance Policy.

On the Summary tab, give the policy a unique name. You can skip the Resource tab for now, because we will define a new TokenServiceRP resource later and associate it to this policy.

On the Conditions tab, click the Plus sign in the top panel to add a new condition. Name it something meaningful like “AllowedUsers” and choose the Token Requestor Identity type. Click OK.

 

Under Condition Details for AllowedUsers, you can specify users or groups that are allowed to have a token issued. Of course, you could also specify a list of users that are not allowed and add a True condition to allow everyone except those users. Basically this is just like the Authorization Policies you create for HTTP resource, so the same rules apply.

So click the Plus sign, then Add Identities.  Search the Identity Store for the users or groups you wish to specify. In our example, we have an LDAP group called ApprovedFedUsers that will contain one or more uniqueMembers who are allowed to Federate. Select the group, and then click Add Selected. Here’s what the finished Condition will look like:

 

Finally, on the Rules tab, under the Allow Rule, click the blue arrow to move the AllowedUsers condition from Available Conditions to Selected Conditions, then save your changes.

 

 

Create TokenServiceRP Resource

Now that you have a Token Issuance Policy, you have to create a resource in OAM that corresponds to the Service Provider to which you will be issuing SAML assertions (tokens). To do this, you will create a new Resource in your Application Domain of type TokenServiceRP.

In your Application Domain, click on the Resources tab, and then click New Resource. Select TokenServiceRP as the Type. For Resource URL, you must provide the Partner Name you specified when creating the Service Provider Partner, not the Provider ID of the SP. This was a confusing point, as the documentation does not spell this out explicitly. Remember, this must match EXACTLY – case matters.

 

 

Finally, select the Token Issuance Policy you created earlier and click Apply.

 

Testing

You can test the SP Partner, Attribute Profile, and Token Issuance Policy configuration by using the ODP-initiated SSO link:

http://hostname:14100/oamfed/idp/initiatesso?providerid={providerID}

The providerid is the SAML provider ID that can be found in the SP Partner configuration. You will be prompted to specify credentials to login. Note that this authentication happens against the default identity store. If the user matches the Allow Rule Condition you defined previously, the SSO will happen successfully.

If the user is denied via the Token Issuance Policy, you will see the default out of the box OAM error page. The good news is, there is a way to customize this.

Customizing Authorization Denied Page

This is a nice trick to customize the Authorization Denied page that is not documented (at least not that we could find). Many of the configuration settings in the oam-config.xml for the federation functionality actually share the same names with their counterparts in the legacy OIF 11.1.1.x configuration file, so we were able to find where OAM store the custom error page settings.

Search for the setting called “urlerror401”. Here you can specify a custom page that OAM will direct you to in case of a Token Issuance Policy denial (which is a 401).