Oracle Access Manager 11g provides a command-line utility to streamline partner registration. Any administrator inside the network can use the remote registration tool to specify WebGate parameters and values using a template. Administrators outside the network can use the utility to provide information to administrators within the network.
This chapter focuses on using the command-line utility to perform partner registration. This chapter includes the following topics:
Before you can perform tasks in this chapter, ensure that an OAM Administration Console and a managed OAM Server are running.
Supported policy enforcement agents must be registered with Oracle Access Manager 11g to communicate with OAM authentication and authorization services. A partner application (one that delegates the authentication function to the OAM SSO provider to spare users from re-authenticating when accessing multiple resources) must also be registered.
Protecting applications with Oracle Access Manager 11g requires an OAM Agent (WebGate) or OSSO Agent (mod_osso) that is registered with the OAM Administration Console, and an application domain that is configured to protect the application with specific authentication and authorization policies.
The following command-line registration functionality is supported:
Secure registration and creation of an application domain by:
In-band Administrators (administrators within the network who manage the Web server that hosts the agent)
In-band Administrators can use either the registration tool or the Oracle Access Manager Administration Console for registration tasks. This chapter focuses on command-line registration.
Out-of-band Administrators (those outside the network)
Administrators outside the network must submit registration requests to an Administrator within the network. After processing the request, the in-band administrator returns the files required by the out-of-band Administrator who uses the files to configure his environment.
Symmetric key generation per Partner Application
One key is generated and used per registered mod_osso or 11g WebGate. However, one single key is generated for all 10g WebGates.
Registration of earlier Oracle Access Manager WebGate and OSSO Agents for backward compatibility with legacy systems is provided. For more information, see the certification matrix on Oracle Technology Network:
http://www.oracle.com/technology/software/products/ias/files/fusion_certification.html
Functionality in the following list is not supported:
Persistence of the Key and Agent Information
Generation of Keys used by internal Oracle Access Manager components
API support for reading Agent information
For more information, see:
Following is a brief overview of in-band Web server administrator tasks for provisioning a partner application using the registration tool. The tasks are the same whether you have an OAM Agent (WebGate) or OSSO Agent (mod_osso) protecting resources.
Note:
mod_osso is an Oracle HTTP Server module that provides OracleAS applications with authentication. This module resides on the Oracle HTTP Server that enables applications protected by OracleAS Single Sign-On to accept HTTP headers in lieu of a user name and password once the user has logged into the OracleAS Single Sign-On server. The values for these headers are stored in a mod_osso cookie.The mod_osso module replaces the single sign-on SDK that was used in earlier releases of OracleAS Single Sign-On to integrate partner applications. Located on the application server, mod_osso simplifies the authentication process by serving as the sole partner application to the single sign-on server. In this way, mod_osso renders authentication transparent to OracleAS applications. The administrator for these applications is spared the burden of integrating them with an SDK. After authenticating a user, mod_osso transmits the simple header values that applications may use to authorize the user:
User name
User GUID (global user identity)
Language and territory
In this overview, the term "Administrator" refers to any user within the network who is part of the LDAP group that is designated for OAM administrators in the primary user identity store that is registered with OAM.
Task overview: In-band administrators performing remote registration
Acquire the Oracle Access Manager 11g Release 1 (11.1.1) registration tool as described in "Acquiring and Setting Up the Registration Tool".
Update the input file with unique values for the agent and application domain as described in "Creating the Registration Request".
Run the registration tool to configure the Agent and create a default application domain for the resources, as described in "Performing In-Band Remote Registration".
Validate the configuration as described in "Validating Remote Registration and Resource Protection" in.
Perform access checks to validate that the configuration is working, as described in "Validating Authentication, Resource Protection, and Access After Remote Registration".
The term out-of-band registration refers to manual registration that involves coordination and actions by both the in-band Administrator and the out-of-band Administrator.
Task overview: Out-of-band remote registration (Agent outside the network)
Out-of-band Administrator creates a starting request input file containing specific application and agent details and submits it to the in-band Administrator.
Acquire the Oracle Access Manager 11g registration tool as described in "Acquiring and Setting Up the Registration Tool".
Copy and edit a template to input unique values for the agent and application domain as described in "Creating the Registration Request".
Submit the starting request input file to the in-band administrator using a method you choose (email or file transfer).
In-band Administrator:
Acquire the Oracle Access Manager 11g registration tool as described in "Acquiring and Setting Up the Registration Tool".
Use the out-of-band starting request with the registration tool to provision the agent and create the following files to return to the out-of-band Administrator. See "Performing In-Band Remote Registration" for details of this and more on the following files:
agentName_Response.xml is generated for the out of band administrator to use in Step 3.
For WebGate Agents, a modified ObAccessClient.xml file is created (and the 11g WebGate cwallet.sso file), which the out-of-band administrator can use to bootstrap the WebGate.
SSO wallet creation applies only to OAM 11g WebGates (not to OAM 10g agents or OSSO agents).
For OSSO Agents, a modified osso.conf file is created for the out-of-band administrator to bootstrap the OSSO module.
Out-of-band Administrator uses the registration tool with the agentName_Response.xml file and copies the Agent configuration and any other generated artifacts to the appropriate file system directory.
In-band Administrator validates the configuration as described in "Validating Remote Registration and Resource Protection".
Out-of-band Administrator performs several access checks to validate that the configuration is working, as described in "Validating Authentication, Resource Protection, and Access After Remote Registration".
Each registered agent has a symmetric key, regardless of the registration method (Administration Console versus remote registration).
Each application will have a symmetric key whether it is protected through mod_osso, or 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.
Each WebGate agent has its own secret key that is shared between the agent and the OAM 11g 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 11g server.
Figure 6-1 illustrates the process of key generation, which occurs automatically when the agent is registered, regardless of the method used (Administration Console versus remote registration). There is one symmetric key per agent.
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 11g WebGates (not to OAM 10g agents or OSSO agents).
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 Partner Registration.
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_Middleware_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.
This topic provides an overview of the registration tool, requirements, usage, and results.
<MiddlewareHome>/Oracle_IDM1/oam/server/rreg/
The registration tool, oamreg, is located in <OAM_HOME>/oam/server/rreg/client/RREG.tar.gz. After you untar the file on the computer hosting the Agent, the tool resides in the following path.
Platform | Path to oamreg |
---|---|
Linux | rreg/bin/oamreg.sh |
Windows | rreg\bin\oamreg.bat |
Before using the script, two environment variables must be set within it as described here. The JDK home should point to JDKL 1.6:
Environment Variable | Description |
---|---|
OAM_REG_HOME | The directory under which RREG.tar was exploded, followed by /rreg. |
JDK_HOME | The location where Java is located on the client computer. For example: WLS_HOME/Middleware/jdk160_11. |
In addition, you must modify several tags in the Registration request. For details, see "About Remote Registration Requests".
The user can be a part of any group that is mapped against the OAM Administrator's Role in the primary user-identity store. For more information, see Table 3-2, "Required User Identity Store Elements".
Remote Registration Modes and Request Files
The command to run the script requires two arguments:
mode: inband
or outofband
input/file
: 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.
Agent Types and Associated Request Files
Both inband
and outofband
modes use a request file with the input argument, as follows.
Table 6-1 Remote Registration Request Files
Agent Type | Request File |
---|---|
10g WebGates |
$OAM_REG_HOME/input/OAMRequest_short.xml |
$OAM_REG_HOME/input/OAMRequest.xml |
|
11g WebGates |
$OAM_REG_HOME/input/OAM11GRequest.xml |
$OAM_REG_HOME/input/OAM11GRequest_short.xml |
|
OSSO Agents (mod_osso) |
$OAM_REG_HOME/input/OSSORequest.xml |
See Also:
"About Remote Registration Requests"In outofband
mode, the in-band administrator uses the starting request file submitted by the out-of-band administrator, and returns a generated agentName_Response.xml file to the out-of-band administrator for additional processing. The out-of-band administrator runs the remote registration tool with agentName_Response.xml as input to generate agent configuration files.
Sample Remote Registration Commands and Results
Sample commands are shown in Table 6-2 and presume the location of the tool to be $OAM_REG_HOME on a Linux system.
Table 6-2 Remote Registration Sample Commands
Command Type | Sample (on Linux) |
---|---|
In-band Administrator using In-band Request |
./bin/oamreg.sh inband input/*Request.xml |
In-band Administrator using Submitted Request |
./bin/oamreg.sh outofband input/starting_request.xml |
Out-of-band Administrator using Returned Response |
./bin/oamreg.sh outofband input/agentName_Response.xml |
After launching the script, administrators are prompted for a username and password. After running the script, messages inform of success or failure. Based on the input file and the mode in which you are running the registration tool, you can expect the results described in Table 6-3.
Table 6-3 Results of Remote Registration
Server Side Results | Client Side Results |
---|---|
|
inband Client-Side Results: The Agent's native configuration file is generated and stored in a directory based on the <agentName> tag in the *Request.xml file (for example, RREG_Home/output/agentName/). The generated configuration file must replace the earlier agent configuration file. Either:
|
outofband Client-Side Results: Depending on the input file you use (starting request or a generated agentName_Response.xml file) the following results occur:
|
This topic describes the registration request files that are available for use with the registration tool, and the elements that are common between them:
Example 6-1 provides an updated version of the OSSO Registration Request for use with the registration tool oamreg.sh (Linux) or oamreg.bat (Windows). The information highlighted in bold must be modified for a mod_osso agent. However, all other fields can use the default values.
... <OSSORegRequest> . <serverAddress>http://sample.us.oracle.com:7001</serverAddress> <hostIdentifier>RREG_Webdomain</hostIdentifier> <agentName>Remote_Reg_OSSO</agentName> <agentBaseUrl>http://sample.us.oracle.com:7777</agentBaseUrl> <oracleHomePath>$ORACLE_HOME</oracleHomePath> <virtualHost></virtualHost> <updateMode></updateMode> <adminInfo></adminInfo> <adminId></adminId> <protectedResourcesList> <resource>/access/resource1.html</resource> <resource>/access/resource2.html</resource> </protectedResourcesList> <publicResourcesList> <resource>/public/index.html</resource> /<publicResourcesList> </OSSORegRequest>
Example 6-2 provides an updated sample of the short OAM registration request for use with the agent registration tool: oamreg.sh (Linux) or oamreg.bat (Windows). The only difference between the short OAM remote registration request for OAM 10g WebGates versus OAM 11g WebGates is the container:
OAMRegRequest
OAM11GRegRequest
Note:
While the short OAM remote registration request is nearly identical for both OAM 10g WebGates and OAM 11g WebGates, be sure to copy the appropriate template for your WebGate release.Within Example 6-2, only the information highlighted in bold must be modified with values for your environment. All other fields in this file can use the default values. When you run oamreg, default values are provided automatically for all other Agent definitions which can be found in the full OAM remote registration requests.
Example 6-2 Sample Simplified Request: OAMRequest_short.xml
<OAMRegRequest> . <serverAddress>http://sample.us.oracle.com:7001</serverAddress> <hostIdentifier>RREG_HostId11G</hostIdentifier> <agentName>Remote_Reg_OAM</agentName> <protectedResourcesList> <resource>/</resource> <resource>/.../*</resource> </protectedResourcesList> <publicResourcesList> <resource>/public/index.html</resource> </publicResourcesList> </OAMRegRequest>
Unless otherwise stated, Table 6-4, explains the global elements within all request files.
Table 6-4 Elements Common to Remote Registration Requests
Element | Description | Example |
---|---|---|
<serverAddress> |
Points to a running instance of the Oracle Access Manager Administration Console, including the host and port. |
<serverAddress>http://{oam_admin_ser ver_host}:{oam_admin_server_port} </serverAddress> |
<agentName> |
Defines a unique identifier for the agent on the OAM (Administration) Server. For every agent on the same server instance, this tag must be unique to avoid re-registering the same agent. Re-registering an agent on the same server instance is not supported without first deleting the existing agent. |
<agentName>RREG_OAM</agentName>
|
<hostIdentifier> |
This identifier represents the Web server host. The field is filled in automatically when you specify a value for the OAM Agent Name. If the agent name or host identifier of the same name already exists, an error occurs during registration. Note: If the <hostIdentifier> tag is specified, its value must be modified for your environment. To use a default value during registration, omit the <hostIdentifier> tag. If a host identifier of the same name already exists, the new agent Web server host:port, if specified, is added to the existing host identifier. |
<hostIdentifier>RREG_HostId11G
</hostIdentifier>
|
<protectedResourcesList> |
Specifies the resource URLs that you want the OAM Agent to protect with some authentication scheme. The resource URLs should be relative paths to the agentBaseUrl. |
<protectedResourcesList> <resource>/</resource> <resource>/.../*</resource> </protectedResourcesList> |
<publicResourcesList> |
Specifies the resource URLs that you want to keep public (not protected by the OAM Agent). The resource URLs should be relative paths to the agentBaseUrl. For instance, you might want to specify the Home page or the Welcome page of your application |
<publicResourcesList> <resource>/public/index.html </resource> </publicResourcesList> |
Table 6-5 describes the remote registration elements that are OSSO-specific.
Table 6-5 OSSO-Specific Elements in a Remote Registration Request
Element | Description | Example |
---|---|---|
<OracleHomePath> |
The absolute file system directory path to the mod_osso agent. |
<oracleHomePath> $ORACLE_HOME </oracleHomePath> |
<virtualHost> |
Default: None specified |
<virtualHost></virtualHost> |
<updateMode> |
Default: None specified |
<updateMode></updateMode> |
<adminInfo> |
Optional administrator details for this mod_osso instance. For example, Application Administrator. Default: None specified > |
<adminInfo></adminInfo> |
<adminInfo> |
Optional administrator log in ID for this mod_osso instance. For example, SiteAdmin. Default: None specified > |
<adminId></adminId> |
Table 6-6 provides information on individual elements in full OAM remote registration requests, which are in addition to those in the short version of the request (in Table 6-4):
OAM11gRequest.xml (11g WebGates)
OAMRequest.xml (10g WebGates)
Note:
Unless explicitly stated, each element appears in both 10g and 11g WebGate requests. Element names might differ slightly from their counterparts in the Console.Table 6-6 Elements Common to Full Remote Registration Requests
Element | Description | Example |
---|---|---|
<agentBaseUrl> |
Defines the Web server host:port on the computer that the agent is intended to protect. All URLs to protect are taken to be relative to this base URL, which should be specified as: http://host:port. Note: Each agentBaseUrl can be registered once only. There is a one-to-one mapping from the Agent's Base URL to the Web Server domain on which the WebGate is installed (as specified with the <hostIdentifier> element). However, there is a one-to-many mapping from the specified domain to the Agent's Base URL (one domain can have multiple Agent's Base URLs). |
<agentBaseUrl>http://{web_server_ host):(web_server_port} </agentBaseUrl> |
<applicationDomain> |
Defines the name of the application domain, which is based on the specified Agent Name (see Table 6-4). |
<applicationDomain>RREG_OAM11G </applicationDomain> |
<autoCreatePolicy> |
During agent registration, you can have authentication and authorization policies created automatically. This option is checked (enabled) by default. Default: true (enabled) Note: If you already have a domain and policies registered, you can simply add new resources to it. If you clear (uncheck) this option, no application domain or policies are generated automatically. |
<autoCreatePolicy>true </autoCreatePolicy> |
<primaryCookieDomain> 10g Request Only In OAMRequest.xml (for 10g WebGates) <hostIdentifier> is also used as the preferred HTTP host. |
Describes the Web server domain (client domain) on which the OAM 10g Agent is deployed, for instance,.acompany.com. You must configure the cookie domain to enable single sign-on among Web servers. Specifically, the Web servers for which you configure single sign-on must have the same Primary Cookie Domain value. The OAM Agent uses this parameter to create the ObSSOCookie authentication cookie. This parameter defines which Web servers participate within the cookie domain and have the ability to receive and update the ObSSOCookie. This cookie domain is not used to populate the ObSSOCookie; rather it defines which domain the ObSSOCookie is valid for, and which Web servers have the ability to accept and change the ObSSOCookie contents. Default: If the client side domain can be determined during registration, the Primary Cookie Domain is populated with that value. However, if no domain is found, there is no value and WebGate uses the host-based cookie. Note: The more general the domain name, the more inclusive your single sign-on implementation will be. For example, if you specify b.com as your primary cookie domain, users will be able to perform single sign-on for resources on b.com and on a.b.com. However, if you specify a.b.com as your primary cookie domain, users will have to re-authenticate when they request resources on b.com. |
<primaryCookieDomain>{client_domain} </primaryCookieDomain> |
<maxCacheElems> |
Number of elements maintained in the cache. Cache elements are the following:
The value of this setting refers to the maximum consolidated count for elements in both of these caches. Default = 100000 |
<maxCacheElems>100000 </maxCacheElems> |
<cacheTimeout> |
Amount of time cached information remains in the OAM Agent cache when the information is neither used nor referenced. Default = 1800 (seconds) |
<cacheTimeout>1800</cacheTimeout> |
<tokenValidityPeriod> 11g Request Only |
Maximum valid time period for an agent token (the content of OAMAuthnCookie for 11g WebGate). Default = 3600 (seconds) |
<tokenValidityPeriod>3600 </tokenValidityPeriod> |
<cookieSessionTime> 10g Request Only |
Maximum amount of time in seconds that a user's authentication session is valid, regardless of their activity. At the expiration of this session time, the user is re-challenged for authentication. This is a forced logout. Default = 3600 (seconds) A value of 0 disables this timeout setting. |
<cookieSessionTime>3600 </cookieSessionTime> |
<maxConnections> |
The maximum number of connections that this OAM Agent 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 |
<maxConnections>1</maxConnections> |
<maxSessionTime> |
Maximum duration, in hours, for a connection between WebGate and the OAM Server. Default = 24 (hours) A value of 0 disables this timeout setting. |
<maxSessionTime>24</maxSessionTime> |
<ssoServerVersion> |
SSO Token version values:
|
<ssoServerVersion> >...</ssoServerVersion> > |
<idleSessionTimeout> 10g Request Only |
Amount of time in seconds that a user's authentication session remains valid without accessing any AccessGate protected resources. Default = 3600 A value of 0 disables this timeout setting. |
<idleSessionTimeout>3600> </idleSessionTimeout |
<failoverThreshold> |
Number representing the point when this OAM Agent 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 OAM Agent opens connections to secondary OAM Server. |
<failoverThreshold>1 </failoverThreshold> |
<aaaTimeoutThreshold>- |
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) 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 Access Server is received, resulting in an error. Both the WaitForFailover parameter and the aaaTimeoutThreshold must use the same value. See Also: Table 5-6 for more information on this parameter. |
<aaaTimeoutThreshold>-1 </aaaTimeoutThreshold> |
<sleepFor> |
The frequency with which the Access Server checks its connections to the directory server. For example, if you set a value of 60 seconds, the Access Server checks its connections every 60 seconds from the time it comes up. |
<sleepFor>60</sleepFor> |
<debug> |
Turns debugging on or off. Default: false (off) |
<debug>false</debug> |
<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, see Appendix E. |
<security>open</security |
<denyOnNotProtected> |
Denies access to all resources to which access is not explicitly allowed by a rule or policy. Always enabled in 11g WebGate registration, and cannot be changed. On a 10g WebGate registration page, you can choose to disable this. When enabled, you must create an anonymous authentication method and allow access to content using an anonymous access policy. |
<denyOnNotProtected>1 </denyOnNotProtected> |
<cachePragmaHeader> <cacheControlHeader> |
These settings apply only to WebGates and control the browser's cache. By default, CachePragmaHeader and CacheControlHeader 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. |
<cachePragmaHeader>no-cache </cachePragmaHeader> <cacheControlHeader>no-cache </cacheControlHeader> |
IP address validation is specific to WebGates and is used to determine whether a client's IP address is the same as the IP address stored in the ObSSOCookie (10g WebGate) or OAMAuthnCookie (11g WebGate) generated for single sign-on. |
<ipValidation>0</ipValidation> |
|
<logOutUrls> |
The Logout URL triggers the logout handler, which removes the cookie (ObSSOCookie for 10g WebGates; OAMAuthnCookie for 11g WebGates) and requires the user to re-authenticate the next time he accesses a resource protected by Oracle Access Manager.
Note: This is the standard OAM 10g WebGate configuration parameter used to trigger initial logout. See Also: Chapter 11 for steps to configure logout for OAM 10g WebGates registered with OAM 11g. |
<logOutUrls> <url>/logout1.html</url> <url>/logout2.html</url> </logOutUrls> |
<logoutCallbackUrl> 11g Request Only |
The URL to oam_logout_success, which clears cookies during the call back. This can be a URI format without host:port (recommended), where the OAM Server calls back on the host:port of the original resource request. For example: /oam_logout_success This can also be a full URL format with a host:port, where OAM 11g server calls back directly without reconstructing callback URL. See Also: Chapter 11 for steps to configure logout for OAM 11g WebGates. |
<logoutCallbackUrl>/oam_logout_success </logoutCallbackUrl> |
<logoutTargetUrlParamName> 11g Request 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 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: Chapter 11 for steps to configure logout for OAM 11g WebGates. |
<logoutTargetUrlParamName>end_url </logoutTargetUrlParamName> |
User-Defined Parameters |
The following user-defined parameters are available for configuration in the remote registration request files only. Note: Each parameter can have only one value. User-defined parameters cannot be set using the OAM Administration Console. |
<userDefinedParameters> <userDefinedParam> <name>...</name> <value>...</value> </userDefinedParam> |
MaxPostDataLength |
Determines the length of POST data. Oracle recommends that you do not set the value to less than 100. By default, or if this parameter is set to a value beyond the specified range, POST data length is limited to the default size of 0.75MB. Default: 750000 See Also: Chapter 19 for more information about configuring IIS Web servers for WebGate. |
<name>MaxPostDataLength</name> <value>750000</value> |
maxSessionTimeUnits |
Allows the Some firewalls forcefully disconnect OAM Server connections over a certain age or idle time. If you cannot modify firewall time-out settings, you can use Default: hours Possible values: minutes |
<name>maxSessionTimeUnits</name> <value>hours</value> |
RetainDownstreamPostData |
Adding this user-defined parameter and setting the value to Default: false |
<name>RetainDownstreamPostData </name> <value>false</value> |
useIISBuiltinAuthentication |
Set to true only if you are using Microsoft Passport or Integrated Windows Authentication on the OAM Server on which the Agent is installed. It is used only for IIS, and is ignored if the WebGate is installed for another type of Web server. Default: false |
<name>useIISBuiltinAuthentication </name> <value>false</value> |
idleSessionTimeoutLogic 10g WebGates only |
Release 7.0.4 WebGates enforced their own idle session timeout only. 10.1.4.0.1 WebGates enforced the most restrictive timeout value among all WebGates the token had visited. With 10g (10.1.4.3), the 7.0.4 behavior was reinstated as the default with this element. To set idleSessionTimeoutLogic:
|
name>idleSessionTimeoutLogic </name> <value>leastComponentIdleTimeout </value> |
URLInUTF8Format |
In an environment that uses Oracle HTTP Server 2, this parameter must be set to true to display latin-1 and other character sets. Default: true |
<name>URLInUTF8Format</name> <value>true</value> |
inactiveReconfigPeriod Shared secret applies to only 10g WebGate Configuration applies to only 11g WebGate. |
In the idle state the WebGate reads the shared secret (configuration) from the OAM Server using the InactiveReconfigPeriod value. If this value is not set, the WebGate polls the OAM Server for the shared secret (configuration) value at an interval of 1 minute even though the updated shared secret (configuration) value will be returned only after 10 minutes. Default: 10 (minutes) |
<name>inactiveReconfigPeriod</name> <value>10</value> |
WaitForFailover 10g WebGate only |
Used only for backward compatibility with NetPoint 5.x systems, this parameter has been replaced by aaaTimeoutThreshold. Both the WaitForFailover parameter, and the aaaTimeoutThreshold parameter, control the TCP/IP timeout between the WebGate and OAM Servers. The default value is "-1," which means the network default TCP/IP timeout value is used. Both the WaitForFailover parameter and the aaaTimeoutThreshold must use the same value. |
<name>WaitForFailover</name> <value>-1</value> |
proxySSLHeaderVar |
This parameter is used 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 |
<name>proxySSLHeaderVar</name> <value>IS_SSL</value> |
client_request_retry_attempts |
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. This is the same for both 10g and 11g WebGates (OAM Agents) with OAM 11g. If the OAM Server takes longer to service a request than the value of the timeout threshold, the OAM 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. The OAM Agent will first try the Primary OAM Server if one is available and then Secondary OAM Servers if one is available. Also, other OAM Servers might require more time to process the request than the time specified on the timeout threshold. In some cases, the OAM Agent can retry the request until the OAM Servers are shut down. You can configure a limit on the number of retries that the OAM Agent performs for a non-responsive server using the client_request_retry_attempts parameter. Setting the value to -1 (or not setting it at all) allows an infinite number of retries. |
<name>client_request_retry_attempts </name> <value>1</value> |
ContentLengthFor401Response |
To set the Content-Length for all 401 responses, add the following as a user defined parameter and value: Zero (0) is the only value you can use. Any other value will be ignored. If you do not use this parameter and value, a mismatch between the content and content length might occur. This would result in either no data displayed in the browser or an error message in the browser. |
<name>ContentLengthFor401Response </name> <value>0</value> |
SUN61HttpProtocolVersion |
SUN v6.1 Web server might have a problem with redirection after reading POST data. If the connection uses the keepAlive (HTTP/1.1) protocol, data is not flushed properly. Thus, redirection might not work consistently. The SUN 6.1 Web server can be forced to use the HTTP/1.0 protocol when you assign a value of Default: 1.0 Any value other than 1.0 will be ignored. |
<name>SUN61HttpProtocolVersion </name> <value>1.0</value> |
impersonationCredentials |
Default: cred |
<name>impersonationCredentials< /name> <value>cred</value> |
UseWebGateExtForPassthrough |
This IIS Web server-specific parameter for use only with IIS v6 and v7 in Worker Process Isolation Mode. Default: false Set the value to true for IIS version 6.x (running in worker process isolation mode) and IIS 7.x in the following situations:
Note: You must also configure webgate.dll as an ISAPI extension (besides configuring it as an ISAPI filter). See Chapter 19, "Configuring the IIS Web Server for 10g WebGates". Also: For IIS 5.0 or IIS6.0 running in IIS 5.0 Isolation Mode this parameter should not be defined (or should be set to false). In this case, postgate.dll must be configured as an ISAPI filter to achieve pass-through functionality. For more information, see "Enabling Pass-Through Functionality for POST Data". |
<name>UseWebGateExtForPassthrough </name> <value>false</value> |
syncOperationMode |
Default: false |
<name>syncOperationMode</name> <value>false</value> |
filterOAMAuthnCookie 11g Request only. |
When set to true, the OAMAuthnCookie is always filtered and not accessible to downstream applications. Default: true |
<name>filterOAMAuthnCookie</name> <value>true</value> |
After performing requested operations, in-band administrators send the following files to out-of-band Administrators for additional processing:
agentName_Response.xml, which must be used as is by the out-of-band administrator.
This is not shown because Oracle recommends that you do not open or edit an agentName_Response.xml.
Native Web server configuration files, which must be used by the out-of-band administrator to update their Web server.
You can use the following procedure to acquire and update the oamreg script for your operating system:
Windows: oamreg.bat
Linux: oamreg.sh
and to update the appropriate *Request*.xml file that provides input for the specific agent you want to register.
For remote registration, two variables are required: JAVA_HOME and OAM_REG_HOME, as described in Table 6-7.
Table 6-7 Variables Required for Remote Registration
Location | Variable | Description |
---|---|---|
Client Side |
JDK_HOME |
The Java 1.6 location on the computer that relies on $JAVA_HOME already set in the environment. |
OAM_REG_HOME |
The exploded directory for RREG.tar/rreg, which must be explicitly set in the script by the user. |
|
rreg folder location as opposed to the RREG.tar.gz |
JDK_HOME |
Relies on $JAVA_HOME already set in the environment. |
OAM_REG_HOME |
Is already set in the script during the installation. |
See Also:
"About the Remote Registration Tool"To acquire the tool and update the script for your environment
Locate RREG.tar.gz file in the following path:
WLS_home/Middleware/domain_home/oam/server/rreg/client/RREG.tar.gz
Untar RREG.tar.gz file.
In the oamreg script, in rreg/bin/oamreg, set the JAVA_HOME environmental variable to JDK 1.6 (Table 6-7).
In the oamreg script, set the OAM_REG_HOME environmental variable to the exploded_dir_for_RREG.tar/rreg variables based on your environment (client side or server side Table 6-7).
Proceed with "Creating the Registration Request".
You can use the following procedure to create an appropriate *Request*.xml file to provide input for the specific agent you want to register.
To create the registration request
Locate the required *Request*.xml input file for the agent you want to register (Table 6-1).
WLS_home/Middleware/domain_home/oam/server/rreg/input
Copy the request file to a new name. For example:
In the Request file, modify information to reflect details for this agent and the resources to protect (Table 6-4 and Table 6-6):
Proceed with:
This section provides steps you can use to perform in-band remote registration.
Prerequisites:
You can use the following procedure to perform remote registration within the network.
Note:
In this situation, the Administrator within the network performs all tasks. The tasks are the same whether you have an OAM Agent (WebGate) or OSSO Agent (mod_osso) protecting resources.This example illustrates registering an OAM Agent using the short registration request on a Linux system. Alternatively, you can use the OAM Administration Console to register the Agent and add an Application domain, as described in Chapter 5 and Chapter 9, respectively.
To perform in-band remote registration
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.
Read the messages on-screen to confirm:
Success: On-screen message confirms
In-band registration process completed successfully!
Native Configuration File Location: "... created in output folder ..."
The output folder is in the same location where RREG.tar.gz was expanded: /rreg/output/AgentName/
Review the native configuration file, ObAccessClient.xml, created for the Agent in the output folder, and replace the earlier agent configuration file if it is not already replaced.
Finalize Agent Registration: Perform the following steps to finalize this agent registration:
Copy ObAccessClient.xml to the OAM Agent host computer to manually update the WebGate configuration.
10g WebGate: $WG_install_dir/oblix/lib/ObAccessClient.xml
11g WebGate: $WebGate_instance_dir/webgate/config (also cwallet.sso) For example:
config/OHS/ohs1/webgate/config
Restart the Managed Server that is hosting the OAM Agent.
Proceed with "Validating Remote Registration and Resource Protection".
This section provides steps for administrators outside the network and those inside the network as they work together to register the remote Agent and set up a default application domain to protect resources.
Prerequisites:
Note:
In this situation, the in-band Administrator and the out-of-band Administrator perform different tasks. Tasks are the same regardless of agent type: OAM Agent or OSSO Agent (mod_osso).In the following procedure, steps illustrate the procedure to register an OAM Agent on a Linux system only:
In-Band refers to a task performed by the Web server administrator within the network.
Out-of-Band refers to a task performed the Web server administrator who is outside the network
To perform out-of-band remote registration
Out-of-Band Administrator: Create and send your starting_request.xml file to the in-band Administrator for processing (see "Creating the 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/AgentName/
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
ObAccessClient.xml and cwallet.sso (for 11g agents) are generated in the output folder location /rreg/output/AgentName/.
Copy ObAccessClient.xml to the OAM Agent host computer to manually update the WebGate configuration.
10g WebGate: $WG_install_dir/oblix/lib/ObAccessClient.xml
11g WebGate: $WebGate_instance_dir/webgate/config (also cwallet.sso). For example:
config/OHS/ohs1/webgate/config
Restart the Web Server that is hosting the OAM Agent.
Proceed with "Validating Remote Registration and Resource Protection".
This section provides the following topics:
You can use the following steps as a guide to validate the registration of an Agent and application regardless of the Agent type.
You must be an in-band Administrator to perform tasks using the OAM Administration Console. Out-of-band Administrators must test authentication and access remotely.
See Also:
To validate agent and application registration
Agent Registration: Confirm Agent details under the System Configuration tab in the OAM Administration Console, as described in Chapter 5 and:
OAM Agent: Ensure that the modified ObAccessClient.xml resides in the WebGate installation directory to bootstrap communication between WebGate and the OAM Server.
WebGate_install_dir\access\
OSSO Agent: Ensure that the modified osso.conf resides in the same directory as the Agent's Web server. Use it to bootstrap communication between OSSO Agent and OAM Server.
Shared Components, Host identifier: Confirm that the host identifier is defined in the OAM Administration Console.
Application Domain: Under the Policy Configuration tab, confirm there is a new default application domain, which is named after the registered Agent.
Resources in the application domain are associated with the host identifier.
Proceed with "Validating Authentication, Resource Protection, and Access After Remote Registration".
After registration, protected resource should be accessible with proper authentication without restart of admin server or Managed Server.
The procedure here provides several methods for confirming that registration, authentication, and authorization are properly configured and operational. The procedures is nearly identical for both OAM Agents (WebGates) and OSSO Agents (mod_osso).
Oracle recommends that the out-of-band administrator perform these verifications.
To verify authentication and access after registration
Enter the URL for an application protected by the registered OAM Agent to confirm that the log in page appears (proving that the authentication redirect URL was specified appropriately). For example:
http://myWebserverHost.us.abc.com:8100/resource1.html
On the Log In page, enter a valid username and password when asked, and click Login.
Check the OAM specific cookies are created in the browser session. For example:
ObSSOCookie:
Set-Cookie: ObSSOCookie=GGVEuvjmrMe%2FhbItbjT24CBmJo1eCIfDIwQ1atdGdnY4mt6kmdSekSFeAAFvFrZZZ xDfvpkfS3ZLZFbaZU2rAn0YYUM3JUWVYkYFwB%2BBK7V4x%2FeuYHj%2B8gwOyxhNYFna3iSx1MSZBE y51KTBfsDYOiw6R%2BCxUhOO8uZDTYHI3s0c7AQSyrEiQTuUV3nv1omaFZlk1GuZa4J7ycaGbIUyqwX rM0cKuBJNd6sX1LiRj9HofYQsvUV7ToqeAOpDS7z9qs5LhqU5Vq60bBn12DTX6zNX6Lcc0L5tVwvh7% 2BnOAkz2%2BoDkLs%2BBTkeGcB3ppgC9;httponly; path=/; domain=.us.oracle.com;
OAM_ID Cookies:
Set-Cookie: OAM_ID=v1.0~0~E1EBBC9846E09857060A68E79AEEB608~AA79FC43C695162B6CDE3738F40E94DA 6408D58B879AC3B467EBBD4800743C899843672B3511141FFABCF58B2CDCB700C83CC734A913625 7C4ABDA6913C9EF5A4E05C5D03D3514F2FECACD02F1C1B9314D76B4A68CB7A8BE42AEB09AFB98B8 EB; path=/; HttpOnly
Proceed as follows:
Success: If you authenticated successfully and were granted access to the resource; the configuration is working properly. Proceed with Steps 5 through 12 for further validations.
Failure: If you received an error during login or were denied access to the resource, check the following:
Login Error: Confirm that you provided a valid user id and password.
Unavailable Resource: Confirm that the resource is available.
Wrong Redirect URL: Verify the redirect URL in the OAM Administration Console.
User Variations: Perform steps 1 through 4 again with user variations to confirm appropriate behavior (either success for authorized users or failure for unauthorized users).
Request Cancellation: Perform a partial log in and click Cancel to confirm that the resource is not accessed.
Modified Authentication URL: Enter a nearly identical authentication URL as you perform Steps 1 through 5 to confirm appropriate response. For example, add a character to the URL string.
Updated Resource: Perform the following steps to ensure the resource is accessible. For example:
Original Resource: /abc/test.html
Updated Resource: /abc/xyz/test.html
Without restarting the Oracle WebLogic Server:
Access the updated resource and confirm the user is asked to authenticate and the resource is accessible.
Access the original resource and confirm that the resource is accessible and the user is not asked for authentication.
Various URL Patterns: Verify authentication for various URL patterns as you perform steps 1 through 5.
New Authentication Scheme: Perform the following steps to confirm authentication operations without restarting the WebLogic Server.
Add a new authentication policy that uses a different Authentication Scheme.
Protect the resource using the new policy.
Without restarting the Oracle WebLogic Server, perform steps 1 through 4.
CGI Resource Header Variable and Cookies: Perform the following steps to confirm authentication operations without having to restart the WebLogic Server.
Add a new authentication policy to protect a Common Gateway Interface (CGI) resource and set the Response for "Authentication Successful".
Protect the resource using the new policy.
Access the CGI resource.
Check for the header values configured for the response in a CGI data dump.
Agent Disabled: Perform the following steps to validate accessibility and authentication if WebGate is disabled in ObAccessClient.xml (WebGate should pick up the enabled value from oam-config.xml).
Disable the Agent (OAM Agent (WebGate) or OSSO Agent (mod_osso)).Start the Web server and OAM Server.Access an application protected by the OAM Agent and confirm that you are asked to authenticate.