1. Installing WebGates for Oracle Access Manager
  2. Configuring Oracle HTTP Server WebGate for Oracle Access Manager

2 Configuring Oracle HTTP Server WebGate for Oracle Access Manager

Configuring Oracle HTTP Server WebGate for Oracle Access Manager involves several steps.

The chapter contains the following sections:

About Oracle HTTP Server Webgate

Oracle HTTP Server WebGate is a Web server plug-in that intercepts HTTP requests and forwards them to an existing Oracle Access Manager instance for authentication and authorization.

General Prerequisites for Configuring Oracle HTTP Server Webgate

Before you configure Oracle HTTP Server WebGate, review the preupgrade requirements for your deployment.

Before you configure Oracle HTTP Server WebGate, you must have installed and configured a certified version of Oracle Access Manager. For the most up-to-date information, see the certification document for your release on the Oracle Fusion Middleware Supported System Configurations page.

Note:

For production environments, it is highly recommended that you install Oracle Access Manager in its own environment and not on the machines that are hosting the enterprise deployment.

For more information about Oracle Access Manager, see the latest Oracle Identity and Access Management documentation, which you can find in the Middleware documentation on the Oracle Help Center.

For Oracle Fusion Middleware 14c (14.1.2.0.0), the WebGate software is installed as part of the Oracle HTTP Server 14c (14.1.2.0.0) software installation. See Registering and Managing OAM Agents in Adminstrator’s Guide for Oracle Access Management.

Configuring Oracle HTTP Server WebGate

Configuring Oracle HTTP Server WebGate for Oracle Access Manager requires several steps.

In the following examples:

  • Replace OHS_ORACLE_HOME with the complete path to the Oracle home where you installed the Oracle HTTP Server software.

  • Replace OHS_CONFIG_DIR with the path to the following location in the Oracle HTTP Server domain home:
    DOMAIN_HOME/config/fmwconfig/components/OHS/ohs_instance_name

  1. Navigate to the deployWebGate directory in the Oracle HTTP Server Oracle home:

    (UNIX) cd OHS_ORACLE_HOME/webgate/ohs/tools/deployWebGate

    (Windows) cd OHS_ORACLE_HOME\webgate\ohs\tools\deployWebGate

  2. Run the following command to create the WebGate Instance directory and enable WebGate logging on OHS Instance:

    (UNIX) ./deployWebGateInstance.sh -w OHS_CONFIG_DIR -oh OHS_ORACLE_HOME

    (Windows) deployWebGateInstance.bat -w OHS_CONFIG_DIR -oh OHS_ORACLE_HOME

  3. Verify that a webgate directory and subdirectories was created by the deployWebGateInstance command:

    For example, on UNIX:

    ls -lart OHS_CONFIG_DIR/webgate/
total 6
drwxr-x---+ 8 orcl oinstall 20 Oct  2 07:14 ..
drwxr-xr-x+ 4 orcl oinstall  4 Oct  2 07:14 .
drwxr-xr-x+ 3 orcl oinstall  4 Oct  2 07:14 config

  4. Run the following command to set the path environment variable:

    (UNIX) export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:OHS_ORACLE_HOME/lib

    (Windows) set PATH=%PATH%;OHS_ORACLE_HOME\bin

  5. Navigate to the EditHttpConf directory:

    (UNIX) cd OHS_ORACLE_HOME/webgate/ohs/tools/setup/InstallTools

    (Windows) cd OHS_ORACLE_HOME\webgate\ohs\tools\EditHttpConf

  6. Run the following command:

    (UNIX) ./EditHttpConf -w OHS_CONFIG_DIR [-oh OHS_ORACLE_HOME] [-o output_file_name] [-dcc custom_dcc_scripts/pages_location]

    (Windows) EditHttpConf -w OHS_CONFIG_DIR [-oh OHS_ORACLE_HOME] [-o output_file_name] [-dcc custom_dcc_scripts\pages_location]

    This command does the following:

    • Copies the apache_webgate.template file from the Oracle HTTP Server Oracle home to a new webgate.conf file in the Oracle HTTP Server configuration directory.

    • Updates the httpd.conf file to add one line, so it includes the webgate.conf.

    • Generates a WebGate configuration file. The default name of the file is webgate.conf, but you can use a custom name by using the output_file argument to the command.

If you want to customize Detached Credential Collector (DCC) scripts or pages, such as the oamsso/logout.html, oamsso-bin/login.pl, or logout.pl scripts), then you can copy these scripts from the following location to the custom location identified by the -dcc parameter to EditHttpConf utility:
ORACLE_HOME/webgate/ohs/

Registering the Oracle HTTP Server WebGate

Oracle Access Manager WebGate component utilizes a high availability environment to eliminate a single point of failure and to distribute the workload using a load balancer (LBR). OAM needs to be registered only once, the same resulting artifacts are used by all the OAM WebGates that are behind the LBR.

You can register the new WebGate agent with Oracle Access Manager using any one of the following options:

Oracle Access Manager Administration console

For complete information about registering WebGate agent using Oracle Access Manager console, see Registering an OAM Agent Using the Console in Administrator's Guide for Oracle Access Management.

RREG tool

For complete information about registering WebGate agent using RREG tool, see:

Locating and Preparing the RREG Tool

To set up the RREG tool, complete the following steps:

  1. Log in to one of the Oracle Access Manager hosts in the Application tier.

  2. Change directory to the following directory in the Oracle Access Manager Oracle home:

    Note:

    The location is required only for the out-of-band mode.

    OAM_ORACLE_HOME/oam/server/rreg/client

    In this example, OAM_ORACLE_HOME refers to the Oracle home on the system where the Oracle Access Manager software was installed.

    Note:

    If the Oracle Enterprise Deployment Guide for IDM was used, OAM_ORACLE_HOME may be /u01/oracle/products/access/iam.

    Note:

    If you do not have privileges or access to the Oracle Access Manager server, then you can use out-of-band mode to generate the required files and register the WebGate with Oracle Access Manager. See About RREG In-Band and Out-of-Band Mode.

  3. Unzip the RREG.tar.gz file to the required directory.

  4. From the unzipped directory, open the oamreg.sh file and set the following environment variables in the file, as follows:

    • Set OAM_REG_HOME to the absolute path to the directory in which you extracted the contents of RREG archive.

      Set JAVA_HOME to the absolute path of the directory in which a supported JDK is installed on your machine.

Updating the Standard Properties in the OAM11gRequest.xml File

Before you can register the Webgate agent with Oracle Access Manager, you must update some required properties in the OAM11gRequest.xml file.

Note:

If you plan to use the default values for most of the parameters in the provided XML file, then you can use the shorter version (OAM11gRequest_short.xml, in which all non-listed fields will take a default value.

Note:

In the primary server list, the default names are mentioned as OAM_SERVER1 and OAM_SERVER2 for OAM servers. Rename these names in the list if the server names are changed in your environment.

To perform this task:

  1. If you are using in-band mode, then change directory to the following location on one of the OAM Servers:

    OAM_ORACLE_HOME/idm/oam/server/rreg/input

    If you are using out-of-band mode, then change directory to the location where you unpacked the RREG archive on the WEBHOST1 server.

  2. Make a copy of the OAM11gRequest.xml file template with an environment-specific name.

    cp OAM11gRequest.xml OAM11gRequest_edg.xml

  3. Review the properties listed in the file, and then update your copy of the OAM11gRequest.xml file to make sure the properties reference the host names and other values specific to your environment.

OAM11gRequest.xml Property Set to...
serverAddress

The host and the port of the Administration Server for the Oracle Access Manager domain.
agentName

Any custom name for the agent. Typically, you use a name that identifies the Fusion Middleware product you are configuring for single sign-on.
applicationDomain

A value that identifies the Web tier host and the FMW component you are configuring for single sign-on.

security

Must be set to the security mode configured on the Oracle Access Management server. The mode options are open or certificate.

Note:

In most cases, avoid using open mode, because in open mode, traffic to and from the Oracle Access Manager server is not encrypted.

For more information using certificate mode or about Oracle Access Manager supported security modes in general, see Securing Communication Between OAM Servers and WebGates in the Administrator's Guide for Oracle Access Management.

cachePragmaHeader

private
cacheControlHeader

private
ipValidation

0

<ipValidation>0</ipValidation>
ipValidationExceptions

The IP address of the front-end load balancer. For example:

<ipValidationExceptions> <ipAddress>130.35.165.42</ipAddress> </ipValidationExceptions>
agentBaseUrl

Fully-qualified URL with the host and the port of the front-end Load Balancer VIP in front of the WEBHOSTn machines on which Oracle HTTP 14c (14.1.2.0.0) WebGates are installed.

For example:

 <agentBaseUrl>https://soa.example.com:443</agentBaseUrl>
virtualHost

Set to true when protecting more than the agentBaseUrl, such as SSO protection for the administrative VIP.

hostPortVariationsList

Add hostPortVariation host and port elements for each of the load-balancer URLs that will be protected by the WebGates.

For example:
<hostPortVariationsList>
  <hostPortVariations>
    <host>soainternal.example.com</host>
    <port>80</port>
  </hostPortVariations>
  <hostPortVariations>
    <host>admin.example.com</host>
    <port>80</port>
  </hostPortVariations>
  <hostPortVariations>
    <host>osb.example.com</host>
    <port>443</port>
  </hostPortVariations>
</hostPortVariationsList>

Running the RREG Tool

The following topics provide information about running the RREG tool to register your Oracle HTTP Server Webgate with Oracle Access Manager.

About RREG In-Band and Out-of-Band Mode

You can run the RREG Tool in one of two modes: in-band and out-of-band.

Use in-band mode when you have the privileges to access the Oracle Access Manager server and run the RREG tool yourself from the Oracle Access Manager Oracle home. You can then copy the generated artifacts and files to the Web server configuration directory after you run the RREG Tool.

Use out-of-band mode if you do not have privileges or access to the Oracle Access Manager server. For example, in some organizations, only the Oracle Access Manager server administrators have privileges access the server directories and perform administration tasks on the server. In out-of-band mode, the process can work as follows:

  1. The Oracle Access Manager server administrator provides you with a copy of the RREG archive file (RREG.tar.gz).

    The server administrator can find it in the location described in Updating the Standard Properties in the OAM11gRequest.xml File.

  2. Untar the RREG.tar.gz file that was provided to you by the server administrator.

    For example:

    gunzip RREG.tar.gz

    tar -xvf RREG.tar

    After you unpack the RREG archive, you can find the tool for registering the agent in the following location:

    RREG_HOME/bin/oamreg.sh

    In this example, RREG_Home is the directory in which you extracted the contents of RREG archive.

  3. Use the instructions in Updating the Standard Properties in the OAM11gRequest.xml File to update the OAM11gRequest.xml file, and send the completed OAM11gRequest.xml file to the Oracle Access Manager server administrator.

  4. The Oracle Access Manager server administrator then uses the instructions in Running the RREG Tool in Out-Of-Band Mode to run the RREG Tool and generate the AgentID_response.xml file.

  5. The Oracle Access Manager server administrator sends the AgentID_response.xml file to you.

  6. Use the instructions in Running the RREG Tool in Out-Of-Band Mode to run the RREG Tool with the AgentID_response.xml file and generate the required artifacts and files on the client system.

Running the RREG Tool in In-Band Mode

To run the RREG Tool in in-band mode:

  1. Navigate to the RREG home directory.

    If you are using in-band mode, the RREG directory is inside the Oracle Access Manager Oracle home:

    OAM_ORACLE_HOME/oam/server/rreg

    If you are using out-of-band mode, then the RREG home directory is the location where you unpacked the RREG archive.

  2. In the RREG home directory, navigate to the bin directory:

    cd RREG_HOME/bin/

  3. Set the permissions of the oamreg.sh command so you can execute the file: 

    chmod +x oamreg.sh

  4. Run the following command:

    ./oamreg.sh inband RREG_HOME/input/OAM11gRequest_edg.xml

In this example:

  • It is assumed the edited OAM11gRequest.xml file is located in the RREG_HOME/input directory.

  • The output from this command will be saved to the following directory:

    RREG_HOME/output/

The following example shows a sample RREG session:

Welcome to OAM Remote Registration Tool!
Parameters passed to the registration tool are: 
Mode: inband
Filename: /u01/oracle/products/fmw/iam_home/oam/server/rreg/client/rreg/input/OAM11gRequest_edg.xml
Enter admin username:weblogic_idm
Username: weblogic_idm
Enter admin password: 
Do you want to enter a Webgate password?(y/n):
n
Do you want to import an URIs file?(y/n):
n

----------------------------------------
Request summary:
OAM11g Agent Name:SOA12214_EDG_AGENT
Base URL: https://soa.example.com:443
URL String:null
Registering in Mode:inband
Your registration request is being sent to the Admin server at: http://host1.example.com:7001
----------------------------------------

Jul 08, 2015 7:18:13 PM oracle.security.jps.util.JpsUtil disableAudit
INFO: JpsUtil: isAuditDisabled set to true
Jul 08, 2015 7:18:14 PM oracle.security.jps.util.JpsUtil disableAudit
INFO: JpsUtil: isAuditDisabled set to true
Inband registration process completed successfully! Output artifacts are created in the output folder.
Running the RREG Tool in Out-Of-Band Mode

To run the RREG Tool in out-of-band mode on the WEBHOST server, the administrator uses the following command:

RREG_HOME/bin/oamreg.sh outofband input/OAM11gRequest.xml

In this example:

  • Replace RREG_HOME with the location where the RREG archive file was unpacked on the server.

  • The edited OAM11gRequest.xml file is located in the RREG_HOME/input directory.

  • The RREG Tool saves the output from this command (the AgentID_response.xml file) to the following directory: 

    RREG_HOME/output/

    The Oracle Access Manager server administrator can then send the AgentID_response.xml to the user who provided the OAM11gRequest.xml file.

To run the RREG Tool in out-of-band mode on the Web server client machine, use the following command:

RREG_HOME/bin/oamreg.sh outofband input/AgentID_response.xml

In this example:

  • Replace RREG_HOME with the location where you unpacked the RREG archive file on the client system.

  • The AgentID_response.xml file, which was provided by the Oracle Access Manager server administrator, is located in the RREG_HOME/input directory.

  • The RREG Tool saves the output from this command (the artifacts and files required to register the Webgate software) to the following directory on the client machine:

    RREG_HOME/output/

Files and Artifacts Generated by RREG

The files that get generated by the RREG Tool vary, depending on the security level you are using for communications between the WebGate and the Oracle Access Manager server. See Securing Communication Between OAM Servers and WebGates in Administrator's Guide for Oracle Access Management.

Note that in this topic any references to RREG_HOME should be replaced with the path to the directory where you ran the RREG tool. This is typically the following directory on the Oracle Access Manager server, or (if you are using out-of-band mode) the directory where you unpacked the RREG archive: 

OAM_ORACLE_HOME/oam/server/rreg/client

The following table lists the artifacts that are always generated by the RREG Tool, regardless of the Oracle Access Manager security level.

File Location
cwallet.sso

  • RREG_HOME/output/Agent_ID/ - For WebGate 14c (14.1.2.0.0) .

  • RREG_HOME/output/Agent_ID/wallet - For WebGate 14c (14.1.2.0.0) and OHS 14c (14.1.2.0.0).

ObAccessClient.xml RREG_HOME/output/Agent_ID/

The following table lists the additional files that an administrator has to generate, if you are using the CERT security level for Oracle Access Manager:

File Location
password.xml RREG_HOME/output/Agent_ID/

Copying Generated Artifacts to the Oracle HTTP Server WebGate Instance Location

After the RREG Tool generates the required artifacts, manually copy the artifacts from the RREG_Home/output/agent_ID directory to the Oracle HTTP Server configuration directory on the Web tier host.

The location of the files in the Oracle HTTP Server configuration directory depends upon the Oracle Access Manager security mode setting (OPEN or CERT).

The following table lists the required location of each generated artifact in the Oracle HTTP Server configuration directory, based on the security mode setting for Oracle Access Manager. In some cases, you might have to create the directories if they do not exist already. For example, the wallet directory might not exist in the configuration directory.

Note:

Avoid using open mode, because in open mode, traffic to and from the Oracle Access Manager server is not encrypted.

For more information using certificate mode or about Oracle Access Manager supported security modes in general, see Securing Communication Between OAM Servers and WebGates in Administrator's Guide for Oracle Access Management.

File Location When Using OPEN Mode Location When Using CERT Mode
wallet/cwallet.sso OHS_CONFIG_DIR/webgate/config/wallet OHS_CONFIG_DIR/webgate/config/wallet/
ObAccessClient.xml OHS_CONFIG_DIR/webgate/config OHS_CONFIG_DIR/webgate/config/
password.xml N/A OHS_CONFIG_DIR/webgate/config/
aaa_key.pem N/A OHS_CONFIG_DIR/webgate/config/
aaa_cert.pem N/A OHS_CONFIG_DIR/webgate/config/
aaa_chain.pem N/A OHS_CONFIG_DIR/webgate/config/

Note:

If you need to redeploy the ObAccessClient.xml to WEBHOST1 and WEBHOST2, delete the cached copy of ObAccessClient.xml and its lock file, ObAccessClient.xml.lck from the servers. The cache location on WEBHOST1 is:
OHS_DOMAIN_HOME/servers/ohs1/cache/

And you must perform the similar step for the second Oracle HTTP Server instance on WEBHOST2: 

OHS_DOMAIN_HOME/servers/ohs2/cache/

Restarting the Oracle HTTP Server Instance

For information about restarting the Oracle HTTP Server instance, see Restarting Oracle HTTP Server Instances by Using WLST in Administering Oracle HTTP Server.

If you have configured Oracle HTTP Server in a WebLogic Server domain, you can also use Oracle Fusion Middleware Control to restart the Oracle HTTP Server instances. See Restarting Oracle HTTP Server Instances by Using Fusion Middleware Control in Administering Oracle HTTP Server.

Enabling Support for Legacy Resource WebGates

In 14c (14.1.2.0.0), the use of MD5 hashing by older WebGates will cause errors when using legacy 12.2.1.4.0 resources with your 14.1.2.0.0 resources. If you are using legacy components in 14c (14.1.2.0.0), then you will need to explicitly enable MD5 usage in 14c WebGates after installation.

The 14c (14.1.2.0.0) WebGate has changed the hashing algorithms which makes it incompatible with 12.2.1.4.0 WebGates. If you are using legacy components in 14c (14.1.2.0.0), then you will need to explicitly enable MD5 after the installation.

For a 14.1.2.0.0 WebGate acting as DCC, if you wish to enable support for legacy Resource WebGates, you will need to add the following user-defined parameter in the 14c (14.1.2.0.0) WebGate profile: 

dccForLegacyRWG=true

For a 14.1.2.0.0 WebGate acting as a Resource WebGate to a 12.2.1.4.0 or older DCC WebGate, you will need to add the following user-defined parameter in the 14c (14.1.2.0.0) WebGate profile: 

rwgForLegacyDCC=true

Note:

The 14c (14.1.2.0.0) WebGate will work in 12.2.1.4.0 compatibility mode with this setting.