Skip Headers
Oracle® Fusion Middleware Installing WebGates for Oracle Access Manager
11g Release 1 (11.1.1.7.0)

Part Number E38584-02
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

2 Installing and Configuring Oracle HTTP Server 11g WebGate for OAM

This chapter describes how to install and configure Oracle HTTP Server 11g WebGate for Oracle Access Manager. For an introduction to WebGates and an overview of installing WebGates, see Chapter 1.

This chapter contains the following topics:

2.1 Prerequisites for Installing Oracle HTTP Server 11g WebGate

This section discusses the following topics:

2.1.1 Oracle Fusion Middleware Certification

The Oracle Fusion Middleware Supported System Configurations document provides certification information for Oracle Fusion Middleware, including supported installation types, platforms, operating systems, databases, JDKs, and third-party products related to Oracle Identity and Access Management 11g Release 1 (11.1.1).

You can access the Oracle Fusion Middleware Supported System Configurations document by searching the Oracle Technology Network (OTN) web site:

http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-100350.html

2.1.2 Installing and Configuring Oracle HTTP Server 11g

You can download the Installer from the Oracle Technology Network (OTN):

http://www.oracle.com/technology/software/products/middleware/htdocs/fmw_11_download.html

Alternatively, you can download the latest Oracle Fusion Middleware 11g software from the following website:

http://edelivery.oracle.com/

For information about installing and configuring Oracle HTTP Server 11g (11.1.1.7.0), see the Oracle Fusion Middleware Installation Guide for Oracle Web Tier.

Note:

After you install and configure Oracle HTTP Server, a working instance of Oracle HTTP Server is configured in an Instance Home.

2.1.3 Installing and Configuring OAM 11g

For information about installing Oracle Access Manager (OAM), see "Installing and Configuring Oracle Identity and Access Management (11.1.1.7.0)" in the Oracle Fusion Middleware Installation Guide for Oracle Identity and Access Management.

For information about configuring Oracle Access Manager in a new or existing WebLogic administration domain, see "Configuring Oracle Access Manager" in the Oracle Fusion Middleware Installation Guide for Oracle Identity and Access Management.

In addition, see the "Securing Communication Between OAM 11g Servers and WebGates" topic in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager for information about configuring Oracle Access Manager in Open, Simple, or Cert mode.

2.1.4 Prerequisites for 64-Bit Oracle HTTP Server 11g WebGates on Windows 2003 and Windows 2008 64-Bit Platforms

If you are using Windows 2003 or Windows 2008 64-bit operating systems, you must install Microsoft Visual C++ 2005 libraries on the machine hosting the Oracle HTTP Server 11g WebGate for Oracle Access Manager.

These libraries are included in the Microsoft Visual C++ 2005 SP1 Redistributable Package (x64), which can be downloaded from the following website:

http://www.microsoft.com/DownLoads/details.aspx?familyid=EB4EBE2D-33C0-4A47-9DD4-B9A6D7BD44DA&displaylang=en

In addition, install the Microsoft Visual C++ 2005 Service Pack 1 Redistributable Package MFC Security Update, which can be downloaded from the following website:

http://www.microsoft.com/downloads/en/details.aspx?familyid=fb01abe6-9099-4544-9aec-0ac13f19bc50&displaylang=en

2.2 Installing Oracle HTTP Server 11g WebGate

This section discusses the following topics:

2.2.1 Obtaining the Software

For information about obtaining the Oracle HTTP Server 11.1.1.7.0 WebGate software, see the Oracle Fusion Middleware Download, Installation, and Configuration ReadMe.

2.2.2 Starting the Oracle HTTP Server 11g WebGate Installer

The installer for Oracle HTTP Server 11g WebGate for Oracle Access Manager is included in the WebGate.zip file.

To start the installation wizard, perform the following steps:

  • On UNIX

    1. Extract the contents of the WebGate.zip file to a directory. By default, this directory is named WebGate.

    2. Go to the Disk1 directory under the WebGate folder.

    3. Run the following command:

      full_path_to_the_runInstaller_directory./runInstaller -jreLoc WebTier_Home/jdk

  • On Windows

    1. Extract the contents of the WebGate.zip file to a directory. By default, this directory is named WebGate.

    2. Go to the Disk1 directory under the WebGate folder.

    3. Run the following command:

      full_path_to_the_setup.exe_directory setup.exe -jreLoc WebTier_Home\jdk

Note:

When you install Oracle HTTP Server, the jdk directory is created under the WebTier_Home directory. You must enter the absolute path of the JRE folder located in this JDK when launching the installer. For example, on Windows, if the JDK is located in D:\oracle\Oracle_WT1\jdk, then launch the installer from the command prompt as follows:

D:\setup.exe -jreLoc D:\oracle\Oracle_WT1\jdk

After the Installer starts, the Welcome screen is displayed. Proceed with the installation by referring to the section "Installation Flow and Procedure of Oracle HTTP Server 11g WebGate" for installing Oracle HTTP Server 11g WebGate for Oracle Access Manager.

2.2.3 Installation Flow and Procedure of Oracle HTTP Server 11g WebGate

To install Oracle HTTP Server 11g WebGate for Oracle Access Manager, follow the instructions in Table 2-1.

If you need additional help with any of the installation screens, click Help to access the online help.

Table 2-1 Installation Flow

No. Screen Description and Action Required

1

Welcome Screen

Click Next to continue.

2

Prerequisite Checks Screen

Click Next to continue.

3

Specify Installation Location Screen

Specify the Middleware Home and Oracle Home locations.

Note that the Middleware Home should contain an Oracle Home for Oracle Web Tier. Oracle WebLogic Server is not a prerequisite for installing Oracle HTTP Server WebGate. However, Oracle HTTP Server, which is a component of Oracle Web Tier, requires only the directory structure for the Middleware home.

For more information about these directories, see "Understanding Oracle Fusion Middleware Concepts and Directory Structure" in the Oracle Fusion Middleware Installation Planning Guide.

Click Next to continue.

4

Installation Summary Screen

Verify the information on this screen.

Click Install to begin the installation.

5

Installation Progress Screen

If you are installing on a UNIX system, you may be asked to run the ORACLE_HOME/oracleRoot.sh script to set up the proper file and directory permissions.

Click Next to continue.

6

Installation Complete Screen

Click Finish to dismiss the installer.


2.3 Post-Installation Steps for Oracle HTTP Server 11g WebGate

You must complete the following steps after installing Oracle HTTP Server 11g WebGate for Oracle Access Manager:

2.4 Verifying the Installation and Configuration of Oracle HTTP Server 11g WebGate

After installing Oracle HTTP Server 11g WebGate for Oracle Access Manager, including the post-installation steps, you can examine the installDATE-TIME_STAMP.out log file to verify the installation. The default location of the log are as follows:

2.5 Getting Started with a New Oracle HTTP Server 11g WebGate

Before you can use the new Oracle HTTP Server 11g WebGate agent for Oracle Access Manager, you must complete the following tasks:

  1. Registering the New Oracle HTTP Server 11g WebGate

  2. Copying Generated Files and Artifacts to the Oracle HTTP Server WebGate Instance Location

  3. Restarting the Oracle HTTP Server Instance

2.5.1 Registering the New Oracle HTTP Server 11g WebGate

You can register the new WebGate agent with Oracle Access Manager by using the Oracle Access Manager Administration Console. For more information, see "Registering Partners (Agents and Applications) by Using the Console" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service.

Alternatively, you can use the RREG command-line tool to register a new WebGate agent. You can use the tool to run in two modes: In-Band and Out-Of-Band.

This section contains the following topics:

2.5.1.1 Setting Up the RREG Tool

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

  • On UNIX

    1. After installing and configuring Oracle Access Manager, go to the following directory:

      Oracle_IDM2/oam/server/rreg/client

    2. Untar the RREG.tar.gz file.

      Example:

      gunzip RREG.tar.gz

      tar -xvf RREG.tar

    The tool for registering the agent is located at:

    RREG_Home/bin/oamreg.sh

    Note:

    RREG_Home is the directory in which you extracted the contents of RREG.tar.gz/rreg.

  • On Windows

    1. After installing and configuring Oracle Access Manager, go to the following location:

      Oracle_IDM2\oam\server\rreg\client

    2. Extract the contents of the RREG.tar.zip file to a destination of your choice.

    The tool for registering the agent is located at:

    RREG_Home\bin\oamreg.bat

    Note:

    RREG_Home is the directory in which you extracted the contents of RREG.tar.gz/rreg.

Set the following environment variables in the oamreg.sh script. on UNIX, and oamreg.bat script, on Windows:

  • OAM_REG_HOME

    Set this variable to the absolute path to the directory in which you extracted the contents of RREG.tar/rreg.

  • JDK_HOME

    Set this variable to the absolute path to the directory in which Java or JDK is installed on your machine.

2.5.1.2 Updating the OAM11gRequest.xml File

You must update the agent parameters, such as agentName, in the OAM11GRequest.xml file in the RREG_Home\input directory on Windows. On UNIX, the file is in the RREG_Home/input directory.

Note:

The OAM11GRequest.xml file or the short version OAM11GRequest_short.xml is used as a template. You can copy this template file and use it.

Modify the following required parameters in the OAM11GRequest.xml file or in the OAM11GRequest_short.xml file:

  • serverAddress

    Specify the host and the port of the OAM Administration Server.

  • agentName

    Specify any custom name for the agent.

  • agentBaseUrl

    Specify the host and the port of the machine on which Oracle HTTP Server 11g WebGate is installed.

  • preferredHost

    Specify the host and the port of the machine on which Oracle HTTP Server 11g WebGate is installed.

  • security

    Specify the security mode, such as open, based on the WebGate installed.

  • primaryServerList

    Specify the host and the port of Managed Server for the Oracle Access Manager proxy, under a Server container element.

After modifying the file, save and close it.

2.5.1.3 Using the In-Band Mode

If you run the RREG tool once after updating the WebGate parameters in the OAM11GRequest.xml file, the files and artifacts required by WebGate are generated in the following directory:

On UNIX:

RREG_Home/output/agent_name

On Windows:

RREG_Home\output\agent_name

Note:

You can run RREG either on a client machine or on the server. If you are running it on the server, you must manually copy the artifacts back to the client.

Complete the following steps:

  1. Open the OAM11GRequest.xml file, which is in RREG_Home/input/ on UNIX and RREG_Home\input on Windows. RREG_Home is the directory on which you extracted the contents of RREG.tar.gz/rreg.

    Edit the XML file and specify parameters for the new Oracle HTTP Server WebGate for Oracle Access Manager.

  2. Run the following command:

    On UNIX:

    ./RREG_Home/bin/oamreg.sh inband input/OAM11GRequest.xml

    On Windows:

    RREG_Home\bin\oamreg.bat inband input\OAM11GRequest.xml

2.5.1.4 Using the Out-Of-Band Mode

If you are an end user with no access to the server, you can email your updated OAM11GRequest.xml file to the system administrator, who can run RREG in the out-of-band mode. You can collect the generated AgentID_Response.xml file from the system administrator and run RREG on this file to obtain the WebGate files and artifacts you require.

After you receive the generated AgentID_Response.xml file from the administrator, you must manually copy the file to the input directory on your machine.

  • On UNIX

    Complete the following steps:

    1. If you are an end user with no access to the server, open the OAM11GRequest.xml file, which is in RREG_Home/input/.

      RREG_Home is the directory on which you extracted the contents of RREG.tar.gz/rreg. Edit this XML file and specify parameters for the new Oracle HTTP Server WebGate for Oracle Access Manager. Send the updated file to your system administrator.

    2. If you are an administrator, copy the updated OAM11GRequest.xml file, which is in RREG_Home/input/ directory.

      This is the file that you received from the end user. Go to your (administrator's) RREG_Home directory and run the following command:

      ./RREG_Home/bin/oamreg.sh outofband input/OAM11GRequest.xml

      An Agent_ID_Response.xml file is generated in the output directory on the administrator's machine, in the RREG_Home/output/ directory. Send this file to the end user who sent you the updated OAM11GRequest.xml file.

    3. If you are an end user, copy the generated Agent_ID_Response.xml file, which is in RREG_Home/input/.

      This is the file that you received from the administrator. Go to your (client's) RREG home directory and run the following command on the command line:

      ./RREG_Home/bin/oamreg.sh outofband input/Agent_ID_Response.xml

    Note:

    If you register the WebGate agent by using the Oracle Access Manager Administration Console, as described in "Registering Partners (Agents and Applications) by Using the Console" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager, you must manually copy the files and artifacts generated after the registration from the server (the machine on which the Oracle Access Manager Administration Console is running) to the client machine. The files and artifacts are generated in the MW_HOME/user_projects/domains/name_of_the_WebLogic_domain_for_OAM/output/Agent_ID directory.

  • On Windows

    Complete the following steps:

    1. If you are an end user with no access to the server, open the OAM11GRequest.xml file, which is in RREG_Home\input\ directory.

      RREG_Home is the directory in which you extracted the contents of RREG.tar.gz/rreg. Edit this XML file, specify parameters for the new Oracle HTTP Server WebGate for Oracle Access Manager, and send the updated file to your system administrator.

    2. If you are an administrator, copy the updated OAM11GRequest.xml file, which is in RREG_Home\input\. This is the file you received from the end user. Go to your (administrator's) RREG_Home directory and run the following command:

      RREG_Home\bin\oamreg.bat outofband input\OAM11GRequest.xml

      An Agent_ID_Response.xml file is generated on the administrator's machine in the RREG_Home\output\ directory. Send this file to the end user who sent you the updated OAM11GRequest.xml file.

    3. If you are an end user, copy the generated Agent_ID_Response.xml file, which is in RREG_Home\input\. This is the file you received from the administrator. Go to your (client's) RREG home directory and run the following command:

      RREG_Home\bin\oamreg.bat outofband input\Agent_ID_Response.xml

    Note:

    If you register the WebGate agent by using the Oracle Access Manager Administration Console, as described in "Registering Partners (Agents and Applications) by Using the Console" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager, you must manually copy the files and artifacts generated after the registration from the server (the machine where Oracle Access Manager Administration Console is running) to the client machine. The files and artifacts are generated in the MW_HOME/user_projects/domains/name_of_the_WebLogic_domain_for_OAM/output/Agent_ID directory.

2.5.1.5 Files and Artifacts Generated by RREG

Regardless of the method or mode you use to register the new WebGate agent, the following files and artifacts are generated in the RREG_Home/output/Agent_ID directory:

  • cwallet.sso

  • ObAccessClient.xml

  • In the SIMPLE mode, RREG generates:

    • password.xml, which contains the obfuscated global passphrase to encrypt the private key used in SSL. This passphrase can be the same as the passphrase used on the server.

    • aaa_key.pem

    • aaa_cert.pem

  • In the CERT mode, RREG generates password.xml, which contains the obfuscated global passphrase to encrypt the private key used in SSL. This passphrase can be different than the passphrase used on the server.

    Note:

    You can use these files generated by RREG to generate a certificate request and get it signed by a third-party Certification Authority. To install an existing certificate, you must use the existing aaa_cert.pem and aaa_chain.pem files along with password.xml and aaa_key.pem.

2.5.2 Copying Generated Files and Artifacts to the Oracle HTTP Server WebGate Instance Location

After RREG generates these files and artifacts, you must manually copy them, based on the security mode you are using, from the RREG_Home/output/Agent_ID directory to the WebGate_Instance_Home directory.

Do the following according to the security mode you are using:

  • In OPEN mode, copy the following files from the RREG_Home/output/Agent_ID directory to the WebGate_Instance_Home/WebGate/config directory:

    • ObAccessClient.xml

    • cwallet.sso

  • In SIMPLE mode, copy the following files from the RREG_Home/output/Agent_ID directory to the WebGate_Instance_Home/WebGate/config directory:

    • ObAccessClient.xml

    • cwallet.sso

    • password.xml

    In addition, copy the following files from the RREG_Home/output/Agent_ID directory to the WebGate_Instance_Home/WebGate/config/simple directory:

    • aaa_key.pem

    • aaa_cert.pem

  • In CERT mode, copy the following files from the RREG_Home/output/Agent_ID directory to the WebGate_Instance_Home/WebGate/config directory:

    • ObAccessClient.xml

    • cwallet.sso

    • password.xml

Generating a New Certificate

You can generate a new certificate as follows:

  1. Go to the WebGate_Home/WebGate/ohs/tools/openssl directory.

  2. Create a certificate request as follows:

    ./openssl req -utf8 -new -nodes -config openssl_silent_ohs11g.cnf -keyout aaa_key.pem -out aaa_req.pem -rand WebGate_Home/WebGate/ohs/config/random-seed

  3. Self-sign the certificate as follows:

    ./openssl ca -config openssl_silent_ohs11g.cnf -policy policy_anything -batch -out aaa_cert.pem -infiles aaa_req.pem

  4. Copy the following generated certificates to the WebGate_Instance_Home/WebGate/config directory:

    • aaa_key.pem

    • aaa_cert.pem

    • cacert.pem located in the simpleCA directory

      Note:

      After copying the cacert.pem file, you must rename the file to aaa_chain.pem.

Migrating an Existing Certificate

If you want to migrate an existing certificate (aaa_key.pem, aaa_cert.pem, and aaa_chain.pem), ensure that you use the same passphrase that you used to encrypt aaa_key.pem. You must enter the same passphrase during the RREG registration process. If you do not use the same passphrase, the password.xml file generated by RREG does not match the passphrase used to encrypt the key.

If you enter the same passphrase, you can copy these certificates as follows:

  1. Go to the WebGate_Instance_Home/WebGate/config directory.

  2. Copy the following certificates to the WebGate_Instance_Home/WebGate/config directory:

    • aaa_key.pem

    • aaa_cert.pem

    • aaa_chain.pem

2.5.3 Restarting the Oracle HTTP Server Instance

You can use the Oracle Process Manager and Notification Server (OPMN) command-line tool to start or stop your Oracle HTTP Server instance. If any instances are running, run the following command on the command-line to stop all running instances:

Oracle_Home_for_Oracle_HTTP_Server/opmn/bin/opmnctl stopall

To restart the Oracle HTTP Server instance, run the following commands on the command line:

  1. Oracle_Home_for_Oracle_HTTP_Server/opmn/bin/opmnctl start

  2. Oracle_Home_for_Oracle_HTTP_Server/opmn/bin/opmnctl startproc ias-component=Oracle_HTTP_Server_Instance_Name

2.6 Deinstalling Oracle HTTP Server 11g WebGate

You should always use the instructions provided in this section for removing the Oracle HTTP Server 11.1.1.7.0 WebGates for Oracle Access Manager. If you try to remove the software manually, you may experience problems when you try to reinstall the software again at a later time. Following the procedures in this section will ensure that the software is properly removed.

To deinstall the WebGate agent, do the following:

  1. Go to the MW_HOME/Webgate_Home/oui/bin directory on UNIX, and MW_HOME\Webgate_home\oui\bin on Windows.

  2. Run the following command:

    On UNIX: ./runInstaller -deinstall

    On Windows: setup.exe -deinstall -jreLoc JRE_LOCATION

    Ensure that you specify the absolute path to your JRE_LOCATION; relative paths are not supported.

After the deinstaller starts, the Welcome screen is displayed. Proceed with the deinstallation by referring to Section 2.6.1.

2.6.1 Deinstallation Screens and Instructions

Follow the instructions in Table 2-2 to complete the deinstallation.

If you need additional help with any of the deinstallation screens, click Help to access the online help.

Table 2-2 Deinstallation Flow

Sl. No. Screen Description Action Required

1.

Welcome

Each time the deinstaller starts, the Welcome screen is displayed.

Click Next.

2.

Deinstall Oracle Home

The Deinstall Oracle Home screen shows the Oracle home you are about to deinstall.

Verify the Oracle home you are about to deinstall.

Click Deinstall.

On the Warning screen, select whether or not you want the deinstaller to remove the Oracle home directory in addition to removing the software.

Click Yes to have the deinstaller remove the software and Oracle home, No to remove only the software, or Cancel to return to the previous screen.

If you select No, go to Section 2.6.2 for instructions on how to manually remove your Oracle home directory.

3.

Deinstallation progress

The Deinstallation Progress screen shows the progress and status of the deinstallation.

Wait until the Deinstallation Complete screen appears.

4.

Deinstallation Complete

The Deinstallation Complete screen appears when the deinstallation is complete.

Click Finish to dismiss the screen.


2.6.2 Manually Removing the Oracle Home Directory

If you have selected No on the warning screen during deinstallation, you must manually remove your Webgate_Home directory and any sub-directories. For example: if your Oracle WebGate home directory was /home/Oracle/Middleware/Oracle_OAMWebGate1, run the following command:

cd /home/Oracle/Middleware/

rm -rf Oracle_OAMWebGate1

On Windows, if your Oracle Common home directory was C:\Oracle\Middleware\Oracle_OAMWebGate1, then use a file manager window, go to the C:\Oracle\Middleware directory, right-click on the Oracle_OAMWebGate1 folder, and then select Delete.

2.7 Silent Installation for Oracle HTTP Server 11g WebGate

To run the Oracle HTTP Server 11g WebGate in silent mode, complete the following steps:

  1. Set the contents of the silent.rsp file. For example:

    [ENGINE]
    #DO NOT CHANGE THIS.
    Response File Version=1.0.0.0.0
    [GENERIC]
    ORACLE_HOME=/home/MW_HOME/ohs_Webgate_home
    MIDDLEWARE_HOME=/home/MW_HOME
    [SYSTEM]
    [APPLICATIONS]
    [RELATIONSHIPS]
    

    In the preceding file, the parameters are as follows:

    • ORACLE_HOME: Provide the Oracle Home location. This is the directory in which you want to install the new Oracle HTTP Server WebGate. The location must be an immediate child folder under the specified Middleware Home location. The Oracle Home directory name can contain only alphanumeric, hyphen (-), dot (.), and underscore (_) characters, and must begin with an alphanumeric character. The total length has to be less than or equal to 128 characters. For example, home/middleware/ohs_webgate.

    • MIDDLEWARE_HOME: Specify the full path to your Middleware home directory.

  2. Extract the contents of the installer to a directory.

  3. Run the following command:

    WebGate_Installer_Directory/Disk1/runInstaller -jreLoc jre_location -invPtrLoc Absolute_Path_Of_the_oraInst.loc_file -silent -response Absolute_Path_Of_the_silent.rsp_file

    In the preceding command:

    • WebGate_Installer_Directory is the absolute path to the directory in which you have extracted the contents of the WebGate installer.

    • jre_location is the absolute path to the JRE directory.

    • Absolute_Path_Of_the_oraInst.loc_file is the absolute path to the oraInst.loc file.

    • Absolute_Path_Of_the_ silent.rsp_file is the absolute path to the silent.rsp file you created.

2.8 Upgrading Oracle HTTP Server Webgate 11.1.1.5.0 or 11.1.1.6.0 to 11.1.1.7.0

To upgrade from Oracle HTTP Server WebGate 11.1.1.5.0 or 11.1.1.6.0 to 11.1.1.7.0, complete all of the steps described in this chapter. However, in the "Specify Installation Location" screen (Table 2-1, step 3), specify the same Oracle home in which the Oracle HTTP Server 11g WebGate for OAM version 11.1.1.5.0 or 11.1.1.6.0 was installed.