15.5 Configuring and Managing Registered OAM Agents Using the Console

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

• Registered OAM Agent Configuration Parameters in the Console

• WebGate Search Controls

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

• Deleting OAM Agent Registration Using the Console

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 11g WebGate Page with the default values.

Figure 15-3 Expanded 11g WebGate Page with Defaults

Description of "Figure 15-3 Expanded 11g WebGate Page with Defaults "

There are only a few differences between 11g and 10g WebGate registration pages.

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 11g and 10g 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".
Primary Cookie Domain 10g WebGate only, Registering and Managing 10g WebGates with Access Manager 11g	This parameter describes the Web server domain on which the Agent is deployed, for instance,.example.com. You must configure the cookie domain to enable single sign-on among Web servers. Specifically, the Web servers for which you configure single sign-on must have the same Primary Cookie Domain value. WebGate uses this parameter to create the ObSSOCookie authentication cookie. This parameter defines which Web servers participate within the cookie domain and have the ability to receive and update the ObSSOCookie. This cookie domain is not used to populate the ObSSOCookie; rather it defines which domain the ObSSOCookie is valid for, and which Web servers have the ability to accept and change the ObSSOCookie contents. Default: If the client side domain can be determined during registration, the Primary Cookie Domain is populated with that value. However, if no domain is found, there is no value and WebGate uses the host-based cookie. Note: The more general the domain name, the more inclusive your single sign-on implementation will be. For example, if you specify b.com as your primary cookie domain, users will be able to perform single sign-on for resources on b.com and on a.b.com. However, if you specify a.b.com as your primary cookie domain, users will have to re-authenticate when they request resources on b.com.
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. (11g 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 11g WebGate only Resource to Authorization Policy) when the information is neither used nor referenced. Default = 1800 (seconds)
Token Validity Period (seconds) 11g WebGate only	Maximum valid time period for an agent token (the content of OAMAuthnCookie for 11g WebGate). This value is the validity period for the obsso cookie. Within this period, only authorization nap calls will pass to the OAM server. Once this period has passed, the obsso cookie will be considered invalid and an 'obrareq.cgi' redirect will occur. The OAM Server will validate the OAM_ID cookie and re-issue a new obsso cookie, or challenge the user if the server side session is expired/deleted/timed out). Default = 3600 (seconds) Note: For 10g WebGates, use Cookie Session Time to set the Token Validity Period.
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.
Idle Session Timeout 10g WebGate only, Registering and Managing 10g WebGates with Access Manager 11g	Default: 3600 Release 7.0.4 WebGates enforced their own idle session timeout only. 10.1.4.0.1 WebGates enforced the most restrictive timeout value among all WebGates the token had visited. With 10g (10.1.4.3), the 7.0.4 behavior was reinstated as the default with this element. To set Idle Session Timeout logic: The default value of leastComponentIdleTimeout instructs the WebGate to use the most restrictive timeout value for idle session timeout enforcement. A value of currentComponentIdleTimeout instructs the WebGates to use the current WebGate timeout value for idle session timeout enforcement. The idle session timeout behavior varies across WebGate versions. For example, with WebGate 10.1.4.3 it is used to control idle timeout. If both Idle Session Timeout and Cookie Session Time are set, the obsso cookie will be considered invalid when one of the events happens (idle session timeout/cookie session time). In this case, the request will go to the OAM server which will use server side parameter validation to decide if the session has timed out/expired followed by a credential challenge or obsso cookie reissue.
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 Performance.
Logout URL 10g and 11g WebGates	The Logout URL triggers the logout handler, which removes the cookie (ObSSOCookie for 10g WebGates; OAMAuthnCookie for 11g WebGates) and requires the user to re-authenticate the next time he accesses a resource protected by Access Manager. Default = [] (not set) Note: This is the standard 10g WebGate configuration parameter used to trigger initial logout through a customized local logout page as described in "Configuring Centralized Logout for 10g WebGate with 11g OAM Servers".
Additional Logout for 11g WebGate Only	For 11g 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 11g 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 11g 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 11g 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 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. 11g WebGate: Always enabled, and cannot be changed 10g WebGate: Can be disabled. 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.
11g WebGate only
Allow Credential Collector Operations 11.1.2.0.0 and later WebGate only	Activates WebGate detached credential collector functionality for simple-form or dynamic multi-factor authentication. Default: Disabled See Also: "Configuring 11g 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.
Sharepoint Impersonation User 10g WebGate only, Registering and Managing 10g WebGates with Access Manager 11g	The trusted user for impersonation, in Active Directory. This user should not be used for anything other than impersonation. The constraints are the same as any other user in Active Directory. Note: SharePoint impersonation is separate and distinct from the Access Manager user impersonation feature described in the Oracle Fusion Middleware Developer's Guide for Oracle Access Management.
Sharepoint Impersonation Password 10g WebGate only, Registering and Managing 10g WebGates with Access Manager 11g	This is the trusted user password for impersonation. The constraints are the same as any other user password in Active Directory. Oracle recommends that the user choose a very complex password, because the trusted user is granted powerful permissions. Also, check the box Password Never Expires. The impersonation module should be the only entity that ever sees the trusted user account. It is extremely difficult for an outside agency to discover that the password has expired.
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).)

15.5.2 WebGate Search Controls

You can create a new WebGate registration, or search for a specific WebGate or group of WebGates (all 11g 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 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. Most of the controls apply to all three (WebGates, OSSO Agents and OpenSSO Agents) tabs; controls specific to each tab are marked accordingly.

Table 15-4 Agent Search Controls

Control	Description
Create WebGate Create OSSO Agent Create OpenSSO Agent	Click to open a fresh WebGate registration page. Click to open a fresh OSSO Agent registration page. Click to open a fresh OpenSSO Agent registration page.
Name	Enter the name (or partial name and wild card (*)) as defined on the registration page. For example: entering a* could return Agent_WebGate_AccessDebugNew in the result table.
Version (Webgates tab only)	Choose a WebGate version to narrow the search and results: 11g 10g
Preferred Host (Webgates tab only)	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 (Webgates tab only)	Choose a state to narrow the search and results: Enabled Disabled
Primary Server (Webgates tab only)	Enter the entire (or partial with a wild card (*)) Primary Server name.
Secondary Server (Webgates tab only)	Enter the entire (or partial with a wild card (*)) Secondary Server name.
Agent ID (OSSO Agents tab only)	Enter the entire (or partial with a wild card (*)) Agent ID value.
Agent Type (OpenSSO Agents tab only)	Select the target Agent type: J2EE Web

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 ID (OSSO Agents tab only): enter the desired Agent ID into the Agent ID field.

   • An Agent Type (OpenSSO Agents tab only): from the Agent Type drop-down list, select J2EE or Web, as appropriate for your search.

   • A WebGate Version: From the Version list, choose 10g or 11g 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:

• Creating OAM WebGate Page and Parameters

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
   11g 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.
   10g WebGate/Access Client ObAccessClient.xml Note: Go to Registering and Managing 10g WebGates with Access Manager 11g before completing this task.	From the AdminServer (Console) host: $DOMAIN_HOME/output/$Agent_Name/ To the Agent host $10gWG_install_dir/oblix/lib/ObAccessClient.xml

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

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

2. Remove the 10g Agent Instance: Perform the following steps (see "Removing a 10g WebGate from the Access Manager 11g Deployment", if needed).

   1. Shut down the Web server.

   2. Remove WebGate software using the utility provided in the following directory path:

      $WebGate_install_dir/oui/bin

      Windows: setup.exe -d
      Unix: runInstaller -d
      

   3. Revert to the httpd.conf version before updates for WebGate. For example:

      Copy: httpd.conf.ORIG

      To: httpd.conf

   4. Restart the Web server.

   5. On the agent host, manually remove the WebGate instance directory:

      11g WebGate/Access Client: $11gWebGate_instance_dir/WebGate/config.

      • 10g WebGate/Access Client:  $WebGate_install_dir/oblix/lib/