15.2 OAM Agent Registration Parameters in the Console

Unless explicitly stated, the information here applies equally to both 11g and 10g WebGates, including programmatic Access Clients.

OAM Agent registration parameters topics include:

• Creating OAM WebGate Page and Parameters

• User-Defined WebGate Parameters

• IP Address Validation for WebGates

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 (*). Whether you register an 11g WebGate or 10g WebGate, the initial information requested is the same.

Figure 15-1 Create OAM 11g WebGate Page

Description of "Figure 15-1 Create OAM 11g WebGate Page"

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

Unless explicitly noted, all elements apply to both 11g and 10g Agents.

Table 15-1 Elements on Create Pages for 11g and 10g OAM Agents

OAM WebGate Element	Description
Version	Specifies whether this will be a 10g or an 11g WebGate.
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 11g 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: When you register a WebGate, allow the process to create a host identifier (a name of your choice), and enable "Auto Create Policies". 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: WebGate1: Register the first WebGate and enable Auto Create Policies to generate a host identifier (named as you like) and policies. 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 reconfiguration 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-23
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-23
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-23
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-23. "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) See Also: Tuning Performance
fallbackToContainerPolicy=true	Used for the IAMSuiteAgent. When set to false, user access to the resource is denied and an HTTP response code, 403 is returned. When set to 'true' the request goes through to the container and uses whatever policy (related to J2EE authentication/authorization) is configured on the container to grant or deny the user access. Default: true
logoutRedirectUrl=	Default = http://OAMServer_host:14200/oam/server/logout
protectWebXmlSecuredPagesOnly=true	Used for the IAMSuiteAgent. After the user is authenticated, this parameter is used for all subsequent requests to determine if the Agent should validate the incoming request. When set to: false: The Agent always validates the incoming request true: The default. The Agent determines whether to validate the incoming request based on the following: If the application specifies 'CLIENT-CERT' as part of the construct: "<auth-method>" in its web.xml, the Agent validates the incoming request. If the application does not specify 'CLIENT-CERT' as part of the construct: "<auth-method>" in its web.xml, the Agent does not validate the incoming request. Instead, the Agent lets the request go through to the application.
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 See Also: Tuning Performance
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. See Also: Tuning Performance.
UniqueCookieNames	Controls WebGate cookie name format: Legacy format (still the default and backward compatible): <prefix>_<host>:<port>_<suffix> Enabled UniqueCookieNames format (rfc2109-compliant cookie name restriction): <prefix>_<host>:<port>_<suffix> Disabled: Cookie name format is <prefix>_<suffix>. No <host>:<port> and No <host>_<port> is added to the cookie name. Any other value is treated as the default legacy format: <prefix>_<host>:<port>_<suffix>
11g 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 11g 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 11g 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-23 "Configuring Challenge Parameters for Encrypted Cookies" "Configuring 11g 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-23 "Configuring Challenge Parameters for Encrypted Cookies" "Configuring 11g WebGate and Authentication Policy for DCC"
obSSOCookieCoExConfig	Controls the cookie properties set on ObSSOCookie during OAM 10g Co-Existence. Default: obSSOCookieCoExConfig=httponly obSSOCookieCoExConfig=Secure Disable either setting: obSSOCookieCoExConfig=disablehttponly obSSOCookieCoExConfig=disableSecure Disable both settings: obSSOCookieCoExConfig=disableSecure;disablehttponly For detached credential collector-enabled 11g WebGates used for Co-Existence (as DCC or with DCC Tunneling), set this parameter in the agent registration page. See the Co-existence chapter in Oracle Fusion Middleware Migration Guide for Oracle Identity and Access Management for more information.
OAMAuthAuthenticationServiceLocation 11g 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). See Also: Managing Oracle Access Management Mobile and Social.
OAMAuthUserAgentPrefix 11g 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). See Also: Managing Oracle Access Management Mobile and Social.
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.

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

• IP Validation Exceptions List

• IP Validation in Load Balanced Environments

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 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"