A Configuring OAM Agent (WebGate) for Oracle Traffic Director 12.2.1.2

WebGate is installed by default along with Oracle Traffic Director. However, you still need to configure it.

A WebGate intercepts HTTP requests and forwards them to the Oracle Access Manager for authentication and authorization. WebGate gets installed by default when you install Oracle Traffic Director.

This appendix contains the following sections:

A.1 Prerequisites for Configuring Webgate

You need to install Oracle Access Manager (OAM) before configuring Oracle Traffic Director. Also, there are version and environment related limitations for installing OAM.

Before you can configure Oracle Traffic Director 12c (12.2.1.2.0) WebGate, you must install one of the following versions of Oracle Access Manager.

Note:

It is highly recommended that Oracle Access Manager is installed in its own environment and not on the same machine as WebLogic Server. Oracle Access Manager and WebLogic Server can be installed on the same machine if they are both 11g versions.

A.2 Configuring Oracle Traffic Director 12c WebGate

Complete the following steps after installing Oracle Traffic Director to configure Oracle Traffic Director 12c (12.2.1.2.0) WebGate for Oracle Access Manager:

  • On UNIX

    1. Go to the $(Oracle_Home)/webgate/otd/tools/deployWebGate directory (Please note that $(Oracle_Home) is the location set as the OracleHome when installing Oracle Traffic Director) by running the following command:

      cd $(Oracle_Home)/webgate/otd/tools/deployWebGate

    2. Run the following command to create the OTD WebGate Instance Directory from $(Oracle_Home)/webgate/otd/tools/deployWebGate:

      ./deployWebGateInstance -w webgate_instanceDirectory -oh $(Oracle_Home) -ws otd

      In this command:

      • $(Oracle_Home) is the path to where Oracle Traffic Director has been installed.

        Example:

        /home/oracle

      • webgate_instanceDirectory is the location of the directory where you will copy the WebGate profile.

        Example:

        $(Domain_Home)/config/fmwconfig/components/OTD/instances/Instance_Name

        (Please note that $(Domain_Home)is the path to the directory which contains the OTD domain.)

    3. Set the environment variable LD_LIBRARY_PATH to WebGate_$(Oracle_Home)/lib

      For example:

      For Linux 64

      export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$(Oracle_Home)/lib

      For Windows

      set PATH=%(Oracle_Home)%\bin;%path%

      For Solaris/Sparc

      export LD_PRELOAD_64=$(Oracle_Home)/lib/libclntsh.so.11.1:$(Oracle_Home)/lib/libnnz11.so

    4. Go to the following directory:

      For Unix-based platforms

      $(Oracle_Home)/webgate/otd/tools/setup/InstallTools

      For Windows

      %(Oracle_Home)%\webgate\otd\tools\EditObjConf

    5. On the command line, run the following command for updating OTD conf files, such as magnus.conf and obj.conf.

      For a standalone Oracle Traffic Director installation:

      ./EditObjConf -f Domain_Home/config/fmwconfig/components/OTD/instances/Instance_Name/config/Instance_Name-obj.conf -w webgate_instanceDirectory [-oh Oracle_Home] -ws otd

      For a collocated Oracle Traffic Director installation:

      ./EditObjConf -f Domain_Home/config/fmwconfig/components/OTD/Instance_Name/config/Instance_Name-obj.conf -w webgate_instanceDirectory [-oh Oracle_Home] -ws otd

      In this command:

      • Oracle_Home is the path to the parent directory of a valid WebLogic Server installation, or to where Oracle Traffic Director is installed.

        Example:

        /home/oracle

      • webgate_instanceDirectory is the location of the directory where you will copy the WebGate profile.

        Example:

        Domain_Home/config/fmwconfig/components/OTD/instances/Instance_Name

  • On Windows

    1. Go to the %Oracle_Home%\webgate\otd\tools\deployWebGate directory by running the following command:

      cd %Oracle_Home%\webgate\otd\tools\deployWebGate

    2. Run the following command to copy the required bits of agent from the %Oracle_Home% directory to the webgate_instanceDirectory location:

      deployWebGateInstance.bat -w webgate_instanceDirectory [-oh Oracle_Home] -ws otd

      In this command:

      • Oracle_Home is the directory in which you have installed Oracle Traffic Director WebGate.

        Example:

        \home\oracle

      • webgate_instanceDirectory is the location of the directory where you will copy the WebGate profile.

        Example:

        Domain_Home/config/fmwconfig/components/OTD/instances/Instance_Name

    3. Run the following command to set the PATH environment variable:

      set %PATH%=%PATH%;%Oracle_Home%\webgate\otd\lib;%Oracle_Home%\bin

    4. Go to the following directory:

      %Oracle_Home%\webgate\otd\tools\EditObjConf

    5. On the command line, run the following command for updating OTD conf files, such as magnus.conf and obj.conf.

      For a standalone Oracle Traffic Director installation:

      EditObjConf -f Domain_Home/config/fmwconfig/components/OTD/instances/Instance_Name/config/Instance_Name-obj.conf -w webgate_instanceDirectory [-oh $(Oracle_Home)] -ws otd

      For a collocated Oracle Traffic Director installation:

      ./EditObjConf -f Domain_Home/config/fmwconfig/components/OTD/Instance_Name/config/Instance_Name-obj.conf -w webgate_instanceDirectory [-oh $(Oracle_Home)] -ws otd

      In this command:

      • Oracle_Home is the directory in which you have installed Oracle Traffic Director WebGate for Oracle Access Manager.

        Example:

        \home\oracle

      • webgate_instanceDirectory is the location of the directory where you will copy the WebGate profile.

        Example:

        Domain_Home/config/fmwconfig/components/OTD/instances/Instance_Name

A.3 Verifying the Configuration of Oracle Traffic Director 12c WebGate

After installing Oracle Traffic Director 12c (12.2.1.2.0) WebGate for Oracle Access Manager and completing the configuration steps, you can examine the installDATE-TIME_STAMP.out log file to verify the installation. The default location of the log are as follows:

  • On UNIX

    $(Oracle_Home)/oraInst.loc

  • On Windows

    C:\Program Files\Oracle\Inventory\logs

A.4 Getting Started with a New Oracle Traffic Director 12c WebGate

Before you can use the new Oracle Traffic Director 12c (12.2.1.2.0) WebGate agent for Oracle Access Manager, you must complete the following tasks:

  1. Registering the New Oracle Traffic Director 12c WebGate

  2. Copying Generated Files and Artifacts to the Oracle Traffic Director WebGate Instance Location

  3. Restarting the Oracle Traffic Director Instance

A.4.1 Registering the New Oracle Traffic Director 12c 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 an OAM Agent Using the Console in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

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:

A.4.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.

A.4.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 Traffic Director 12c WebGate is installed.

  • preferredHost

    Specify the host and the port of the machine on which Oracle Traffic Director 12c 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.

A.4.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 Traffic Director 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

A.4.1.4 Using the Out-Of-Band Mode

If you are an end user with no access to the server, you can e-mail 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 Traffic Director 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 an OAM Agent Using the Consolein the Oracle Fusion Middleware Administrator's Guide for Oracle Access Management, 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 $(Oracle_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 Traffic Director 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 an OAM Agent Using the Console in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Management, 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 $(Oracle_Home)/user_projects/domains/name_of_the_WebLogic_domain_for_OAM/output/Agent_ID directory.

A.4.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:

  • wallet/cwallet.sso

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

A.4.2 Copying Generated Files and Artifacts to the Oracle Traffic Director 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_instanceDirectory 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_instanceDirectory/webgate/config directory:

    • wallet/cwallet.sso

    • ObAccessClient.xml

    • cwallet.sso

  • In SIMPLE mode, copy the following files from the RREG_Home/output/Agent_ID directory to the webgate_instanceDirectory/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_instanceDirectory/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_instanceDirectory/webgate/config directory:

    • ObAccessClient.xml

    • cwallet.sso

    • password.xml

A.4.2.1 Generating a New Certificate

You can generate a new certificate as follows:

  1. Go to the $(Oracle_Home)/webgate/otd/tools/openssl directory.

  2. Create a certificate request as follows:

    ./openssl req -utf8 -new -nodes -config openssl_silent_otd11g.cnf -keyout aaa_key.pem -out aaa_req.pem -rand $(Oracle_Home)/webgate/otd/config/random-seed/

  3. Self-sign the certificate as follows:

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

  4. Copy the following generated certificates to the webgate_instanceDirectory/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.

A.4.2.2 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_instanceDirectory/webgate/config directory.

  2. Copy the following certificates to the webgate_instanceDirectory/webgate/config directory:

    • aaa_key.pem

    • aaa_cert.pem

    • aaa_chain.pem

A.4.3 Restarting the Oracle Traffic Director Instance

For information about restarting the Oracle Traffic Director instance, see "Starting, Stopping, and Restarting Oracle Traffic Director Instances by Using WLST" in Administering Oracle Traffic Director.

If you have configured Oracle Traffic Director in a WebLogic Server domain, you can also use Oracle Fusion Middleware Control to restart the Oracle Traffic Director Instances. For more information, see "Starting, Stopping, and Restarting Oracle Traffic Director Instances Using Fusion Middleware Control" in Administering Oracle Traffic Director.

For a standalone instance, you can restart from Domain_Home/config/fmwconfig/components/OTD/instances/Instance_Name/bin using the ./restart command.