Oracle® Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service 11g Release 1 (11.1.1) Part Number E15478-06 |
|
|
PDF · Mobi · ePub |
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 Oracle Access Manager Console and a managed OAM Server are running.
See Also:
Chapter 27 for information about registering and using 10g Webgates with Oracle Access Manager 11gSupported policy enforcement agents must be registered with Oracle Access Manager 11g to communicate with Oracle Access Manager authentication and authorization services. A partner application (one that delegates the authentication function to the Oracle Access Manager 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 Oracle Access Manager 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 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 Administrators in the Default System User Identity Store registered with Oracle Access Manager.
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 (Oracle Access Manager 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.
Key Use
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.
Key Generation
Figure 10-1 illustrates the process of key generation, which occurs automatically when the agent is registered, regardless of the method used (Oracle Access Manager 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.
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_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.
Location
The registration tool, oamreg, is located in:
<OAM_HOME>/oam/server/rreg/client/RREG.tar.gz
After untarring RREG.tar.gz on the computer hosting the Agent, the registration tool, oamreg, resides in the following path:
<OAM_HOME>/oam/server/rreg/client/rreg/bin/oamreg
Platform | Path to oamreg |
---|---|
Linux | /rreg/bin/oamreg.sh |
Windows | \rreg\bin\oamreg.bat |
Requirements
Before using the script, two environment variables must be set within the script as described here:
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. |
In addition, you must modify several tags in the Registration request. For details, see "About Remote Registration Request Files".
Registration Administrators
The user can be a part of any group that is mapped against the Administrator's Role in the primary user-identity store. For more information, see Table 5-2, "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 described in the previous "Requirements" table.
Agent Types and Associated Request Files
Both inband
and outofband
modes use a request file with the input argument, as follows (as described in the previous "Requirements" table):
Table 10-1 Remote Registration Request Files
Agent Type | Request File |
---|---|
10g Webgates |
$OAM_REG_HOME/input/OAMRequest_short.xml |
$OAM_REG_HOME/input/OAMRequest.xml |
|
$OAM_REG_HOME/input/OAMUpdateAgentRequest.xml |
|
11g Webgates |
$OAM_REG_HOME/input/OAM11GRequest.xml |
$OAM_REG_HOME/input/OAM11GRequest_short.xml |
|
$OAM_REG_HOME/input/OAM11GUpdateAgentRequest.xml |
|
OSSO Agents (mod_osso) |
$OAM_REG_HOME/input/OSSORequest.xml |
$OAM_REG_HOME/input/OSSOUpdateAgentRequest.xml |
|
Create New Host Identifiers and an Application Domain without Registering an Agent |
$OAM_REG_HOME/input/CreatePolicyRequest.xml See Also: "Managing Agents Remotely" |
Update existing Host Identifiers and Application Domain not associated with an Agent Registration |
$OAM_REG_HOME/input/UpdatePolicyRequest.xml See Also: "Managing Agents Remotely" |
See Also:
Generated Files
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 10-2 and presume the location of the tool to be $OAM_REG_HOME (previous "Requirements" table) on a Linux system.
Table 10-2 Remote Registration Sample Commands
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 |
./bin/oamreg.sh outofband input/agentName_Response.xml |
[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 |
After launching the script, administrators are prompted for a username and password (unless -noprompt is used as described in Table 10-2. 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 10-3.
Table 10-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:
See Also:
"Introducing Remote Management Modes"Example 10-1 provides 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.
Example 10-1 OSSORequest.xml
... <OSSORegRequest> <serverAddress>http://{oam_admin_server_host}:{oam_admin_server_port} <http://%7boam_admin_server_host%7d:%7boam_admin_server_port%7d> </serverAddress> <hostIdentifier>RREG_HostId</hostIdentifier> <agentName>RREG_OSSO</agentName> <agentBaseUrl>http://{web_server_host}:{web_server_port} <http://%7bweb_server_host%7d:%7bweb_server_port%7d> </agentBaseUrl> <applicationDomain>RREG_OSSO</applicationDomain> <autoCreatePolicy>true</autoCreatePolicy> <ssoServerVersion>v3.0</ssoServerVersion> <oracleHomePath>$ORACLE_HOME</oracleHomePath> <virtualHost></virtualHost> <updateMode></updateMode> <adminInfo></adminInfo> <adminId></adminId> <logoutUrl></logoutUrl> <failureUrl></failureUrl> </OSSORegRequest>
Example 10-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 10-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 10-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> <excludedResourcesList> <resource>/excluded/index.html</resource> </excludedResourcesList> </OAMRegRequest>
Unless otherwise stated, Table 10-4, explains the global elements within all request files.
Table 10-4 Elements Common to Remote Registration Requests
Element | Description | Example |
---|---|---|
<serverAddress> |
Points to a running instance of the Oracle Access Manager 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. A unique identifying name for each Agent registration is preferred. However:
|
<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 < 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>
|
Table 10-5 describes the remote registration elements that are OSSO-specific.
Table 10-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> |
<adminId> |
Optional administrator log in ID for this mod_osso instance. For example, SiteAdmin. Default: None specified > |
<adminId></adminId> |
<logoutUrl> |
Include the Logout URLs for consumption during remote registration. Default: None specified > |
<logoutUrl>logout1.html</logoutUrl> |
<failureUrl> |
Include the Failure URLs for consumption during remote registration. Default: None specified > |
<failureUrl>failure1.html</failureUrl> |
Table 10-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 10-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 10-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 < |
<agentBaseUrl>http://{web_server_ host):(web_server_port} </agentBaseUrl> |
<virtualhost> |
Specifies whether this is a virtual host. Values: true or false Default: false See Also: "About Virtual Web Hosting". |
<virtualhost>false<virtualhost> |
<hostportVariations> |
Specifies all variations of a particular host. Registered Agents protect all requests that match the addressing methods defined for the host identifier used in a policy. A request sent to any address on the list is mapped to the official host name and OAM can apply the policies that protect the resource and OAM can apply the policies that protect the resource. See Also: "About Host Identifiers". |
<hostPortVariationsList> <host>host1</host> <port>7777</port> </hostPortVariations> <host>host2</host> <port>7778</port> </hostPortVariations> </hostPortVariationsList> |
<applicationDomain> |
Defines the name of the application domain, which is based on the specified Agent Name (see Table 10-4). |
<applicationDomain>RREG_OAM11G </applicationDomain> |
<autoCreatePolicy> Absent in OAM 11g Short Version |
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> |
<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> |
<excludedresourcesList> |
Specifies the HTTP type 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. Only HTTP resource types can be excluded. Typically security insensitive files like Images (*.jpg, *.png) that do not require Authentication, Authorization, Response processing, Session management, and Auditing. Excluded resources cannot be added to any user-defined policy in the console. See Also: Table 13-1, "Resource Definition Elements" for more information on excluded resource lists. |
<excludedresourcesList> <resource>/excluded/index.html </resource> </excludedresourcesList> |
<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 Agentuses 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 See Also: Table 9-5 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> |
<allowManagementOperations> |
This Agent Privilege function enables the provisioning of session operations per agent, as follows:
Default: false 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. |
<allowManagementOperations> false/<allowManagementOperations> |
<cachePragmaHeader> <cacheControlHeader> |
These settings apply only to Webgates and control the browser's cache. By default, both 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> |
|
Exceptions to IP address validation. |
<ipValidationExceptions> <ipAddress>10,11,11,11</ipAddress> <ipAddress>10,11,11,12</ipAddress> <ipAddress>10,11,11,13</ipAddress> </ipValidationExceptions> |
|
<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 15 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 15 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 15 for steps to configure logout for OAM 11g Webgates. |
<logoutTargetUrlParamName>end_url </logoutTargetUrlParamName> |
User-Defined Parameter Names |
Descriptions
|
Examples <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 29 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
|
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 Default: 10 (minutes) |
<name>inactiveReconfigPeriod</name> <value>10</value> |
WaitForFailover 10g Webgate only |
Used only for backward compatibility, this parameter has been replaced by Both the Both the |
<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 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 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 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> |
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 29. 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.
Note:
Oracle Recommends using the latest tool and files release by applying the latest bundle patch and untarring RREG.tar.gz again.For remote registration, two variables are required: JAVA_HOME and OAM_REG_HOME, as described in Table 10-7.
Table 10-7 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. |
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 IM_ORACLE_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:
"About the Remote Registration Tool"To acquire the tool and update the script with your environment variables
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 /client
containing 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 10-7).
Set OAM_REG_HOME to the exploded_dir_for_RREG.tar/rreg based on your environment (client side or server side Table 10-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 10-1).
ORACLE_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 10-4 and Table 10-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 Oracle Access Manager Console to register the Agent and add an Application domain, as described in Chapter 9 and Chapter 13, 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/Access Client: $WG_install_dir/oblix/lib/ObAccessClient.xml
11g Webgate/Access Client: $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/Access Client: $WG_install_dir/oblix/lib/ObAccessClient.xml
11g Webgate/Access Client: $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 Oracle Access Manager 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 Oracle Access Manager Console, as described in Chapter 9 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 Oracle Access Manager 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 Oracle Access Manager 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.
This section provides the following topics:
Several remote management modes enable Administrators to update, or validate, or delete an existing agent registration. Table 10-8 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 10-8 Remote Agent and Policy Updates
Mode and Input Files | Description and Syntax |
---|---|
agentUpdate mode OSSOUpdateAgentRequest.xml OAM11GUpdateAgentRequest.xml OAMUpdateAgentRequest.xml |
Allows Administrators to update agent attributes: ./bin/oamreg.sh agentUpdate input/OAM11GUpdateAgentRequest.xml |
agentValidate mode No input file needed. |
Validates whether the agent is already provisioned in Oracle Access Manager 11g: ./bin/oamreg.sh agentValidate agentname
|
agentDelete mode No input file needed. |
Allows Administrators to delete the agent registration: ./bin/oamreg.sh agentDelete agentname
|
For a look at the templates for the agentUpdatemode, see:
You use OSSOUpdateAgentRequest.xml to pass specific values to the remote registration tool, oamreg. The primary differences between the update template and the original registration template is that the update template:
Provides a <startDate>yyyy_mm_dd</startDate> element to track changes
Provides a <homeUrl> element that specifies the agent_base_url_port
Omits the <hostidentifier> element
Omits the <agentbaseURL> element
See Also:
Table 10-5, "OSSO-Specific Elements in a Remote Registration Request" for details about elements and valuesFigure 10-2 illustrates the update template for the OSSO Agent.
You use OAM11GUpdateAgentRequest.xml to pass specific Agent-update values to the remote registration tool, oamreg. The primary differences between the update template and the original registration template is that the update template:
Provides the <ipValidation> element but omits <ipValidationExceptions>
Omits the <authCreatePolicy> and application domain-related elements
Omits the <hostidentifier>, <virtualhost>, and <hostportVariations> elements
Omits the <agentbaseURL> element
Omits the <ssoServerVersion> element
Omits the <idleSessionTimeout> element
See Also:
Table 10-10, "<rregApplicationDomain> Remote Management Template Elements"
Table 10-6, "Elements Common to Full Remote Registration Requests" for details about elements and values
Figure 10-2 illustrates the update template for the OAM 11g Agent.
You use OAMUpdateAgentRequest.xml to pass specific OAM 10g Agent-update values to the remote registration tool, oamreg. The primary differences between this update template and the original OAM 10g Agent registration template is that the update template:
Provides the <ipValidation> element but omits <ipValidationExceptions>
Omits the <authCreatePolicy> and application domain-related elements
Omits the <hostidentifier>, <virtualhost>, and <hostportVariations> elements
Omits the <agentbaseURL> element
Omits the <ssoServerVersion> element
Omits the <idleSessionTimeout> element
See Also:
Table 10-10, "<rregApplicationDomain> Remote Management Template Elements"
Table 10-6, "Elements Common to Full Remote Registration Requests" for details about elements and values
Figure 10-4 illustrates OAMUpdateAgentRequest.xml for OAM 10g Agents.
Oracle Access Manager 11g provides two modes to manage Application Domains without registering or modifying an Agent.
Note:
Remote Application Domain management supports only create and update functions. Remove application domain management does not support remote removal of any application domains. Application Domains removal is a manual task that must be performed using the Oracle Access Manager Console.Table 10-9 describes these remote Application Domain management modes. Again, command parameters include the mode, and an input *Request.xml file using a relative path with respect to OAM_REG_HOME, the preferred location for input files):
./oamreg.sh <mode> <input_file> [prompt_flag] [component.oam.config_file] <mode> value
Table 10-9 Remote Application Domain Management Modes
Mode | Description |
---|---|
policyCreate CreatePolicyRequest.xml |
Allows Administrators to create Host Identifiers and an Application Domain without registering an Agent. ./bin/oamreg.sh policyCreate input/CreatePolicyRequest.xml Functions include:
|
policyUpdate UpdatePolicyRequest.xml |
Allows Administrators to update existing Host Identifiers and Application Domain without updating an Agent. ./bin/oamreg.sh policyUpdate input/UpdatePolicyRequest.xml Functions include:
|
[prompt_flag] value: [-noprompt] |
Optional. When the -noprompt flag is used, oamreg can read input from system.in by using echo and pipe to pass data. Examples from OAM_REG_HOME location: (echo username; echo password; echo webgate_password;) | ./bin/oamreg.sh inband input/Request.xml -noprompt component.oam.conf (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 |
component.oam.config_file |
Optional. Remote registration accepts a configuration file with a URI list as an argument. component.oam.config_file defines the full path to a file containing any number of protected or public URIs. Ensure that the file uses the following syntax and format:
Note: You can configure the authentication scheme for a protected policy using the following format (the policy name and authentication scheme name must be separated by a Tab character): <Policy Name> 'tab' <Authentication Scheme Name> For example: ######################## protected_uris ######################## protected policy1 Basic Over LDAP /finance/protected1/* /finance/protected2/* protected policy2 Client Certificate /finance/protected3/.../{*.js,*.png,*.gif} ######################## public_uris ######################## /finance/public /finance/test1/public |
For more information, see:
The following information can be created using policyCreate
mode and the CreatePolicyRequest.xml without creating or updating an agent registration:
Create a Host Identifier add multiple hostPortVariations
(host port pairs).
Create an Application Domain.
Add multiple protected, public, and excluded resources. Resources can be with or without query strings, both are supported.
Create default authentication and authorization policies for the resources that do not require customized policies.
Some parameters in the CreatePolicyRequest.xml file are new and not included in the full agent registration XML files, while certain elements in the original agent registration file are used to create or update. However, some elements are The primary differences of CreatePolicyRequest.xml are specific to:
Elements for Authentication and Authorization Policies and resources are provided
No <agentName> element or related elements are provided
Figure 10-5 illustrates CreatePolicyRequest.xml.
See Also:
"About <rregApplicationDomain> Elements"Many of the same parameters are found in the CreatePolicyRequest.xml file and the full agent registration XML files discussed earlier. The CreatePolicyRequest.xml file provides elements for Authentication and Authorization Policies and resources (and no <agentName> element).
Figure 10-6 illustrates the UpdatePolicyRequest.xml, which is nearly identical to CreatePolicyRequest.xml.
The UpdatePolicyRequest.xml provides the same elements as the CreatePolicyRequest.xml, with the exception of the <protectedAuthnScheme
> element. Using UpdatePolicyRequest.xml, Administrators can:
Update a Host Identifier add multiple hostPortVariations
(host port pairs)
Update an Application Domain
Add multiple protected, public, and excluded resources.Resources can be with or without query strings, both are supported.
Update default authentication and authorization policies for the resources that do not require customized policies
Create customized policies that include:
Policy display name
Policy description
Authentication scheme (Authentication policies only)A subset of resources to be associated with the policy
This section describes the unique remote management elements for Application Domains shown in Figure 10-7. These are found in the CreatePolicyRequest.xml and UpdatePolicyRequest.xml files and described in Table 10-10.
Figure 10-7 Remote Management Elements for Application Domains
See Also:
Table 10-6, "Elements Common to Full Remote Registration Requests" for a description of elements common to remote registration and remote management.Table 10-10 <rregApplicationDomain> Remote Management Template Elements
Element | Description | Example |
---|---|---|
<rregAuthenticationPolicies> <rregAuthenticationPolicy> |
Specifies the name and description for the Authentication Policy (to use when creating it anew or updating an existing policy). |
<rregAuthenticationPolicies> <rregAuthenticationPolicy> <name>AuthenticationPolicy1</name> <description>Authentication policy created using policyUpdate mode of rreg tool</description> . . </rregAuthenticationPolicy> </rregAuthenticationPolicies> |
<authnSchemeName> |
Specifies the Authentication Scheme to use in the Authentication Policy. |
<rregAuthenticationPolicies> . . authnSchemeName>LDAPScheme </authnSchemeName> . . </rregAuthenticationPolicy> </rregAuthenticationPolicies> |
<uriList> |
Identifies a resource that requires authentication using the Authentication Policy. |
<rregAuthenticationPolicies> . . <uriList> - <uriResource> <uri>/res1</uri> <queryString /> </uriResource> </uriList> . . </rregAuthenticationPolicy> </rregAuthenticationPolicies> |
<rregAuthorizationPolicies> <rregAuthorizationPolicy> |
Specifies the name and description for the Authorization Policy (to use when creating it anew or updating an existing policy). |
<rregAuthorizationPolicies> <rregAuthorizationPolicy> <name>AuthorizationPolicy1</name> <description>Authorization policy created using policyUpdate mode of rreg tool</description> . . </rregAuthorizationPolicy> </rregAuthorizationPolicies> |
<uriList> |
Identifies a resource that requires Authorization using the Authorization Policy. |
<rregAuthorizationPolicies> . . <uriList> - <uriResource> <uri>/res1</uri> <queryString /> </uriResource> </uriList> . . </rregAuthorizationPolicy> </rregAuthorizationPolicies> |
This section provides the following topics:
Prerequisites
Review About Remote Agent Management Modes
To remotely update an Agent registration
Set up the registration tool as described in, "Acquiring and Setting Up the Registration Tool".
Create your update request using one of these templates:
On the computer hosting the Agent, run the following command with agentUpdate
mode specify your own *Request*.xml as the input file. For example:
./bin/oamreg.sh agentUpdate input/*UpdateAgentRequest.xml
Provide the registration Administrator user name and password when asked.
Read the messages on-screen to confirm:
Success: On-screen message confirms
agentUpdate 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 an OAM Agent registration:
Copy ObAccessClient.xml to the OAM Agent host computer to manually update the Webgate configuration.
10g Webgate/Access Client: $WG_install_dir/oblix/lib/ObAccessClient.xml
11g Webgate/Access Client: $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.
Prerequisites
Review About Remote Agent Management Modes
To remotely validate an Agent registration
Set up the registration tool as described in, "Acquiring and Setting Up the Registration Tool".
On the computer hosting the Agent, run the following command in agentValidate
mode. For example:
./bin/oamreg.sh agentValidate agentname
Provide the registration Administrator user name and password when asked.
Read the messages on-screen to confirm:
Success: On-screen message confirms
AgentValidation 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/
Prerequisites
Review About Remote Agent Management Modes
To remotely remove an Agent registration
Set up the registration tool as described in, "Acquiring and Setting Up the Registration Tool".
On the computer hosting the Agent, run the following command in agentDelete
mode. For example:
./bin/oamreg.sh agentDelete agentname
Provide the registration Administrator user name and password when asked.
Read the messages on-screen to confirm:
Success: On-screen message confirms
AgentDelete process completed successfully
!
Prerequisites
Review About Remote Application Domain Management Modes
To create or update an application domain without an Agent
Set up the registration tool as described in, "Acquiring and Setting Up the Registration Tool".
Create your policy update request using one of these templates:
Create Policy Request File
Update Policy Request File
On the computer hosting the Agent, run the following command with agentUpdate
mode specify your own *Request*.xml as the input file. For example:
Create:
./bin/oamreg.sh policyCreate input/CreatePolicyRequest.xml
Update:
./bin/oamreg.sh policyUpdate input/UpdatePolicyRequest.xml
Provide the registration Administrator user name and password when asked.
Read the messages on-screen to confirm:
Success: On-screen message confirms
agentUpdate 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/