15.6 Remote Registration Tool, Modes, and Process

As an alternative to using the console for agent registration, you can use the remote registration utility, oamreg, with Oracle-provided templates.

Administrators using the Oracle Access Management Console or remote registration utility must have credentials stored in the System Store (Managing Data Sources).

This section provides details about remote registration in the following topics:

See Also:

"OAM Remote Registration"

15.6.1 Remote Registration Command Arguments and Modes

Before using the remote registration tool, two environment variables within the script must be set: OAM_REG_HOME and JAVA_HOME.

Table 15-5describes the samples, which presume the location of the tool to be $OAM_REG_HOME on a Linux system. Your environment might be different.

Table 15-5 Environment Variables to Set within oamreg

Environment Variable Description

OAM_REG_HOME

The directory under which RREG.tar was exploded, followed by /rreg:

$OAM_HOME/oam/server/rreg/client/rreg

JAVA_HOME

The location where Java is located on the client computer. For example: $WLS_HOME/Middleware/jdk160_11.

Note: $JAVA_HOME should point to JDK 1.6. (JDK 1.7 can also be used in R2PS3.)

Additionally, before using the remote registration tool, you must modify several tags in the request file, as described later (Table 15-9).

The arguments required to run the remote registration script are listed in Table 15-6.

Table 15-6 Remote Registration Command Arguments: mode

Arguments Description

mode

Either:

  • inband

  • outofband

input/filename.xml

Either the absolute path to the input file (*request.xml or an agentName_Response.xml), or the path relative to the value of $OAM_REG_HOME.

The preferred location is $OAM_REG_HOME/input

The sample commands illustrated in Table 15-7 presume the location of the tool to be $OAM_REG_HOME on a Linux system.

Table 15-7 Remote Registration Command Samples

Command Type Sample (on Linux)

In-band Administrator In-band Request

 
./bin/oamreg.sh inband input/*Request.xml

In-band Administrator Submitted Request

 
./bin/oamreg.sh outofband input/starting_request.xml

Out-of-band Administrator Returned Response

 
./bin/oamreg.sh outofband input/agentName_Response.xml

[prompt_flag] value: [-noprompt]

Optional. When -noprompt is used, oamreg does not wait for prompts (password, and so on). Instead these values can be piped in, either from an input file or from the command line itself using an echo command.

Examples from $OAM_REG_HOME location:

(echo username; echo password; echo WebGate_password;) | ./bin/oamreg.sh inband input/Request.xml -noprompt config.file

(echo username; echo password; echo WebGate_password; echo httpscert_trust_prompt;) | ./bin/oamreg.sh inband input/Request.xml -noprompt

(echo username; echo password; echo WebGate_password; echo cert_password;) | ./bin/oamreg.sh inband input/Request.xml -noprompt

(echo username; echo password; echo WebGate_password; echo httpscert_trust_prompt; echo cert_password;) | ./bin/oamreg.sh inband input/Request.xml -noprompt

See Also: "Updating Agents Remotely"

Note:

After launching the script, Administrators are prompted for a username and password (unless -noprompt is used as shown in Table 15-7.)

After running the script, messages inform you of success or failure. Following a successful registration or update, you must copy the artifacts to the Agent host, as outlined in "Updating Agent Configuration Files".

15.6.2 Common Elements within Remote Registration Request Templates

Regardless of agent type, global elements are common within all remote registration request files.

Table 15-8, shows the global elements.

Note:

In Table 15-8, descriptions of each element are omitted; see Table 15-1.

Table 15-8 Common Elements in Remote Registration Requests

Element Example

<serverAddress>

 
<serverAddress>http://{oam_admin_ser
ver_host}:{oam_admin_server_port}
</serverAddress>

<agentName>

 
<agentName>RREG_OAM</agentName>

<hostIdentifier>

 
<hostIdentifier>RREG_HostId11G
</hostIdentifier>

<agentBaseUrl>

Note:

Extended Templates only
 
<agentBaseUrl>http://{web_server_
host):(web_server_port}
</agentBaseUrl>

<autoCreatePolicy>

Note:

Extended Templates only
 
<autoCreatePolicy>true
</autoCreatePolicy>

<applicationDomain>

Note:

Extended Templates only
 
<applicationDomain>RREG_OAM11G
</applicationDomain>

<virtualhost>

Note:

Extended Templates only
 
<virtualhost>false<virtualhost>

15.6.3 Key Use, Generation, Provisioning, and Storage

Each registered agent has a symmetric key, regardless of the registration method ( Oracle Access Management Console versus remote registration).

Each application will have a symmetric key whether it is protected through mod_osso, or an OAM Agent. This key is generated by the registration tool. Storage of the application mapping, key, and type of Agent persists in the system configuration for retrieval as needed. The following sections contain details.

15.6.3.1 Key Use

Each 11g WebGate agent has its own secret key that is shared between the agent and the OAM Server.

If one 11g WebGate is compromised, other 11g WebGates are unaffected. The following presents an overview:

  • Encrypt/Decrypt the host-based WebGate-specific OAMAuthnCookie_<host:port>_<random number>.

  • Encrypt/Decrypt the data that is redirected between WebGate and OAM Server.

15.6.3.2 Key Generation Process

The key generation occurs automatically when the agent is registered, regardless of the method used ( Oracle Access Management Console versus remote registration). There is one symmetric key per agent.

Figure 15-5 illustrates the process of key generation.

Figure 15-5 Key Generation

Description of Figure 15-5 follows
Description of "Figure 15-5 Key Generation"

15.6.3.3 Key Accessibility and Provisioning

Each Agent specific key must be accessible to the corresponding WebGate through a secure local storage on the client machine. Cryptographic keys are not stored in the data store. Instead, an alias to an entry in a Java keystore or CSF repository is stored; the Partner and Trust Management API obtain the actual key when it is requested.

The agent specific secret key:

  • Is provisioned during remote registration (either in-band mode or out-of-band mode)

  • Is unique so that it can uniquely identify each agent.

  • Is distributed securely back to the agent (either through the wire during in-band mode or through a separate secure channel during out-of-band mode).

  • Is saved in the Oracle Secret Store, in the SSO wallet. SSO wallet creation applies only to 11g WebGates (not to 10g WebGates or other agent types).

    Note:

    The Oracle Secret Store is a container that consolidates the storage of secret keys and other security-related secret information inside the Oracle Wallet, not in plain-text. The SSO wallet relies on underlying file system security to protect its data. Opening this wallet does not require a password. The SSO wallet depends on the operating system and file permissions for its security.

  • Is saved in the Oracle Secret Store, in an auto-login editable SSO wallet, upon completion of registration.

15.6.3.4 Key Storage

The SSO wallet containing the agent key must be located in cwallet.sso, in the directory with ObAccessClient.xml in WebGate_instance_dir/WebGate/config (for example, $WebTier_MW_Home/Oracle_WT1/instances).

The SSO wallet does not require a user password, and should be protected with the proper file permission (700) or registry on Windows.