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:

• Introduction to Identity Federation with Oracle Access Manager

• Integrating Access Manager 11gR2 with Identity Federation 11gR1

• Running Access Manager-OIF Integration Scripts to Automate Tasks

6.1 Introduction to Identity Federation with Oracle Access Manager

This section provides background about federation with Access Manager.

Topics include:

• About Oracle Access Management Identity Federation

• About Deployment Options for Identity Federation

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 About 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 Administering 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 12c (12.2.2). 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 10g and Access Manager 11g

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 Oracle Access Management Console.	Introduction to Federation within Oracle Access Suite Console in Administering Oracle Access Management Integrating Access Manager 11gR2 with Identity Federation 11gR1
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 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.	Deploying Oracle Identity Federation with Oracle Access Manager 10g in Administrator's Guide for Oracle Identity Federation.

6.1.3 References

Introduction to Oracle Identity Federation in Administrator's Guide for Oracle Identity Federation.

6.2 Integrating Access Manager 11gR2 with Identity Federation 11gR1

This section describes how to integrate Access Manager 12c (12.2.2) with Oracle Identity Federation 11g Release 1 (11.1.1).

This is also referred to as Access Manager 11gR2 with Oracle Identity Federation 11gR1.

• About SP and Authentication Integration Modes

• Access Manager and Oracle Identity Federation Integration Overview

• Prerequisites to Integrating Access Manager with Oracle Identity Federation

• Verifying Servers are Running and a Resource is Protected

• Registering Oracle HTTP Server WebGate with Access Manager for Access Manager and OIF Integration

• Configuring Oracle Identity Federation for Access Manager and OIF Integration

• Configuring Access Manager for Integration with Oracle Identity Federation

• Configuring Access Manager to Protect a Resource with the OIFScheme

• Testing the Access Manager and Oracle Identity Federation Integration Configuration

6.2.1 About SP and Authentication Integration Modes

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 Access Manager and Oracle Identity Federation Integration Overview

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 Verifying Servers are Running and a Resource is Protected.

• Register Oracle HTTP Server as a partner with Access Manager to protect a resource. For details, see Registering Oracle HTTP Server WebGate with Access Manager for Access Manager and OIF Integration.

• 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 Configuring Oracle Identity Federation for Access Manager and OIF Integration.

• 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 Configuring Access Manager for Integration with Oracle Identity Federation.

6.2.3 Prerequisites to Integrating Access Manager with Oracle Identity Federation

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:

About the Oracle Identity and Access Management Installation in Installing and Configuring Oracle Identity and Access Management.

6.2.4 Verifying Servers are Running and a Resource is Protected

Check the following components before starting the configuration process:

• 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 Registering Oracle HTTP Server WebGate with Access Manager for Access Manager and OIF Integration

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 Oracle Access Management 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 Configuring Oracle Identity Federation for Access Manager and OIF Integration

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:

• Verifying the Oracle Identity Federation User Data Store

• Configuring the Oracle Identity Federation Authentication Engine

• Configuring the Oracle Identity Federation SP Integration Module

6.2.6.1 Verifying the Oracle Identity Federation 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 Configuring the Oracle Identity Federation Authentication Engine

Note:

Running Access Manager-OIF Integration Scripts to Automate Tasks 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 Configuring the 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:

Running Access Manager-OIF Integration Scripts to Automate Tasks 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 Configuring Access Manager for Integration with Oracle Identity Federation

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:

• Configuring Access Manager to Redirect Users to Oracle Identity Federation

• Registering Oracle Identity Federation as a Trusted Access Manager Partner

6.2.7.1 Configuring Access Manager to Redirect Users to Oracle Identity Federation

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 Oracle Access Management 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 Registering 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 Registering Oracle Identity Federation for Use in SP Mode.

If Oracle Identity Federation is used in authentication mode only, refer to Registering Oracle Identity Federation for Use in Authentication Mode.

Note:

Running Access Manager-OIF Integration Scripts to Automate Tasks 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 Registering 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 Registering 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 Configuring Access Manager to Protect a Resource with the 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 Testing the Access Manager and Oracle Identity Federation Integration Configuration

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

• Testing the SP Mode Configuration

• Testing the Authentication Mode Configuration

6.2.9.1 Testing the 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 Testing the 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 Running Access Manager-OIF Integration Scripts to Automate Tasks

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

This section describes scripts that automate some of the Oracle Identity Federation configuration tasks described in Integrating Access Manager 11gR2 with Identity Federation 11gR1 for Oracle Access Manager integration.

This section contains these topics:

• Performing Prerequisite Steps Before Integration

• Verifying WebLogic and Oracle Identity Federation Servers are Running

• Executing the Automated Procedure for Access Manager-OIF Integration

6.3.1 Performing Prerequisite Steps Before Integration

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 Installing and Configuring Oracle Internet Directory.

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

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

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

6.3.2 Verifying WebLogic and Oracle Identity Federation Servers are Running

Verify WebLogic and Oracle Identity Federation Servers are running.

• 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 Executing the Automated Procedure for Access Manager-OIF Integration

Automating some tasks in the integration of Access Manager with Oracle Identity Federation is achieved by executing python scripts provided in the distribution.

Configuring Oracle Identity Federation for Access Manager and OIF Integration describes the tasks that you can automate with scripts.

• Tasks Performed by Federation Configuration Scripts

• Copying the Access Manager-OIF Integration Scripts to the Access Manager Machine

• Understanding Inputs to the Access Manager-OIF Integration Scripts

• Running the Access Manager-OIF Integration Scripts

6.3.3.1 Tasks Performed by Federation Configuration Scripts

The scripts perform the following tasks/procedures:

• Automation of all Oracle Identity Federation configuration

• Registration of Oracle Identity Federationas DAP partner in Access Manager

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

6.3.3.2 Copying the Access Manager-OIF Integration 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 Understanding Inputs to the Access Manager-OIF Integration 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 Access Manager-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 Oracle Access Management Console.

6.3.3.4 Running the Access Manager-OIF Integration Scripts

The automation is run by executing the script file setupOIFOAMConfig.sh (Linux) 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"