10 Integrating with Identity Federation

This chapter explains how Oracle Access Management Access Manager leverages identity federation to create an authenticated session with a federation partner.

This chapter contains these sections:

• Section 10.1, "Background and Integration Overview"

• Section 10.2, "Integration with Access Manager 11gR2"

10.1 Background and Integration Overview

This section provides background about federation with Access Manager. Topics include:

• About Oracle Access Management Identity Federation

• Deployment Options for Identity Federation

• References

10.1.1 About Oracle Access Management Identity Federation

Identity federation is available in two architectures:

• As a federation engine, known as Oracle Access Management Identity Federation, built into Oracle Access Management (11g Release 2 (11.1.2).

• As a standalone, self-contained federation server, known as Oracle Identity Federation, that enables single sign-on and authentication in a multiple-domain identity network (11g Release 1 (11.1.1).

  The SP integration Engine included with Oracle Identity Federation consists of a servlet that processes requests from the server to create a user authenticated session at the Identity and Access Management (IAM) server. The engine includes several internal plug-ins that allow it to interact with different IAM servers, including Access Manager (formerly Oracle Access Manager).

10.1.2 Deployment Options for Identity Federation

See Also:

Introduction to Oracle Access Management in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management for details about naming conventions and name changes in Oracle Access Management.

Various deployment options are available for leveraging identity federation with Access Manager to create an authenticated user session.

The Oracle Fusion Middleware framework supports these integrated approaches to cross-domain single sign-on:

• An Oracle Access Management Identity Federation engine built into the Access Manager server. All configuration is performed in Access Manager.

  This approach is available in 11g Release 2 (11.1.2). In this initial release Identity Federation is limited to Service Provider mode. Identity Provider mode still requires an Oracle Identity Federation 11gR1 installation.

• Separate Oracle Identity Federation and OAM servers that can be integrated to provide federation capabilities. Management and configuration of both servers is required for this integration.

  This approach is available in 11g Release 1 (11.1.1).

  Under this approach, Oracle Identity Federation provides two deployment scenarios for Oracle Access Manager:

  • Oracle Identity Federation 11g Release 1 (11.1.1) integrated with Oracle Access Manager 10g.

  • Oracle Identity Federation 11g Release 1 (11.1.1) integrated with Access Manager 11g.

Table 10-1 summarizes the options available to integrate the identity federation products with Oracle Access Management Access Manager and provides links to deployment procedures:

Table 10-1 Deployment Options involving Oracle Access Manager

Access Manager Version	Description	Additional Information
Oracle Access Management Access Manager 11gR2	Access Manager contains a built-in federation engine that provides SP mode functionality configurable through the Access Manager administration console. For IdP functionality, Access Manager integrates with Oracle Identity Federation 11g Release 1.	Introduction to Federation within Oracle Access Suite Console in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Management. Section 10.2
Access Manager 11gR1	The stand-alone Oracle Identity Federation 11g Release 1 server integrates with the Access Manager 11g OAM server.	Integrating Oracle Identity Federation in the Oracle Fusion Middleware Integration Guide for Oracle Access Manager.
Oracle Access Manager 10g	The stand-alone Oracle Identity Federation 11g Release 1 server integrates with the Oracle Access Manager 10g server.	Oracle Fusion Middleware Administrator's Guide for Oracle Identity Federation.

10.1.3 References

Oracle Fusion Middleware Administrator's Guide for Oracle Identity Federation.

10.2 Integration with Access Manager 11gR2

This section describes how to integrate Access Manager 11g Release 2 (11.1.2) with Oracle Identity Federation 11g Release 1 (11.1.1) (also referred to as Access Manager 11gR2 with Oracle Identity Federation 11gR1).

• Architecture

• Overview of Integration Tasks

• Prerequisites

• Additional Setup

• Register Oracle HTTP Server with Access Manager

• Configure Oracle Identity Federation

• Configure Access Manager

• Protecting a Resource with OIFScheme

• Test the Configuration

10.2.1 Architecture

Two integration modes are described in this chapter:

• SP Mode

  This mode enables Oracle Identity Federation to authenticate the user via Federation SSO and propagate the authentication state to Access Manager, which maintains the session information.

• Authentication Mode

  This mode enables Access Manager to authenticate the user on behalf of Oracle Identity Federation.

Figure 10-1 describes the processing flow in each mode:

Figure 10-1 Access Manager with Identity Federation

In the SP mode, Oracle Identity Federation uses the federation protocols to identify a user, and requests Access Manager to create an authenticated session at Access Manager.

In the authentication mode, Oracle Identity Federation delegates authentication to Access Manager through the use of a WebGate agent protecting an Oracle Identity Federation resource. Once the user is authenticated, the WebGate will assert the user's identity by an HTTP Header that Oracle Identity Federation will read to identify the user.

10.2.2 Overview of Integration Tasks

The integration between Access Manager and Oracle Identity Federation requires the following tasks:

• Ensure that the necessary components, including Oracle WebLogic Server and Identity Management (IdM) components, are installed and operational. For details, see Section 10.2.4.

• Register Oracle HTTP Server as a partner with Access Manager to protect a resource. For details, see Section 10.2.5.

• Configure the Oracle Identity Federation server to function as a service provider (SP) and/or as an identity provider (IdP) with Access Manager. For details, see Section 10.2.6.

• Configure Access Manager to delegate authentication to Oracle Identity Federation and/or to authenticate a user on behalf of Oracle Identity Federation, For details, see Section 10.2.7.

10.2.3 Prerequisites

You must install the following components prior to undertaking the integration tasks:

• Oracle WebLogic Server

• Oracle HTTP Server 11g

• Oracle Access Manager 11g

• Oracle Identity Federation 11g

• WebGate (required in authentication mode)

Note:

Refer to the Certification Matrix for platform and version details.

See Also:

Oracle Fusion Middleware Installation Guide for Oracle Identity Management

10.2.4 Additional Setup

Oracle WebLogic Server

Ensure that the administration and managed servers are up and running.

Oracle HTTP Server

For testing purposes, identify or create a resource to be protected; for example, create an index.html file to serve as a test resource.

Oracle Identity Federation

Access the Fusion Middleware Control console for the Oracle Identity Federation server using a URL of the form:

http://oif_host:oif_em_port/em

Verify that all the servers are running.

10.2.5 Register Oracle HTTP Server with Access Manager

This section shows how you can register Oracle HTTP Server and 11g WebGate with Access Manager, depending on the protection mechanism you have chosen.

Follow these steps to register Oracle HTTP Server and Access Manager 11g WebGate with Access Manager for authentication:

Note:

In this procedure, MW_HOME represents the Oracle Fusion Middleware Home directory.

1. Locate the OAM11GRequest.xml file or the OAM11GRequest_short.xml file, which resides in the directory:

   MW_HOME/Oracle_IDM1/oam/server/rreg/input
   

2. Make the necessary changes to the file.

3. Locate the oamreg.sh script, which resides in the directory:

   MW_HOME/Oracle_IDM1/oam/server/rreg/bin
   

4. Execute the script using the command string:

   Note:

   The user is weblogic, and you must supply the password.

    ./oamreg.sh inband input/OAM11GRequest.xml
   

   or

    ./oamreg.sh inband input/OAM11GRequest_short.xml
   

5. Using the Access Manager console, create a resource representing the Oracle Identity Federation URL to be protected by Access Manager for authentication. This URL contains the hostname and port of the Oracle Identity Federation server, and the path to the resource, which is mode-dependent:

   https://oif-host:oif-port/fed/user/authnoam11g
   

6. Protect this resource with an authentication policy and an authorization policy.

7. Restart Oracle HTTP Server:

   Oracle_WT1/instances/instance1/bin/opmnctl restartproc process-type=OHS
   

10.2.6 Configure Oracle Identity Federation

This section describes how to configure Oracle Identity Federation to be integrated with Access Manager:

• In SP mode, where Access Manager will delegate authentication to Oracle Identity Federation for Federation SSO.

• In Authentication mode, where Oracle Identity Federation will delegate authentication to Access Manager.

This section contains these topics:

• Verify the User Data Store

• Configure Oracle Identity Federation Authentication Engine

• Configure Oracle Identity Federation SP Integration Module

10.2.6.1 Verify the User Data Store

Oracle Identity Federation and Access Manager must use the same LDAP directory:

• The LDAP directory to be used must be defined in Access Manager as the default Identity Store.

• The Oracle Identity Federation User Data Store must reference the LDAP directory to be used.

Take these steps to verify the data store configuration:

1. Locate the Oracle Identity Federation instance in Fusion Middleware Control.

2. Navigate to Administration, then Data Stores.

3. Ensure that the User Data Store points to the same directory as the default Access Manager Identity Store

10.2.6.2 Configure Oracle Identity Federation Authentication Engine

Take these steps to configure the Oracle Identity Federation Authentication Engine to retrieve information provided by the WebGate 11g agent:

1. Locate the Oracle Identity Federation instance in Fusion Middleware Control.

2. Navigate to Administration, then Authentication Engines.

3. Enable the Oracle Access Manager 11g authentication engine.

4. Select WebGate 11g as the Agent Type.

5. Enter OAM_REMOTE_USER as the User Unique ID Header.

6. In the Default Authentication Engine drop-down list, select Oracle Access Manager 11g.

7. Logout configuration:

   • If Oracle Identity Federation is also going to be integrated with Access Manager in SP mode, disable logout as the logout integration with Access Manager 11g will be performed with the OAM11g SP Engine.

   • If Oracle Identity Federation is not going to be integrated with Access Manager in SP mode:

     • Enable logout

     • Enter the following as the URL:

       http://oam_host:oam_port/oam/server/logout
       

8. Click Apply.

10.2.6.3 Configure Oracle Identity Federation SP Integration Module

This section lists the steps that need to be performed to configure Oracle Identity Federation in SP mode for Access Manager, so that Oracle Identity Federation can send assertion tokens and direct session management to Access Manager.

The steps to achieve this are as follows:

1. Locate the Oracle Identity Federation instance in Fusion Middleware Control.

2. Navigate to Administration, then Service Provider Integration Modules.

3. Select the Oracle Access Manager 11g tab.

4. Configure the page as follows:

   • Check the Enable SP Module box.

   • In the Default SP Integration Module drop-down, select Oracle Access Manager 11g.

   • Check the Logout Enabled box.

   • Configure these URLs:

     Login URL :  http://oam_host:oam_port/oam/server/dap/cred_submit
     Logout URL:  http://oam_host:oam_port/oam/server/logout
     

     where oam_host and oam_port are the host and port number of the Access Manager server respectively.

   • Set Username Attribute value to "cn" to match the Access Manager username attribute.

   • Click Apply.

5. Click Regenerate.

   This action generates a keystore file that contains the keys used to encrypt and decrypt the tokens that are exchanged between the Access Manager and Oracle Identity Federation servers. Be sure to save the keystore file using the Save As dialog.

   Copy the keystore file to a location within the installation directory of Access Manager.

   Note: Make a note of the location, since you will need to refer to it later.

10.2.7 Configure Access Manager

This section describes how to configure Access Manager to integrate with Oracle Identity Federation:

• In SP mode, where Access Manager will delegate authentication to Oracle Identity Federation for Federation SSO.

• In Authentication mode, where Oracle Identity Federation will delegate authentication to Access Manager.

This section contains these topics:

• Configure OIFScheme

• Register Oracle Identity Federation as a Trusted Access Manager Partner

10.2.7.1 Configure OIFScheme

This task configures Access Manager to redirect the user to Oracle Identity Federation for authentication when the OIFScheme is used to protect a resource via Federation SSO. The steps needed to achieve this are as follows:

1. Log in to the Access Manager Administration Console.

2. Select the Policy Configuration tab.

3. Select and open the OIFScheme.

4. In the Challenge URL field, modify the value of OIFHost and port.

5. Confirm that the value of the Context Type drop-down is set to "external".

6. Click Apply to save the changes.

10.2.7.2 Register Oracle Identity Federation as a Trusted Access Manager Partner

If Oracle Identity Federation is used in SP mode only, or authentication and SP mode, refer to Section 10.2.7.2.1.

If Oracle Identity Federation is used in authentication mode only, refer to Section 10.2.7.2.2.

10.2.7.2.1 Register Oracle Identity Federation for Use in SP Mode

Copy the keystore file to a directory under the middleware home in which the Access Manager server is installed.

Use a WLST command to update the OIFDAP partner block in the oam-config.xml configuration file. The steps and syntax are as follows:

1. Enter the shell environment by executing:

   $DOMAIN_HOME/common/bin/wlst.sh
   

2. Connect to the Access Manager administration server with the following command syntax:

   connect('weblogic','password','host:port')
   

3. Execute the command to update the partner block in the configuration file:

   registerOIFDAPPartner(keystoreLocation=location of keystore file, logoutURL=logoutURL)
   

   where logoutURL is the Oracle Identity Federation logout URL to invoke when the Access Manager server logs out the user.

   For example:

   registerOIFDAPPartner(keystoreLocation="/home/pjones/keystore", logoutURL="http://abcdef0123.in.mycorp.com:1200/fed/user/spslooam11g?doneURL=http://abc1234567.in.mycorp.com:6001/oam/pages/logout.jsp")
   

10.2.7.2.2 Register Oracle Identity Federation for Use in Authentication Mode

Use a WLST command to update the OIFDAP partner block in the oam-config.xml configuration file. The steps and syntax are as follows:

1. Enter the shell environment by executing:

   $DOMAIN_HOME/common/bin/wlst.sh
   

2. Connect to the Access Manager administration server with the following command syntax:

   connect('weblogic','password','host:port')
   

3. Execute the command to update the partner block in the configuration file:

   registerOIFDAPPartnerIDPMode(logoutURL=logoutURL)
   

   where logoutURL is the Oracle Identity Federation logout URL to invoke when the Access Manager server logs out the user.

   For example:

   registerOIFDAPPartnerIDPMode(logoutURL="http://abcdef0123.in.mycorp.com:1200/fed/user/authnslooam11g?doneURL=http://abc1234567.in.mycorp.com:6001/oam/pages/logout.jsp")
   

10.2.8 Protecting a Resource with OIFScheme

After the integration of Access Manager and Oracle Identity Federation in SP mode, a resource can now be protected via OIFScheme, which will trigger a Federation SSO operation when an unauthenticated user requests access to a resource protected by that scheme.

In an Application Domain of the Policy Configuration tab, define an Authentication Policy using the OIFScheme, and protect a resource with that authentication policy.

10.2.9 Test the Configuration

The final configuration task is to test whether the integration is correctly configured. The steps differ between authentication mode and SP mode.

• Test SP Mode Configuration

• Test Authentication Mode Configuration

10.2.9.1 Test SP Mode Configuration

Take these steps to test for correct configuration in SP mode:

1. Establish Federated Trust between Oracle Identity Federation and a remote Identity Provider.

2. Set that Identity Provider as the Default SSO Identity Provider.

3. Try accessing the protected resource.

4. When set up correctly, you should be redirected to the IdP for authentication. Verify that user credentials are required on this page.

5. Enter valid credentials on the login page.

   Note:

   The user should exist in both the IdP security domain and the Oracle Identity Federation/Access Manager security domain.

6. Check that you are redirected to the protected page.

7. Verify that the following cookies are created:

   • OAM_ID

   • ORA_OSFS_SESSION

   • OHS Cookie

10.2.9.2 Test Authentication Mode Configuration

Take these steps to test for correct configuration in authentication mode:

1. Establish Federated Trust between Oracle Identity Federation and a remote Service Provider.

2. Initiate Federation SSO from the Service Provider.

3. Verify that you are redirected to the Access Manager login page at the IdP. On this page user credentials are requested.

4. Enter the relevant credentials and process the page.

5. Verify that you are redirected to the Service Provider domain.