Processing Incoming Attributes with OAM and SP

When OAM acts as a Service Provider, it:

• Validates the incoming SSO response from the IdP

• Maps the SSO response to an LDAP user record

• Extracts the user identifier and optional attributes contained in the SSO response and stores them in the OAM session.

Those attributes stored in the OAM session can later be used:

• In Authorization Policies, where the conditions/rules evaluates the attributes in the OAM session

• As Policy Responses to provide those attributes to web applications protected by WebGate/OAM, as HTTP Headers or cookies

This article discusses how OAM acting as a Service Provider can be configured to:

• Process attributes contained in an incoming SAML Assertion or OpenID SSO Response to map the names of incoming attributes to local names.

• Request attributes from the OP via the OpenID protocol (SAML does not provide a way for SPs at runtime to request attributes from the IdP during a Federation SSO operation)

Overview

Attribute Name Mapping

The main reason for processing incoming attributes is to map the names of the attributes from the SSO response to local names, recognized by other local components. This feature is useful in Federation deployments, because different remote partners sometimes use different names to reference the same attribute.

For example, let’s assume the following use case:

• IdP1 sends the user’s first name as firstname in the SAML Assertion

• IdP2 sends the user’s first name as f_name in the SAML Assertion

• The local components (protected applications, OAM…) expect to reference the user’s first name as first_name at runtimeBy processing the incoming attributes, OAM/SP can map:

By processing the incoming attributes, OAM/SP can map:

• firstname to first_name for IdP1

• f_name to first_name for IdP2

This allows the consumer of the data sent in SAML/OpenID messages to reference the user’s first name only by the first_name identifier:

• An authorization policy condition will only reference the first name from the OAM session using first_name

• A policy response references the first name from the OAM session using first_name

• The policy objects are not aware of firstname or f_name used by the remote IdPs

Requesting Attributes

The OpenID 2.0 protocol defines a way for SP/RP partners to request attributes from the IdP/OP at runtime.

OAM/SP provides a way to request attributes from the OpenID OP

Attribute Profiles

Previously we explained what SP Attributes Profiles were in IdP and how to use them:

• They define which attributes should be sent to SP partners

• How the attributes should be named

• How to set the values of those attributes

• Whether those attributes should always be sent or only when requested

In OAM/SP, there is a similar concept for requesting attributes and mapping attribute names. The IdP Attribute Profile is a collection of rules that indicates to OAM/SP:

• Which attributes should be requested at runtime (OpenID 2.0 only)

• How the names of attributes contained in SAML/OpenID messages should be mapped to locally

Examples

The rest of the article discusses how to configure OAM/SP to:

• Map incoming attribute names to local names, via the OAM Administration Console, for a remote SAML 2.0 IdP

• Request attributes at runtime and map incoming attribute names to local names, via OAM WLST commands, for a remote OpenID 2.0 OP

Use the Test SP Application bundled with OAM/SP to see how the attributes of the SAML/OpenID SSO Response are processed.

Mapping Incoming Attributes

This section shows how to configure OAM/SP to process incoming SAML 2.0 attributes via the admin console. The example is based on a Federation with a remote SAML 2.0 IdP partner identified as AcmeIdP in OAM/SP:

• The IdP is sending Unspecified as the NameID format

• The NameID value contains the user ID

• The Assertion contains the following SAML Attributes

• The user’s first name, identified by fname

• The user’s last name, identified by surname

• The user’s email address, identified by email

• OAM/SP will first be configured to not map any attribute names, and then it will be

• configured to Map fname to firstname

• Map surname to lastname

• Leave email as is

For this, create a new IdP Attribute Profile, and assign it to AcmeIdP.

Note: If new IdP partners are on boarded later on and are sending the attributes with the same names, it will be possible to assign the existing IdP Attribute Profile to those new partners.

Creating the Partner with no Mapping Rules

Before configuring OAM/SP to map incoming attributes to local names, perform a test Federation SSO to see how attributes look like if left unchanged by OAM/SP.

In this case, the IdP partner is bound to an empty IdP Attribute Profile and OAM/SP will not modify the names of the incoming attributes contained in the SSO response.

The IdP partner is configured similar to (with idp-attribute-profile being the default IdP Attribute Profile, which in our test is empty):

Description of the illustration Create_ID_Partner.jpg

When using the Test SP application to do a Federation SSO operation with AcmeIdP, the result of the operation shows that for user alice, the following was sent in the Assertion:

• NameID set to email address format and value set to alice

• Attributes sent:

  • email set to <[e-mail]>

  • fname set to Alice

  • surname set to Appleton

The XML SAML Response with the Assertion sent back by the IdP is:

<samlp:Response ..>
    <saml:Issuer ...>http://acme.com/idp</saml:Issuer>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
    </samlp:Status>
    <saml:Assertion ...>
        <saml:Issuer ...>http://adc00peq.us.oracle.com:7499/fed/idp</saml:Issuer>
        <dsig:Signature ...>
        ...
        </dsig:Signature>
        <saml:Subject>
            <saml:NameID ...>alice</saml:NameID>
            ...
        </saml:Subject>         <saml:Conditions ...>
         ...
        </saml:Conditions>         <saml:AuthnStatement ...>
        ...
        </saml:AuthnStatement>
        <saml:AttributeStatement ...>
            <saml:Attribute Name="email" ...>
                <saml:AttributeValue ...>[e-mail]</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="surname" ...>
                <saml:AttributeValue ...>Appleton</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="fname" ...>
                <saml:AttributeValue ...>Alice</saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>
</samlp:Response>

The Test SP page shows how OAM/SP processed the attributes. Since there are no mapping rules, the names of the attributes were left unchanged.

Description of the illustration Federation_SSO.jpg

Creating Mapping Rules

To create a new IdP Attribute Profile, execute the following steps:

1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole

2. Navigate to Identity Federation , Service Provider Administration

3. Click on the Identity Provider Attribute Profiles tab

4. Click on the Create IdP Attribute Profile button

Description of the illustration Create_Mapping_Rules.jpg

Set up the basic information about the new IdP Attribute Profile:

• Enter a name

• Enter a description if needed

Note about Ignore Unmapped Attributes: If checked, OAM/SP discards any attributes in the SAML/OpenID response not defined in this Attribute Profile.

Note about Default IdP Partner Attribute Profile: If checked, this will be the pre-assigned IdP Attribute Profile when a new IdP Partner is created via the UI

• If checked, it will be the IdP Attribute Profile used for IdP partners which do not have an IdP Attribute Profile assigned (for example the ones created via WLST commands)

Description of the illustration Create_Attr_Profile.jpg

Add the necessary mappings. Perform the following operations to add the firstname mapping:

• Click the Add Entry button in the Attribute Mapping table

• Set up the email attribute:

  • Message Attribute Name: fname

  • OAM Session Attribute Name: firstname

  • Request from partner: checked (not relevant for SAML)

  

  Description of the illustration Attr_Mapping.jpg

Perform the following operations to add the surname mapping:

• Click the Add Entry button in the Attribute Mapping table

• Set up the Name attribute:

  • Message Attribute Name: surname

  • OAM Session Attribute Name: lastname

  • Request from partner: checked (not relevant for SAML)

The IdP Attribute Profile has now been configured to map the fname and surname attributes to local names for IdP partners linked to this profile.

Note: We do not need to create a mapping for email, since

• We do not want to change the attribute name

• We left Ignore Unmapped Attribute unchecked. If that box would have been checked, we must create a mapping for email to email.

Description of the illustration IdP_Attr_Profile.jpg

The IdP Partner must be updated to use the new IdP Attribute Profile:

1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole

2. Navigate to Identity Federation , Service Provider Administration

3. Click on the Search Identity Provider Partners

4. Open the desired IdP Partner

5. In the Attribute Mapping section, select the newly created IdP Attribute Profile as the Attribute Profile

6. Click Save

Description of the illustration Update_IdP_Attr_Profile.jpg

Test

We are using the Test SP application again to do a Federation SSO operation with OAM using the new IdP Attribute Profile.

The XML SAML Response with the Assertion sent back by the IdP is still the same:

<samlp:Response ..>
    <saml:Issuer ...>http://acme.com/idp</saml:Issuer>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
    </samlp:Status>
    <saml:Assertion ...>
        <saml:Issuer ...>http://adc00peq.us.oracle.com:7499/fed/idp</saml:Issuer>
        <dsig:Signature ...>
        ...
        </dsig:Signature>
        <saml:Subject>
            <saml:NameID ...>alice</saml:NameID>
            ...
        </saml:Subject>         <saml:Conditions ...>
         ...
        </saml:Conditions>         <saml:AuthnStatement ...>
        ...
        </saml:AuthnStatement>
        <saml:AttributeStatement ...>
            <saml:Attribute Name="email" ...>
                <saml:AttributeValue [e-mail]</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="surname" ...>
                <saml:AttributeValue ...>Appleton</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="fname" ...>
                <saml:AttributeValue ...>Alice</saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>
</samlp:Response>

The Test SP page shows different results, since OAM/SP processed the attributes according to the rules where:

• email was not changed

• fname was mapped to firstname

• surname was mapped to lastname

Description of the illustration Test_Federation_SSO.jpg

Requesting Attributes

This section shows how to configure OAM/SP to request attributes from an IdP at runtime by using the OAM WLST commands. The example is based on a Federation with a remote OpenID 2.0 IdP/OP partner, and the OAM/SP is configured to:

Request the following attributes:

• Email address with the OpenID attribute name set to http://axschema.org/contact/email and local name set to email

• UserID with the OpenID attribute name set to http://schemas.openid.net/ax/api/user_id and local name set to userid

For this, create a new IdP Attribute Profile, and assign it to acmeOP. Later on, if new OP partners are on boarded, it will be possible to assign the existing IdP Attribute Profile so that OAM/SP requests the same attributes from those new IdPs.

Assume that you are already in the WLST environment and connected using:

1. Enter the WLST environment by executing: $IAM_ORACLE_HOME/common/bin/wlst.sh

2. Connect to the WLS Admin server: connect()

3. Navigate to the Domain Runtime branch: domainRuntime()

Steps

To configure the new IdP Attribute Profile, execute the following steps:

1. Create a new SP Attribute Profile createIdPPartnerAttributeProfile("openIDAttrProfile")

2. Specify the name of the new IdP Attribute Profile

3. Create the mapping for the email attribute and request it at runtime setIdPPartnerAttributeProfileEntry("openIDAttrProfile", "http://axschema.org/contact/email", "email", requestFromIdP="true")

4. Specify the name of the IdP Attribute Profile to modify

5. Specify the OpenID attribute name to http://axschema.org/contact/email

6. Specify the local name for the attribute: email

7. Indicate that OAM/SP should request it at runtime: requestFromIdP="true"

8. Create the mapping for the email attribute and request it at runtime setIdPPartnerAttributeProfileEntry("openIDAttrProfile", "http://schemas.openid.net/ax/api/user_id", "userid", requestFromIdP="true")

9. Specify the name of the IdP Attribute Profile to modify

10. Specify the OpenID attribute name to http://schemas.openid.net/ax/api/user_id

11. Specify the local name for the attribute: userid

12. Indicate that OAM/SP should request it at runtime: requestFromIdP="true"

To update the IdP partner to use that IdP Attribute Profile, execute:

• The setIdPPartnerAttributeProfile command: setIdPPartnerAttributeProfile("acmeOP", "openIDAttrProfile") Specify the IdP partner name

• Specify the name of the IdP Attribute Profile to use

OpenID Response

The OpenID Response generated by the remote IdP for alice/[e-mail] will be:

https://acme.com/oam/server/fed/sp/sso?reEd=id-TEMxjNN7SEdYWowvioAuTAx7UPuKAUsj-NPWLSUf&openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0&openid.mode=id_res&openid.op_endpoint=http%3A%2F%2Fadc00peq.us.oracle.com%3A7499%2Ffed%2Fidp%2Fopenidv20&openid.claimed_id=http%3A%2F%2Fadc00peq.us.oracle.com%3A7499%2Ffed%2Fidp%2Fopenidv20%3Fid%3Did-YxEgHp7b49OrDy9dJP4BWrwbNUQ-&openid.identity=http%3A%2F%2Fadc00peq.us.oracle.com%3A7499%2Ffed%2Fidp%2Fopenidv20%3Fid%3Did-YxEgHp7b49OrDy9dJP4BWrwbNUQ-&openid.return_to=http%3A%2F%2Fadc00pcc.us.oracle.com%3A23002%2Foam%2Fserver%2Ffed%2Fsp%2Fsso%3FreEd%3DidTEMxjNN7SEdYWowvioAuTAx7UPuKAUsj-NPWLSUf&openid.response_nonce=2014-03-07T22%3A22%3A24Zid-8PQjU4IXHX6inl35bHEFws1Yv-8-&openid.assoc_handle=id-Iek3nx7-n2LldOPeooa4auWKC4-&openid.ns.ax=http%3A%2F%2Fopenid.net%2Fsrv%2Fax%2F1.0&openid.ax.mode=fetch_response&openid.ax.type.attr0=http%3A%2F%2Fschemas.openid.net%2Fax%2Fapi%2Fuser_id&openid.ax.value.attr0=alice&openid.ax.type.attr1=http%3A%2F%2Faxschema.org%2Fcontact%2Femail&openid.ax.value.attr1=alice%40oracle.com&openid.signed=op_endpoint%2Cclaimed_id%2Cidentity%2Creturn_to%2Cresponse_nonce%2Cassoc_handle%2Cns.ax%2Cax.mode%2Cax.type.attr0%2Caopenid.sig=JBPLV5nDISw4qeWv8Yv4iPGJ6Y8%3D

The decoded URL query parameters related to the attributes are:

• Name of attribute #0: openid.ax.type.attr0= http://schemas.openid.net/ax/api/user_id

• Value for attribute #0: openid.ax.value.attr0=alice

• Name of attribute #1: openid.ax.type.attr1= http://axschema.org/contact/email

• Value for attribute #1: openid.ax.value.attr1=[e-mail]

The Test SP page shows different results, since OAM/SP processed the attributes according to the rules where:

• http://schemas.openid.net/ax/api/user_id was mapped to userid

• http://axschema.org/contact/email was mapped to email

Description of the illustration OpenID_Response.jpg

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.

---

Title and Copyright Information

Processing Incoming Attributes with OAM and SP

F61883-01

September 2022

Copyright © 2022, Oracle and/or its affiliates.