31 Managing Identity Federation Partners

This chapter introduces the concept of federation partners (service providers and identity providers) in Oracle Access Management Identity Federation. This chapter includes the following sections:

31.1 Understanding Federation And Partners

The topics in this chapter assume some familiarity with the federation and partner concepts described in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Federation. The current chapter also assumes that you have performed Section 30.8, "Enabling Identity Federation" as described.

31.2 Managing Federation Partners

This 11g Release 2 (11.1.2.2) of the integrated Identity Federation provides the ability to be configured as a Service Provider (SP) or an Identity Provider (IdP). Following this provider definition, remote providers (whether service or identity) partnered in Federation SSO need to be managed as well. Towards this end, Identity Federation developed the configuration hierarchy concepts of a partner and a partner profile.

  • A partner profile refers to settings specific to a partner type (IdP or SP) or a protocol version (SAML 2.0, SAML 1.1, OpenID 2.0). It is a configuration group that represents a sets of common properties that apply to all partners that reference it. It contains mostly secondary configuration objects such as Authentication Method mappings, cryptographic settings (SHA-1 vs SHA-256) and the like.

  • A partner refers to the configuration for a specific organization partnered in the Federation SSO process. Each partner is associated with a partner profile. The partnerprofileid property in a Partner entry defines the partner profile to which this partner is assigned. If the partnerprofileid property is not defined, the default Partner Profile for the Partner (based on the Partner type and the Partner protocol) will be used.

All Partners associated with the same Partner Profile will share its defined settings unless they are specifically overridden for a partner at the Partner configuration level. A Partner configuration overrides a Partner Profile configuration which, in turn, overrides a global configuration.

Partner profiles are only manageable using WLST commands. Each new partner created will be bound to one of the default partner profiles listed in Table 31-1. To assign a new partner profile to a partner, use the setFedPartnerProfile() WLST command after creating the partner. See Section 31.9, "Using WLST for Identity Federation Administration" for details.

Table 31-1 Default Partner Profiles

Default Partner Profile Description

saml20-idp-partner-profile

SAML 2.0 Partner Profile for IdP partners

saml20-sp-partner-profile

SAML 2.0 Partner Profile for SP partners

saml11-idp-partner-profile

SAML 1.1 Partner Profile for IdP partners

saml11-sp-partner-profile

SAML 1.1 Partner Profile for SP partners

openid20-idp-partner-profile

OpenID 2.0 Partner Profile for IdP partners

openid20-sp-partner-profile

OpenID 2.0 Partner Profile for SP partners

31.3 Administering Identity Federation As A Service Provider

When the integrated Identity Federation is configured as an SP, you must define any remote IdP partners as trusted by creating and managing profiles that contain details regarding each remote IdP. To begin administration of the integrated Identity Federation server as an SP, click the Service Provider Administration link under Identity Federation from the Launch Pad in the Oracle Access Management Console. This section provides the following topics.

31.3.1 Creating Remote Identity Provider Partners

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 31-1 shows the Create Identity Provider Partner page when service details are configured by loading an XML metadata file.

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

Surrounding text describes Figure 31-1 .

Figure 31-2 shows the Create Identity Provider Partner page when service details are configured by entering values manually.

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

Surrounding text describes Figure 31-2 .

Table 31-2 describes each element on the New Identity Provider page.

Table 31-2 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. Applies to SAML 2.0 only.

Issuer ID

This is the issuer ID of the provider. Applies to SAML 2.0 and SAML 1.1 only.

Succinct ID

This is the succinct ID of the provider. This element is required if using the artifact profile. Applies to SAML 2.0 and SAML 1.1 only.

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. Applies to SAML 2.0 only.

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. Applies to SAML 2.0 only.

Signing Certificate

This is the signing certificate used by the provider. You can specify it in pem and der formats. Applies to SAML 2.0 and SAML 1.1 only.

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. Optionally, if no user identity store is selected, the default Access Manager store 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.)

Attribute Mapping Profile

Indicates the attribute profile to which the partner is bound.

Service Details

Indicates which of the following options Identity Federation (the RP) uses to perform Federation SSO with the IdP. Applies to OpenID 2.0 only.

  • By discovering the IdP SSO URLs via the IdP XRDS metadata available at the Discovery Service URL.

  • By using the specified static OpenID login endpoint which is the IDP SSO service URL.

Discovery URL

Defines the location where the IdP publishes its XRDS metadata. Applies to OpenID 2.0 only.

Endpoint URL

Defines the IdP SSO Service location. Applies to OpenID 2.0 only.

Enable Global Logout

Indicates whether or not Identity Federation should notify the remote partner when the user is signing off during the logout flow. Applies to SAML 2.0 only.

HTTP POST SSO Response Binding

Indicates whether the SAML Assertion should be sent back from the IdP using the HTTP POST Binding or the Artifact Binding. Applies to SAML 2.0 only.

Authentication Request NameID Format

Indicates the NameID format that Identity Federation will request from the IdP during the Federation SSO operation. If none is selected, a NameID format is not specified in the request. Applies to SAML 2.0 only.
   

Note:

For 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):

  1. From the Oracle Access Management Console, click Service Provider Administration.

  2. Click the Create ID Provider button to display the New Identity Provider Page.

  3. SAML 2.0 is typically configured with metadata. In the Service Details drop-down, select "Load from Provider Metadata."

  4. A new field appears named Metadata File. Click Browse.

  5. Select the metadata file of interest.

  6. The metadata is loaded from the file.

  7. 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):

  1. From the Oracle Access Management Console, click Service Provider Administration.

  2. Click the Create ID Provider button to display the New Identity Provider page.

  3. Fill in the New Identity Provider page using values for your environment (Table 31-2). The information you provide depends on the protocol chosen for the provider and other factors.

  4. Click Save to create the identity provider definition.

    Note:

    Some SAML 1.1 configuration parameters are not exposed through the Oracle Access Management Console. The values of these parameters can be modified using the updatePartnerProperty WLST command. For details, see the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

To Define OpenID 2.0 Identity Providers for Federation

In 11g Release 2 (11.1.2.2) the Identity Federation supports OpenID, and acts as an OpenID RP/SP. OpenID Providers can be registered as IdP partners. Authentication schemes created using these OpenID partners protect Access Manager resources using authentication services provided by the OpenID identity providers. Take these steps to create a new OpenID 2.0 identity provider (IdP).

  1. Log in to the Oracle Access Management Console.

  2. From the Launch Pad, click Service Provider Administration under Identity Federation.

  3. Click the Create Identity Provider Partner button.

    The Create Identity Provider Partner page is displayed.

  4. Fill in the values appropriate for your environment either manually or by uploading a metadata file.

    The information you provide depends on the protocol chosen for the provider and other factors.

  5. Click Save to create the identity provider definition.

Google IdP Partners

Take these steps to add Google as an OpenID 2.0 IdP.

  1. Log in to the Oracle Access Management Console.

  2. From the Launch Pad, click Service Provider Administration under Identity Federation.

  3. Click the Create Identity Provider Partner button.

    The Create Identity Provider Partner page is displayed.

  4. Select OpenID 2.0 from the Protocol drop down menu.

  5. Select Google provider default settings from the Service Details drop down menu.

  6. Click Save to create the identity provider definition.

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

Table 31-3 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.

Yahoo IdP Partners

Take these steps to add Yahoo as an OpenID 2.0 IdP.

  1. Log in to the Oracle Access Management Console.

  2. From the Launch Pad, click Service Provider Administration under Identity Federation.

  3. Click the Create Identity Provider Partner button.

    The Create Identity Provider Partner page is displayed.

  4. Select OpenID 2.0 from the Protocol drop down menu.

  5. Select Yahoo provider default settings from the Service Details drop down menu.

  6. Click Save to create the identity provider definition.

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

Table 31-4 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.

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")

31.3.2 Managing the Remote Identity Provider Partners

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

To Search for Existing Identity Providers

Follow these steps:

  1. From the Oracle Access Management Console, click Service Provider Administration.

  2. 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 31-5 for details about the search parameters.

  3. Click Search.

  4. The search results are displayed in a table.

Table 31-5 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.

Table 31-5 demonstrates an example of search results from an IdP search.

Figure 31-3 Searching for Identity Providers

Surrounding text describes Figure 31-3 .

To Update Identity Providers for Federation

  1. From the Oracle Access Management Console, click Service Provider Administration.

  2. Search for the provider you wish to update. See "To Search for Existing Identity Providers" for details.

  3. Select the provider of interest from the search results table.

  4. 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.

  5. Update the provider information. See Table 31-2 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.

  6. Click Save to update the Identity Provider definition.

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

Figure 31-4 Updating an Identity Provider

Surrounding text describes Figure 31-4 .

31.4 Administering Identity Federation As An Identity Provider

When the integrated Identity Federation is configured as an IdP, you must define any remote SP partners as trusted by creating and managing profiles that contain details regarding each remote SP. This section provides the following topics.

31.4.1 Creating Remote Service Provider Partners

Use the Service Provider Partner page to define a partner profile when Identity Federation is configured as an IdP. You can specify service details manually or load them from a metadata file.

  1. Log in to the Oracle Access Management Console as administrator.

    The Launch Pad is displayed.

  2. Click Identity Provider Administration under Identity Federation.

    The Identity Provider Administration page is displayed.

  3. Click the Create Service Provider Partner button.

    The Create Service Provider Partner page is displayed.

  4. Enter values for the parameters.

    Table 31-6 describes each element on the New Service Provider page.

    Table 31-6 Service Provider Partner Settings

    Element Description

    Name

    This is the provider name.

    Enable Partner

    Select whether this partner is currently participating in the federation.

    Description

    This is a brief description of the provider. (Optional).

    Protocol

    This is the provider protocol (SAML 1.1, SAML 2.0 or OpenID 2.0).

    Service Details

    Select whether to enter service details manually or load from metadata. If selecting the latter, browse for the metadata file. Applies to SAML 2.0 only.

    Metadata File

    This field appears if loading metadata from a file. Click Browse to select a file to use. Applies to SAML 2.0 only.

    Provider ID

    The provider ID or issuer ID of the remote Service Provider. Applies to SAML 2.0 and SAML 1.1 only.

    Assertion Consumer URL

    A URL to which Assertion responses are sent. Applies to SAML 2.0 and SAML 1.1 only.

    Load Signing Certificate

    Upload the signing certificate used by this SP. Only visible when Enter Manually is selected. Applies to SAML 2.0 and SAML 1.1 only.

    Logout Request URL

    A URL to which logout requests are sent. Applies to SAML 2.0 only.

    Logout Response URL

    A URL to which responses to logout requests are sent. Applies to SAML 2.0 only.

    Load Encryption Certificate

    Upload the encryption certificate used by this SP. Only visible when Enter Manually is selected. Applies to SAML 2.0 only.

    NameID Format

    Indicates which NameID format should be used for this SP. Applies to SAML 2.0 and SAML 1.1 only. See Section 30.4.1, "Using SAML 2.0" or Section 30.4.2, "Using SAML 1.1" respectively for details on the NameID format.

    NameID Value

    Indicates how to populate the NameID Value. Applies to SAML 2.0 and SAML 1.1 only.

    • If User ID Store Attribute is selected, specify the user attribute to be used.

    • If Expression is specified, enter the expression to be used

    Attribute Mapping Profile

    Indicates the attribute mapping profile to which the partner is bound. Applies to SAML 2.0 and SAML 1.1 only.

    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. (This is only relevant when OIF is an Attribute Authority for the SAML Attribute Sharing protocol. It is not used during SSO.)

    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.)

    Enable Global Logout

    Indicates whether or not OIF should notify the remote partner when the user is signing off, during the logout flow. Applies to SAML 2.0 only.

    SSO Response Binding

    Indicates whether the SAML Assertion should be sent back from the IdP using the HTTP POST Binding or the Artifact Binding, Applies to SAML 2.0 and SAML 1.1 only.

    Encrypt Assertion

    Indicates whether or not the Assertion should be encrypted for this partner. Applies to SAML 2.0 only.

    Realm

    The URL identifying an OpenID SP. Applies to OpenID 2.0 only.

    Endpoint URL

    The URL to which the IdP will redirect the user with the OpenID Assertion. Applies to OpenID 2.0 only.

  5. Click Save to create the remote SP partner profile.

31.4.2 Managing the Remote Service Provider Partners

To edit and manage the profiles of remote SP partners, search for the profile and make changes to the attribute values.

To Search for Existing Service Provider Partner Profiles

  1. Click Identity Provider Administration under Identity Federation in the Oracle Access Management Console Launch Pad.

    The Identity Provider Administration page is displayed.

  2. 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 31-5 for details about the search parameters.

  3. Activate the Search Service Provider Partners tab.

  4. Enter the search criteria and click Search.

    The search results are displayed.

  5. Select the appropriate partner in the Search Results table and select Edit under Actions (or click the pencil).

    A new tab is activated that displays the partner's attributes. In addition to the attributes documented in Table 31-6, the following advanced attributes can be modified.

    • Enable Global Logout

    • Encrypt Assertion

    • SSO Response Binding (HTTP POST or Artifact)

  6. Click Save to keep the changes.

Note:

If using SAML 1.1, you can include a certificate in the signature. See Oracle Fusion Middleware WebLogic Scripting Tool Command Reference for details.

31.5 Using Attribute Mapping Profiles

Identity Federation (when configured as an SP) supports the capability to request attributes from an IdP during the Federation process. To configure for this, map the name of an attribute from the incoming Assertion to a local attribute that will be available in the Access Manager session ($session.attr.fed.attr.ATTR_NAME, for example). An IdP Attribute Mapping Profile contains these mappings.

Similarly, Identity Federation (when configured as an IdP) supports including attributes in an SSO Assertion or allowing SP partners to request that attributes be placed in the SSO Assertion. Configuring Identity Federation as an IdP involves setting up an SP Attribute Mapping profile that defines the name of the attribute in the SSO assertion, the expression to be used to populate the attribute value, and whether or not to always send the attribute in the SSO Assertion.

Note:

The protocol used by the provider must support the feature; for example, OpenID 2.0.

Each partner type (IdP or SP) references an Attribute Mapping Profile that defines the applicable mappings. It indicates how to map attributes for that partner to attributes defined in the Identity Federation server. If a partner does not have an Attribute Mapping Profile defined, the default Attribute Mapping Profile (based on the partner type) will be used. There is a default Attribute Mapping Profile for each provider type.

31.5.1 Using the SP Attribute Mapping Profile

When the Identity Federation instance is configured as an IdP, the SP Attribute Mapping Profile allows the administrator to define which message attributes (included in an incoming or outgoing Identity Federation message) map to which Access Manager session attributes. An expression is used to find the value for the Access Manager attribute when including it in an Assertion or outgoing message. Table 31-7 documents some sample SP attribute mappings.

Table 31-7 Sample SP Attribute Mappings

Message Attribute Access Manager Session Attribute Always Send

mail

$user.attr.mail

  

firstname

$user.attr.givenname

true

lastname

$user.attr.sn

true

authn-level

$session.authn_level

true

Always Send indicates if the attribute should be sent even when it has not been specifically requested. If an attribute has to be included in an outgoing Assertion irrespective of whether it has been requested, Always Send should be set to true. If Always Send is false, this attribute will not be included in the Assertion unless requested. When an SP sends a request, message attributes are looked up and the mapping value for this message attribute is calculated by evaluating its expression.

Note:

The Value expression will use the OAM Policy Expression Language as documented in Section 20.9, "Introduction to Policy Responses for SSO." More than one message attribute can have the same value expression.

When creating or modifying an SP partner profile (as documented in Section 31.4.1, "Creating Remote Service Provider Partners"), the available Attribute Mapping Profiles are displayed in a drop-down list. sp-attribute-profile is the default profile. Select the default or click the green plus sign to create a custom mapping profile. When creating a new Attribute Mapping for an SP partner, the expressions documented in Table 31-8 can be embedded in the value string of the attribute. These expressions will be replaced by their runtime values.

Table 31-8 Attribute Mapping Value Expressions

Value Type Accepted Values Expression

request

httpheader.HTTP_HEADER_NAME

HTTP_HEADER_NAME being the name of an HTTP Header stored as $request.httpheader.HTTP_HEADER_NAME
 

cookie.COOKIE_NAME

COOKIE_NAME being the name of a cookie stored as $request.cookie.COOKIE_NAME
 

client_ip

stored as $request.client_ip

session

authn_level

stored as $session.authn_level
 

authn_scheme

stored as $session.authn_scheme
 

count

stored as $session.count
 

creation

stored as $session.creation
 

expiration

stored as $session.expiration
 

attr.ATTR_NAME

ATTR_NAME being the name of an Access Manager Session Attribute stored as $session.attr.ATTR_NAME

user

userid

stored as $user.userid
 

id_domain

stored as $user.id_domain
 

guid

stored as $user.guid
 

groups

stored as $user.groups
 

attr.ATTR_NAME

ATTR_NAME being the name of an LDAP User Attribute stored as $user.attr.ATTR_NAME

expression

(Based on the identifiers defined above and qualified with the type of data)

- request:

  • $request.httpheader.HTTP_HEADER_NAME

  • $request.cookie.COOKIE_NAME

  • $request.client_ip

-

  • HTTP_HEADER_NAME being the name of an HTTP Header

  • COOKIE_NAME being the name of a cookie
 

- session:

  • $session.authn_level

  • $session.authn_scheme

  • $session.count

  • $session.creation

  • $session.expiration

  • $session.attr.ATTR_NAME

-

  • ATTR_NAME being the name of an Access Manager Session Attribute
 

- from user:

  • $user.userid

  • $user.id_domain

  • $user.guid

  • $user.groups

  • $user.attr.ATTR_NAME

  • can be any string, with '.' (dot) characters, spaces characters (like "$user.userid" or "$user.attr.givenname $user.attr.sn" or "This is the number of sessions: $session.count")

-

  • ATTR_NAME being the name of an LDAP User Attribute

31.5.2 Using the IdP Attribute Mapping Profile

When the Identity Federation instance is configured as an SP, the IdP Attribute Mapping Profile allows the administrator to define which attributes (included in an incoming or outgoing Identity Federation message) map to which Access Manager session attributes. The profile allows for the inclusion of the following data:

  • Message Attribute: the name of the attribute in the incoming/outgoing Federation messages.

  • Access Manager Session Attribute: the name by which the attribute is known to the local Access Manager server.

  • Request From Partner: Indicates if this attribute is sent in the Request made to the IdP (a value for this attribute is requested by the SP).

Table 31-9 documents sample IdP attribute mappings.

Table 31-9 Sample IdP Attribute Mappings

Message Attribute Access Manager Session Attribute Request for Inclusion

mail

email

true

givenname

  

true

sn

surname

  

uid

uid

  

In a protocol where a SP can specify which attributes are required in a response from the IdP, a Message Attribute name is sent in the request to the IdP. In cases when the SP receives an assertion or response from an IdP, the Attributes from the assertion are stored in the Access Manager session. If no Access Manager value is specified, the Message Attribute is stored.

When creating or modifying an IdP partner profile (as documented in Section 31.3.1, "Creating Remote Identity Provider Partners"), the Attribute Mapping Profile is displayed with a drop-down list. The idp-attribute-profile is the default profile. Select the default or click the green plus sign to create a custom mapping profile.

The Ignore Umapped Attributes checkbox (in the configuration screen) indicates how to deal with Assertion Attributes not present (or that are present but have no value in the Access Manager Session Attribute column). If this checkbox is not checked, all Assertion Attributes that are not present in the table (or don't have a value mapped to Access Manager) will be stored in the Access Manager session with the same attribute name it had in the Assertion. If checked, any Assertion Attribute not present in the table (or with no value mapped to Access Manager) will be ignored and not added to the Access Manager session.

Note:

When the Identity Federation instance is configured as an SP it can request attributes only if the federation protocol used supports it. OpenID 2.0 supports this feature; SAML 2.0 and SAML 1.1 do not.

31.6 Mapping Federation Authentication Methods to Access Manager Authentication Schemes

A Federation Authentication Method (FAM) is an identifier representing an authentication mechanism in Federation messages. This identifier can either be well known (such as the identifiers defined in the SAML specifications like urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport or urn:oasis:names:tc:SAML:1.0:am:password) or it can be an arbitrary identifier agreed upon between the two communicating partners.

In its responsibilities as an IdP, Identity Federation generates an Assertion (SAML or OpenID) that might contain information on how the user was authenticated. During the Assertion generation process, the IdP will retrieve the Authentication Scheme with which the user was authenticated and attempt to map it to a FAM. If such a mapping exists, the IdP will include the FAM in the outgoing Assertion. If no mapping exists, the IdP will include the defined Authentication Scheme as the FAM in the Assertion.

Note:

Session attributes can be used in proxy mode when a mapping is not defined. Identity Federation (when acting as an IdP) can use session attributes for the FAM value when creating the assertion, if both protocols are equivalent.

Table 31-10 lists the default, out-of-the-box mappings between FAMs and Access Manager Authentication Schemes.

Table 31-10 Default Federation Authentication Method and Access Manager Authentication Scheme Mappings

Protocol Mapping

saml20-sp-partner-profile

urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport to:

  • LDAPScheme (scheme used if the SP Partner requests urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport)

  • FAAuthScheme

  • BasicScheme

  • BasicFAScheme

saml11-sp-partner-profile

urn:oasis:names:tc:SAML:1.0:am:password to:

  • LDAPScheme (scheme used if the SP Partner requests urn:oasis:names:tc:SAML:1.0:am:password)

  • FAAuthScheme

  • BasicScheme

  • BasicFAScheme

More details are in the following sections.

31.6.1 Understanding Federation SSO As An IdP

When Identity Federation acts as an IdP, it processes incoming Authentication Request messages sent by SP partners. These messages might specify a FAM with which the user should be challenged by Access Manager (the IdP). If the Authentication Request contains a FAM, the IdP will attempt to map it to an Access Manager Authentication Scheme. If such a mapping is defined, Access Manager will authenticate the user using that scheme - only if the user needs to be challenged. The user would need to be challenged if, for example, the session timed out or does not exist or, the authentication level of the current session is lower than the level of the mapped Authentication Scheme or, the user has not yet been authenticated by Access Manager. If no mapping is defined, the IdP will return an error to the SP indicating that the FAM is unknown.

When the IdP Authentication Module invokes Access Manager to challenge the user, it will determine the Authentication Scheme to be used for the operation in one of the following ways:

  • The SP requests a specific means to authenticate the user with a Federation Authentication Request.

  • The SP settings in the IdP configuration that define a default scheme. The Partner configuration is checked first, followed by the Partner Profile configuration and finally the global default Authentication Scheme defined in the IdP configuration (LDAPScheme).

Note:

By default, the Partner and Partner Profile configurations do not define a default Authentication Scheme. As such, the global default Authentication Scheme is in effect: LDAPScheme.

After authentication, the IdP creates an Assertion and maps the Access Manager Authentication Scheme (and appropriate level) to a FAM, if such a mapping exists. The FAM is set as the Authentication Context. If no mapping exists, Identity Federation sends the default Access Manager Authentication Scheme as the Authentication Context. Following this process, the user is redirected back to Identity Federation.

31.6.2 Understanding Federation SSO As An SP

When acting as an SP in a Federation SSO process, Identity Federation processes an incoming Assertion generated by an IdP partner. This process results in the creation of an Access Manager session for the user and the mapping of the FAM contained in the Assertion to the default SchemeID/Access Manager authentication scheme. Identity Federation provides the authentication level, if set, that should be used when Access Manager creates the user session. (By default, the Authentication Level of the Access Manager session will be set to the Authentication Level of the defined FederationScheme.) The FAM will be saved as a session attribute.

The administrator can define a mapping where the SP will create an Access Manager session with a level set to the mapped Authentication Level for the FAM contained in the Assertion. This provides a way to reflect the strength of the mechanism with which the user was originally authenticated by the IdP.

31.6.3 Configuring an Alternate Authentication Scheme

During a Federation SSO operation, the IdP invokes the Access Manager Authentication Module to challenge the user when required; for example, if the user is not authenticated in Access Manager, has an Access Manager session that has been inactive too long or timed out or, if the Service Provider indicates (with a Federation Authentication Request) that the IdP must re-challenge the user. For certain clients, an IdP might be required to use another Authentication Scheme to challenge a user besides the default one. This is especially true for mobile phones when an administrator might want to challenge a user with an Authentication Scheme that is different than the one used for computer-based browsers; for example, instead of an HTTP Basic Authentication Scheme, a scheme designed for mobile clients would be used.

Identity Federation (when working as an IdP) can be configured to evaluate whether an alternate Authentication Scheme should be used instead of the configured one by examining the HTTP Header sent by the user's browser. Identity Federation evaluates based on the following configurable settings:

  • A setting indicating which HTTP Header attribute is sent by the user's browser.

  • A setting containing a regular expression that will evaluate the value of the above HTTP Header attribute.

  • A setting containing the alternate Authentication Scheme to use.

Note:

If the SP requested a specific Authentication Scheme, evaluation does not apply.

An alternate Authentication Scheme is only configurable using WLST commands and not the Oracle Access Management Console. For information on the setSPPartnerAlternateScheme and setSPPartnerProfileAlternateScheme WLST commands, see the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

31.6.4 Using WLST For Mapping Administration

All Authentication Method/Scheme/Level mappings are configured using the WLST commands. This can be done either at the partner level or, if not defined at the partner level, at the partner profile level. See Section 31.9, "Using WLST for Identity Federation Administration" for details.

31.7 Using the Attribute Sharing Plug-in for the Attribute Query Service

Identity Federation provides an attribute sharing plug-in to enable Access Manager to request user attributes from an IdP. In this interaction, the SP is an <AttributeQuery> requestor and the IdP is an <AttributeQuery> responder. The Attribute Sharing Plug-in depends on the Attribute Query Service, a request/response protocol transported using SOAP.

Note:

The Attribute Sharing Plug-in leverages the AttributeQuery requestor service to implement (a superset of) the X.509 Authentication Based Attribute Sharing Profile (XASP) in the context of Access Manager authentication flows.

Identity Federation (when configured as an SP) can send a SAML 2.0 <AttributeQuery> to the IdP in response to a SOAP call. The plug-in can be configured as a step in an Authentication Scheme. It can be invoked after authentication (by another plug-in) to fetch attributes for the authenticated user and set them into the Access Manager session. The following sections contain additional details.

31.7.1 Understanding the Plug-in and Query Service Design

Identity Federation must be configured as an SP to request user attributes from a remote IdP. From a high level, the design of the Attribute Sharing plug-in is illustrated in Figure 31-5.

Figure 31-5 Attribute Sharing Plug-in Design

Description of Figure 31-5 follows
Description of "Figure 31-5 Attribute Sharing Plug-in Design"

The Attribute Sharing plug-in can be part of an Access Manager Custom Authentication Module and is invoked after a user has been authenticated. The Attribute Sharing plug-in will fetch the user attributes by invoking the Identity Federation Java API, setting the attributes into the Access Manager session and transforming the Java arguments into an Attribute Request that can be processed by the SP. The Identity Federation SP receives the Attribute Request (at an exposed SOAP endpoint), determines the attributes being requested and sends an (optionally) signed and encrypted SAML 2.0 <AttributeQuery> using the requested attribute names over a SOAP/HTTP/SSL channel to the IdP's Attribute Responder Service.

Note:

When invoking the Attribute Sharing plug-in, the framework will provide the following for inclusion in the <AttributeQuery>:

  • User ID of the authenticated user or SubjectDN if available

  • Partner ID user session attribute (available only if the Federation Authentication plug-in was used to authenticate user)

  • Tenant Name

  • IdP Name if the plug-in was created specifically for an IdP

The Attribute Responder Service (at the remote IdP) receives the <AttributeQuery>, decrypts it (verifying the signature if necessary) and determines (from its local policy) if the SP is authorized to request the attributes. If so, it retrieves the attributes from a user repository, constructs and (optionally) signs and encrypts an <Assertion> (with an <AttributeStatement> containing the attribute values) and returns a <Response> with the assertion to the SP. On receiving the <Response>, the SP decrypts the assertion, verifies (if necessary) its signature, extracts the attributes from the assertion and set the information in the Access Manager session. The following sections contain more details.

31.7.1.1 Using the SP Attribute Requester

The Attribute Requester Service processes the SOAP Attribute Request and returns a SOAP Attribute Response. (See Section 31.7.1.3, "Using the SOAP Endpoint" for details.) The Attribute Request will contain a SubjectDN and a list of other requested attributes and their values. The Attribute Requester Service identifies the IdP from which to fetch attributes by extracting one of the following (searched for in the order listed) from the request.

  1. The partner/IdP name if the request comes from the Federation engine.

  2. The IdP configured in the plug-in used for authentication.

  3. The request's Subject DN to determine which IdP will get the query from the configured SubjectDN-IdP map. Map the SubjectDN from most specific (cn=Joe User,ou=Finance,o=Company,c=US) to least specific (c=US).

  4. The default IdP.

Following this discovery, the Attribute Requester Service retrieves the SOAP Attribute Responder Service endpoint URL from the IdP's metadata and creates a list of attributes to fetch by processing the attributes in the request through the Attribute Mapping profile.

Note:

Attribute Mapping profile specified for the target IdP will be used to change any incoming attribute names as well as add any attributes that are configured as send-with-sso (always requested) in the Attribute Mapping for this IdP.

A SAML Attribute Query is generated with the attribute list and sent to the IdP's SOAP endpoint. Once a response is received, the subject is verified and the each attribute is extracted from the Assertion, its value is found and both attribute and value are cached. Finally, an Attribute Response SOAP message is constructed and returned to the caller. Example 31-1 is a sample SOAP Attribute Request.

Example 31-1 Sample SOAP Attribute Request

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body>
      <attrreq:AttributeRequest TargetIDP="adc.example.com"
          xmlns:attrreq="http://www.example.com/fed/ar/10gR3">
      <attrreq:Subject
         Format="oracle:security:nameid:format:emailaddress">alice@example.com
      </attrreq:Subject>
         <attrreq:Attribute Name="cn">
         </attrreq:Attribute>
      </attrreq:AttributeRequest>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Example 31-2 is a sample SOAP attribute response.

Example 31-2 Sample SOAP Attribute Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <soap:Envelope xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"  xmlns:ns2="http://www.w3.org/2005/08/addressing"  xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"  xmlns:enc="http://www.w3.org/2001/04/xmlenc#"  xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"  xmlns:wst14="http://docs.oasis-open.org/ws-sx/ws-trust/200802"  xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"  xmlns:ic="http://schemas.xmlsoap.org/ws/2005/05/identity"  xmlns:mdext="urn:oasis:names:tc:SAML:metadata:extension"  xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust"  xmlns:ns11="http://docs.oasis-open.org/ws-sx/ws-trust/200512"  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"  xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"  xmlns:ns14="urn:oasis:names:tc:SAML:2.0:assertion"  xmlns:xrds="xri://$xrds" xmlns:xrd="xri://$xrd*($v*2.0)"  xmlns:tns="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"  xmlns:ns18="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"  xmlns:ns19="urn:oasis:names:tc:SAML:1.0:protocol"  xmlns:ns20="http://www.w3.org/2003/05/soap-envelope"  xmlns:wsse11="http://docs.oasis-open.org/wss/
   oasis-wss-wssecurity-secext-1.1.xsd"  xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"  xmlns:query="urn:oasis:names:tc:SAML:metadata:ext:query"  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
   oasis-200401-wss-wssecurity-utility-1.0.xsd"  xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/
   oasis-200401-wss-wssecurity-secext-1.0.xsd"  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  xmlns:x500="urn:oasis:names:tc:SAML:2.0:profiles:attribute:X500"  xmlns:orafed-arxs="http://www.oracle.com/fed/ar/10gR3/"  xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute"  xmlns:ns31="urn:oasis:names:tc:SAML:profiles:v1metadata"  xmlns:ecp="urn:oasis:names:tc:SAML:2.0:profiles:SSO:ecp"> 
<soap:Body><orafed-arxs:AttributeResponse CacheFor="899"> <orafed-arxs:Status>Success</orafed-arxs:Status> <orafed-arxs:Subject Format="oracle:security:nameid:format:emailaddress">
   alice@example.com</orafed-arxs:Subject> <orafed-arxs:Attribute Name="cn"> <orafed-arxs:Value>alice</orafed-arxs:Value> </orafed-arxs:Attribute> </orafed-arxs:AttributeResponse></soap:Body></soap:Envelope>

31.7.1.2 Using the IdP Attribute Responder

The Identity Federation IdP Attribute Responder receives the SAML Attribute Query and returns a SAML response with an Attribute Statement that contains values for the requested attributes. The IdP first identifies the requester as an SP partner and then confirms that the user is in the user data store by searching on the NameId or SubjectDN value. It then uses the Attribute Mapping profile of the SP partner to retrieve values for each of the requested attributes. Finally, it constructs and returns a SAML response containing an Attribute Statement with attribute values. (This is only relevant when OIF is an Attribute Authority for the SAML Attribute Sharing protocol. It is not used during SSO.)

Note:

The Attribute Responder uses the SP partner's Attribute Mapping profile to retrieve values. An empty value is returned for an attribute if there is no mapping present in the Attribute Mapping profile. If the value expression contains variables in the namespace of a session or request, this also evaluates to an empty string. Value Expressions in the Attribute Mapping Profile can only use variables in the namespace of user.attr to be evaluated correctly.

31.7.1.3 Using the SOAP Endpoint

The Attribute Requester Service on the SP exposes a SOAP interface for client requests. The SOAP service is available on the SP at the following URL:

http://<SP-managed-server>:<SP-port>/oamfed/ar/soap

31.7.2 Configuring for Attribute Sharing

The Attribute Sharing Plug-in can optionally be provided with the configuration parameters documented in Table 31-11.

Table 31-11 Configuration Parameters for Attribute Sharing Plug-in

Parameter Description

NameIDValueAttribute

The name of the session attribute from which the user's nameID can be retrieved.

NameIDFormatAttribute

The name of the attribute that contains the value to be used as the nameID format.

AttributeAuthorityAttribute

The name of the attribute that contains the value used as the IdP to which the SP will send the <AttributeQuery>.

RequestedAttributes

This parameter can be used to specify attributes to be requested in the URL query format; for example, attr1&attr2&attr3=value1. In this case, attr1 and attr2 will be fetched but attr3 will be present in the response ONLY if one of its values is value1.

DefaultNameIDFormat

The nameID format to be used if it is undetermined from the other parameters and session attributes.

DefaultAttributeAuthority

The default IdP partner from whom to request the user's attributes.

The Attribute Sharing Plug-in can also access the attributes documented in Table 31-12. These attributes may be present in the Access Manager session during its operation.

Table 31-12 Session Attributes Accessible To Attribute Sharing Plug-in

Attribute Description

fed.partner

If Federation was used to authenticate the user, this value is used to determine the IdP used. The same IdP would then be used for Attribute Sharing.

fed.nameidformat

If Federation was used to authenticate the user, the value of this attribute is used to determine the NameID format.

fed.nameidvalue

If Federation was used to authenticate the user, the value of this attribute is used to determine the NameID of the user. If present in the session, it will be used as the DN to locate the user in the SP's identity store.

KEY_USERNAME_DN

If this value is present, it will be used as the DN to locate the user in the SP's identity store.

The following sections have additional details on parameters and how they determine how the Attribute Sharing process.

31.7.2.1 NameID

This is the name identifier of the user for whom the SP is requesting attributes. To determine the NameID, the following searches will be conducted in order.

In the Attribute Sharing plug-in

  1. If the NameIDValueAttribute is specified, retrieve the value of the specified attribute from the session and use it as the NameID.

  2. If NameIDValueAttribute is not specified, use the value of fed.nameidvalue for the NameID.

  3. If undetermined by the above, the Attribute Sharing Plug-in will invoke the Federation Engine with a null/empty NameID and the UserID (specified in the KEY_USERNAME_DN session attribute) is sent to the SP Attribute Requester.

In the Attribute Requester (SP)

  1. If the NameID is in the Request, use its value for the user's nameID.

  2. If a NameID is undetermined but a UserID is present (which occurs when invoking the Authentication Plug-in), retrieve the value of the defaultattrrequestnameiduserattribute attribute (found in the SP configuration for this IdP) and use it as the NameID.

  3. When using SAML 2.0 only: If a NameID is not determined and SSO is configured for Simple NameID mapping, use the nameiduserattribute attribute (found in the SP configuration for this IdP). For example, if the value of this attribute is $user.attr.mail, extract the name of the user from this attribute and use it as the NameID.

  4. If a NameID is still undetermined, an error is thrown.

31.7.2.2 NameID Format

This is the format of the user's NameID. To determine the NameID format, the following searches will be conducted in order.

In the Attribute Sharing plug-in

  1. If the NameIDFormatAttribute parameter (Table 31-11) is specified, retrieve the value of the specified attribute and use it as the NameID format.

  2. Use the value of the fed.nameidformat attribute (Table 31-12) as the NameID format.

  3. Use the value of the DefaultNameIDFormat (Table 31-11) as the NameID format.

  4. If NameID Format is still undetermined, the Attribute Sharing plug-in will invoke Federation with a null/empty NameID Format.

In the Attribute Requester (SP)

  1. Use the NameID Format specified in the request.

  2. Use the value of the defaultattrrequestnameidformat attribute (found in the SP configuration for this IdP).

  3. When using SAML 2.0 only: If the NameID Format is still undetermined, use the value of the defaultauthnrequestnameidformat attribute (found in the SP configuration for this IdP).

  4. If a NameID Format is still undetermined, an error is thrown.

31.7.2.3 IdP

This is the IdP partner to which the attribute request should be sent. To determine the IdP partner, the following searches will be conducted in order.

In the Attribute Sharing plug-in

  1. If the AttributeAuthorityAttribute (Table 31-11) is specified, retrieve its value and use it as the IdP name.

  2. Use the value of the fed.partner attribute (Table 31-12) as the IdP name.

  3. Use the value of the DefaultAttributeAuthority parameter (Table 31-11) as the IdP name.

  4. If the IdP is still undetermined, the Attribute Sharing plug-in will invoke Federation with a null/empty NameID Format.

In the Attribute Requester (SP)

  1. Use the IdP name included with the request sent to the Attribute Sharing plugin.

  2. When using x509 only: look up the dn-idp mapping to determine the IdP for this user DN.

  3. Use the value of the defaultattrauthority attribute (found in the SP configuration).

  4. Use the value of the defaultssoidp attribute (found in the SP configuration).

  5. If an IdP name is still undetermined, an error is thrown.

31.7.2.4 RequestedAttributes

These are the attributes to be requested from the Attribute Authority. To determine the attributes, the following searches will be conducted in order.

In the Attribute Sharing plug-in

If the RequestedAttributes parameter (Table 31-11) is defined, use the attributes specified. If none are specified, no attributes are sent.

In the Attribute Requester (SP)

  1. If the RequestedAttributes parameter (Table 31-11) is defined, use the attributes specified.

  2. Append (or add) attributes to the request from partner(send-with-sso) attribute in the IdP partner profile.

In the Attribute Responder (IdP)

  1. If the <AttributeQuery> from the SP contains requests for specific attribute values, return values for those attributes.

  2. If no attribute values are requested, return any attributes specified as Always Send (send-with-sso) in the SP attribute profile configuration.

31.8 Using the Federation Proxy

When configured as an IdP, Identity Federation can enable the Federation Proxy to receive an Authentication Request from a remote SP partner. Rather than authenticating the user locally, the IdP begins a second Federation SSO flow (SP2) with a second, remote IdP (IdP2). IdP2 then authenticates the user, creates an Assertion and redirects the user back to the Federation Proxy (IdP/SP2). The proxy validates the Assertion, identifies the user and resumes the first Federation SSO flow by creating a second Assertion and redirecting the user back to the original SP. With Federation Proxy, the first IdP is proxying the authentication to the second IdP.

Note:

The Federation Proxy does not refer to the HTTP Proxy settings listed under Federation Settings. That is used by Identity Federation to connect to remote servers when a firewall is present.

To use Federation IdP Proxy, the administrator configures Identity Federation to use FederationScheme for authentication rather than a local scheme (like LDAPScheme or BasicScheme). At runtime, if the user needs to be authenticated using the FederationScheme, Identity Federation will act as an SP and start the Federation SSO flow with a remote IdP.

Note:

There is an option to include the proxied Federation authentication method used by the second IdP in the Assertion created for the first SP. This is only possible if the Federation SSO operation between SP2 and IdP2 use the same protocol as the one used between SP1 and IdP1.

For information on how to enable Federation Proxy using the useProxiedFedAuthnMethod WLST command, see the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

31.9 Using WLST for Identity Federation Administration

Identity Federation uses WLST commands for administration. There are commands for managing authentication mappings, partner profiles and SAML 1.1 that do not have applicable administrative fields for configuration in the Oracle Access Management Console. For information on these and other WLST commands, see the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.