20 Installing and Configuring Oracle HTTP Server 11g Webgate for OAM

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

20.2.2 Installing and Configuring OAM 11g

For information about installing Oracle Access Manager (OAM), see Installing Oracle Identity and Access Management (11.1.1.5.0). For information about configuring Oracle Access Manager in a new or existing WebLogic administration domain, see Configuring Oracle Access Manager.

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.

20.2.3 Installing and Configuring Oracle HTTP Server 11g

Oracle HTTP Server 11g Webgate for Oracle Access Manager is supported on Oracle HTTP Server 11.1.1.3.0, Oracle HTTP Server 11.1.1.4.0, and Oracle HTTP Server 11.1.1.5.0. You can choose to install any of these versions. You must install the Oracle HTTP Server 11.1.1.2.0 software before patching it to 11.1.1.3.0, 11.1.1.4.0, or 11.1.1.5.0.

If you do not have Oracle HTTP Server 11.1.1.2.0 installed, you can download the Oracle Web Tier 11g (11.1.1.2.0) 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/

20.2.4 Installing Third-Party GCC Libraries (Linux and Solaris Operating Systems Only)

If you are installing Oracle HTTP Server 11g Webgate for Oracle Access Manager on a Linux or Solaris operating system, you must download and install third-party GCC libraries on your machine. See Table 20-2 for more information.

You can download the appropriate GCC library from the following third-party website:

http://gcc.gnu.org/

strings -a libgcc_s.so.1 | grep -c "GCC_3.0"
strings -a  libgcc_s.so.1 | grep -v "GCC_3.3.1" | grep -c "GCC_3.3"
file  libgcc_s.so.1 | grep "32-bit" | grep -c "80386" 
file  libstdc++.so.5  | grep "32-bit" | grep -c "80386" 

strings -a libgcc_s.so.1 | grep -c "GCC_3.0"
strings  -a libgcc_s.so.1  | grep -v "GCC_3.3.1" | grep -c "GCC_3.3"
strings -a libgcc_s.so.1 | grep -c "GCC_4.2.0"
file  libgcc_s.so.1 | grep "64-bit" | grep -c "x86-64"
file  libstdc++.so.6  |  grep "64-bit" | grep -c "x86-64"

strings -a libgcc_s.so.1 | grep -c "GCC_3.0"
strings  -a libgcc_s.so.1  | grep -v "GCC_3.3.1" | grep -c "GCC_3.3"
file  libgcc_s.so.1 | grep "64-bit" | grep -c "SPARC"
file  libstdc++.so.5 | grep "64-bit" | grep -c "SPARC"

20.2.5 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

20.3.1 Launching the Installer

The Installer program for Oracle HTTP Server 11g Webgate for Oracle Access Manager is included in the webgate.zip file.

Perform the following steps to start the installation wizard:

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

2. Move to the Disk1 directory under the webgate folder.

3. Start the Installer by executing one of the following commands:

   UNIX: <full path to the runInstaller directory>./runInstaller -jreLoc <WebTier_Home>/jdk

   Windows: <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 appears. Continue by referring to the section Installation Flow and Procedure for installing Oracle HTTP Server 11g Webgate for Oracle Access Manager.

20.3.2 Installation Flow and Procedure

Follow the instructions in Table 20-3 to install Oracle HTTP Server 11g Webgate for Oracle Access Manager.

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

20.6.1 Register the New Webgate Agent

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

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

Setting Up the RREG Tool

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

   On UNIX operating systems:

   <Oracle_IDM2>/oam/server/rreg/client

   On Windows operating systems:

   <Oracle_IDM2>\oam\server\rreg\client

2. On the command line, untar the RREG.tar.gz file using gunzip, as in the following example:

   gunzip RREG.tar.gz

   tar -xvf RREG.tar

The tool used to register the agent is located in the following location:

On UNIX operating systems:

<RREG_Home>/bin/oamreg.sh

On Windows operating systems:

<RREG_Home>\bin\oamreg.bat

Set the following environment variables in the oamreg.sh script or in the oamreg.bat script:

• OAM_REG_HOME - Set this variable to the absolute path to the directory where you extracted the contents of RREG.tar/rreg.

• JDK_HOME - Set this variable to the absolute path to the directory where Java/JDK is installed on your machine.

Updating the OAM11gRequest.xml File

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

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 Administration Server.

• <agentName>

  Specify any custom name for the agent.

• <agentBaseUrl>

  Specify the host and the port of the machine where Oracle HTTP Server 11g Webgate is installed.

• <preferredHost>

  Specify the host and the port of the machine where 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 Oracle Access Manager proxy, under a <Server> container element.

After modifying the file, save the file and close.

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 operating systems:

<RREG_Home>/output/<agent_name>

On Windows operating systems:

<RREG_Home>\output\<agent_name>

Complete the following steps:

1. Open the OAM11GRequest.xml file, which is located in the input directory (<RREG_Home>/input/ on UNIX, and <RREG_Home>\input on Windows). <RREG_Home> is the directory where you extracted the contents of RREG.tar.gz/rreg to. Edit this XML file and fill in parameters for the new Oracle HTTP Server Webgate for Oracle Access Manager.

2. Run the following command on the command line:

   On UNIX operating systems:

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

   On Windows operating systems:

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

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.

Complete the following steps:

1. If you are an end-user with no access to the server, open the OAM11GRequest.xml file, which is located in the input directory (<RREG_Home/input/ on UNIX, and <RREG_Home\input\ on Windows). <RREG_Home> is the directory where you extracted the contents of RREG.tar.gz/rreg to. Edit this XML file and fill in 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 to the input directory on your machine (<RREG_Home>/input/ on UNIX, and <RREG_Home>\input\ on Windows). This is the file you received from the end-user. Move to your (administrator's) RREG_Home directory and run the following command on the command line:

   On UNIX operating systems:

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

   On Windows operating systems:

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

   An <Agent_ID>_Response.xml file is generated in the output directory on the administrator's machine (<RREG_Home>/output/ on UNIX, and <RREG_Home>output\ on Windows). 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 to your input directory (<RREG_Home>/input/ on UNIX, and <RREG_Home>input\ on Windows). This is the file you received from the administrator. Move to your (client's) RREG home directory and run the following command on the command line:

   On UNIX operating systems:

   ./<RREG_Home>/bin/oamreg.sh outofband input/<Agent_ID>_Response.xml

   On Windows operating systems:

   <RREG_Home>\bin\oamreg.bat outofband input\<Agent_ID>_Response.xml

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

20.6.2 Copy Generated Files and Artifacts to the Webgate Instance Location

After RREG generates these files and artifacts, you must manually copy them (cwallet.sso, ObAccessClient.xml, password.xml, aaa_key.pem, aaa_cert.pem, based on the security mode you are using) from the <RREG_Home>/output/<Agent ID> directory to the <Webgate_Instance_Home> directory.

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

After copying the files, you must either generate a new certificate or migrate an existing certificate.

Generating a New Certificate

You can generate a new certificate as follows:

1. From your present working directory, move to the <Webgate_Home>/webgate/ohs/tools/openssl directory.

2. On the command line, 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), be sure to remember the 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 paraphrase used to encrypt the key.

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

1. From your present working directory, move 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

20.6.3 Restart 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>