29 Managing Identity Federation Partners

You need to familiarize yourself with the concept of federation partners (service providers and identity providers) in Oracle Access Management Identity Federation.

The following topics describe how to manage identity federation partners:

29.1 Understanding Federation And Partners

You must have already familiarized with the federation and partner concepts before you start to manage identity federation partners.

You must have completed the following task:

See Enabling Identity Federation.

The integrated Identity Federation server supports the transport and receipt of request and response messages using either the Security Access Markup Language (SAML) 2.0 specifications, SAML 1.1, OpenID 2.0 or WS-Federation 1.1. Thus, Identity Provider (IdP) and Service Provider (SP) partners can be created with any of these protocols defined. SAML and OpenID partners can be defined using the Oracle Access Management Console. WS-Federation partners can be created using WLST commands.

See Creating Remote Identity Provider Partners.

See Creating Remote Service Provider Partners.

See Oracle Fusion Middleware WebLogic Scripting Tool Command Reference for Identity and Access Management.

29.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 29-1. To assign a new partner profile to a partner, use the setFedPartnerProfile() WLST command after creating the partner.

See Using WLST for Identity Federation Administration.

Table 29-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

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

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

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

Description of Figure 29-1 follows
Description of "Figure 29-1 New Identity Provider Page, Service Details Loaded from Metadata"

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

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

Description of Figure 29-2 follows
Description of "Figure 29-2 New Identity Provider Page, Service Details entered Manually"

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

Table 29-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.

29.3.1.1 Defining a New SAML 2.0 Identity Provider for Federation

You can define a new SAML 2.0 identity provider (IdP) for federation.

To create a new identity provider:

  1. In the Oracle Access Management Console, click Federation at the top of the window.
  2. In the Federation console, select Create Identity Provider Partner from the Create (+) drop-down list in the Federation section.
  3. In the Service Details field, select Load from provider metadata. (SAML 2.0 is typically configured with metadata.)
  4. A new field named Metadata File appears. 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.
29.3.1.2 Defining a New SAML 1.1 Identity Provider for Federation

You can define a new SAML 1.1 identity provider (IdP) for federation.

To create a new identity provider:

  1. In the Oracle Access Management Console, click Federation at the top of the window.
  2. In the Federation console, select Create Identity Provider Partner from the Create (+) drop-down list in the Federation section.
  3. In the Service Details field, select Enter Manually.
  4. Fill in the New Identity Provider page using values for your environment (). The information you provide depends on the protocol chosen for the provider and other factors.

    See Table 29-2.

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

    See updatePartnerPropertyWLST Command Reference for WebLogic Server guide.

29.3.1.3 Defining a New OpenID 2.0 Identity Providers for Federation

From 11g Release 2 (11.1.2.3) 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.

To define a new OpenID 2.0 identity provider (IdP) for federation:

  1. In the Oracle Access Management Console, click Federation at the top of the window.

  2. In the Federation console, select Create Identity Provider Partner from the Create (+) drop-down list in the Federation section.

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

  4. Click Save to create the identity provider definition.

Google IdP Partners

To add Google as an OpenID 2.0 IdP.

  1. In the Oracle Access Management Console, click Federation at the top of the window.

  2. In the Federation console, select Create Identity Provider Partner from the Create (+) drop-down list in the Federation section.

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

  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 from the Google IdP and maps them to the corresponding session attribute names:

SeeTable 29-3.

Table 29-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

To add Yahoo as an OpenID 2.0 IdP:

  1. In the Oracle Access Management Console, click Federation at the top of the window.
  2. In the Federation console, select Create Identity Provider Partner from the Create (+) drop-down list in the Federation section.
  3. Select OpenID 2.0 from the Protocol drop down menu.
  4. Select Yahoo provider default settings from the Service Details drop down menu.
  5. Click Save to create the identity provider definition.

The partner is configured so that the SP requests the assertion attributes from the Yahoo IdP and maps them to the corresponding session attribute names:

See Table 29-4.

Table 29-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.

29.3.1.4 Enabling 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")
29.3.1.5 Disabling OpenID Simple Registration

You can disable Simple Registration to Attribute Exchange extension.

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 the Remote Identity Provider Partners

The following topics describe how to manage an existing IdP for Identity Federation.

29.3.2.1 Searching for Existing Identity Providers

You can search for existing identity providers from the Federation console.

To search:

  1. In the Oracle Access Management Console, click Federation at the top of the window.
  2. In the Federation console, click Identity Provider Management in the Federation section.
  3. 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-5 for details about the search parameters.

  4. Click Search.
  5. The search results are displayed in a table.

    Table 29-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 29-5 describes the parameters by which providers can be searched.

    Figure 29-3 Searching for Identity Providers

    Description of Figure 29-3 follows
    Description of "Figure 29-3 Searching for Identity Providers"
29.3.2.2 Updating Identity Providers for Federation

You can search for Identity Providers for Federation and update providers information.

To update Identity Providers for Federation:

  1. In the Oracle Access Management Console, click Federation at the top of the window.
  2. In the Federation console, click Identity Provider Management in the Federation section.
  3. Search for the provider you wish to update.
  4. Select the provider of interest from the search results table.
  5. 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.
  6. Update the provider information.

    See Table 29-2 for details.

  7. Click Save to update the Identity Provider definition.

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

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

To create remote service provider partners:

  1. In the Oracle Access Management Console, click Federation at the top of the window.
  2. In the Federation console, select Create Service Provider Partner from the Create (+) drop-down list in the Federation section.
  3. Enter values for the parameters.

    Table 29-6 describes each element on the Create Service Provider page.

    Table 29-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 Using SAML 2.0.

    See Using SAML 1.1.

    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.

    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.

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

29.4.2 Managing the Remote Service Provider Partners

You can 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. In the Oracle Access Management Console, click Federation at the top of the window.
  2. In the Federation console, click Service Provider Management in the Federation section.
  3. 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-5 for details about the search parameters.

  4. Click Search.
  5. Select the appropriate partner in the Search Results table and click Edit in the toolbar.

    A new tab is activated that displays the partner's attributes. In addition to the attributes.

    See Table 29-6 for more information about advanced attributes that you can modify.

    • 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 addCertificateRequest.

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

  • SP Attribute Mapping Profile: Each SP partner profile will reference an SP Attribute Mapping Profile. A default SP Attribute Mapping Profile will be used if none is configured.

    See Using the SP Attribute Mapping Profile.

  • IdP Attribute Mapping Profile: Each IdP partner profile will reference an IdP Attribute Mapping Profile. A default IdP Attribute Mapping Profile will be used if none is configured.

    See Using the IdP Attribute Mapping Profile.

29.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 29-7 documents some sample SP attribute mappings.

Table 29-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. More than one message attribute can have the same value expression.

See Introduction to Policy Responses for SSO.

When you create or modify an SP partner profile ), the available Attribute Mapping Profiles are displayed in a drop-down list. sp-attribute-profile is the default profile.

See Creating Remote Service Provider Partners.

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 can be embedded in the value string of the attribute. These expressions are then replaced by their runtime values.

Table 29-8 lists the expressions for the attribute mapping values.

Table 29-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

request

cookie.COOKIE_NAME

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

request

client_ip

stored as $request.client_ip

session

authn_level

stored as $session.authn_level

session

authn_scheme

stored as $session.authn_scheme

session

count

stored as $session.count

session

creation

stored as $session.creation

session

expiration

stored as $session.expiration

session

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

user

id_domain

stored as $user.id_domain

user

guid

stored as $user.guid

user

groups

stored as $user.groups

user

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

expression

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

- 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

expression

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

- 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

29.5.1.1 AWS Role Mapping Attribute in SAML Response

OAM provides a new function that can be configured in the SP Attribute Profile for supporting the AWS Role mapping attribute in SAML response.

Use the following expression in the SP Attribute Profile:
$func.aws_assertion_role_attr_mapping("$base_expression", "account-number", "saml-provider-name")
where, $base_expression is an expression that evaluates to user groups, account-number is the AWS account-number, and saml-provider-name is the AWS saml-provider-name.

For example, the following expression:

$func.aws_assertion_role_attr_mapping("$user.groups","123456789","OAM")

with attribute name https://aws.amazon.com/SAML/Attributes/Role and user belonging to groups OAMSSORole and EC2SSORole returns the following SAML Response:


<Attribute Name="https://aws.amazon.com/SAML/Attributes/Role">
<AttributeValue>arn:aws:iam::123456789:role/OAMSSORole,arn:aws:iam::123456789:saml-provider/OAM</AttributeValue>
<AttributeValue>arn:aws:iam::123456789:role/EC2SSORole,arn:aws:iam::123456789:saml-provider/OAM</AttributeValue>
</Attribute>

29.5.2 Using Attribute Value Mapping and Filtering

29.5.2.1 About Attribute Value Mapping

Attribute value mapping allows you to specify the value that needs to be assigned to the local attribute in a SAML message when sending or receiving messages.

Attribute value mapping has the following characteristics:

  • A value mapping consists of a combination, or duet, of a local value and the corresponding external value.
  • Value mappings can be defined for any local attributes. Multiple value mappings can be defined for each local attribute.
  • Different external values can be mapped to the same local value using value mappings. A default attribute is used to determine which external value will be used in outgoing mode.
  • Different local values can be mapped to the same external value by means of value mappings. A default attribute is used to determine which local value to use in incoming mode when mapping external values into local values.

Attribute value mapping can be configured either through the OAM console or using WLST commands.

For more information about configuring attribute value mapping through OAM console, see Configuring Attribute Value Mapping.

For details about the WLST commands available for configuration, see setSPPartnerAttributeValueMapping,deleteSPPartnerAttributeValueMapping, displaySPPartnerAttributeValueMapping, setIdPPartnerAttributeValueMapping, deleteIdPPartnerAttributeValueMapping, and displayIdPPartnerAttributeValueMapping under Identity Federation Commands in WebLogic Scripting Tool Command Reference for Identity and Access Management.

29.5.2.2 Configuring Attribute Value Mapping

Follow the steps to define attribute value mappings through OAM Console.

On the IdP-side

  1. In the Oracle Access Management Console, click Federation at the top of the window.
  2. Click Identity Provider Management in the Federation section.
  3. Select the Service Provider Attribute Profiles tab and click Search.
  4. Select the required service attribute profile from the search results, for edit.
  5. In Attribute Mapping table, click Create and create attribute name mapping for each attribute, for which values need to be mapped.
  6. In Attribute Value Mapping table, click Create and populate the following fields in the Attribute Value Mappings window:
    • Message Attribute Name: Select the required attribute name that you had created in the previous step.
    • Send Unmapped Values: Select Send Unmapped Values to allow OAM Identity Federation to send values, for which a mapping is not defined.
    • Click Create and populate the following fields to create a value mapping:
      • Local Value: The local value of the attribute
      • External Value: The corresponding value to be sent in external messages
      • Ignore Case: If selected, indicates that the string comparison must be case-sensitive when matching attribute values.
      • Local Null: If selected, indicates that the local value equals a null string (this is different from an empty string "").
      • External Null: If selected, indicates that the external value equals a null string (this is different from an empty string "").
      • Default: If selected, indicates that this local value will be used in case an incoming external value is mapped to several local values.

On the SP-side

  1. In the Oracle Access Management Console, click Federation at the top of the window.
  2. Click Service Provider Management in the Federation section.
  3. Select the Identity Provider Attribute Profiles tab and click Search.
  4. Select the required identity attribute profile from the search results, for edit.
  5. In Attribute Mapping table, click Create and create attribute name mapping for each attribute, for which values need to be mapped.
  6. In Attribute Value Mapping table, click Create and populate the following fields in the Attribute Value Mappings window:
    • OAM Session Attribute Name: Select the required attribute name that you had created in the previous step.
    • Receive Unmapped Values: Select Receive Unmapped Values to allow OAM Identity Federation to receive values, for which a mapping is not defined.
    • Click Create and populate the following fields to create a value mapping:
      • Received Value: The value received by the SP provider.
      • External Value: The corresponding value to save in the OAM session.
      • Ignore Case: If selected, indicates that the string comparison must be case-sensitive when matching attribute values.
      • Received Null: If selected, indicates that the received value equals a null string (this is different from an empty string "").
      • External Null: If selected, indicates that the external value equals a null string (this is different from an empty string "").
      • Default: If selected, indicates that this external value will be used in case a received value is mapped to several external values.

Example

The following example shows the value mappings configuration for the attribute title and the corresponding result.

Sample Configuration

  • Attribute Name: title
  • Unmapped Values:
    • Send: Selected
    • Receive: Selected
  • Value Mappings:
    Local Value External Value Ignore Case Local Null External Null Default
    Senior Member of Technical Staff smts selected     selected
    Principal Member of Technical Staff pmts selected      
    none   selected    
    Senior Member of Technical Staff srmts selected      
    Consulting Member of Technical Staff cmts selected      

Sample Results

External Value maps to Local Value
Consulting Member of Technical Staff cmts
PRINCIPAL MEMBER OF TECHNICAL STAFF pmts
Principal Member of Technical Staff pmts
Senior Member of Technical Staff smts
Vice President Vice President
Local Value maps to External Value
NULL none
smts Senior Member of Technical Staff
srmts Senior Member of Technical Staff
CEO CEO

Note the following:

  • As value mappings was defined as case-insensitive, both "PRINCIPAL MEMBER OF TECHNICAL STAFF" and "Principal Member of Technical Staff" gets mapped to pmts.
  • As Unmapped Values: Send is selected and there is no rule defined for value "Vice President", it is mapped to itself.
  • As smts is defined as default local value for "Senior Member of Technical Staff", "Senior Member of Technical Staff" gets mapped to smts even though srmts also maps to "Senior Member of Technical Staff".
  • A local value of NULL gets mapped to the string none.
  • Both smts and srmts map to "Senior Member of Technical Staff"
  • As Unmapped Values: Receive is selected and there is no rule defined for "CEO", it is mapped to itself.
29.5.2.3 About Attribute Value Filtering

Attribute value filtering lets you specify the local values that can be allowed when sending a SAML message.

Attribute value filtering has the following characteristics:

  • Filter rules can be defined for any local attributes. A filter rule evaluates each attribute value to determine if it can be sent. If the evaluation is positive, the value is sent; otherwise, it is removed from the list of attribute values to be sent.
  • Multiple filter rules can be defined for each local attribute.

    When sending a value, OAM Identity Federation can be setup to either:

    • send only after all filters evaluate successfully
    • send if at least one filter evaluates successfully
  • You can define a filtering rule by specifying the type of comparison and the string value to compare.
  • OAM Identity Federation supports the following comparison types when comparing the attribute value to a string:
    • equals
    • not equals
    • starts with
    • ends with
    • contains
    • does not contain
    • equals null
    • not equals null
  • In addition to these comparison types, filtering supports regular expressions, allowing you to match the attribute value against a regular expression. The filtering rules allow you to specify whether the comparison will be case-sensitive.

Attribute value filtering can be configured either through the OAM console or using WLST commands.

For more information about configuring attribute value filtering through OAM console, see Configuring Attribute Value Filtering.

For details about the WLST commands available for configuration, see setSPPartnerAttributeValueFilter, deleteSPPartnerAttributeValueFilter, and displaySPPartnerAttributeValueFilter under Identity Federation Commands in WebLogic Scripting Tool Command Reference for Identity and Access Management.

29.5.2.4 Configuring Attribute Value Filtering

Follow the steps to define attribute value filtering through OAM Console.

  1. In the Oracle Access Management Console, click Federation at the top of the window.
  2. Click Identity Provider Management in the Federation section.
  3. Select the Service Provider Attribute Profiles tab and click Search.
  4. Select the required service attribute profile from the search results, for edit.
  5. In Attribute Mapping table, click Create and create attribute name mapping for each attribute, for which values need to be filtered.
  6. In Attribute Value Filter table, click Create and populate the following fields in the Attribute Value Filter window:
    • Message Attribute Name: Select the required attribute name that you had created in the previous step.
    • Condition Operator: Select one of the following
      • Select AND to indicate that all conditions need to be met.
      • Select OR to indicate that meeting one condition is sufficient for an attribute to be sent.
    • Click Create and populate the following fields:
      • Condition: The condition that will be used to evaluate the attribute value. For more details about the conditions supported, see Table 29-9
      • Expression: The value or regular expression that will be used to evaluate the attribute value.
      • Ignore Case: If selected, indicates that the string comparison must be case-sensitive when matching attribute values.

OAM provides the following filtering conditions. The rules are used to determine the allowed values. Consequently, if a rule evaluates to true, this means that it is permissible to send the value.

Table 29-9 Attribute Value Filtering Condtions

Condition Description
equals The filtering rule returns true if the expression value is equal to the outgoing attribute value.
does not equal Filtering rule returns true if the expression value is different from the outgoing attribute value.
starts with Filtering rule returns true if the outgoing attribute value begins with the expression value.
ends with Filtering rule returns true if the outgoing attribute value ends with the expression value.
contains Filtering rule returns true if the outgoing attribute value contains the expression value.
does not contain Filtering rule returns true if the outgoing attribute value does not contain the expression value.
equals null Filtering rule returns true if the outgoing attribute value is null.
does not equal null Filtering rule returns true if the outgoing attribute value is not null.
regexp Filtering rule returns true if the outgoing attribute value matches the regular expression, which is defined in the expression value.

Note:

  • The expression value must be a standard Unix regular expression.
  • The ignoreCase flag is disregarded during attribute value processing because regular expressions already support case-insensitivity.
Example: Regular Expression Description
.*rector any string that ends with rector
[^abc] any character except a, b, or c (negation)
user\d user0, user1, ..., user9
a*b any string that begins with a characters and ends with a letter b (for example, aaaaab)

Example 1

The following example shows the value filter configuration for the attribute title and the corresponding result.

Sample Configuration

  • Attribute Name: title
  • Condition Operator: and
  • Value Filters:
    Condition Expression Ignore Case
    does not equal Vice-President selected
    contains President selected

Sample Result

Value Send Value?
Vice-President no
President yes
Vice-President no
Senior Vice-President yes

Example 2

Suppose attribute value mappings are as defined in the: Configuring Attribute Value Mapping Example

The value filter configuration for the attribute title provides the result as shown:

Sample Configuration

  • Attribute Name: title
  • Condition Operator: and
  • Value Filters:
    Condition Expression Ignore Case
    does not equal mngr selected
    ends with mts not selected

Sample Result

Value Send Value? Value Sent
mngr no  
cmts yes Consulting Member of Technical Staff

Note:

  • For a value to be sent, it must not equal mngr, so the value mngr is not sent.
  • cmts can be sent (as all filter conditions evaluate to true), and it is mapped to Consulting Member of Technical Staff.

The same results apply for the following value filters, as well:

Condition Expression Ignore Case
does not equal mngr selected
regexp *mts N/A

29.5.3 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 29-10 provides sample IdP attribute mappings.

Table 29-10 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, 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.

See Creating Remote Identity Provider Partners.

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.

29.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 29-11 lists the default, out-of-the-box mappings between FAMs and Access Manager Authentication Schemes.

Table 29-11 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 included in the following topics:

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

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

29.6.3 Configuring an Alternate Authentication Scheme

An alternate Authentication Scheme is only configurable using WLST commands and not the Oracle Access Management Console.

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.

For information on the setSPPartnerAlternateScheme and setSPPartnerProfileAlternateScheme WLST commands that are used to configure alternate Authentication Scheme, see WLST Command Reference for WebLogic Server.

29.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 Using WLST for Identity Federation Administration.

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

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

Figure 29-4 illustrates the design of the Attribute Sharing plug-in from a high level.

Figure 29-4 Attribute Sharing Plug-in Design

Description of Figure 29-4 follows
Description of "Figure 29-4 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.

29.7.1.1 Using the SP Attribute Requester

The Attribute Requester Service processes the SOAP Attribute Request and returns a SOAP Attribute Response.

See Using the SOAP Endpoint.

The Attribute Request includes 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.

To use the SP Attribute Requester

  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.

The following example represents a sample SOAP Attribute Request.

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>

The following example represents a sample SOAP attribute response.

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

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.

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

29.7.2 Configuring for Attribute Sharing

Attribute Sharing Plug-in can optionally be provided with the configuration parameters.

Table 29-12 lists the Attribute Sharing Plug-in.

Table 29-12 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 29-13. These attributes may be present in the Access Manager session during its operation.

Table 29-13 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.

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

29.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 is specified, retrieve the value of the specified attribute and use it as the NameID format.

    See Table 29-12.

  2. Use the value of the fed.nameidformat attribute as the NameID format.

    See Table 29-13..

  3. Use the value of the DefaultNameIDFormat as the NameID format.

    See Table 29-12.

  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.

29.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 as specified, retrieve its value and use it as the IdP name.

    See Table 29-12.

  2. Use the value of the fed.partner attribute as the IdP name.

    See Table 29-13.

  3. Use the value of the DefaultAttributeAuthority parameter as the IdP name.

    See Table 29-12.

  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.

29.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 is defined, use the attributes specified. If none are specified, no attributes are sent.

See Table 29-12.

In the Attribute Requester (SP)

  1. If the RequestedAttributes parameter is defined, use the attributes specified.

    See Table 29-12.

  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.

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

29.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, familiarize yourself with the following document:

See the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference for Identity and Access Management.

29.10 Configuring OAM (IDP) for SAML Holder-of-Key (HoK) Profile with OCI Government Regions (SP)

This section provides information about configuring OAM 12c Identity Provider (IDP) for SAML Holder-of-Key (HOK) Profile with OCI-GOV Service Provider (SP) Partners.

OAM supports SAML Holder-of-Key (HoK) Profile, while acting as IDP.

Note:

This configuration is applicable only for setting up Oracle OCI-GOV. HoK is enabled by default for OCI-GOV instances. The configuration is not supported with any other Service Providers (SP).
  1. Stop all the Administration and Managed Servers.
  2. Edit the $OAM_DOMAIN_HOME/bin/setDomainEnv.sh and set the following system properties, as shown:
    EXTRA_JAVA_PROPERTIES="-Dosdt.useLineBreaks=false 
    -Dcom.sun.xml.ws.spi.db.BindingContextFactory=com.sun.xml.ws.db.glassfish.JAXB RIContextFactory 
    -Djavax.xml.bind.JAXBContext=com.sun.xml.bind.v2.ContextFactory ${EXTRA_JAVA_PROPERTIES}"
    export EXTRA_JAVA_PROPERTIES
    
  3. Start the Administration and Managed Servers.
  4. OCI-GOV instances have HoK enabled by default. Configure OAM federation with OCI-GOV. For setting up OCI-GOV with Identity Providers, using federation, see Federating with Identity Providers
  5. Set up X.509 Authentication for the SP Partner by configuring the out-of-the-box X509AuthScheme to use the X509Plugin. Alternatively, you can use any Custom Plugin that is capable of an X509 challenge. Optionally, you can also configure OCSP validation. For details, see Native X.509 Authentication Module
  6. (Optional, but Recommended) Set a default Authentication Scheme for the SP and IDP partners using the following WLST command:
    setSPPartnerDefaultScheme(partner="<OCI_GOV_SP_PARTNER_NAME>",authnScheme="<X509SchemeName>")
    setIdPDefaultScheme("<X509SchemeName>")
  7. Enable SSO HoK profile using the following WLST command. This results in the SAML metadata being enabled.
    putBooleanProperty("/fedserverconfig/hokprofileenabled", "true")
  8. Exchange metadata with OCI-GOV and establish a federation agreement.
  9. Map the incoming SAML Authentication Context Class to the appropriate OAM Authentication Scheme for the SP Partner.
    addSPPartnerAuthnMethod("<OCI_GOV_SP_PARTNER_NAME>", "urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient", "<X509SchemeName>")
  10. Configure the SP Partner to respond using the SAML HoK profile.
    updatePartnerProperty(partnerName="<OCI_GOV_SP_PARTNER_NAME>", partnerType="sp", propName="hokenabled", propValue="true", type="boolean")
  11. Configure OAM to use X509Scheme for the SP partner.
    updatePartnerProperty(partnerName="<OCI_GOV_SP_PARTNER_NAME>", partnerType="sp", propName="hokauthenticationscheme",
     propValue="<X509SchemeName>", type="string")
  12. Launch a browser and access the OCI-GOV console to confirm the setup is working.

    You are challenged by OAM for your X.509 certificate, after which you should be able to see the OCI-GOV Console.