4 Integrating Oracle Identity Federation

This chapter describes how to integrate Oracle Access Manager with Oracle Identity Federation to create an authenticated session.

This chapter contains these sections:

4.1 Background and Integration Overview

This section provides background about the integration procedure. Topics include:

4.1.1 About Integration with Oracle Identity Federation

About Oracle Identity Federation

Oracle Identity Federation is a standalone, self-contained federation server that enables single sign-on and authentication in a multiple-domain identity network.

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 Oracle Access Manager.

About the Integration

Two integration modes are described in this chapter:

  • SP Mode

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

  • Authentication Mode

    This mode enables Oracle Access Manager to authenticate the user.

Figure 4-1 describes the processing flow in each mode.

Figure 4-1 Oracle Access Manager and Oracle Identity Federation

Surrounding text describes Figure 4-1 .

In the SP mode, Oracle Identity Federation uses the federation protocols to identify a user, and requests the authentication module to create an authenticated session at Oracle Access Manager. To integrate in SP mode, see "SP Mode Integration Procedure".

In the authentication mode, Oracle Access Manager looks up the user identity in the LDAP store and obtains a session cookie so that the user can access the requested resource, which is protected by either mod_osso or Oracle Access Manager 11g WebGate. To integrate in authentication mode, see "Authentication Mode Integration Procedure".

4.1.2 Overview of Integration Tasks

The tasks required to integrate Oracle Access Manager with Oracle Identity Federation are similar for both modes, with some variation.

SP Mode Integration Procedure

Configuring the SP mode requires the following tasks:

  1. Ensure that the necessary components, including Oracle WebLogic Server and Identity Management (IdM) components, are installed and operational.

    For details, see Section 4.1.3 and Section 4.1.4.

  2. Register Oracle HTTP Server as a partner with Oracle Access Manager to protect a resource.

    For details, see Section 4.2.

  3. Configure the Oracle Identity Federation server to function as a service provider (SP) with Oracle Access Manager.

    For details, see Section 4.3.1.

  4. Configure the Oracle Access Manager server to delegate the authentication to Oracle Identity Federation.

    For details, see Section 4.3.2.

  5. Test the integration.

    For details, see Section 4.5.1.

Authentication Mode Integration Procedure

Configuring the authentication mode requires the following tasks:

  1. Ensure that the necessary components, including Oracle WebLogic Server and Identity Management (IdM) components, are installed and operational.

    For details, see Section 4.1.3 and Section 4.1.4.

  2. Register Oracle HTTP Server as a partner with the Oracle Access Manager server to protect a resource.

    For details, see Section 4.2.

  3. Configure the Oracle Identity Federation server to function as an identity provider (IdP) with Oracle Access Manager.

    For details, see Section 4.4.

  4. Test the integration.

    For details, see Section 4.5.2.

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

  • mod_osso (required in authentication mode)

Note:

Refer to the Certification Matrix for platform and version details.

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

4.2 Register Oracle HTTP Server with Oracle Access Manager

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

This section contains these topics:

4.2.1 Register Oracle HTTP Server and mod_osso with Oracle Access Manager

Follow these steps to register Oracle HTTP Server and mod_osso with Oracle Access Manager:

Note:

MW_HOME represents the Oracle Fusion Middleware Home directory.
  1. Locate the OSSORequest.xml file in the directory:

    MW_HOME/Oracle_IDM1/oam/server/rreg/input
    

    Make the necessary changes to the file by setting the host, port, and agent name to appropriate values. The server address is the Oracle Access Manager admin server address and AgentBaseURL must have the Oracle HTTP Server host and port.

  2. Locate the oamreg.sh script, which resides in:

    MW_HOME/Oracle_IDM1/oam/server/rreg/bin
    

    Execute the script using this command string (user is weblogic, and you must supply the password):

    ./oamreg.sh inband input/OSSORequest.xml
    
  3. Configure mod_osso with static directives. For instructions see "Configuring mod_osso with Static Directives" in the Oracle Fusion Middleware Application Security Guide.

  4. The script executed in Step 3 generates an osso.conf file in the directory:

    MW_HOME/Oracle_IDM1/oam/server/rreg/output/AgentName
    

    Copy the file to the following location:

    Oracle_WT1/instances/instance1/config/OHS/ohs1/moduleconf/osso/
    
  5. Locate the mod_osso.conf file in the directory:

    Oracle_WT1/instances/instance1/config/OHS/ohs1/moduleconf
    

    Add these directives to the file:

    OssoSecureCookies offOssoConfigFile path_to_osso.conf_file
    
  6. Uncomment the Location tag and fill in the protected resource path.

    In authentication mode:

    <Location /fed/user/authnosso>
       require valid-user
       AuthType Osso
    </Location>
    

    In SP mode:

    <Location /protected-url-context/protected-url-path>
       require valid-user
       AuthType Osso
    </Location>
    
  7. Restart Oracle HTTP Server.

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

4.2.2 Register Oracle HTTP Server and WebGate with Oracle Access Manager

Integrating Oracle Access Manager 11g WebGate with Oracle Identity Federation requires:

  • Integrating Oracle Identity Federation with Oracle Access Manager 11g in SP mode (as described in Section 4.3), using the Oracle Single Sign-On (OSSO) SP engine

  • Enabling logout in the OSSO SP engine: the logout integration with Oracle Access Manager 11g will be performed using the OSSO SP engine, instead of the authentication engine.

Follow these steps to register Oracle HTTP Server andOracle Access Manager 11g WebGate with Oracle 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
    

    Make the necessary changes to the file.

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

    MW_HOME/Oracle_IDM1/oam/server/rreg/bin
    

    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
    
  3. Using the Oracle Access Manager console, create a resource representing the Oracle Identity Federation URL to be protected by Oracle 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.

    For example, in authentication mode:

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

    And in SP mode:

    https://oif-host:oif-port/protected-url-path
    
  4. Protect this resource with an authentication policy and an authorization policy.

  5. Restart Oracle HTTP Server:

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

4.3 Integrate Oracle Identity Federation in SP Mode

This section describes the remaining steps to integrate Oracle Identity Federation and Oracle Access Manager so that Oracle Identity Federation acts as the SP.

This section contains these topics:

4.3.1 Configure Oracle Identity Federation Providers

Take these steps to configure Oracle Identity Federation when acting as SP:

4.3.1.1 Generate Provider Metadata

Take these steps to generate metadata at the IdP and SP respectively:

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

  2. Navigate to Administration, then Security and Trust.

  3. Click the Provider Metadata tab.

  4. In the Generate Metadata section of the page, using the Provider Type drop-down, select Service Provider.

    Surrounding text describes oiftrustprovmet.gif.
  5. Click Generate. This creates metadata for the service provider.

  6. Repeat Steps 4 and 5 to generate metadata for the identity provider.

4.3.1.2 Register the Providers

Take these steps to register providers:

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

  2. Navigate to Administration, then Federations.

  3. Click Add. The Add Trusted Provider dialog appears.

    Surrounding text describes aiing_ss_03.gif.
  4. Check the Load Metadata box.

  5. Click Choose File, and select the metadata file you generated for the IdP in Section 4.3.1.1, "Generate Provider Metadata".

  6. Repeat the procedure to load metadata for the SP.

    Verify that both providers appear in the list of trusted providers:

    Surrounding text describes aiing_ss_04.gif.

4.3.1.3 Configure Data Store

Take these steps to configure the data store:

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

  2. Navigate to Administration, then Data Stores.

  3. Specify the details of the user data store, as in this example:

    Surrounding text describes aiing_ss_05.gif.

4.3.1.4 Configure the Authentication Engine

In this task, the authentication engine is configured to point to a user data store, enabling Oracle Identity Federation to validate users against that store.

For details, see Section 4.4.4.

4.3.1.5 Set the Default Identity Provider

This task sets the Identity Provider (IdP) that was created in an earlier task as the default IdP. Take these steps to achieve this task:

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

  2. Navigate to Administration, then Service Provider.

  3. Check the Enable Service Provider box.

  4. For Default SSO Identity Provider, specify the IdP set up in Section 4.3.1.2, "Register the Providers".

  5. Click Apply.

4.3.1.6 Configure Oracle Identity Federation in SP Mode

Having generated the IdP/SP metadata and registered those modules, the final task of configuring Oracle Identity Federation for the integration is to provide the Oracle Access Manager server details, so that Oracle Identity Federation can send assertion tokens and direct session management to Oracle 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 Single Sign-On tab.

    Surrounding text describes spintosso.gif.
  4. Configure the page as follows:

    • In the Default SP Integration Module drop-down, select Oracle Single Sign On.

    • Check the Enable SP Module box.

    • 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 Oracle Access Manager server respectively.

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

  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 Oracle Access Manager and Oracle Identity Federation servers.

    Be sure to save the keystore file using the Save As dialog.

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

    Note:

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

4.3.2 Delegate Authentication to Oracle Identity Federation

As a result of performing the task in Section 4.2, "Register Oracle HTTP Server with Oracle Access Manager", clients seeking access to a protected resource are directed to Oracle Access Manager for authentication.

The final task in the integration procedure is to configure Oracle Access Manager to redirect the user to Oracle Identity Federation for authentication. The steps needed to achieve this are as follows:

  1. Log in to the Oracle Access Manager Admin Console.

  2. Select the Policy Configuration tab.

  3. Protect the resource by selecting 'OIFScheme' in the Authentication Scheme drop-down.

    Surrounding text describes aiing_ss_06.gif.
  4. Click Apply.

  5. Update the authentication scheme.

    In the Policy Configuration tab, in the Shared Components tree, select Authentication Schemes, then OIFScheme.

    Surrounding text describes oifscheme1.gif.

    Take these actions:

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

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

    • Click Apply to save the changes.

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

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

    1. Enter the shell environment by executing:

      $DOMAIN_HOME/common/bin/wlst.sh
      
    2. Connect to the Oracle 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 Oracle Access Manager server logs out the user.

      For example:

      registerOIFDAPPartner(keystoreLocation="/home/pjones/keystore", logoutURL="http://abcdef0123.in.mycorp.com:1200/fed/user/spsloosso?doneURL=
      http://abc1234567.in.mycorp.com:6001/ngam/pages/logout.jsp")
      
  8. Add the federated user to the LDAP directory.

    1. Access the Oracle Access Manager administration console with the following syntax:

      http://weblogic_host:weblogic_admin_port/console
      
    2. Navigate to Security Realms, then Users and Groups, then New to create a new user.

      Note:

      Both Oracle Identity Federation and Oracle Access Manager must be able to identify this user; that is, the data store configured against the authentication engine in Section 4.3.1.4 must contain this user.
  9. Restart the administration server and managed servers.

Verification

To verify the action you took in Step 7 above, examine the $OAM_HOME/oam/server/config/oam-config.xml file to confirm that the properties in the OIFDAPPartner block were updated as mandated in that step. The logout URL should be of the form:

http://oifhost:oifport/fed/user/spsloosso?doneURL=URLEncoded(host:port/ngam/pages/logout.jsp

If the configuration is correct, a logout initiated from Oracle Access Manager will cause logout in Oracle Identity Federation.

4.4 Integrate Oracle Identity Federation (Authentication Mode)

The following tasks are required to configure Oracle Identity Federation when acting as IdP:

4.4.1 Generate Provider Metadata

Take these steps to generate provider metadata:

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

  2. Navigate to Administration, then Server Properties.

  3. Change the host name and port number to the Oracle HTTP Server host and port respectively.

    Save the changes.

  4. Navigate to Administration, then Security and Trust.

  5. Click the Provider Metadata tab.

  6. In the Generate Metadata section of the page, using the Provider Type drop-down, select Identity Provider.

    Surrounding text describes oiftrustprovmet.gif.
  7. Click Generate. This creates metadata for the identity provider.

4.4.2 Register the Providers

Take these steps to register the providers:

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

  2. Navigate to Administration, then Federations.

  3. Click Add. The Add Trusted Provider dialog appears.

  4. Check the Load Metadata box.

  5. Click Choose File, and select the metadata file you generated for the IdP in Section 4.4.1.

  6. Repeat the procedure to load metadata for the SP.

    Verify that both providers appear in the list of trusted providers.

4.4.3 Configure the Data Store

For details about this step, see Section 4.3.1.3.

4.4.4 Configure Authentication Engines

This task depends on whether you are configuring an OSSO agent or an Oracle Access Manager 11g Webgate agent.

4.4.4.1 Oracle Single Sign-ON (OSSO) Agent

The steps to configure an OSSO agent are as follows:

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

  2. Navigate to Administration, then Authentication Engines.

  3. In the Default Authentication Engine drop-down, select Oracle Single Sign-On.

  4. Click Apply.

4.4.4.2 WebGate 11g Agent

You can also protect Oracle Identity Federation with an Oracle Access Manager 11g WebGate and thus challenge the user through WebGate instead of using mod_osso: in this case, Oracle Identity Federation's Oracle Access Manager authentication engine is used for the integration.

Integrating WebGate with Oracle Identity Federation requires:

  • Integrating Oracle Identity Federation with Oracle Access Manager 11g in SP mode (as described in Section 4.3), using the OSSO SP Engine

  • Enabling logout in the OSSO SP engine: the logout integration with Oracle Access Manager 11g will be performed using the OSSO SP engine, instead of the authentication engine.

The steps to configure a WebGate 11g agent are as follows:

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

  2. Navigate to Administration, then Authentication Engines.

  3. Enable the Oracle Access Manager authentication engine.

  4. Enter OAM_REMOTE_USER as the User Unique ID Header.

  5. In the Default Authentication Engine drop-down list, select Oracle Access Manager.

  6. Disable logout, since the logout integration with Oracle Access Manager 11g will be performed with the OSSO SP Engine.

  7. Click Apply.

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

4.5.1 Test SP Mode Configuration

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

  1. Try accessing the protected resource.

  2. When set up correctly, you should be redirected to an Oracle Identity Federation login page. Verify that user credentials are required on this page.

  3. Enter valid credentials on the login page.

    Note:

    The user should exist in both the Oracle Identity Federation Data Store and in the Oracle Access Manager store.
  4. Check that you are redirected to the protected page.

  5. Verify that the following cookies are created:

    OAM_ID
    ORA_OSFS_SESSION
    OHS Cookie
    

4.5.2 Test Authentication Mode Configuration

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

  1. Start single sign-on (SSO) from the SP test page.

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

  3. Enter the relevant credentials and process the page.

  4. Verify that you are redirected to the SP test result page.