29 Managing Partners for Identity Federation Using Oracle Access Management Console

This chapter introduces federation partners for use by Oracle Access Management Identity Federation. This chapter includes the following sections:

Prerequisites
Introduction to Managing Federation Partners
Managing Identity Provider Partners for Federation

29.1 Prerequisites

The topics in this chapter assume that you have performed "Managing the Federation Service" as described in the previous chapter. The current chapter also assumes some familiarity with Oracle Identity Federation 11.1.1, which is described in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Federation.

29.2 Introduction to Managing Federation Partners

Identity Federation features in Oracle Access Management Access Manager enable you to add trusted partners for federated single sign-on operations.

You can create federation partners using the Oracle Access Management Console or the WLST command line utility.

Note:

WLST commands for Identity Federation support using key-value pairs or only the value; Access Manager though only supports key-value pairs. The following example is a WLST command using key-value pairs.

setIdPPartnerAttributeProfileEntry(attrProfileID="openid-idp-attribute-profile", messageAttributeName="http://axschema.org/namePerson", oamSessionAttributeName="name", requestFromIdP="true")

Examples in this document might be defined in either of these manners.

SP-Mode and IdP-Mode Functionality

11g Release 2 (11.1.2.1) provides federation service provider or SP-mode functionality integrated with Access Manager. If you need identity provider (IdP-mode) functionality, however, you must use Oracle Identity Federation 11.1.1.

29.3 Managing Identity Provider Partners for Federation

An identity provider (IdP) is responsible for managing, authenticating, and asserting a set of user identities for its Service Provider (SP) partners. In order for the Identity Federation service to perform SSO with external identity providers, they must be defined as trusted partners.

This section provides the following topics:

Creating Federation Identity Providers
Managing Identity Providers for Federation

29.3.1 Creating Federation Identity Providers

Use the New Identity Provider Page to define an identity provider (IdP) partner record for Access Manager. You can specify service details manually or load them from a metadata file.

Figure 29-1 shows the New Identity Provider page for a federated IdP partner when service details are loaded from metadata.

Figure 29-1 New Identity Provider Page, Service Details Loaded from Metadata

Surrounding text describes Figure 29-1 .

Figure 29-2 shows the New Identity Provider page for a federated IdP partner when service details are entered manually.

Figure 29-2 New Identity Provider Page, Service Details entered Manually

Surrounding text describes Figure 29-2 .

Table 29-1 describes each element on the New Identity Provider page.

Table 29-1 Identity Provider Partner Settings

Element	Description
Name	This is the provider name.
Description	This is a brief description of the provider. (Optional).
Protocol	This is the provider protocol (SAML 1.1, SAML 2.0 and so on).
Service Details	This drop-down enables you to choose whether to enter service details manually or load from metadata.
Metadata File	This field appears if loading metadata from a file. Click Browse to select a file to use.
Issuer ID	This is the issuer ID of the provider.
Succinct ID	This is the succinct ID of the provider. This element is required if using the artifact profile.
SSO Service URL	This is the URL address to which SSO requests are sent.
SOAP Service URL	This is the URL address to which a SOAP service request is sent. This element is required if using artifact profile.
Logout Request Service URL	This is the URL address to which a logout request is sent by the provider. This element is required if using the logout feature.
Logout Response Service URL	This is the URL address to which a logout response is sent. This element is required if using the logout feature.
Signing Certificate	This is the signing certificate used by the provider. You can specify it in `pem` and `der` formats.
User Identity Store	This is the identity store in which the IdP's users will be located and mapped. Identity Federation supports multiple identity stores, defined on a per-partner basis. If no user identity store is selected, the default store defined for Access Manager is used.
User Search Base DN	This is the base search DN used when looking up user records. (Optional. If omitted, the default user search base DN configured for the selected user identity store is used.)
Mapping Option	This setting indicates how an incoming assertion is mapped to a user in the identity store. Select one of the following: Map Assertion Name ID to User ID Store Attribute Enter the identity store attribute to which the assertion NameID will be mapped. Map Assertion Attribute to User ID Store Attribute Enter assertion attribute and the identity store attribute to which it will be mapped. Map Assertion to User Record Using LDAP Query Enter an LDAP query with placeholders for incoming data. You may use: - an attribute from the SAML assertion's `AttributeStatement` element, referenced by its name prefixed and suffixed with the `%` character - the SAML assertion subject's `NameID`, referenced by `%fed.nameidvalue%` - the identity provider's partner name, referenced by %fed.partner%. For example, an LDAP query to map an incoming assertion based on two assertion attributes (lastname and email) would be (&(sn=%lastname%)(mail=%email%)).
Enable Basic HTTP Authentication	Check this box to accept HTTP basic credentials. (Advanced element, available only in provider Edit mode.)

Note:

For identity provider (IdP) functionality, use the 11g Release 1 (11.1.1) Oracle Identity Federation server. For details, see Oracle Fusion Middleware Administrator's Guide for Oracle Identity Federation.

To Define SAML 2.0 Identity Providers for Federation

Take these steps to define a new SAML 2.0 identity provider (IdP):

From the Oracle Access Management Console, go to Federation Identity Providers:
```
System Configuration tab
Federation section
Identity Providers node
```
Click the Create ID Provider button to display the New Identity Provider Page.
SAML 2.0 is typically configured with metadata. In the Service Details drop-down, select "Load from Provider Metadata."
A new field appears named Metadata File. Click Browse.
Select the metadata file of interest.
The metadata is loaded from the file.
Click Save to create the Identity Provider definition.

To Define SAML 1.1 Identity Providers for Federation

Take these steps to create a new SAML 1.1 identity provider (IdP):

From the Oracle Access Management Console, go to Federation Identity Providers:
```
System Configuration tab
Federation section
Identity Providers node
```
Click the Create ID Provider button to display the New Identity Provider page.
Fill in the New Identity Provider page using values for your environment (Table 29-1). The information you provide depends on the protocol chosen for the provider and other factors.
Click Save to create the identity provider definition.

To Define OpenID 2.0 Identity Providers for Federation

In 11g Release 2 (11.1.2.1) the Federation Service supports OpenID, and acts as an OpenID RP/SP. OpenID Providers (OP's) can be registered as IdP partners. Authentication schemes created using these OpenID partners protect OAM resources using authentication services provided by the OpenID identity providers.

Use federation WLST commands to register and manage OpenID IdP partners. The Federation Service supports key-value pair values and single values for the WLST commands but Oracle Access Management Access Manager only supports key-value pair values so be consistent. For example:

setIdPPartnerAttributeProfileEntry(attrProfileID="openid-idp-attribute-profile", 
messageAttributeName="http://axschema.org/namePerson", 
oamSessionAttributeName="name", requestFromIdP="true")

Note:

For more information, see the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

Google IdP Partners

Run this WLST command to add a Google IdP partner:

addOpenID20GoogleIdPFederationPartner()

This creates an IdP partner with the name google using a discovery URL:

https://www.google.com/accounts/o8/id

The partner is configured so that the SP requests the assertion attributes listed in Table 29-2 from the Google IdP and maps them to the corresponding session attribute names:

Table 29-2 Attributes for Google OpenID Partner

Assertion Attribute Name	Session Attribute Name
http://axschema.org/contact/country/home	country
http://axschema.org/contact/email	email
http://axschema.org/namePerson/first	firstname
http://axschema.org/pref/language	language
http://axschema.org/namePerson/last	lastname

The Google partner uses mail as the user mapping attribute, so that an incoming http://axschema.org/contact/email attribute should match the mail attribute of the user in the user identity store.

Use this WLST command to make Google the default IdP:

putStringProperty("/spglobal/defaultssoidp","google")

Yahoo IdP Partners

Run this WLST command to add a Yahoo IdP partner:

addOpenID20YahooIdPFederationPartner()

This creates an IdP partner with the name yahoo using a discovery URL:

https://open.login.yahooapis.com/openid20/user_profile/xrds

The partner is configured so that the SP requests the assertion attributes listed in Table 29-3 from the Yahoo IdP and maps them to the corresponding session attribute names:

Table 29-3 Attributes for Yahoo OpenID Partner

Assertion Attribute Name	Session Attribute Name
http://axschema.org/contact/country/home	country
http://axschema.org/contact/email	email
http://axschema.org/namePerson/first	firstname
http://axschema.org/pref/language	language
http://axschema.org/namePerson/last	lastname

The yahoo partner uses mail as the user mapping attribute, so that an incoming http://axschema.org/contact/email attribute should match the mail attribute of the user in the user identity store.

Use this WLST command to make Yahoo the default IdP:

putStringProperty("/spglobal/defaultssoidp", "yahoo")

Other OpenID 2.0 IdP Partners

Run this WLST command to add an OpenID 2.0 IdP partner other than Google or Yahoo:

addOpenID20IdPFederationPartner(partnerName, idpSSOURL, discoveryURL, description)

where:

partnerName is the name of the partner to be created.
idpSSOURL is the initiate SSO URL of the IdP. Set to "" if the discovery URL is specified and intended to be used.
discoveryURL is the OpenID discovery URL of the IdP. Set to "" if the IdP SSO URL is specified and intended to be used.
description is the partner description. This parameter is optional.

Example 1:

addOpenID20IdPFederationPartner("testpartner1", "", "http://host:port/discoveryurl", description="Test IdP1")

Example 2:

addOpenID20IdPFederationPartner("testpartner2", 
"http://host:port /openidv20/sso", "", description="Test IdP2")

To Set the Identity Store for a Partner IdP

Use this WLST command to specify the identity store used to map users for an IdP. The identity store must be registered in OAM; you can view the registered stores in the administration console by navigating to System Configuration, then Common Configuration, then Data Sources, then User Identity Stores.

setPartnerIDStoreAndBaseDN(partnerName, "idp", storeName, searchBaseDN)

where:

partnerName is the name of the partner to be updated.
storeName is the name of the identity store.
searchBaseDN is the search base DN for the LDAP (optional).

For example:

setPartnerIDStoreAndBaseDN(partnerName="testpartner", partnerType="idp", storeName="testldap", searchBaseDN="dc=company,dc=com")

To Map an Assertion Attribute to a User Attribute

You can specify that an attribute from the OpenID assertion received from the IdP be mapped to a given data store attribute to identify a user. Use this WLST command to configure a partner for assertion mapping of a user with attributes:

setIdPPartnerMappingAttribute(partnerName, assertionAttr,userstoreAttr)

where:

partnerName is the ID of the partner to be updated.
assertionAttr is the attribute in the assertion to be used in mapping.
userstoreAttr is the attribute name in the user store to which the assertion attribute value is mapped.

For example:

setIdPPartnerMappingAttribute(partnerName="testpartner", assertionAttr="email", userstoreAttr="mail")

Note:

To ensure that the assertion received from the IdP contains the assertionAttr being used for user mapping, you can indicate which attributes you want the IdP to send.

For details, see the topic below titled "To Map Attributes."

To Configure an Attribute Profile for an IdP Partner

You can create an attribute profile to indicate which attributes should be requested from the OpenID IdP.

Use this WLST command to create the profile:

createIdPPartnerAttributeProfile(attrProfileID)

where attrProfileID is the identifier referencing the IdP partner attribute profile to be created. For example:

createIdPPartnerAttributeProfile(attrProfileID="openid-idp-attribute-profile")

Next create an attribute profile entry for each attribute that is requested from the IdP:

setIdPPartnerAttributeProfileEntry(attrProfileID, messageAttributeName, oamSessionAttributeName, "true")

where:

attrProfileID identifies the IdP Partner Attribute Profile to which the entry belongs.
messageAttributeName is the name of the requested attribute.
oamSessionAttributeName is the name of the attribute as it will appear in the OAM session ($session.attr.fed.attr.%oamSessionAttributeName%, replacing %oamSessionAttributeName% with the name of the attribute).

For example:

setIdPPartnerAttributeProfileEntry(attrProfileID="openid-idp-attribute-profile", messageAttributeName="http://axschema.org/namePerson", oamSessionAttributeName="name", requestFromIdP="true")

Note:

The final parameter of the command must remain "true" to indicate that this attribute must be requested from the IdP.

Finally, specify the attribute profile you created as the attribute profile to use for your OpenID IdP partner:

setIdPPartnerAttributeProfile(partnerName, attrProfileID)

where:

partnerName is the ID of the IdP partner
attrProfileID is the attribute profile to use for the IdP partner.

For example:

setIdPPartnerAttributeProfile(partnerName="testpartner", attrProfileID="openid-idp-attribute-profile")

To delete an attribute profile

Use the following WLST command to delete an attribute profile:

deleteIdPPartnerAttributeProfile(<attrProfileID>)

where attrProfileID is the identifier of the IdP partner attribute profile to be deleted. For example:

deleteIdPPartnerAttributeProfile("openid-idp-attribute-profile")

Note:

Ensure that there are no partners referring to an attribute profile before deleting an attribute profile.

To designate an OpenId IdP partner as the default Federation IdP

Use this WLST command to designate an OpenId IdP partner as the default Federation IdP:

putStringProperty("/spglobal/defaultssoidp", partnerName)

where partnerName is the ID of the IdP partner to designate as the default Federation IdP. For example:

putStringProperty("/spglobal/defaultssoidp", "testpartner")

To delete an OpenID IdP partner

Use this WLST command to delete an OpenID IdP partner:

deleteFederationPartner(partnerName, "idp")

where partnerName is the ID of the IdP partner. For example:

deleteFederationPartner("testpartner", "idp")

To create an Authentication Scheme to Protect Resources in OAM

You can protect resources in OAM with an authentication scheme that uses the OpenD IdP. Use this WLST command to create the authentication scheme and module:

createAuthnSchemeAndModule(partnerName)

where partnerName is the ID of the IdP partner for which the authentication scheme and module are being created. For example:

createAuthnSchemeAndModule("testpartner")

To Enable OpenID Simple Registration

By default, Identity federation uses the Attribute Exchange extension to obtain user identity attributes from an OpenID IdP. However, if you need to use the older Simple Registration (SREG) extension, you can enable it by running the following WLST commands:

putBooleanProperty("/spglobal/openid20axenabled", "false")
putBooleanProperty("/spglobal/openid20sregenabled", "true")

To Disable OpenID Simple Registration

To switch from the Simple Registration (SREG) extension to the Attribute Exchange extension to obtain user identity attributes from an OpenID IdP:

putBooleanProperty("/spglobal/openid20axenabled", "true")
putBooleanProperty("/spglobal/openid20sregenabled", "false")

29.3.2 Managing Identity Providers for Federation

You can use the following procedure to manage an existing IdP for Identity Federation.

Prerequisites

Enabling the Federation Service

To Search for Existing Identity Providers

Follow these steps:

From the Oracle Access Management Console, go to Federation Identity Providers:
```
System Configuration tab
Federation section
Identity Providers node
```
In the Search section of the page, enter appropriate search criteria for identity provider(s). The characters "*" (asterisk) and "." (period) are supported as search wildcards. See Table 29-4 for details about the search parameters.
Click Search.
The search results are displayed in a table.

Table 29-4 Elements Used for IdP Provider Search

Element	Description
Partner Name	Searches for a specific partner name.
Provider ID	Searches by provider ID.
Status	Searches providers matching a status.
Description	Searches by provider description.
Protocol	Searches for providers that use a specified protocol.

Note:

OpenID 2.0 IdP partners that were created using WLST commands will appear in IdP search results. However, they cannot be edited or updated using the administration console; instead, use the relevant WLST commands.

Table 29-4 demonstrates an example of search results from an IdP search:

Figure 29-3 Searching for Identity Providers

Surrounding text describes Figure 29-3 .

To Update Identity Providers for Federation

From the Oracle Access Management Console, go to Federation Identity Providers:
```
System Configuration tab
Federation section
Identity Providers node
```
Search for the provider you wish to update. See "To Search for Existing Identity Providers" for details.
Select the provider of interest from the search results table.
Click the pencil icon to display the provider update page. The page is divided into sections for: Service Information, Signing Certificates, User Mapping, and Advanced.
Update the provider information. See Table 29-1 for details.

For information on configuring HTTP Basic Authentication to protect SOAP URLs after it has been enabled, see the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Federation.
Click Save to update the Identity Provider definition.

Figure 29-4 shows an example of updating an IdP definition.

Figure 29-4 Updating an Identity Provider

Surrounding text describes Figure 29-4 .