34.2 Using Federation Attributes for OAM Authorization and Protected Web Applications

This chapter describes how attributes received in SAML/OpenID SSO messages can be used in the Oracle Access Manager (OAM) authentication process and how they can be provided to protected web applications.

At runtime, when Oracle Identity Federation (OIF)/ Service Provider(SP) successfully processes a SAML/OpenID SSO response message, the server saves some of the information from the response in the OAM session as attributes and can be used in OAM authorization policies:

• As conditions in authorization rules
• As responses to provide the SAML/OpenID attributes to protected web applications

The SAML/OpenID SSO Response information is saved in the OAM session as attributes referenced by the following identifiers:

• The IdP partner name, referenced by $session.attr.fed.partner.
• The NameID value from the SSO response, referenced by $session.attr.fed.nameidvalue.
• The NameID format from the SSO response for SAML protocols referenced by $session.attr.fed.nameidformat.
• Attributes contained either in the SAML Assertion's Attribute Statement or in the OpenID SSO Response are referenced using $session.attr.fed.attr.ATTR_NAME, with ATTR_NAME being either the local session attribute name, if the IdP Attribute Profile mapping is applied or the attribute name from the SSO response, if no IdP Attribute Profile mapping is applied for this attribute.

34.2.1 Overview of Authenticating User Access to a Protected Resource

Oracle Access Management environment is made of the following components:

• LDAP directory
• OAM admin server, with the OAM admin console
• OAM runtime server
• Web applications
• WebGate agents protecting web applications on HTTP servers (OHS, IIS, and so on)

The WebGate performs the following tasks when an authenticated user requests access to a protected resource. Interprets the call and ensures that the:

• Interprets the call and ensures that the:
  • User is authenticated
  • User is authorized to access the resource by evaluating authorization policies for the resource
• Injects data as cookies or HTTP headers into the HTTP request, and forwards the HTTP request to the protected resource

The following are the various conditions that the OAM Authorization Policies consider when determining whether a user can access a resource:

• Identity: Condition based on the user's identity or groups to which the user belongs
• IP Address: Condition based on the user's IP address
• Temporal: Condition based on time
• Attributes: Condition based on attributes (LDAP, HTTP request, or session attributes)

Following are the components based on which the OAM Authorization Responses inject data into the HTTP request to make it available for protected web applications:

• User LDAP attributes
• HTTP request data
• Static strings
• OAM session attributes

Similar to OAM Authization Policies, an administrator can inject federation data into an HTTP request using OAM session attributes ($session.attr.fed.partner, $session.attr.fed.attr.ATTR_NAME…)

34.2.2 Prerequisites for Setting up Federation SSO

Following are the requirements for setting up Federation SSO:

• OIF acting as a Service Provider
• The IdP (AcmeIdP) sending a SAML assertion with NameID set to userID
• Set the following attributes:
  • email to user's email address
  • fname to user's first name
  • surname to user's last name
  • title to user's last job title
• Confugure OIF/SP with an IdP attribute profile to map:
  • fname to firstname
  • surname to lastname
  • leave email as is

Configure two users with the following values:

• User 1: Alice
  • userID: alice
  • email: [e-mail]
  • first name: Alice
  • last name: Appleton
  • title: manager
• User 2: Bob
  • userID: bob
  • email: [e-mail]
  • first name: Bobby
  • last name: Smith
  • title: engineer

The XML SAML response with the assertion sent back by the IdP must be as follows.

<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://acme.com/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="title" ...>
<saml:AttributeValue...>manager</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 displays different results, as the OIF/SP processes the attributes according to the rules where:

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

34.2.3 Prerequisites for Protected Web Application

Ensure that the following components are configured.

• OHS is installed
• A WebGate agent must be configured for the OHS instance
• An OAM Application Domain must be created for the WebGate, which protects all the resources on the OHS server
• Authentication Policy:
  • Name: Protected Resource Policy
  • Authentication Scheme: FederationScheme
• Authorization Policy:
  • Name: Protected Resource Policy
  • Resources linked to 'Protected Resource Policy' of Authentication Policy and 'Protected Resource Policy' of the Authorization Policy

The /cgi-bin/printenv resource on OHS prints the following data when processing the HTTP Request sent by the browser:

• HTTP Headers
• Request Data (path, query string)
• Server Data (IP address, port)

An example of a browser accessing the resource without being protected by OAM/WebGate would result in the following display (in the test, the web application will be protected as listed below):

34.2.4 Constructing Authorization Policy Using Federation Attributes

The following example shows how to construct an Authorization Policy using Federation attributes stored in the OAM session for a resource with the following constraints:

• Users authenticated through Federation SSO (The resource is protected through FederationScheme Authentication Policy).
• IdP provides the job title of the user and is locally known as title (if an IdP sends the job title through a name other than the title then an IdP Attribute Profile must be used to map it to the local title name).
• Only users with the manager title must have access to the resource.

Following are the steps to create an authorization policy:

1. Go to the OAM Administration Console:
   https://oam-admin-host:oam-adminport/oamconsole
2. Navigate to Access Manager , Application Domains.
3. Search and click Application Domain for the resource.
4. Click Authorization Policies.
5. Open the Authorization Policy protecting the resource (Protected Resource Policy in this example)
6. Click Conditions tab.
7. Click Add to define a new condition and select the following values:
   • Name: TitleCondition
   • Type: Attribute
8. Click Add Selected.
   
   

   

   
   
9. Select the newly created condition.
10. In the Condition Details window, click Add and select the following values.
    • Namespace: Session
    • Attribute Name: Other
    • Enter the attribute name: fed.title
    • Operator: Equals
    • Attribute Value: Manager
    
    

    

    
    
11. Click OK.
12. Click Rules tab.
13. Remove the TRUE condition, if present in the Allow Rule, Selected Conditions.
14. Add the TitleCondition to the Allow Rule, Selected Conditions.
15. click Apply.
    
    

    

    
    

    To test, open a new browser and access the protected resource. You will be redirected to the IdP.

    If you authenticate at the IdP as alice then the browser displays the following information at the end of the flow showing the Remote User HTTP header set to alice(Since at IdP the title attribute is set to manager, the OAM only allows access to the users with the OAM session attribute fed.title set to manager).
    
    

    If you authenticate at the IdP as bob, the browser displays an error at the end of the flow (since at IdP the title attribute is set to engineer, the OAM only allows access to users with the OAM session attribute fed.title set to engineer).
    
    

34.2.5 Injecting Federation Attributes

The following example shows how to inject SAML/OpenID attributes collected from the SSO Response as HTTP Headers for the protected Web with the following constraints:

• Users authenticated through Federation SSO (The resource is protected through a FederationScheme Authentication Policy).
• IdP provides the job title of the user and is locally known as title (if an IdP sends the job title through a name other than the title then an IdP Attribute Profile must be used to map it to the local title name).
• OAM/WebGate is configured to inject:
  • Email address as emailaddress
  • First name as firstname
  • Last name as lastname
• The configuration is done through the use of Authorization Response objects in an Authorization Policy definition.

Following are the steps to inject Federation attributes:

1. Go to the OAM Administration Console:
   http(s)://oam-admin-host:oam-adminport/oamconsole
2. Navigate to Access Manager , Application Domains.
3. Search and click Application Domain for the resource.
4. Open the Authorization Policy protecting the resource (Protected Resource Policy in this example)
5. Click Responses tab.
6. Click Add to create the entry for the email address:
   • Type: Header
   • Name: emailaddress
   • Value: $session.attr.fed.attr.email
7. Click Add to add a response.
   
   

   

   
   
8. Click Add to create the entry for the first name:
   • Type: Header
   • Name: firstname
   • Value: $session.attr.fed.attr.Lrstname
9. Click Add.
10. Click Add to create the entry for the last name:
    • Type: Header
    • Name: lastname
    • Value: $session.attr.fed.attr.lastname
11. Click Add.
12. Click Apply to save the values.
    
    

    

    
    

    To test, open a new browser and access the protected resource. You will be redirected to the IdP where the authentication occurs.

    OAM/WebGate then injects the Authorization Response items based on the OAM Session attributes (received from the IdP) and the protected web application displays them (my test page displays an HTTP header as HTTP_NAME, where NAME is the name of the HTTP Header).