A Configuring OAM Agent (WebGate) for Oracle Traffic Director
Note:
As of 12.2.1.4.0, Oracle Traffic Director is deprecated.
In the future, for equivalent functionality, use Oracle HTTP Server, Microsoft IIS Web Server, or Apache HTTP Server plug-ins, or a native Kubernetes load balancer, such as Traefik.
This section contains the following topics:
- Prerequisites for Configuring
You need to install Oracle Access Manager (OAM) before configuring Oracle Traffic Director. Also, there are version and environment related limitations for installing OAM. - Configuring WebGate for Oracle Traffic Director 12c (12.2.1.4.0)
- Getting Started with a New Oracle Traffic Director 12c WebGate
Prerequisites for Configuring
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 Director12c (12.2.1.4.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.For more information, see About the Oracle Identity and Access Management Installation in Installing and Configuring Oracle Identity and Access Management.
Configuring WebGate for Oracle Traffic Director 12c (12.2.1.4.0)
Complete the following steps after installing Oracle Traffic Director to configure Oracle Traffic Director12c (12.2.1.4.0) WebGate for Oracle Access Manager.
-
On UNIX
-
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 entering the following command:cd
ORACLE_HOME/webgate/otd/tools/deployWebGate
-
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.
-
-
Set the environment variable
LD_LIBRARY_PATH
toWebGate_Oracle_Home
/lib
For example:
For Linux 64:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:ORACLE_HOME/lib
For Solaris/Sparc:
export LD_PRELOAD_64=ORACLE_HOME/lib/libclntsh.so.11.1:ORACLE_HOME/lib/libnnz11.so
-
Change to the following directory:
For Unix-based platforms:
ORACLE_HOME/webgate/otd/tools/setup/InstallTools
-
On the command line, enter the following command for updating OTD configuration files, such as
magnus.conf
andobj.conf
.For a standalone Oracle Traffic Director installation:
./EditObjConf -f
Domain_Home
/config/fmwconfig/components/OTD/instances/
Instance_Name
/config/Instance_Name
-obj.conf -wwebgate_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
-
Go to the
%Oracle_Home%\webgate\otd\tools\deployWebGate
directory by running the following command:cd
%Oracle_Home%\webgate\otd\tools\deployWebGate
-
Enter the following command to copy the required bits of agent from the
%Oracle_Home%
directory to thewebgate_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
-
-
Run the following command to set the
PATH
environment variable:set PATH=PATH;
ORACLE_HOME\webgate\otd\lib;
%Oracle_Home%
\bin
-
Go to the following directory:
ORACLE_HOME\webgate\otd\tools\EditObjConf
-
On the command line, run the following command for updating OTD conf files, such as
magnus.conf
andobj.conf
.For a standalone Oracle Traffic Director installation:
EditObjConf -f
DOMAIN_HOME
/config/fmwconfig/components/OTD/instances/
Instance_Name
/config
/Instance_Name
-obj.conf -wwebgate_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
-
-
Getting Started with a New Oracle Traffic Director 12c WebGate
Before you can use the new Oracle Traffic Director 12c (12.2.1.4.0) WebGate agent for Oracle Access Manager, you must complete the following tasks:
Registering the New Oracle Traffic Director 12c WebGate
You can register the newly configured 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 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:
Setting Up the RREG Tool
To set up the RREG tool, follow the procedure below:
-
On UNIX
-
After installing and configuring Oracle Access Manager, change to the following directory:
ORACLE_IDM2
/oam/server/rreg/client
-
Extract 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
RREG_HOME
is the directory in which you extracted the contents ofRREG.tar.gz/rreg
. -
-
On Windows
-
After installing and configuring Oracle Access Manager, change to the following location:
ORACLE_IDM2
\oam\server\rreg\client
-
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
RREG_Home
is the directory in which you extracted the contents ofRREG.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.
Parent topic: Registering the New Oracle Traffic Director 12c WebGate
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
Used to specify the host and the port of the OAM Administration Server.
-
agentName
Used to specify any custom name for the agent.
-
agentBaseUrl
Used to specify the host and the port of the machine on which Oracle Traffic Director 12c WebGate is installed.
-
preferredHost
Used to specify the host and the port of the machine on which Oracle Traffic Director 12c WebGate is installed.
-
security
Used to specify the security mode, such as
open
, based on the WebGate installed. -
primaryServerList
Used to 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.
Parent topic: Registering the New Oracle Traffic Director 12c WebGate
Registering a New WebGate Agent 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.
To register a new WebGate Agent, perform the following steps:
-
Open the
OAM11GRequest.xml
file, which is inRREG_HOME
/input/
on UNIX andRREG_HOME
\input
on Windows.RREG_HOME
is the directory on which you extracted the contents ofRREG.tar.gz
.Edit the XML file and specify the parameters for the new Oracle Traffic Director WebGate for Oracle Access Manager.
-
To register, enter 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
Parent topic: Registering the New Oracle Traffic Director 12c WebGate
Registering a New WebGate Agent 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 by 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:
To register a new WebGate agent:
-
If you are an end user with no access to the server, open the
OAM11GRequest.xml
file, which is inRREG_HOME
/input/
.RREG_HOME
is the directory on which you extracted the contents ofRREG.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. -
If you are an administrator, copy the updated
OAM11GRequest.xml
file, which is inRREG_HOME
/input/
directory.This is the file that you received from the end user. Go to your (administrator's)
RREG_HOME
directory and enter the following command:./
RREG_HOME
/bin/oamreg.sh outofband input/OAM11GRequest.xml
An
Agent_ID
_Response.xml
file is generated in theoutput
directory on the administrator's machine, in theRREG_HOME
/output/
directory. Send this file to the end user who sent you the updatedOAM11GRequest.xml
file. -
If you are an end user, copy the generated
Agent_ID
_Response.xml
file, which is inRREG_HOME
/input/
.This is the file that you received from the administrator. Go to your (client's) RREG home directory and enter the following command:
./
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 Console in 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 theORACLE_HOME
/user_projects/domains/
name_of_the_WebLogic_domain_for_OAM
/output
/Agent_ID
directory. -
-
On Windows:
Complete the following steps:
-
If you are an end user with no access to the server, open the
OAM11GRequest.xml
file, which is inRREG_Home
\input\
directory.RREG_HOME
is the directory in which you extracted the contents ofRREG.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. -
If you are an administrator, copy the updated
OAM11GRequest.xml
file, which is inRREG_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 theRREG_HOME\
output\
directory. Send this file to the end user who sent you the updatedOAM11GRequest.xml
file. -
If you are an end user, copy the generated
Agent_ID
_Response.xml
file, which is inRREG_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 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 theORACLE_HOME
/user_projects/domains/
name_of_the_WebLogic_domain_for_OAM
/output
/Agent_ID
directory. -
Parent topic: Registering the New Oracle Traffic Director 12c WebGate
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
andaaa_chain.pem
files along withpassword.xml
andaaa_key.pem
.
Parent topic: Registering the New Oracle Traffic Director 12c WebGate
Copying Generated Files and Artifacts to the Oracle Traffic Director WebGate Instance
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 thewebgate_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 thewebgate_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 thewebgate_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 thewebgate_instanceDirectory
/webgate/config
directory:-
ObAccessClient.xml
-
cwallet.sso
-
password.xml
-
Generating a New Certificate
You can generate a new certificate:
-
Change to the
ORACLE_HOME/webgate/otd/tools/openssl
directory: -
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/
-
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
-
Copy the following certificates to the
webgate_instanceDirectory
/webgate/config
directory:-
aaa_key.pem
-
aaa_cert.pem
-
cacert.pem
located in thesimpleCA
directoryNote:
After copying the
cacert.pem
file, rename the file toaaa_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:
-
Change to the
webgate_instanceDirectory
/webgate/config
directory. -
Copy the following certificates to the
webgate_instanceDirectory
/webgate/config
directory:-
aaa_key.pem
-
aaa_cert.pem
-
aaa_chain.pem
-
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 Enterprise Manager 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.