Processing Incoming Attributes with OIF / SP

When OIF 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 will evaluate 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

In this article, I will discuss how OIF 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)

Enjoy the reading!

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 runtime

By processing the incoming attributes, OIF/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 will reference 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.

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

Attribute Profiles

In a previous article, I explained what SP Attributes Profiles were in OIF/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 OIF/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 OIF/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

In the rest of the article, I will showcase how OIF/SP can be configured 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 OIF WLST commands, for a remote OpenID 2.0 OP

I will use the Test SP Application bundled with OIF/SP to see how the attributes of the SAML/OpenID SSO Response are processed.

Mapping Incoming Attributes


In this section, I will show how to configure OIF/SP to process incoming SAML 2.0 attributes via the admin console. The example will be based on a Federation with a remote SAML 2.0 IdP partner identified as AcmeIdP in OIF/SP:

  • The IdP is sending Unspecified as the NameID format
  • The NameID value will contain the user ID
  • The Assertion will contain 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
  • OIF/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, I will 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 OIF/SP to map incoming attributes to local names, we will perform a test Federation SSO to see how attributes look like if left unchanged by OIF/SP.

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

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

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 alice@oracle.com
    • 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 ...>alice@oracle.com</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 OIF/SP processed the attributes. Since there are no mapping rules, the names of the attributes were left unchanged.

Creating Mapping Rules

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

  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Identity Federation -> Service Provider Administration
  • Click on the Identity Provider Attribute Profiles tab
  • Click on the “Create IdP Attribute Profile” button

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, OIF/SP will discard 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)

We will now 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)

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 would have needed to create a mapping for email to email.

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

  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Identity Federation -> Service Provider Administration
  • Click on the Search Identity Provider Partners
  • Open the desired IdP Partner
  • In the Attribute Mapping section, select the newly created IdP Attribute Profile  as the Attribute Profile
  • Save

Test

We are using the Test SP application again to do a Federation SSO operation with OIF 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 ...alice@oracle.com</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 OIF/SP processed the attributes according to the rules where:

  • email was not changed
  • fname was mapped to firstname
  • surname was mapped to lastname

Requesting Attributes


In this section, I will show how to configure OIF/SP to request attributes from an IdP at runtime by using the OIF WLST commands. The example will be based on a Federation with a remote OpenID 2.0 IdP/OP partner, and the OIF/SP will be 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, I will 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 OIF/SP will request the same attributes from those new IdPs.

I will assume that you are already in the WLST environment and connected using:

  • Enter the WLST environment by executing:
    $IAM_ORACLE_HOME/common/bin/wlst.sh
  • Connect to the WLS Admin server:
    connect()
  • Navigate to the Domain Runtime branch:
    domainRuntime()

Steps

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

  • Create a new SP Attribute Profile
    createIdPPartnerAttributeProfile("openIDAttrProfile")
    • Specify the name of the new IdP Attribute Profile
  • Create the mapping for the email attribute and request it at runtime
    setIdPPartnerAttributeProfileEntry("openIDAttrProfile", "http://axschema.org/contact/email", "email", requestFromIdP="true")
    • Specify the name of the IdP Attribute Profile to modify
    • Specify the OpenID attribute name to http://axschema.org/contact/email
    • Specify the local name for the attribute: email
    • Indicate that OIF/SP should request it at runtime: requestFromIdP="true"
  • 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")
    • Specify the name of the IdP Attribute Profile to modify
    • Specify the OpenID attribute name to http://schemas.openid.net/ax/api/user_id
    • Specify the local name for the attribute: userid
    • Indicate that OIF/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/alice@oracle.com will be:

https://acme.com/oam/server/fed/sp/sso?refid=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%3Frefid%3Did-TEMxjNN7SEdYWowvioAuTAx7UPuKAUsj-NPWLSUf&openid.response_nonce=2014-03-07T22%3A22%3A24Zid-8PQjU4IXHX6inl35bHEFws1Yv-8-&openid.assoc_handle=id-Iek3nx7-n2LldOPeooa4-auWKC4-&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%2Cax.value.attr0%2Cax.type.attr1%2Cax.value.attr1&openid.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=alice@oracle.com

The Test SP page shows different results, since OIF/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


In my next article, I will discuss how to use Federation attributes received in SAML/OpenID SSO messages in OAM Authorization Policies and how to provide them to protected web applications.
Cheers,
Damien Carru

Comments:

Hi Damien,

First of all Thank you so much for these useful and informative posts you are doing.I had gone through all your blog posts wherever OAM/OIF was acting as SP and they are very much useful to me to understand the product lot better.

I need your valuable suggestions on a solution I am working presently. I have OAM11.1.2.2.0 as SP and ADFS 2.0 as my IdP. Presently the authentication is working completely and Built In User Provisioning is working partially(Users getting created in OAM Id Store But not with all attributes).My challenge comes here,

When the User sent for authentication to IdP, It will take the credentials and see if that user already agreed the "User Agreement" or not

(a) If the user not agreed to the agreement then it will send only one Assertion attribute called "MySAMLID" which is a complex id and I am using that id to create the users in OAM id store, Even though I don't like that id as it is very complex id and I don't prefer my LDAP to do search on that due to performance reasons I am anticipating.
If we want all other attributes like userid,first name,last name , email id etc then we have to redirect the user to "PreProceeURL" which is in IdP domain and once the user accepts the agreement them SAML assertion will be as in (b) below

(b) If the User is already accepted the User agreement then the IdP with SAML Assertion with all the assertion attributes

with that background I have the following questions:

1) When OAM/SP gets only "MySAMLID" assertion attribute , Is there a way I can redirect the user to the "PreProcessURL" ? authentication condition and response? I prefer UserProvisioningPlugIn NOT to be invoked at this time as I want to use the simple Userid(instead of MySAMLID) as the authentication mapping attribute.

2) Is the User Provisioning Plugin invoked every time If the SAML attributes are different from what we have in the OAM Id store?I mean does the User Provisioning Plugin ONLY creates the users or does it modify also?

3) I am trying to avoid the Custom User Provisioning Plug In, But if it is unavoidable then How can we redirect to a "PreProcessURL" in the Custom User Provisioning Plugin code you gave in your blog(please give some pointer)?

Note: "PreProcessURL" is a URL which IdP is aware of and it will redirect the response back to where it has come from

I hope I made the issue clear and your response will be highly appreciated.

Thanks & Regards,
Srini Kommineni

Posted by guest on June 09, 2014 at 09:23 AM EDT #

Hi Srini,

OIF/SP executes the following flow:
- When processing an Assertion it will attempt to map it to a user record
- If this succeeds, then OIF/SP returns and the next plugin in the OAM Authn Module is invoked
- Otherwise, if user provisioning is enabled, OIF/SP will invoke it. Once the user provisioning returns, OIF/SP will attempt to locate the user in the LDAP directory (the user should now exists if the user provisioning returned with a success): then OIF/SP returns and the next plugin in the OAM Authn Module is invoked
- If the user provisioning returned an error, then OIF/SP will also return an error and the authentication flow will abort (no SAML data will be returned)

Note: the user provisioning is a Java plugin which does not allow user interaction.

In your case, the IdP does not follow the usual Federation SSO agreements, where the IdP will return different NameIDs depending on the status of the user at the IdP. Normally, the IdP should either deny Federation SSO if the user did not agree to the terms or perform Federation SSO if the user did. In this case, Federation SSO occurs, even if the user did not agree to the terms.

As a workaround to this behavior from the IdP, you should return an error to the user indicating that Federation SSO fails, perhaps because the user agreement at the IdP was not accepted

Posted by Damien on June 20, 2014 at 11:53 AM EDT #

Post a Comment:
  • HTML Syntax: NOT allowed
About

Damien Carru is a member of the Oracle Identity Management organization, focusing on Federation and SSO. This blog will cover Federation use cases involving Oracle Access Manager, Oracle Identity Federation and Oracle Security Token Service

Search

Categories
Archives
« May 2015
SunMonTueWedThuFriSat
     
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
      
Today