23.6 Getting Started with a New Oracle HTTP Server 11g Webgate Agent for Oracle Access Manager

23.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:

   <IDM_Home>/oam/server/rreg/client

   On Windows operating systems:

   <IDM_Home>\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 or 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.

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

Note:

If you register the Webgate agent using the Oracle Access Manager Administration Console, as described in the "Registering Partners (Agents and Applications) by Using the Console" topic 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 machine (the machine where Oracle Access Manager Administration Console is running) to the client machine. The files and artifacts are generated in the <Middleware_Home>/user_projects/domains/<name_of_the_WebLogic_domain_for_OAM>/output/<Agent_ID> directory.

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.

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

23.6.3 Restart the Oracle HTTP Server Instance

You can use the 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>