Unless explicitly stated, the information here applies equally to both 11g and 10g WebGates, including programmatic Access Clients.
OAM Agent registration parameters topics include:
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.
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:
|
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):
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:
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:
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
For more information, see Securing Communication. |
Resource Lists |
|
Protected Resource (URI) List |
URIs for the protected application: / 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
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
See Also: "Resource URL, Prefixes, and Patterns". |
See Also: |
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.
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" |
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" |
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" |
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 Default: When set to 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: |
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 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: |
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:
|
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:
|
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 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 ( |
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.
See Also: |
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.
See Also: |
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.
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.
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. |
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.
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.)
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.
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.
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.
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"