1. Administering Oracle Access Management
  2. Managing Access Manager Settings and Agents
  3. Registering and Managing OAM Agents

15 Registering and Managing OAM Agents

You can register and manage WebGates (and the programmatic equivalent, Access Clients) using either the Oracle Access Management Console or the remote registration command-line utility. During registration, you can identify specific applications to be protected by Access Manager policies.

The following topics describe how to register and manage OAM Agents:

15.1 Before Registering and Managing Agents

Ensure that the Oracle Access Management Console host (AdminServer) and a managed OAM Server are running.

See Also:

The following, as needed for your environment.

15.2 OAM Agent Registration Parameters in the Console

Unless explicitly stated, the information here applies to WebGates, including programmatic Access Clients.

OAM Agent registration parameters topics include:

15.2.1 Creating OAM WebGate Page and Parameters

The Create OAM ... WebGate page requests minimal information to streamline registration.

Required details are identified by the asterisk (*).

Figure 15-1 Create OAM WebGate Page

Description of Figure 15-1 follows
Description of "Figure 15-1 Create OAM WebGate Page"

Table 15-1 describes the Create page for OAM WebGates (or Access Clients).

Table 15-1 Elements on Create Pages for OAM Agents

OAM WebGate Element Description

Name

The unique identifying name for this Agent registration. This is often the name of the computer that is hosting the Web server used by WebGate.

A unique identifying name for each Agent registration is preferred. However:

  • If the Agent Name exists, no error occurs and the registration does not fail. Instead, Access Manager creates the policies if they are not already in place.

  • If the host identifier exists, the unique Agent Base URL is added to the existing host identifier and registration proceeds.

Description

A meaningful description of this Agent registration.

Base URL

Optional

The host and port of the computer on which the Web server for the WebGate is installed. For example, http://example_host:port or https://example_host:port. The port number is optional.

Note: A particular Base URL can be registered once only. There is a one-to-one mapping from this Base URL to the Web server domain on which the WebGate is installed (as specified with the Host Identifier element). However, one domain can have multiple Base URLs.

Access Client Password

Optional

An optional, unique password for this WebGate, which can be assigned during this registration process.

When a registered WebGate connects to an OAM Server, the password is used for authentication to prevent unauthorized WebGates from connecting to OAM Servers and obtaining policy information.

Security

Level of communication transport security between the Agent and the OAM Server (this must match the level specified for the OAM Server):

  • Open--No transport security

  • Simple--SSL v3/TLS v1.0 secure transport using dynamically generated session keys

  • Cert--SSL v3/TLS v1.0 secure transport using server side x.509 certificates. Choosing this option displays a field where you can enter the Agent Key Password.

    Agent Key Password: The private key file (aaa_key.pem) is encrypted using DES algorithm. The Agent Key Password is saved in obfuscated format in password.xml and is required by the server to generate password.xml. However, this password is not retained by the server. When editing an WebGate registration, password.xml is updated only when the mode is changed from Open to Cert or Simple to Cert. In Cert mode, once generated, password.xml cannot be updated. Editing the Agent Key Password does not result in creation of a new password.xml.

Note: For more information on Simple and Cert modes, and private key encryption, see Securing Communication.

Host Identifier

This identifier represents the Web server host. This is automatically seeded with the value in the agent Name field.

Note: You can register multiple OAM WebGates (or Access Clients) under a single host identifier with the same Application Domain and policies, as follows:

  1. When you register a WebGate, allow the process to create a host identifier (a name of your choice), and enable "Auto Create Policies".

  2. Register a second WebGate with the same host identifier as Step 1, and clear the "Auto Create Policies" box to eliminate policy creation.

See Also: "About Virtual Web Hosting".

User-defined Parameters

Parameters you can enter to enable specific WebGate behaviors:

See Also: "User-Defined WebGate Parameters".

Virtual Host

Check the box beside Virtual Host if you installed a WebGate on a Web server that contains multiple Web site and domain names. The WebGate must reside in a location that enables it to protect all of the Web sites on that server.

See Also: "About Virtual Web Hosting".

Auto Create Policies

During agent registration, you can have authentication and authorization policies created automatically. This option is checked (enabled) by default.

Default: Enabled

Shared Registration and Policies: Multiple WebGates (or Access Clients) installed on different Web servers can share a single registration and policies to protect the same resources. This is useful in a high-availability failover environment. To do this:

  1. WebGate1: Register the first WebGate and enable Auto Create Policies to generate a host identifier (named as you like) and policies.

  2. WebGate2: Register the second WebGate, specify the same host identifier as the first WebGate, and disable Auto Create Policies.

After registering the second agent, both WebGates use the same host identifier and policies.

IP Validation

Check the box beside IP Validation to ensure a client's IP address is the same as the IP address stored in the ObSSOCookie generated for single sign-on. In the IP Validation Exceptions box, enter any IP addresses to exclude from validation using standard notation for the addresses: for example, 10.20.30.123.

When enabled, the IP address stored in the ObSSOCookie must match the client's IP address. Otherwise, the cookie is rejected and the user must re-authenticate.

Default: Disabled

See Also: "IP Address Validation for WebGates".

Agent Key Password

Requested for only Cert mode communication, this passphrase is used to encrypt the private key used for SSL communication between WebGate and the OAM Server in Simple and Cert modes.

Note: The Agent Key Password has no relationship to the Access Client Password described earlier within this table.

Cert Mode: In this mode, the agent key can be different on the client and server; it is no longer global. Administrators must enter the Agent Key Password to enable generation of a password.xml file during agent registration, which must be copied to the agent side. For certificate generation, you must encrypt the private key (used for SSL) using this password through openssl or other third-party tools to be placed inside aaa_key.pem. At runtime, WebGate retrieves the key from password.xml, and uses it to decrypt the key in aaa_key.pem.

  • If the key is encrypted, WebGate internally invokes the call back function to obtain the password.

  • If the key is encrypted and password.xml does not exist, WebGate cannot establish connections with the OAM Server.

  • If the key is not encrypted, there is no attempt to read password.xml.

For more information, see Securing Communication.

Resource Lists

Protected Resource (URI) List

URIs for the protected application: /myapp/login, for example. Each URI for the protected application should be specified in a new row of the table for the Protected Resource List.

Default: /**

The default matches any sequence of characters within zero or more intermediate levels spanning multiple directories.

Add Resources: Each URI should be specified in a new row of the table for the Protected Resource List. Click the + button to add a resource to the Protected Resource List. For instance, if you add /financial (and repeat to add /myfinancial) the following URLS are seeded into the designated policies of the Application Domain when Auto Create Policies is selected):

  • /financial yields Resource URL /financial/**
  • /myfinancial yields Resource URL /myfinancial/**
  • /**

See Also: "Resource URL, Prefixes, and Patterns".

Public Resource (URI) List

Each public application should be specified in a new row of the table for the Public Resource List.

Add Resources: Each URI should be specified in a new row of the table for the Public Resource List. Click the + button to add a resource to the Public Resource List. For instance, if you add /people the following URLS are included here and in the Application Domain (when Auto Create Policies is selected):

  • /people

See Also: "Resource URL, Prefixes, and Patterns".

See Also:

Table 15-3

To help streamline WebGate registration, some elements are concealed during the create operation and default values are applied.

Note:

All changes made using the Oracle Access Management Console are taken up without restarting the application server. Changes are reflected automatically after the re-configuration timeout period.

15.2.2 User-Defined WebGate Parameters

Certain supported parameters can be defined by Administrators entering values directly on the WebGate registration page or within the OAM Agent remote registration request template.

Table 15-2 describes supported user-defined parameters. Each parameter can have only one value.

Table 15-2 User-Defined WebGate Parameters

User-Defined WebGate Parameter Description

ChallengeRedirectMethod

Configure this user-defined authentication POST data preservation parameter for both the embedded credential collector (ECC) and the detached credential collector (DCC).

Value: GET|POST|DYNAMIC

Note: Preference is given first to the Authentication Scheme containing this parameter; second to the WebGate providing this user defined parameter. Otherwise, default behavior is Dynamic.

See Also: Table 22-25

ChallengeRedirectMaxMessageBytes

Configure this user-defined WebGate parameter to limit the size of the message data received as obrareq.cgi and obrar.cgi. Message data is comprised of query string length, if present (or POST data length, if POST data is present). If message size exceeds this limit, the message is not processed and the existing message is shown in the browser. The event is logged as usual.

Default: 8192 bytes

Notes:

obrareq.cgi is the authentication request in the form of a query string redirected from WebGate to OAM Server.

obrar.cgi is the authentication response string redirected from the OAM Server to WebGate.

See Also: "Configuring Authentication POST Data Handling"

Table 15-2

MaxPostDataBytes

Authentication post-data preservation parameter for both the embedded credential collector (ECC) and the detached credential collector (DCC).

This parameter requires a positive integer value that restricts the maximum number of bytes of POST data that is submitted as user credentials and sent to the OAM Server.

Default: 8192 bytes

Assigning MaxPostDataBytes to a Resource WebGate gives preference to restricting the size of the post data received from the application before forwarding the post data to be preserved.

See Also: "Configuring the PasswordPolicyValidationScheme"

"Configuring Authentication POST Data Handling"

Table 22-25

MaxPreservedPostDataBytes

Configure this user-defined WebGate parameter (or user-defined Authentication Scheme challenge parameter) for authentication POST-data preservation.

Default: 8192 bytes

Note: Preference is given first to the Authentication Scheme containing this parameter; second to the WebGate providing this user-defined parameter. Otherwise, default behavior is 8192 bytes.

This parameter defines the maximum length of POST data that WebGate can preserve. If the size of inbound raw user POST data (or encrypted post data after processing), crosses this limit, POST data is dropped and the existing authentication flow continues. The event is logged as usual.

See Also: "Configuring Authentication POST Data Handling"

Table 22-25

PostDataRestoration

Authentication post-data preservation parameter for both the embedded credential collector (ECC) and the detached credential collector (DCC). This parameter requires a value of true or false.

Default: false

When set to true, WebGate initiates POST data preservation.

See Also: "Configuring Authentication POST Data Handling"

serverRequestCacheType

ECC Only

Authentication post-data preservation parameter by the embedded credential collector (ECC).

This OAM Server parameter in oam-config.xml indicates mechanism to be used to remember the request context. Possible values are FORM, COOKIE, or CACHE.

Default: COOKIE

FORM is the required value for POST data preservation.

See Also: TempStateMode in Table 22-25.

"Configuring Authentication POST Data Handling"

UrlInUTF8Format=true

In an environment that uses Oracle HTTP Server 2, this parameter must be set to true to display latin-1 and other character sets.

ProxySSLHeaderVar=IS_SSL

Uses when the WebGate is located behind a reverse proxy, SSL is configured between the client and the reverse proxy, and non-SSL is configured between the reverse proxy and the Web server. It ensures that URLs are stored as HTTPS rather than HTTP. The proxy ensures that URLs are stored in HTTPS format by setting a custom header variable indicating whether it is servicing an SSL or non-SSL client connection.

The value of the ProxySSLHeaderVar parameter defines the name of the header variable the proxy must set. The value of the header variable must be "ssl" or "nonssl".

If the header variable is not set, the SSL state is decided by the SSL state of the current Web server.

Default: IS_SSL

client_request_retry_attempts=1

WebGate-to-OAM Server timeout threshold specifies how long (in seconds) the WebGate waits for the OAM Server before it considers it unreachable and attempts the request on a new connection.

If the OAM Server takes longer to service a request than the value of the timeout threshold, the WebGate abandons the request and retries the request on a new connection.

Default: 1

Note: The new connection that is returned from the connection pool can be to the same OAM Server, depending on your connection pool settings. Also, other OAM Servers may also require more time to process the request than the time specified on the timeout threshold. In some cases, the WebGate can retry the request until the OAM Servers are shut down. You can configure a limit on the number of retries that the WebGate performs for a non-responsive server using the client_request_retry_attempts parameter.

InactiveReconfigPeriod=10

The WebGate update thread reads the shared secret from the OAM Server every 1 minute when WebGate is active. The OAM Server server returns the shared secret in its own cache (the OAM Server cache).

Default: 10 (minutes)

logoutRedirectUrl=

Default = http://OAMServer_host:14200/oam/server/logout

maxAuthorizationResultCacheElems

Max Authorization Results Cache Elements—Number of elements maintained in the Authorization Result Cache. This cache maintains information about authorization results for associated sessions. For example:

maxAuthorizationResultCacheElems=10000

Default = 100000

authorizationResultCacheTimeout

Authorization Results Cache Timeout—Number of elements maintained in the Authorization Result Cache. This cache maintains information about authorization results for associated sessions. For example:

authorizationResultCacheTimeout=60

Default, if no time is specified = 15 (seconds)

Note: Authorization Results Cache Timeout is not set by default.

With the cache enabled, the first request result persists for the cache duration. This magnifies the effect causing a brief time delay. For example suppose you set an authentication policy Response and set a custom session attribute exmpl:sample. The corresponding authorization policy Response returns this as HEADER SESSION_ATTR_EXMPL=sample. When a user access the URL protected by these policies, the header comes after a few refreshes. Initially, however, the value might not be found.

A value of 0 disables the cache. With no cache, it takes two requests for the header response to be filled. The first sets the session variable used, the second uses the session variable. Oracle recommends that you do not set a Response value in the same authorization request that triggers it.

UniqueCookieNames

Controls WebGate cookie name format:

  • Legacy: Backward compatible and supports the colon (:) character. The format is <prefix>_<host>:<port>_<suffix>

  • Enabled: Default and enable rfc2109-compliant cookie name restriction. The format is <prefix>_<host>_<port>_<suffix>

  • Disabled: no <host>[:/_]<port> is added in the cookie name. The format is <prefix>_<suffix>.

  • Any other value is treated as the default enabled format. <prefix>_<host>_<port>_<suffix>

EnableFIPSMode=true

Enables FIPS mode for WebGates in CERT security mode.

In FIPS mode, a Federal Information Processing Standard (FIPS) 140-2 certified security module is used by the WebGates to establish SSL/TLS connections.

Note:

For WebGates, only OAP over TCP is FIPS compliant.

By default, FIPS mode is disabled. From WebGate 12c PS1 release onwards, you can enable the FIPS mode by setting EnableFIPSMode=true.

Ensure the root certificate CA that is added in cwallet.sso is not MD5. If the root CA is MD5, the TLS handshake fails and the following error is logged: Error: TLS Handshake unsuccessful

If the FIPS mode is initialized successfully, the following message is logged in the webgate.log file: "Fips Mode Initialized Successfully...."

Note:

If the FIPS mode fails to initialize due to missing or corrupted libraries, the WebGate switches to non-FIPS Mode and the following message is logged in the webgate.log file:

Missing/Corrupted FIPS Libraries at the specified location path. Hence proceeding without FIPS Mode.

OAM WebGate only

SetKeepAlive

By default, SetKeepAlive is ON. In this case, a first keep-alive message will be sent after the default idle time of 2 minutes. To change this behavior, set a new value for the parameter. If SetKeepAlive=Off, the feature is disabled and no keep-alive messages will be sent. If SetKeepAlive=x (where x is some positive integer value), the keep-alive message will be sent after the channel is idle for x minutes. Any firewall or load balancer should be configured to forward the TCP/IP keep-alive messages to the actual end parties (front-ending Access Manager server).

A programmatic way to change the idle time is implemented for Linux64, Linux32, and Windows32 WebGates. This is not possible on SPARC Solaris platforms; in that case, SetKeepAlive is enabled and the idle time out for Keep alive must be set manually by the system administrator.

filterOAMAuthnCookie

For WebGate, a user-defined parameter (filterOAMAuthnCookie (default true)) can be used to prevent the OAMAuthnCookie from being passed to downstream applications for security consideration. If you do want to pass the cookie on, then set the filterOAMAuthnCookie parameter to false.

ssoCookie

Controls the OAMAuthnCookie cookie.

Default:

ssoCookie=httponly

ssoCookie=Secure

Disable either setting:

ssoCookie=disablehttponly

ssoCookie=disableSecure

Note: These parameters are configured differently depending on your credential collector configuration.

  • For detached credential collector-enabled OAM WebGates, set these parameters directly in the agent registration page.

  • For non-DCC agents (Resource WebGates), these parameters are configured through user-defined challenge parameters in authentication schemes.

See Also:

Table 22-25

"Configuring Challenge Parameters for Encrypted Cookies"

"Configuring OAM WebGate and Authentication Policy for DCC"

miscCookies

Controls other miscellaneous Access Manager internal cookies. By default, httponly is enabled for all other (miscellaneous) cookies.

Default:

miscCookies=httponly

miscCookies=Secure

Disable either setting:

miscCookies=disablehttponly

miscCookies=disableSecure

Note: These parameters are configured differently depending on your credential collector configuration.

  • For detached credential collector-enabled WebGates, set these parameters directly in the agent registration page.

  • For non-DCC agents (Resource WebGates), these parameters are configured through challenge parameters of the same name.

See Also:

Table 22-25

"Configuring Challenge Parameters for Encrypted Cookies"

"Configuring OAM WebGate and Authentication Policy for DCC"

OAMAuthAuthenticationServiceLocation

WebGate non-browser client functionality

Activates non-browser client functionality and defines the location of the authentication service.

OAMAuthUserAgentPrefix=prefix string that acts as the prefix for the "user-agent" HTTP header value.

For example, to activate this functionality for Identity Connect:

OAMAuthAuthenticationServiceLocation=https://login.example.com/nbc

Non-browser client functionality is deactivated if the parameter is omitted (or is provided with no value).

OAMAuthUserAgentPrefix

WebGate non-browser client functionality

Activates non-browser client functionality and defines the string that acts as a prefix for the "user-agent" http header value.

OAMAuthAuthenticationServiceLocation=full URL location of the NBC authentication service.

For example, to activate this functionality for Identity Connect:

OAMAuthUserAgentPrefix=NBC

Non-browser client functionality is deactivated if this parameter is omitted (or is provided with no value).

RequestContextCookieExpTime

Controls the time (in seconds) to expire OAMRequestContext cookie. Configuring the cookie lifetime is an optional control for deployments with a critical need to handle situations where the cookies could proliferate.

Default: not set

In the Resource WebGate registration, add this parameter to expire the OAMRequestContext cookie in the configured number of seconds using the "Max-Age" directive on all but IE browsers (default 5 minutes).

Note: For Internet Explorer only, this parameter requires a time sync between the browser and Web server hosts because IE uses the "Expires" directive to expire the cookie with an absolute time. However, on IE browsers, when this parameter is not set, OAMRequestContext cookie is a transient session cookie.

On other (non-IE) browsers, the cookie is persistent and expires based on the time set using the "Max-Age" directive.

See Also:

OAMRequestContext in Table 21-6

ProxyTrustedIPList

Multi-valued parameter that holds the list of IP addresses of the trusted proxies or load balancers. See ProxyTrustedIPList.

ProxyRemoteIPHeaderVar

Specifies the name of the HTTP header that contains the list of IP addresses. See ProxyRemoteIPHeaderVar.

IsXssHandleByWG

Configure this user-defined WebGate parameter to prevent XSS attacks. The WebGate parses the URL and will block the request when XSS is detected.

Default: false

IsAllowedIllegalChar

Configure this user-defined WebGate parameter to allow defined characters to bypass XSS checking. This is typically required when a WebGate is protecting a legacy application.

The following characters are allowed: '<', '>','{', '}','`', '\0'.

Default: false

15.2.3 IP Address Validation for WebGates

IP address validation is a function that determines if a client's IP address is the same as the IP address stored in the cookie generated for single sign-on. The IPValidation parameter turns IP address validation on and off; it is a WebGate specific parameter found in the WebGate profile.

If IPValidation is true, the IP address stored in the cookie must match the client's IP address, otherwise, the SSO cookie (Table -00) is rejected and the user must reauthenticate. By default, IPValidation is false. The following is true in regards to enabling and disabling IP Validation.

  • Enabling IP Validation on the WebGate automatically enables it on the OAM server side; this can be verified in the Access Manager settings.

  • Disabling IP Validation on the WebGate will not disable it on the OAM server.

  • IP Validation on the OAM server side should be disabled manually, if and only if it is disabled on all the WebGates.

  • When IP Validation is enabled on the WebGate side, server side IP Validation should never be turned off.

Note:

Access Manager now supports Internet Protocol version 6 (IPv6) as well as IPv4.

To configure single sign-on between WebGate and an Access Client that does not have the client IP address at authentication, the IP validation option can be explicitly turned off (set IP Validation to false). When the IP Validation parameter is set to false, the browser or client IP address is not used as a part of the SSO cookie. However, Oracle recommends that you keep IP validation on whenever possible. For WebGate profile configuration information, see Viewing or Editing an OAM Agent Registration Page in the Console. Additional details are in the following sections.

15.2.3.1 IP Validation Exceptions List

The IP Validation parameter can cause problems with certain Web application deployments.

For example, Web applications managed by a proxy server typically change the user's IP address, substituting the IP address of the proxy. This prevents single sign-on from using the cookie. The IP Validation Exceptions parameter lists IP addresses that are exceptions to this process. When IPValidation is true, the IP address is compared to the IP Validation Exceptions List. If the address is found on the list, it does not need to match the IP address stored in the cookie.

You can add as many IP addresses as needed to the Exceptions list - the actual IP addresses of the client and not the IP addresses stored in the ObSSOCookie SSO cookie. If an SSO cookie is from one of the exception IP addresses, the Access System ignores the address stored in the SSO cookie for validation. (The IP addresses in the IP Validation Exceptions List can be used when the IP address in the cookie is for a reverse proxy.)

15.2.3.2 IP Validation in Load Balanced Environments

In the case of (proxy servers or) a load balancer, Oracle Access Manager cannot enforce true IP validation because an attacker can use the IP address defined in the exception list. Web applications managed thusly typically change the user's IP address (substituting the IP address of the proxy or load balancer). This can prevent single sign-on using the SSO cookie.

A load balancer adds an "X-forwarded-for" header variable to incoming HTTP requests, containing a comma-space-separated list of the original IP number of the requester. Consider the following example in which the request passed proxy1, proxy2 and proxy3 (proxy3 appears as the remote address of the request). The last IP address is always the IP address that connects to the last proxy.

X-Forwarded-For: client1, proxy1, proxy2

The trust list will be referenced to look up each IP address from the header, starting with the right-most value. The left-most IP address being the farthest downstream client and each successive proxy that passed the request (adding the IP address from which it received the request).

Within the specified order, the first IP address that does not match any of those in the trusted list is treated as an apparent client IP (defined as the IP address of the initiator of the connection to the furthest node along the communication path that can be trusted). Additionally:

  • When all IP addresses from the header (starting from the right side) match with entries in the trusted list, WebGate chooses the end client IP (the left most IP address in the header).

  • When the IP address is determined, WebGate obtains a session token that contains the apparent client IP address and IP validation is evaluated by comparing the IP address against the address in the session token.

  • When the IP validation feature is enabled within a load balanced deployment, authentication (session creation) and authorization is done by the WebGate with this feature; otherwise the authenticated user must re-authenticate. When WebGate searches for the particular HTTP header, the search is case-insensitive. For example, "X-Forwarded-For" and "X-FORWARDED-FOR" are treated the same.

15.2.3.2.1 ProxyTrustedIPList

ProxyTrustedIPList is a user defined, multi-valued WebGate parameter that holds the list of IP addresses for the trusted proxies or load balancers.

The values are space separated. The IP addresses in the IP Validation Exceptions List can be used when the IP address in the cookie is for a reverse proxy.

Figure 15-2 Load Balanced Deployment

Description of Figure 15-2 follows
Description of "Figure 15-2 Load Balanced Deployment"

In Figure 15-2, the end user's HTTP request passes through REVERSEPROXY1 and REVERSEPROXY2 to reach the actual Web server. In this case, the IP addresses of REVERSEPROXY1 and REVERSEPROXY2 should be added in the ProxyTrustedIPList list as follows: 

ProxyTrustedIPList=10.77.199.59 10.77.199.26

Note:

In a centralized authentication deployment, if any Resource WebGate (RWG) or Authentication WebGate (AWG) is behind a proxy, the IP addresses of all intermediaries must be configured (in the ProxyTrustedIPList parameter) in the profile of the WebGate behind the proxy. Otherwise, IP validation failures can occur.

15.2.3.2.2 ProxyRemoteIPHeaderVar

The ProxyRemoteIPHeaderVar parameter specifies the name of the HTTP header that contains the list of IP addresses.

If this parameter is not provided, the default header X-Forwarded-For is used. This parameter can be configured like any other user-defined parameter in a WebGate profile. For example, in the deployment described in ProxyTrustedIPList, "X-FORWARDED-FOR" and other headers that come to the Web server take the following form. 

HTTP_X_FORWARDED_FOR="10.77.199.129, 10.77.199.59"
REMOTE_ADDR="10.77.199.26"

15.3 Registering an OAM Agent Using the Console

The registration procedure for WebGate or programmatic Access Client is the same. You can register an OAM-type agent before you deploy it.

Users with valid Administrator credentials can perform the following task to register a WebGate using the Oracle Access Management Console.

When the Oracle Access Manager (OAM) WebGate component is required to be used in a Highly Available (HA) environment to eliminate a single point of failure and distribute the workload via a load balancer (LBR), the OAM WebGate component only has to be registered once. The Resulting Artifacts will be used by all of the OAM WebGates behind the LBR.

See Also:

After agent registration, you can change the communication mode of the OAM Server if needed. Communication between the agent and server continues to work as long as the WebGate mode is at least at the same level as the OAM Server mode or higher. See Securing Communication.

Note:

You use the same procedure to register a programmatic Access Client. The version is the same as the SDK used to create the Access Client.

Before you begin, confirm that at least one OAM Server is running in the same mode as the agent to be registered.

  1. In the Oracle Access Management Console, click Application Security at the top of the window.

  2. In the Application Security console, select Create WebGate from the Agents menu.

  3. On the Create WebGate page, enter required details (those with an *) to register this Agent.

  4. Protected Resource List: In this table, enter individual resource URLs to be protected by this Agent, as shown in Table 15-1.

  5. Public Resource List: In this table, enter individual resource URLs to be public (not protected), as shown in Table 15-1.

  6. Auto Create Policies: Check to create a fresh Application Domain and policies (or clear and use the same host identifier as another WebGate and share policies (Table 15-1)).

  7. Click Apply to submit the registration.

    You may also close the page without applying changes, if applicable.

  8. Click the Download button to download the generated artifacts.

    Downloaded artifacts are located in the $DOMAIN_HOME/output/$Agent_name folder.

  9. Copy the artifacts as follows (or install WebGate with the same specifications, then copy artifacts), including any Simple or Cert mode files. For example, Open mode files include:

    Agent & Artifacts Artifacts

    WebGate/Access Client

    ObAccessClient.xml and cwallet.sso

    From the AdminServer (Console) host: $DOMAIN_HOME/output/$Agent_Name/

    To the Agent host: $11gWG_install_dir/WebGate/config

  10. Verify Registration: These are similar to steps in "Validating Agent Registration using the Oracle Access Management Console".

    1. Under Agents in Application Security, search and confirm the Agent name is listed.

    2. Confirm the Agent's page contains the appropriate information.

    3. Auto Create Policies: Confirm the Application Domain was generated, the host identifier was created for the application, and that resources were created in the Application Domain and associated with the host identifier.

    4. Perform further tests, as described in "Verifying Authentication and Access After Remote Registration".

  11. Proceed as needed for your deployment:

15.4 Bulk Updates to WebGates

Multiple WebGate profiles can be updated simultaneously by grouping common parameters of WebGates into a WebGate template.

Topics

15.4.1 Updating Multiple WebGate Profiles

Use WebGate template to group WebGates sharing common parameters and values. You can update the WebGate template using WLST commands. The command updates the parameters across all WebGates associated with the specified WebGate template.

To update multiple WebGates at the same time:
  1. Create a WebGate template and map all WebGates with common parameters to that template. See Creating a WebGate Template and Mapping WebGates to that Template for more information.
  2. Run the updateWebgateTemplateParams command with the required parameters. For example, to update ipValidation exceptions across multiple WebGates, specify the parameter and its corresponding values in the command:
    updateWebgateTemplateParams(webgateTemplateName="TemplateA", webgateParamsList="ipValidation,ipValidation exceptions", webgateValuesList="1,192.168.1.3:1.2.4.6:255.255.255.1:234.12.12.13", batchSize="20")

    This command updates the ipvalidation exception parameter with the IP addresses provided in the command across all WebGates that are associated with TemplateA .

    The updateWebgateTemplateParams command does not remove existing parameters and values. To remove any of the parameters, use the removeWebgateTemplateParams command.
15.4.1.1 Creating a WebGate Template and Mapping WebGates to that Template

Use the createWebgateTemplate and updateWebgateTemplateToWebgateMapping WLST commands to create a WebGate template and map WebGates to that template.

  1. Create a WebGate template by running the createWebgateTemplate WLST command.
    createWebgateTemplate(webgateTemplateName="TemplateA",webgateParamsList="cookieSessionTime,maxConnections",webgateValuesList="24,5")
  2. Associate WebGates to this template using the updateWebgateTemplateToWebgateMapping command.
    updateWebgateTemplateToWebgateMapping( webgateTemplateName="TemplateA", webgateIdsList="IAMSuiteAgent", isWebgateIdsListAFilePath = "False")
    To use a file containing a list of WebGate Ids, set the isWebgateIdsListAFilePath to true and specify the file path in the isWebgateIdsListAFilePath argument.
    updateWebgateTemplateToWebgateMapping( webgateTemplateName="TemplateA", webgateIdsList="/tmp/test.txt", isWebgateIdsListAFilePath="True", batchSize="20")

15.4.2 WLST Commands for Bulk Updates to WebGate Profiles

The following WebLogic Scripting Tool (WLST) commands support bulk updates to WebGate profiles. More information in the following sections.

15.4.2.1 createWebgateTemplate

The createWebgateTemplate command enables you to create a WebGate template with the parameters and values specified within the command.

Description

The createWebgateTemplate command creates a WebGate template with the specified parameters and values.

Syntax

createWebgateTemplate(webgateTemplateName="<NameOfTemplate>", webgateParamsList="<webgateParamsList>", webgateValuesList="<webgateValuesList>")
Arguments Definition

webgateTemplateName

 Specifies the name of the WebGate template to be created.

webgateParamsList

 A comma-seperated list of WebGate parameters that needs to be added to the WebGate template.

webgateValuesList

 Specifies the values corresponding to the webgateParamsList.

Example

This example illustrates the use of the createWebgateTemplate command. 

createWebgateTemplate(webgateTemplateName="TemplateA", webgateParamsList="cookieSessionTime, maxConnections", webgateValuesList="24,5")
15.4.2.2 updateWebgateTemplateToWebgateMapping

The updateWebgateTemplateToWebgateMapping command enables you to associate WebGates with a WebGate template.

Description

The updateWebgateTemplateToWebgateMapping command enables you to associate all the WebGates having common parameters with a WebGate template, using WebGate IDs. This command overrides the existing parameters and values.

Syntax

updateWebgateTemplateToWebgateMapping(webgateTemplateName="<NameOfTemplate>", webgateIdsList="<webgateIdsList>", webgateIdsExclusionList="<Webgate1, Webgate2, ...>", [isWebgateIdsListAFilePath="False"], [batchSize="<batchSize>"])
Argument Definition

webgateTemplateName

 Specifies the name of the WebGate template.

webgateIdsList

 A comma-separated list of WebGate IDs that needs to be associated with the WebGate template.

Supports a file containing a list (separated by new-line) of WebGate IDs.

webgateIdsExclusionList

 Specifies the IDs of the WebGates that need to be excluded from the WebGate template.

isWebgateIdsListAFilePath

 [Optional] Defaults to False. Set this value to True to specify a file containing the WebGate IDs.

batchSize

 [Optional] Specifies the number of WebGate instances to be processed per thread. Default value is 10.

Example

These examples illustrates the use of updateWebgateTemplateToWebgateMapping command. 

updateWebgateTemplateToWebgateMapping(webgateTemplateName="TemplateA", webgateIdsList="/tmp/test.txt", webgateIdsExclusionList="Webgate1,Webgate2", isWebgateIdsListAFilePath = "True", batchSize="20")

updateWebgateTemplateToWebgateMapping(webgateTemplateName="TemplateA", webgateIdsList="IAMSuiteAgent", isWebgateIdsListAFilePath = "False")
15.4.2.3 updateWebgateTemplateParams

The updateWebgateTemplateParams command enables you to update an existing WebGate template with the common parameters and values specified within the command.

Description

The updateWebgateTemplateParams command updates the WebGate template with the specified parameters and values that are common across the WebGates of the specified template type. You can use this command to update the WebGate template with additional parameters. This command does not remove the existing parameters. You must use the removeWebgateTemplateParams command to remove the parameters from the template.

Syntax

updateWebgateTemplateParams (webgateTemplateName="<NameOfTemplate>", webgateParamsList="<webgateParamsList>", webgateValuesList="<webgateValuesList>", [batchSize="<batchSize>"])
Argument Definition

webgateTemplateName

 [Mandatory] Specifies the name of the WebGate template that needs to be updated. If the template does not exist, a new WebGate template is created with the specified name.

webgateParamsList

 List of WebGate parameters associated with the WebGate template. Specify the parameters in the format: webgateParamsList="Parameter1, Parameter2, ...".

Specify the user defined parameters in the format:userdefinedparameters/[parameters].

webgateValuesList

 Specifies the values corresponding to the parameters in the webgateValuesList. Specify the values for the parameters in the format: webgateValuesList="ParameterValue1, ParamaterValue2, ..."

Specify the IP for IPValidationExceptions in the following format, for example:192.168.1.1:255.255.255.1. Use a colon (:) to separate the IP values.

batchSize

 [Optional] Specifies the number of WebGate instances to be processed per thread of the ThreadPool. Default value is 10. Specify the size in the following format, for example batchSize="20"

Example

This example illustrates the use of updateWebgateTemplateParams command. 

updateWebgateTemplateParams(webgateTemplateName="TemplateA", webgateParamsList="idleSessionTimeout", webgateValuesList="3650", batchSize="20")
15.4.2.4 removeWebgateTemplateParams

The removeWebgateTemplateParams command removes the specified parameters from the WeGate template.

Description

The removeWebgateTemplateParams command removes the specified parameters from the WebGate template.

Syntax

removeWebgateTemplateParams(webgateTemplateName="<NameOfTemplate>", webgateParamsList="<webgateParamsList>")
Arguments Definition

webgateTemplateName

 Specifies the name of the WebGate template.

webgateParamsList

 A comma-seperated list of WebGate parameters that needs to be removed from the WebGate template.

Example

This example illustrates the use of the removeWebgateTemplateParams command. 

removeWebgateTemplateParams(webgateTemplateName="webgateTemplateName1",webgateParamsList="idleSessionTimeout")
15.4.2.5 rollbackWebgatesToPreviousState

The rollbackWebgatesToPreviousState command returns the WebGate profiles to its previous successful state.

Description

If an update to the WebGate template fails, you can revert all the WebGate information to its previous values (successful state before running the command) using the rollbackWebgatesToPreviousState command.

Syntax

rollbackWebgatesToPreviousState()

There are no arguments for this command

Example

This example illustrates the use of the rollbackWebgatesToPreviousState command. 

rollbackWebgatesToPreviousState()
15.4.2.6 showWebgateTemplate

The showWebgateTemplate command displays the metadata of the specified WebGate template.

Description

The showWebgateTemplate command can be used to view the current property and values of an existing Webgate Template. This command also lists the WebGates associated with that template.

Syntax

showWebgateTemplate(webgateTemplateName="<NameOfTemplate>")
Arguments Definition

webgateTemplateName

 [Mandatory] Specifies the name of the WebGate template. The command displays the properties and values for this template.

Example

This example illustrates the use of the showWebgateTemplate command. 

showWebgateTemplate(webgateTemplateName="DemoTemplate")

15.5 Configuring and Managing Registered OAM Agents Using the Console

This section provides the following topics to help you manage registered WebGates:

15.5.1 Registered OAM Agent Configuration Parameters in the Console

Whether you registered the agent using the Oracle Access Management Console or the remote registration utility, you can view the full agent configuration page in the console

Figure 15-3 shows the OAM WebGate Page with the default values.

Figure 15-3 Expanded OAM WebGate Page with Defaults

Description of Figure 15-3 follows
Description of "Figure 15-3 Expanded OAM WebGate Page with Defaults "

Note:

Most elements on the agent's page are the same as those you define when using the remote registration tool with the expanded OAM template. ObAccessClient.xml is populated with values after agent registration or modification, regardless of the method you use.

Table 15-3 describes elements on an expanded registration. Additional settings revealed here are used by the OAM Proxy.

Table 15-3 Elements on Expanded OAM WebGate/Access Client Registration Pages

Element Description

Name

Version

Description

Access Client Password

Security

User-defined Parameters

IP Validation

See: Table 15-1.

See Also: "User-Defined WebGate Parameters"

See Also: "IP Address Validation for WebGates".

State

Only in the console.

Specifies whether this registration is enabled or disabled.

Default = Enabled

Max Cache Elements

Number of elements maintained in the cache. Caches are the following:

  • Resource to Authentication Scheme—This cache maintains information about Resources (URLs), including whether it is protected and, if so, the authentication scheme used for protection.

  • (OAM WebGate only) Resource to Authorization Policy—This cache maintains information about Resources and associated authorization policy—This cache stores authentication scheme information for a specific authentication scheme ID.

The value of this setting refers to the maximum consolidated count for elements in these caches.

Default = 100000

Cache Timeout (seconds)

Amount of time cached information remains in the WebGate caches (Resource to Authentication Scheme, Authentication Schemes, and OAM WebGate only Resource to Authorization Policy) when the information is neither used nor referenced.

Default = 1800 (seconds)

Max Connections

The maximum number of connections that this WebGate can establish with the OAM Server. This number must be the same as (or greater than) the number of connections that are actually associated with this agent.

Default = 1

Max Session Time (hours)

Maximum time to keep network connections from this WebGate to the OAM Server alive. After elapsed time, all the WebGate to OAM Server network connections will be shutdown and replaced with new ones. The unit is based on the maxSessionTimeUnits user-defined parameter which can be 'minutes' or 'hours'. When maxSessionTimeUnits is not defined, the unit is defaulted to 'hours'.

Failover Threshold

Number representing the point when this WebGate opens connections to a Secondary OAM Server.

Default = 1

For example, if you type 30 in this field and the number of connections to primary OAM Server falls to 29, this Agent opens connections to secondary OAM Server.

AAA Timeout Threshold

Number (in seconds) to wait for a response from the OAM Server. If this parameter is set, it is used as an application TCP/IP timeout instead of the default TCP/IP timeout.

Default = -1 (default network TCP/IP timeout is used)

If using a simple mode WebGate, you can improve the response time of the OAM login page by changing the aaaTimeoutThreshold time parameter in the WebGate profile from -1 to 10.

A typical value for this parameter is between 30 and 60 seconds. If set to a very low value, the socket connection can be closed before a reply from OAM Server is received, resulting in an error.

For example, suppose a WebGate is configured to talk to one primary OAM Server and one secondary OAM Server. If the network wire is pulled from the primary OAM Server, the WebGate waits for the TCP/IP timeout to learn that there is no connection to the primary OAM Server. The WebGate tries to reestablish the connections to available servers starting with the primary OAM Server. Again, the Agent waits for the TCP/IP timeout to determine if a connection can be established. If it cannot, the next server in the list is tried. If a connection can be established to another OAM Server (either a primary or secondary), the requests are re-routed. However this can take longer than desired.

When finding new connections, WebGate checks the list of available servers in the order specified in its configuration. If there is only one primary OAM Server and one secondary OAM Server specified, and the connection to the primary OAM Server times out, the Agent still tries the primary OAM Server first. As a result, the Agent cannot send requests to an OAM Server for a period greater than twice the setting in the OAM Server Timeout Threshold.

If the OAM Server takes longer to service a request than the value of the timeout threshold, the Agent abandons the request and retries the request on a new connection. Note that the new connection that is returned from the connection pool can be to the same OAM Server, depending on your connection pool settings. Also, other OAM Server may also take longer to process the request than the time specified on the threshold. In these cases, the Agent can continue to retry the request until the OAM Server is shut down.

ServerConnectionReadTimeout

This parameter can be configured in the ASDK Agent User Defined Parameters section, for further timeout fine-tuning. This setting can be configured for TCP read timeout if required. The read timeout is the timeout on waiting to read data. Specifically, if the server fails to send a byte n seconds after the last byte, a read timeout error will be raised.

poolTimeOut

This parameter can be configured in the ASDK Agent User Defined Parameters section. poolTimeout is the maximum time a request thread will wait to get a connection from the connection pool, before throwing an exception. The default is 30 seconds.

Preferred Host

Specifies how the hostname appears in all HTTP requests as users attempt to access the protected Web server. The hostname within the HTTP request is translated into the value entered into this field regardless of the way it was defined in a user's HTTP request.

The Preferred Host function prevents security holes that can be inadvertently created if a host's identifier is not included in the Host Identifiers list. However, it cannot be used with virtual Web hosting. For virtual hosting, you must use the Host Identifiers feature.

Defaults to Name (of WebGate registration)

User Defined Parameters

See Also: "User-Defined WebGate Parameters" and Tuning Database Parameters in the Fusion Middleware Performance and Tuning Guide.

Logout URL

OAM WebGates

The Logout URL triggers the logout handler, which removes the cookie (OAMAuthnCookie for OAM WebGates) and requires the user to re-authenticate the next time the user accesses a resource protected by Access Manager.

Default = [] (not set)

Additional Logout for OAM WebGate Only

For OAM WebGate single sign-off behavior, specific logout elements and values automate the redirect to a central Logout URL, callback URL, and end_URL.

See Also: Table 27-2

Logout Callback URL

OAM WebGate only

The URL to oam_logout_success, which clears cookies during the call back. This can be a URI format without host:port (recommended), where the OAM Server calls back on the host:port of the original resource request. For example:

Default = /oam_logout_success

This can also be a full URL format with a host:port, where OAM Server calls back directly without reconstructing callback URL.

Note: In the remote registration template this parameter is named logoutCallbackUrl (Table 15-10).

See Also: Table 27-2

Logout Redirect URL

OAM WebGate only

This parameter is automatically populated after agent registration completes.By default, this is based on the OAM Server host name with a default port of 14200. For example:

Default = http://OAMServer_host:14200/oam/server/logout

See Also: Table 27-2

Logout Target URL

OAM WebGate only

The value is the name for the query parameter that the OPSS applications passes to WebGate during logout; the query parameter specifies the target URL of the landing page after logout completes.

Default: end_url

Note: The end_url value is configured using param.logout.targeturl in jps-config.xml.

See Also: Table 27-2

Sleep for (seconds)

The frequency (in seconds) with which the OAM Server checks its connections to the directory server. For example, if you set a value of 60 seconds, the OAM Server checks its connections every 60 seconds from the time it comes up.

Default: 60 (seconds)

Cache Pragma Header

Cache Control Header

WebGate only (not Access Clients)

These settings apply only to WebGates and control the browser's cache.

By default, both parameters are set to no-cache. This prevents WebGate from caching data at the Web server application and the user's browser.

However, this may prevent certain operations such as downloading PDF files or saving report files when the site is protected by a WebGate.

You can set the Access Manager SDK caches that the WebGate uses to different levels. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html section 14.9 for details.

All of the cache-response-directives are allowed. For example, you may need to set both cache values to public to allow PDF files to be downloaded.

Defaults: no-cache

Note: Browsers may store a local cached copy of content served by an OAM protected resource. Some browsers, including Internet Explorer, cache content accessed via HTTPS which may be retrieved by other users who have access to the same computer at a future time. Please ensure that the Cache Directives are set based on the sensitivity of the application content.

See Also: Tuning Oracle HTTP Server in Tuning Performance

Debug

Debugging can be enabled or not.

Deny on Not Protected

WebGates only (not Access Clients)

Oracle recommends enabling Deny On Not Protected.

When enabled, this element denies access to all resources to which access is not explicitly allowed by a rule or policy. Enabling this can limit the number of times the WebGate queries the OAM Server, and can improve performance for large or busy Application Domains.

  • OAM WebGate: Always enabled, and cannot be changed

Important: Deny on Not Protected overrides Host Identifiers and Preferred Host. Oracle recommends enabling Deny on Not Protected. Otherwise security holes can occur in large installations with multiple Host Identifiers, virtual hosts, and other complex configurations.

Allow Management Operations

This Agent Privilege function enables the provisioning of session operations per agent, as follows:

  • Terminate session

  • Enumerate sessions

  • Add or Update attributes for an existing session

  • List all attributes for a given session ID or read session

Default: Disabled

Note: Only privileged agents can invoke session management operations. When this parameter is enabled, session management requests (listed above) are processed by the OAM Server. If disabled, such requests are rejected for the agent.

OAM WebGate only

Allow Credential Collector Operations

Activates WebGate detached credential collector functionality for simple-form or dynamic multi-factor authentication.

Default: Disabled

See Also: "Configuring OAM WebGate and Authentication Policy for DCC"

Allow Master Token Retrieval

Allows the ASDK code to retrieve the OAM_ID cookie.

Allow Token Scope Operations

Allows the ASDK code to scope the OAM_ID cookie to the domain level instead of host level.

Primary Server List

Identifies Primary Server details for this Agent. The default is based on the OAM Server:

  • Server Name

  • Host Name

  • Host Port

  • Max Number (maximum connections this WebGate will establish with the OAM Server (not the maximum total connections the WebGate can establish with all OAM Servers).)

Secondary Server List

Identifies Secondary OAM Server details for this agent, which must be specified manually:

  • Server Name

  • Host Name

  • Host Port

  • Max Number (maximum connections this WebGate will establish with the OAM Server (not the maximum total connections the WebGate can establish with all OAM Servers).)

Token Validity Period

The duration in seconds that the WebGate token (OAMAuthnCookie) will be valid for this agent. When the validity period is reached, the OAMAuthnCookie will be invalidated by WebGate. For resource WebGates, this means the user will be redirected to the credential collector, where either their overall session token will be validated, or they will need to reauthenticate if their overall session token is invalidated. The Token Validity Period controls the length of the user session for DCC WebGates, overriding the session lifetime configured on the OAM server.

Default = 3600 (seconds)

15.5.2 WebGate Search Controls

You can create a new WebGate registration, or search for a specific WebGate or group of WebGates (all OAM WebGates, for instance).

Figure 15-4 shows the WebGates Search controls, defaults, and the empty Search Results table.

Figure 15-4 WebGate Search Controls and Create Button

Description of Figure 15-4 follows
Description of "Figure 15-4 WebGate Search Controls and Create Button"

If you do not know the exact name, you can use a wild card (*) in the search string. From the search results table, you can choose an name to open and view or edit the registration page.

The controls available on this page are described in Table 15-4.

Table 15-4 Agent Search Controls

Control Description

Create WebGate

Click to open a fresh WebGate registration page.

Name

Enter the name (or partial name and wild card (*)) as defined on the registration page.

Preferred Host

Enter all (or part of with a wild card (*)) hostname as it appears in HTTP requests. For example: iam* could return IAMSuiteAgent in the result stable.

State

Choose a state to narrow the search and results:

  • Enabled

  • Disabled

Primary Server

Enter the entire (or partial with a wild card (*)) Primary Server name.

Secondary Server

Enter the entire (or partial with a wild card (*)) Secondary Server name.
15.5.2.1 Searching for an OAM Agent Registration

Before you begin, the Agent must be a registered agent of Access Manager.

  1. In the Oracle Access Management Console, click Application Security at the top of the window.
  2. In the Application Security console, click Agents.
  3. If not already displayed, select the desired agent type tab.
  4. Find:

    • All Enabled: Select Version All, State All, and click the Search button.

    • An Agent/WebGate Name: In the text field, enter the exact name of the instance you want to find and click the Search button. For example: 

      my_OAM_WebGate
  5. Click the Search Results tab to display the results table, then:

    • Edit or View: Click the Edit command button in the tool bar to see the configuration page.

    • Delete: Proceed to "Deleting OAM Agent Registration Using the Console".

    • Detach: Click Detach in the tool bar to expand the table to a full page.

    • Reconfigure Table: Select a View menu item to alter the appearance of the results table.

  6. Apply any changes (or dismiss the page) when you finish.

15.5.3 Viewing or Editing an OAM Agent Registration Page in the Console

Users with valid Administrator credentials can change any setting for registered WebGates and programmatic Access Clients using the Oracle Access Management Console.The procedure is the same whether you are editing a WebGate or Access Client registration.

For example, you might want to revise the time-out threshold or other settings used by the OAM Proxy.

After changes, updated details are propagated through a runtime configuration update process. There is usually no need to copy the artifacts over to the WebGate configuration area. (Artifacts need only be copied to the WebGate directory path if the agent name, access client password, or security mode is changed.)

Note:

All changes made using the Oracle Access Management Console are taken up without restarting the application server, and are reflected automatically after the reconfiguration time-out period.

Before you begin, the agent must be registered and available in the Oracle Access Management Console.

See Also:

  1. From the Oracle Access Management Console, click SSO Agents.

    1. Double-click OAM Agents node to display the Search page.

    2. Find the Registration: See "WebGate Search Controls".

    3. Click the Agent name in the results table to open the page.

  2. Modify Agent details, and Primary or Secondary Server details, as needed (Table 15-1, Table 15-3).

  3. User-Defined Parameters: Add or modify these as desired (Table 15-2).

  4. Click Apply to submit changes and dismiss the Confirmation window (or close the page without applying changes).

  5. Copy the artifacts as follows (or install WebGate with the same specifications, then copy artifacts), including any Simple or Cert mode files. For example, Open mode files include:

    Agent & Artifacts Artifacts

    OAM WebGate/Access Client

    ObAccessClient.xml and cwallet.sso

    From the AdminServer (Console) host:

    $DOMAIN_HOME/output/$Agent_Name/

    To the Agent host: $11gWG_install_dir/WebGate/config.

  6. Proceed as needed for your deployment:

    Managing Access Manager SSO, Policies, and Testing.

15.5.4 Deleting OAM Agent Registration Using the Console

Users with valid Administrator credentials can delete a registered WebGate or Access Client from the Oracle Access Management Console. Deleting an agent registration removes only the registration and not the associated host identifier, Application Domain, resources, or the agent itself.

See Also:

OAM Agent Registration Parameters in the Console

Before you begin, evaluate the Application Domain, resources, and policies associated with this agent and ensure that these are configured to use another agent (or be removed).

  • In the Oracle Access Management Console, click Application Security at the top of the window.

    1. In the Application Security console, click Agents to display the Search page.

    2. Find the Registration: See "WebGate Search Controls".

    3. Select the desired registration from the results table, and open it to confirm it is the right agent to remove, close the page.

    4. Select the name in the results table, click the Delete (X) button, check the Confirmation dialog and then close the page.

    5. Confirm the Agent name is no longer listed in the navigation tree.

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 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 OAM WebGate agent has its own secret key that is shared between the agent and the OAM Server.

If one WebGate is compromised, other 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 OAM WebGates.

    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.

15.7 Remote Registration Templates: OAM Agents

Oracle provides both a short and extended registration request template for use with the remote agent registration tool: oamreg.sh (Linux) or oamreg.bat (Windows).

This topic focuses on OAM Agent templates (WebGates and Access Clients).

Table 15-9 Remote Registration Request Templates for OAM Agents

Template Type Template Name in $OAM_REG_HOME/input/

Abbreviated (Short) Form

  • OAM11GRequest_short.xml (11g WebGates)

Extended (Full) Form

  • OAM11gRequest.xml (11g WebGates)

Other Templates

Update Agent

Create Policies, Update Policies

Out-of-band Response

For a look at these specialized tasks and templates, see:

15.7.1 OAM Agent Parameters for Remote Registration

Element names in request templates might differ slightly from counterparts in the Oracle Access Management Console.

Table 15-10 describes elements specific to OAM Agent remote registration requests. Protected, public, and excluded resource lists are included in both the short and extended request templates for OAM Agents.

Note:

Descriptions of elements in Table 15-10 are in Table 15-3.

Table 15-10 Elements in Extended OAM Agent Remote Registration Requests

Element Example

<serverAddress>

<agentName>

<hostIdentifier>

<agentBaseUrl>

<autoCreatePolicy>

<applicationDomain>

<virtualhost>

<allowCredentialCollectorOperations>

<allowMasterTokenRetrieval>

See Table 15-8.

<hostPortVariationsList>

 
<hostPortVariationsList>
  <host>host1</host> 
  <port>7777</port>
 </hostPortVariations>
  <host>host2</host> 
  <port>7778</port>
 </hostPortVariations>
</hostPortVariationsList>

<protectedResourcesList> 

<protectedResourcesList>
   <resource>/</resource>
</protectedResourcesList>

<publicResourcesList> 

<publicResourcesList>
   <resource>/public/index.html
   </resource>
</publicResourcesList>

<excludedresourcesList> 

<excludedresourcesList>
   <resource>/excluded/index.html
   </resource>
</excludedresourcesList>

<maxCacheElems>

 
<maxCacheElems>100000
</maxCacheElems>

<cacheTimeout>

 
<cacheTimeout>1800</cacheTimeout>

<tokenValidityPeriod>

OAM WebGate Only

 
<tokenValidityPeriod>3600
</tokenValidityPeriod>

<maxConnections>

 
<maxConnections>1</maxConnections>

<maxSessionTime>

 
<maxSessionTime>24</maxSessionTime>

<failoverThreshold>

 
<failoverThreshold>1
</failoverThreshold>

<aaaTimeoutThreshold>-

 
<aaaTimeoutThreshold>-1
</aaaTimeoutThreshold>

<sleepFor>

 
<sleepFor>60</sleepFor>

<debug>

 
<debug>false</debug>

<security>

 
<security>open</security

<denyOnNotProtected>

 
<denyOnNotProtected>1
</denyOnNotProtected>

<allowManagementOperations> 

<allowManagementOperations>false/<allowManagementOperations>

<cachePragmaHeader>

<cacheControlHeader>

 
<cachePragmaHeader>no-cache
</cachePragmaHeader>

<cacheControlHeader>no-cache
</cacheControlHeader

<ipValidation>

 
<ipValidation>0</ipValidation>

<ipValidationExceptions>

 
<ipValidationExceptions>
  <ipAddress>10,11,11,11</ipAddress>
  <ipAddress>10,11,11,12</ipAddress>
  <ipAddress>10,11,11,13</ipAddress>
</ipValidationExceptions>

<logOutUrls>

 
<logOutUrls>
    <url>/logout1.html</url>
    <url>/logout2.html</url>
</logOutUrls>

<logoutCallbackUrl>

OAM WebGate Only

 
<logoutCallbackUrl>/oam_logout_success
</logoutCallbackUrl>

<logoutTargetUrlParamName>

OAM WebGate Only

 
<logoutTargetUrlParamName>end_url
</logoutTargetUrlParamName>

User-Defined Parameter Names

Examples

<userDefinedParameters>
   <userDefinedParam>
      <name>...</name>
      <value>...</value>
</userDefinedParam>

MaxPostDataLength

 
<userDefinedParameters>
   <userDefinedParam>
      <name>MaxPostDataLength</name>
      <value>750000</value>
</userDefinedParam>

maxSessionTimeUnits

 
<userDefinedParameters>
   <name>maxSessionTimeUnits</name>
   <value>hours</value>
</userDefinedParam>

useIISBuiltinAuthentication

 
<userDefinedParameters>
<name>useIISBuiltinAuthentication
   </name>
   <value>false</value>
</userDefinedParam>

URLInUTF8Format

 
<userDefinedParameters>

   <name>URLInUTF8Format</name>
   <value>true</value>
</userDefinedParam>

inactiveReconfigPeriod

Configuration applies to only OAM WebGate. 

<userDefinedParameters>
<name>inactiveReconfigPeriod</name>
<value>10</value>
</userDefinedParam>

WaitForFailover

 
<userDefinedParameters>
   <name>WaitForFailover</name>
   <value>-1</value>
</userDefinedParam>

proxySSLHeaderVar

 
<userDefinedParameters>
   <name>proxySSLHeaderVar</name>
   <value>IS_SSL</value>
</userDefinedParam>

client_request_retry_attempts

 
<userDefinedParameters>
   <name>client_request_retry_attempts </name>
   <value>1</value>
</userDefinedParam>

ContentLengthFor401Response

 
<userDefinedParameters>
   <name>ContentLengthFor401Response
</name>
   <value>0</value>
</userDefinedParam>

SUN61HttpProtocolVersion

 
<userDefinedParameters>
   <name>SUN61HttpProtocolVersion
</name>
   <value>1.0</value>
</userDefinedParam>

impersonationCredentials

 
<userDefinedParameters>
   <name>username:password
</name>
   <value>cred</value>
</userDefinedParam>

UseWebGateExtForPassthrough

 
<userDefinedParameters>
   <name>UseWebGateExtForPassthrough
</name>
   <value>false</value>
</userDefinedParam>

syncOperationMode

 
<userDefinedParameters>
   <name>syncOperationMode</name>
   <value>false</value>
</userDefinedParam>

filterOAMAuthnCookie

OAM WebGate only. 

<userDefinedParameters>
   <name>filterOAMAuthnCookie</name>
   <value>true</value>
</userDefinedParam>

15.8 Performing Remote Registration for OAM Agents

This section includes the following topics describing how to perform remote registration, which is similar regardless of the agent type:

15.8.1 Acquiring and Setting Up the Remote Registration Tool

The oamreg client tool can be used anywhere, not just on the OAM Server.

If the oamreg home is already exploded, you can use the following procedure to acquire and update the oamreg script for your operating system:

Windows: oamreg.bat

Linux: oamreg.sh

Note:

Oracle Recommends using the latest tool and files by applying the latest bundle patch and untarring RREG.tar.gz again as described here.

For remote registration, two variables are required: JAVA_HOME and OAM_REG_HOME, as described in Table 15-11.

Table 15-11 Variables Required for Remote Registration

Location Variable Description

Client Side

JAVA_HOME

The JDK 1.6 location on the computer that relies on $JAVA_HOME already set in the environment. (JDK 1.7 can also be used in R2PS3.)

OAM_REG_HOME

The absolute file location for RREG HOME (directory under which RREG.tar was exploded, followed by /rreg and one directory above where the scripts reside).

For example:

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

If $ORACLE_IDM_HOME is $MW_HOME/Oracle_IDM:

export $OAM_REG_HOME=$MW_HOME/Oracle_IDM/oam/server/rreg

rreg folder location (not RREG.tar.gz location)

JAVA_HOME

Relies on $JAVA_HOME already set in the environment.

OAM_REG_HOME

Is already set in the script during the installation.

See Also:

"Remote Registration Command Arguments and Modes"

  1. Locate RREG.tar.gz file in the following path:

    $ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz

  2. Untar RREG.tar.gz file, which creates directories beneath /client containing the required tool and templates.

  3. In the oamreg script (.../rreg/client/rreg/bin) set environment variables as follows:

    1. Set JAVA_HOME to JDK 1.6 (Table 15-11).

      JDK 1.7 can also be used in R2PS3.

    2. Set OAM_REG_HOME to the exploded_dir_for_RREG.tar/rreg based on your environment (client side or server side Table 15-11).

  4. Proceed with "Creating Your Remote Registration Request".

15.8.2 Creating Your Remote Registration Request

You can create an appropriate *Request*.xml file to provide input for the specific agent you want to register.

Before you begin, read Remote Registration Templates: OAM Agents

  1. Locate the required *Request*.xml input file for the agent you want to register:
  2. Copy the request file to a new name. For example:
    • From: OAM11GRequest.xml
    • To: my11gagent_request.xml
  3. In the Request file, modify information to reflect details for your agent and the resources to protect using details in:
  4. Proceed with task needed for your environment:

15.8.3 Performing In-Band Remote Registration

The OAM Administrator within the network performs all tasks. Regardless of agent type, you can perform in-band remote registration.

For this example, an OAM Agent is being registered using the short request on a Linux system. Your agent type, request template, and output files will be different.

See Also:

Configuring Oracle HTTP Server WebGate for Oracle Access Manager in Installing WebGates for Oracle Access Manager

Before you begin, read:

  1. On the computer hosting the Agent, run the registration command and specify your own *Request*.xml as the input file. For example:

    ./bin/oamreg.sh inband input/myagent_request.xml

  2. Provide the registration Administrator user name and password when asked.

    The following example illustrates a sample rreg registration output.

    Welcome to OAM Remote Registration Tool!
Parameters passed to the registration tool are:
Mode: inband
Filename: /scratch/work/mw1916/idm1385/oam/server/rreg/input/1.xml
Enter admin username:oamadminuser
Username: oamadminuser
Enter admin password:
Do you want to enter a Webgate password?(y/n):
n
Do you want to import an URIs file?(y/n):
n

----------------------------------------
Request summary:
OAM Agent Name:RREG_1234
URL String:RREG_1234
Registering in Mode:inband
Your registration request is being sent to the Admin server at: http://slc01huw.us.example.com:20081
----------------------------------------

Inband registration process completed successfully! Output artifacts are created in the output folder.

    The output folder is in the same location where RREG.tar.gz was expanded: /rreg/output/AgentName/

  3. Review the native configuration file created for the agent in the /rreg/output/AgentName/ folder.

  4. Finalize Registration: Perform the following steps to replace the earlier agent configuration file if it is not already replaced:

    1. Copy artifacts in /rreg/output/AgentName/ to update the agent configuration. For example:

      From the AdminServer (Console) host

      /rreg/output/Agent_Name/ObAccessClient.xml and cwallet.sso

      To the Agent host: $11gWG_install_dir/WebGate/config. For example:

      • $WebTier_MW_Home/Oracle_WT1/instances/instance1
      • /config/OHS/ohs1/WebGate/config

    2. Restart the OAM Server hosting the agent.

  5. Proceed with "Validating Remote Registration and Resource Protection".

15.8.4 Performing Out-of-Band Remote Registration

This section provides steps for Administrators outside (and inside) the network as they work together to register an agent remotely. During out-of-band remote registration, an administrator outside the network submits a registration request to an Administrator within the network. After processing the request, the in-band Administrator returns the following files to the out-of-band Administrator to configure his environment.

Table 15-12 Files Returned by in-band Administrator to out-of-band Administrator

File Description

agentName_Response.xml

Returned to, and used by, the out-of-band Administrator. Oracle recommends that you do not open or edit agentName_Response.xml.

Native Web server configuration files

Returned to, and used by, the out-of-band Administrator to update his Web server.

See Also

"Updating Agent Configuration Files"

The steps performed by each Administrator are identified:

  • In-Band Administrator: Identifies a task performed by the Web server Administrator within the network.

  • Out-of-Band Administrator Identifies a task performed by the Web server Administrator outside the network

See Also:

Configuring Oracle HTTP Server WebGate for Oracle Access Manager in Installing WebGates for Oracle Access Manager

Steps here illustrate registering an OAM Agent on a Linux system. Your templates and output files will be different.

Before you begin, read Acquiring and Setting Up the Remote Registration Tool

  1. Out-of-Band Administrator: Create and send your starting_request.xml file to the in-band Administrator for processing (see "Creating Your Remote Registration Request"): 

    $WLS_Home/Middleware/Oracle_$IDM1/oam/server/rreg/client/rreg/output/AgentName/starting_request.xml

  2. In-Band Administrator:

    1. Run the registration command and specify the out-of-band Administrator's starting_request.xml as the input file. For example:

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

    2. Provide the Registration Administrator user name and password when asked.

    3. Read messages on-screen to confirm:

      Success: "... registration process completed successfully!

      Response.xml location: "... created in input folder ..."

      The input folder is in the same location where RREG.tar.gz was expanded: /rreg/input/

    4. Return the agentName_Response.xml file to the out-of-band Administrator along with any other artifacts. For example:

      agentName_Response.xml

  3. Out-of-Band Administrator: Updates the environment, as follows.

    1. On the computer hosting the Agent, run the remote registration command and specify the received agentName_Response.xml as the input file. For example:

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

    2. Copy artifacts generated in /rreg/output/AgentName/ to update the agent configuration (), then restart the OAM Server hosting the agent. For example, ObAccessClient.xml and cwallet.sso:

      From the AdminServer (Console) host /rreg/output/Agent_Name/ObAccessClient.xml and cwallet.sso

      To the Agent host: $11gWG_install_dir/WebGate/config. For example:

      • $WebTier_MW_Home/Oracle_WT1/instances/instance1
      • /config/OHS/ohs1/WebGate/config

    3. Proceed with "Validating Remote Registration and Resource Protection".

15.9 Remote Agent Update Modes and Templates

Administrators quickly update, validate, or delete an existing agent registration using remote management modes.

This section provides the following topics:

15.9.1 Remote Agent Update Modes

To manage an existing agent registration, remote agent management modes can be used.

Table 15-13 presents remote agent management modes. Command parameters include the mode, input *Request.xml file (a relative path with respect to $OAM_REG_HOME, the preferred location for the input *Request.xml files): 

./oamreg.sh <mode> <input_file> [prompt_flag] [component.oam.config_file] <mode> value

Table 15-13 Remote Agent Update Modes and Input Files

Mode and Input Files Description and Syntax

agentUpdate mode

OAM11GUpdateAgentRequest.xml

OAMUpdateAgentRequest.xml

Allows Administrators to update existing agent attributes, regardless of agent type:

./bin/oamreg.sh agentUpdate input/*UpdateAgentRequest.xml

agentValidate mode

No input file needed.

Validates whether the agent is already provisioned in Oracle Access Manager: 

./bin/oamreg.sh agentValidate agentname

agentDelete mode

No input file needed.

Allows Administrators to delete the agent registration:

./bin/oamreg.sh agentDelete agentname

15.9.2 Remote OAM Agent Updates Template

You use OAM11GUpdateAgentRequest.xml to pass specific Agent-update values to the remote registration tool, oamreg.

The primary differences between the update request and the original registration request is that the update request.

Table 15-14 Delta: OAM Agent Update versus Registration Request

Delta Element

Adds

<ipValidation>

Omits

<ipValidationExceptions>

Omits

<hostidentifier>

Omits

<virtualhost>

Omits

<hostportVariations>

Omits

<authCreatePolicy> and application domain-related elements

Omits

<ssoServerVersion>

Omits

<idleSessionTimeout>

See Also:

15.10 Updating Agents Remotely

This section provides the following topics for agents registered with Access Manager, regardless of agent type:

15.10.1 Updating Agent Registrations Remotely

Regardless of agent type, you can remotely update agents registered with Access Manager.

This topic provides the steps to update agents registered with Access Manager, regardless of agent type. Before you begin, review Remote Agent Update Modes

  1. Set up the registration tool as described in, "Acquiring and Setting Up the Remote Registration Tool".
  2. Create your update request using one of the following templates:

    • OAM11GUpdateAgentRequest.xml

  3. On the computer hosting the Agent, run the following command with agentUpdate mode specify your own *Request*.xml as the input file. For example:
    ./bin/oamreg.sh agentUpdate input/*UpdateAgentRequest.xml
  4. Provide the registration Administrator user name and password when asked.
  5. Read the messages on-screen to confirm:

    • Success: On-screen message confirms

      agentUpdate process completed successfully!

      Native Configuration File Location: "... created in output folder ..."

      The output folder is in the same location where RREG.tar.gz was expanded: /rreg/output/AgentName/

  6. Finalize Agent Registration: Copy the updated ObAccessClient.xml and cwallet.sso.

    From the AdminServer (Console) host: /rreg/output/Agent_Name/

    To the Agent host: $11gWG_install_dir/WebGate/config. For example:

    • $WebTier_MW_Home/Oracle_WT1/instances/instance1/ config/OHS/ohs1/WebGate/config
  7. Restart the OAM Server that is hosting this agent and proceed to "Validating an Agent Registration Remotely".

15.10.2 Validating an Agent Registration Remotely

Regardless of agent type, you can remotely validate agent registration.

This topic provides the steps to validate agent registration, regardless of agent type. Before you begin, review Remote Agent Update Modes

  1. Set up the registration tool as described in, "Acquiring and Setting Up the Remote Registration Tool".
  2. On the Agent host, run the following command in agentValidate mode. For example:
    ./bin/oamreg.sh agentValidate agentname
  3. Provide the registration Administrator user name and password when asked.
  4. Read the messages on-screen to confirm:

    • Success: On-screen message confirms

      AgentValidation process completed successfully!

15.10.3 Removing an Agent Registration Remotely

You can remove a registered agent, regardless of agent type.

Before you begin, review Remote Agent Update Modes

  1. Set up the registration tool as described in, "Acquiring and Setting Up the Remote Registration Tool".
  2. On the computer hosting the Agent, run the following agentDelete command. For example:
    ./bin/oamreg.sh agentDelete agentname
  3. Provide the registration Administrator user name and password when asked.
  4. Read the messages on-screen to confirm:

    • Success: On-screen message confirms

      AgentDelete process completed successfully!

15.11 Validating Remote Registration and Resource Protection

You can validate registration of an agent regardless of the agent type.

You must be an in-band Administrator to perform tasks using the Oracle Access Management Console. Out-of-band Administrators must test authentication and access remotely.

15.11.1 Validating Agent Registration using the Oracle Access Management Console

Only an in-band Administrator can validate agent registration.

See Also:

Managing Policies to Protect Resources and Enable SSO

  1. Validate Agent Registration in the Oracle Access Management Console:

    1. Confirm Agent details under Application Security in the Oracle Access Management Console.

    2. Confirm the updated Agent configuration files are in the appropriate location, as described in "Performing Remote Registration for OAM Agents".

  2. Validate Shared Components, Host identifier: Confirm that the host identifier is defined in the Oracle Access Management Console.

  3. Validate Application Domain: Under the Policy Configuration tab, confirm there is a new Application Domain named after the registered agent. Resources in the Application Domain should be associated with the host identifier.

  4. Proceed with "Verifying Authentication and Access After Remote Registration".

15.11.2 Verifying Authentication and Access After Remote Registration

After registration, protected resource should be accessible with proper authentication without restarting the AdminServer or OAM Server.

Both in-band and out-of-band Administrators can use the following procedure to validate proper registration and policies.

The procedure here provides several methods for confirming that registration, authentication, and authorization are properly configured and operational. The procedures is nearly identical for all agent types.

  1. Enter the URL for an application protected by the registered OAM Agent to confirm that the log in page appears (proving that the authentication redirect URL was specified appropriately). For example:
    http://exampleWebserverHost.sample.com:8100/resource1.html
  2. On the Log In page, enter a valid username and password when asked, and click Login.
  3. Check the OAM specific cookies are created in the browser session. For example:

    ObSSOCookie:

    Set-Cookie: 
ObSSOCookie=GGVEuvjmrMe%2FhbItbjT24CBmJo1eCIfDIwQ1atdGdnY4mt6kmdSekSFeAAFvFrZZZ
xDfvpkfS3ZLZFbaZU2rAn0YYUM3JUWVYkYFwB%2BBK7V4x%2FeuYHj%2B8gwOyxhNYFna3iSx1MSZBE
y51KTBfsDYOiw6R%2BCxUhOO8uZDTYHI3s0c7AQSyrEiQTuUV3nv1omaFZlk1GuZa4J7ycaGbIUyqwX
rM0cKuBJNd6sX1LiRj9HofYQsvUV7ToqeAOpDS7z9qs5LhqU5Vq60bBn12DTX6zNX6Lcc0L5tVwvh7%
2BnOAkz2%2BoDkLs%2BBTkeGcB3ppgC9;httponly; path=/; domain=.example.com;

    OAM_ID Cookie: 

    Set-Cookie: 
OAM_ID=v1.0~0~E1EBBC9846E09857060A68E79AEEB608~AA79FC43C695162B6CDE3738F40E94DA
6408D58B879AC3B467EBBD4800743C899843672B3511141FFABCF58B2CDCB700C83CC734A913625
7C4ABDA6913C9EF5A4E05C5D03D3514F2FECACD02F1C1B9314D76B4A68CB7A8BE42AEB09AFB98B8
EB; path=/; HttpOnly
  4. Proceed as follows:

    • Success: If you authenticated successfully and were granted access to the resource; the configuration is working properly. Proceed with Steps 5 through 12 for further validations.

    • Failure: If you received an error during login or were denied access to the resource, check the following:

      • Login Error: Confirm that you provided a valid user id and password.

      • Unavailable Resource: Confirm that the resource is available.

      • Wrong Redirect URL: Verify the redirect URL in the Oracle Access Management Console.

  5. User Variations: Perform steps 1 through 4 again with user variations to confirm appropriate behavior (either success for authorized users or failure for unauthorized users).
  6. Request Cancellation: Perform a partial log in and click Cancel to confirm that the resource is not accessed.
  7. Modified Authentication URL: Enter a nearly identical authentication URL as you perform Steps 1 through 5 to confirm appropriate response. For example, add a character to the URL string.
  8. Updated Resource: Perform the following steps to ensure the resource is accessible. For example:

    Original Resource: /abc/test.html

    Updated Resource: /abc/xyz/test.html

    Without restarting the Oracle WebLogic Server:

    • Access the updated resource and confirm the user is asked to authenticate and the resource is accessible.

    • Access the original resource and confirm that the resource is accessible and the user is not asked for authentication.

  9. Various URL Patterns: Verify authentication for various URL patterns as you perform steps 1 through 5.
  10. New Authentication Scheme: Perform the following steps to confirm authentication operations without restarting the WebLogic Server.

    • Add a new authentication policy that uses a different Authentication Scheme.

    • Protect the resource using the new policy.

    • Without restarting the Oracle WebLogic Server, perform steps 1 through 4.

    See Also:

    Managing Policies to Protect Resources and Enable SSO

  11. CGI Resource Header Variable and Cookies: Perform the following steps to confirm authentication operations without having to restart the WebLogic Server.

    • Add a new authentication policy to protect a Common Gateway Interface (CGI) resource and set the Response for "Authentication Successful".

    • Protect the resource using the new policy.

    • Access the CGI resource.

    • Check for the header values configured for the response in a CGI data dump.

  12. Agent Disabled: Perform the following steps to validate accessibility and authentication if WebGate is disabled in ObAccessClient.xml (WebGate should pick up the enabled value from oam-config.xml).

    • Disable the Agent State.Start the Web server and OAM Server.Access an application protected by the Agent and confirm that you are asked to authenticate.

15.12 setAllowEmptyHostIdentifier

Enables and disables the use of an empty preferred host parameter.

Description

Enables or disables the use of an empty preferred host parameter. The following parameters (added to the oam-config.xml file) will be set to enable or disable an empty preferred host parameter in the ObAccessClient.xml file.

<Setting Name="AutoUpdateHostIdentifier" 
 Type="xsd:string">AUTO_UPDATE_HOSTID</Setting>
<Setting Name="AllowEmptyHostIdentifier" 
 Type="xsd:boolean">true</Setting>

Syntax

setAllowEmptyHostIdentifier(enable="true/false")
Argument Definition 
enable

Set to true or false to allow for an empty host identifier or not.

Sample

setAllowEmptyHostIdentifier(enable ="true")