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 (*).
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:
|
|
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 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-22 |
|
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) |
|
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:
|
|
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. By default, FIPS mode is disabled. From WebGate 12c PS1 release
onwards, you can enable the FIPS mode by setting
Ensure the root certificate CA that is added in
If the FIPS mode is initialized successfully, the
following message is logged in the 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 thewebgate.log file:
|
|
EnableFIPSimpleMode=true |
Enables FIPS mode for WebGates in SIMPLE security mode. Note: You must set bothEnableFIPSMode=true and
EnableFIPSimpleMode=true to enable FIPS in
SIMPLE 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 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 ( |
|
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: |
|
OAMAuthAuthenticationServiceLocation 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). |
|
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.
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. |
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) 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.
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.
See Also:
- Configuring Oracle HTTP Server WebGate for Oracle Access Manager in Installing WebGates for Oracle Access Manager
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.
-
In the Oracle Access Management Console, click Application Security at the top of the window.
-
In the Application Security console, select Create WebGate from the Agents menu.
-
On the Create WebGate page, enter required details (those with an *) to register this Agent.
-
Protected Resource List: In this table, enter individual resource URLs to be protected by this Agent, as shown in Table 15-1.
-
Public Resource List: In this table, enter individual resource URLs to be public (not protected), as shown in Table 15-1.
-
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)).
-
Click Apply to submit the registration.
You may also close the page without applying changes, if applicable.
-
Click the Download button to download the generated artifacts.
Downloaded artifacts are located in the
$DOMAIN_HOME/output/$Agent_namefolder. -
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
-
Verify Registration: These are similar to steps in "Validating Agent Registration using the Oracle Access Management Console".
-
Under Agents in Application Security, search and confirm the Agent name is listed.
-
Confirm the Agent's page contains the appropriate information.
-
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.
-
Perform further tests, as described in "Verifying Authentication and Access After Remote Registration".
-
-
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.
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.
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 |
|---|---|
|
|
Specifies the name of the WebGate template to be created. |
|
|
A comma-seperated list of WebGate parameters that needs to be added to the WebGate template. |
|
|
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 |
|---|---|
|
|
Specifies the name of the WebGate template. |
|
|
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. |
|
|
Specifies the IDs of the WebGates that need to be excluded from the WebGate template. |
|
|
[Optional] Defaults to False. Set this value to True to specify a file containing the WebGate IDs.
|
|
|
[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 |
|---|---|
|
|
[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. |
|
|
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: |
|
|
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 |
|
|
[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 |
|---|---|
|
|
Specifies the name of the WebGate template. |
|
|
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 |
|---|---|
|
|
[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 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:
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 |
|
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 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 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.
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:
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:
|
|
Secondary Server List |
Identifies Secondary OAM Server details for this agent, which must be specified manually:
|
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 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:
|
|
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.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:
-
From the Oracle Access Management Console, click SSO Agents.
-
Double-click OAM Agents node to display the Search page.
-
Find the Registration: See "WebGate Search Controls".
-
Click the Agent name in the results table to open the page.
-
-
Modify Agent details, and Primary or Secondary Server details, as needed (Table 15-1, Table 15-3).
-
User-Defined Parameters: Add or modify these as desired (Table 15-2).
-
Click Apply to submit changes and dismiss the Confirmation window (or close the page without applying changes).
-
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.
-
Proceed as needed for your deployment:
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.
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.
-
In the Application Security console, click Agents to display the Search page.
-
Find the Registration: See "WebGate Search Controls".
-
Select the desired registration from the results table, and open it to confirm it is the right agent to remove, close the page.
-
Select the name in the results table, click the Delete (X) button, check the Confirmation dialog and then close the page.
-
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:
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:
|
|
input/ |
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 |
|
|
[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.
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 |
|
|
Extended (Full) Form |
|
|
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:
-
Locate RREG.tar.gz file in the following path:
$ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz
-
Untar RREG.tar.gz file, which creates directories beneath
/clientcontaining the required tool and templates. -
In the oamreg script (...
/rreg/client/rreg/bin) set environment variables as follows:-
Set JAVA_HOME to JDK 1.6 (Table 15-11).
JDK 1.7 can also be used in R2PS3.
-
Set OAM_REG_HOME to the exploded_dir_for_RREG.tar/rreg based on your environment (client side or server side Table 15-11).
-
-
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
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 ManagerBefore you begin, read:
-
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 -
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/
-
Review the native configuration file created for the agent in the /rreg/output/AgentName/ folder.
-
Finalize Registration: Perform the following steps to replace the earlier agent configuration file if it is not already replaced:
-
Copy artifacts in /rreg/output/AgentName/ to update the agent configuration. For example:
From the AdminServer (Console) host
/rreg/output/Agent_Name/ObAccessClient.xmlandcwallet.ssoTo the Agent host: $11gWG_install_dir/
WebGate/config. For example:- $WebTier_MW_Home/Oracle_WT1/instances/instance1
- /config/OHS/ohs1/WebGate/config
-
Restart the OAM Server hosting the agent.
-
-
Proceed with "Validating Remote Registration and Resource Protection".
15.8.4 Performing Out-of-Band Remote Registration
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 |
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 ManagerSteps 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
-
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
-
In-Band Administrator:
-
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 -
Provide the Registration Administrator user name and password when asked.
-
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/
-
Return the agentName_Response.xml file to the out-of-band Administrator along with any other artifacts. For example:
agentName_Response.xml
-
-
Out-of-Band Administrator: Updates the environment, as follows.
-
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 -
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.xmlandcwallet.ssoTo the Agent host: $11gWG_install_dir/
WebGate/config. For example:- $WebTier_MW_Home/Oracle_WT1/instances/instance1
- /config/OHS/ohs1/WebGate/config
-
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
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
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
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.
-
Validate Agent Registration in the Oracle Access Management Console:
-
Confirm Agent details under Application Security in the Oracle Access Management Console.
-
Confirm the updated Agent configuration files are in the appropriate location, as described in "Performing Remote Registration for OAM Agents".
-
-
Validate Shared Components, Host identifier: Confirm that the host identifier is defined in the Oracle Access Management Console.
-
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.
-
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.
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 |
|---|---|
|
Set to true or false to allow for an empty host identifier or not. |
Sample
setAllowEmptyHostIdentifier(enable ="true")