6 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:

• Background and Integration Overview

• Integration with Access Manager 11gR2

• Scripts for Integration Tasks

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

6.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).

6.1.2 Deployment Options for Identity Federation

See Also:

For details about naming conventions and name changes in Oracle Access Management, see Introduction to Oracle Access Management in Administrator's Guide for 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.3.0). The engine supports both Service Provider (SP) and Identity Provider (IdP) modes.

• Separate Oracle Identity Federation and Oracle Access Manager 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 6-1 summarizes the options available to integrate the identity federation products with Oracle Access Management Access Manager and provides links to deployment procedures:

Table 6-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 supports both SP and IdP mode functionality configurable through the Access Manager administration console.	Introduction to Federation within Oracle Access Suite Console in the Administrator's Guide for Oracle Access Management Section 6.2
Oracle Access Manager 11gR1	The stand-alone Oracle Identity Federation 11g Release 1 server integrates with the Access Manager 11g 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

6.1.3 References

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

6.2 Integration with Access Manager 11gR2

This section describes how to integrate Access Manager 11g Release 2 (11.1.2.3.0) with Oracle Identity Federation 11g Release 1 (11.1.1). This is 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

6.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 6-1 describes the processing flow in each mode:

Figure 6-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.

6.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 6.2.4.

• Register Oracle HTTP Server as a partner with Access Manager to protect a resource. For details, see Section 6.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 6.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 6.2.7.

6.2.3 Prerequisites

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

• Oracle WebLogic Server

• Oracle HTTP Server 11g

• 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

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

6.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:

   http(s)://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
   

   You can also restart Oracle HTTP Server with:

   Oracle_WT1/instances/instance1/bin/opmnctl stopall
   Oracle_WT1/instances/instance1/bin/opmnctl startall
   

6.2.6 Configure Oracle Identity Federation

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

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

• In Authentication mode, 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

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

6.2.6.2 Configure Oracle Identity Federation Authentication Engine

Note:

Section 6.3 describes scripts that you can execute to automatically perform the manual operations shown here.

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 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. Configure logout:

   • If Oracle Identity Federation is also going to be integrated with Access Manager in SP mode, then 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(s)://oam_host:oam_port/oam/server/logout
       

8. Click Apply.

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

Note:

Section 6.3 describes scripts that you can execute to automatically perform the manual operations shown here.

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(s)://oam_host:oam_port/oam/server/dap/cred_submit
     Logout URL:  http(s)://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.

6.2.7 Configure Access Manager

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

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

• In Authentication mode, 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

6.2.7.1 Configure OIFScheme

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

1. Log in to the Access Manager Administration Console:

   http://oam_adminserver_host:oam_adminserver_port/oamconsole
   

2. Select the Policy Configuration tab.

3. Select and open the OIFScheme.

4. In the Challenge URL field, modify the value of OIF-Host and OIF-Port:

   http(s)://oif-host:oif-port/fed/user/spoam11
   

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

6. Click Apply to save the changes.

6.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 6.2.7.2.1.

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

Note:

Section 6.3 describes scripts that you can execute to automatically perform the manual operations shown here to register Oracle Identity Federation as a trusted partner.

6.2.7.2.1 Register Oracle Identity Federation for Use in SP Mode

Note:

Prior to performing this procedure, ensure that OAM admin server and all managed servers are running.

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 that is invoked 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")
   

6.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 that is invoked 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")
   

6.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 with OIFScheme, which will trigger a Federation single sign-on 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.

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

6.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 (IdP).

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

6.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 single sign-on 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.

6.3 Scripts for Integration Tasks

This section describes scripts that automate some of the Oracle Identity Federation configuration tasks described in Section 6.2 for Oracle Access Manager integration .

The automated steps make the integration smoother and faster than a purely manual procedure.

This section contains these topics:

• Perform the Preliminary Procedure

• Additional Setup

• Execute the Automated Procedure

6.3.1 Perform the Preliminary Procedure

The prerequisite procedure is performed before you do anything else for integration. Ensure that the following have been done:

1. The following components are installed:

   • Oracle WebLogic Server

   • Oracle HTTP Server

   • Oracle Access Manager 11g

   • Oracle Identity Federation 11g

   Note:

   Refer to the Certification Matrix for platform and version details.

   For guidance on integration prerequisites, see Oracle Fusion Middleware Installation Guide for Oracle Identity Management.

2. Oracle Identity Federation 11g and Oracle HTTP Server are integrated; that is, Oracle HTTP Server is configured as the front end to the Oracle Identity Federation server.

   For details, see "Deploying Oracle Identity Federation with Oracle HTTP Server" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Federation.

3. The SSO agent is already created and integrated with Access Manager 11g .

6.3.2 Additional Setup

Oracle WebLogic Server

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

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.

6.3.3 Execute the Automated Procedure

This section describes the procedure that automates some tasks in the integration of Oracle Access Manager with Oracle Identity Federation. The procedure is performed by executing python scripts provided in the distribution.

Section 6.2.6, "Configure Oracle Identity Federation" describes the tasks that you can automate with scripts.

6.3.3.1 Scope of the Automated Process

The scripts perform the following tasks/procedures:

• Automation of all Oracle Identity Federation configuration

• Registration of Oracle Identity Federation as DAP partner in Access Manager

• Addition of Oracle Identity Federation URLs as protected resources in the policy domain.

6.3.3.2 Copy the Scripts to the Access Manager Machine

You need to copy certain files to the Access Manager host. The files are as follows:

• setupOIFOAMConfig.sh,

• setupOIFOAMIntegration.py

• locale specific resource bundle oifWLSTResourceBundle_locale.properties

Create a directory to save these files or copy into an existing directory, in the Access Manager host machine. For example, /scratch/scripts (linux) or c:\temp\scripts (Windows).

6.3.3.3 Understand the inputs to the Scripts

The script takes in named parameters as inputs (order of inputs does not matter). The inputs mostly have default values if not passed in.

Table 6-2 shows the inputs needed by the scripts:

Table 6-2 Inputs for the OAM-OIF 11gR1 Integration Scripts

Parameter	Description	Default	Required?
oifHost	Hostname of Oracle Identity Federation managed server	None	Yes
oifPort	Port number of Oracle Identity Federation Managed server	7499	No
oifAdminHost	Hostname of Oracle Identity Federation Admin server	oifHost	No
oifAdminPort	Port number of Oracle Identity Federation Admin server	7001	No
oamAdminHost	Hostname of Access Manager Admin server	localhost	No
oamAdminPort	Port number of Access Manager Admin server	7001	No
agentType	Agent type used, such as webgate10g, webgate11g, mod_osso	webgate11g	No

Note:

The agent type is the agent created in Access Manager using the rreg tool or through the Access Manager console.

6.3.3.4 Run the Scripts

The automation is run by executing the script file setupOIFOAMConfig.sh (Unix) or setupOIFOAMConfig.cmd (Windows).

The steps are as follows:

On Unix

The following steps show how to run the script. Substitute the sample parameter values with appropriate values.

1. In a command line prompt set the DOMAIN_HOME:

   export DOMAIN_HOME=path to domain home
   

2. If Oracle Identity Federation administration and managed server are on the same host and the agent type is non-default (for example, webgate10g), execute the command:

   ./setupOIFOAMConfig.sh oifHost=myhost oifPort=portnum oamAdminHost=myhost2 oamAdminPort=portnum2 agentType=webgate10g 
   

3. If Oracle Identity Federation administration and managed server are on different hosts, with a default agent type (webgate11g), execute the command:

   ./setupOIFOAMConfig.sh oifHost=myhost oifPort=portnum oifAdminHost=myhost2 oifAdminPort=portnum2 oamAdminHost=myhost3 oamAdminPort=portnum3 
   

4. If Oracle Identity Federation administration and managed server are on the same host, and all defaults apply from Table 6-2, execute the command:

   ./setupOIFOAMConfig.sh oifHost=myhost oamAdminHost=myhost2 
   

On Windows

The following steps show how to run the script. Substitute the sample parameter values with appropriate values.

1. In a command line prompt set the DOMAIN_HOME:

   set DOMAIN_HOME=path to oam domain home
   

2. If Oracle Identity Federation administration and managed server are on the same host and the agent type is non-default (for example, webgate10g), execute the command:

   setupOIFOAMConfig.cmd  "oifHost=myhost" "oifPort=portnum" "oamAdminHost=myhost2" "oamAdminPort=portnum2" "agentType=webgate10g" 
   

3. If Oracle Identity Federation administration and managed server are on different hosts, with a default agent type (webgate11g), execute the command:

   setupOIFOAMConfig.cmd "oifHost=myhost" "oifPort=portnum" "oifAdminHost=myhost2" "oifAdminPort=portnum2" "oamAdminHost=myhost3" "oamAdminPort=portnum3" 
   

4. If Oracle Identity Federation administration and managed server are on the same host, and all defaults apply from Table 6-2, execute the command:

   setupOIFOAMConfig.cmd "oifHost=myhost" " "oamAdminHost=myhost3"