6 Registering Partners (Agents and Applications) Remotely

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:

Prerequisites

Before you can perform tasks in this chapter, ensure that an OAM Administration Console and a managed OAM Server are running.

Introduction to Remote Partner Registration

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:

About In-Band Remote Registration

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

  1. Acquire the Oracle Access Manager 11g Release 1 (11.1.1) registration tool as described in "Acquiring and Setting Up the Registration Tool".

  2. Update the input file with unique values for the agent and application domain as described in "Creating the Registration Request".

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

  4. Validate the configuration as described in "Validating Remote Registration and Resource Protection" in.

  5. Perform access checks to validate that the configuration is working, as described in "Validating Authentication, Resource Protection, and Access After Remote Registration".

About Out-of-Band 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)

  1. Out-of-band Administrator creates a starting request input file containing specific application and agent details and submits it to the in-band Administrator.

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

  3. 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.

  4. In-band Administrator validates the configuration as described in "Validating Remote Registration and Resource Protection".

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

About Key Use, Generation, Provisioning, and Storage

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.

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

Figure 6-1 Key Generation

Key Generation

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.

About the Remote Registration Tool

This topic provides an overview of the registration tool, requirements, usage, and results.

Location

<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

Requirements

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

Registration Administrators

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"

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.

See Also:

"About Out-of-Band Registration Responses"

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

  • The oam-config.xml file contains an entry for the newly registered agent based on the <agentName> tag in the *Request.xml file.

  • The oam-policy.xml file on the server includes the following new entries:

    An application domain to protect resources created and named after the Agent based on the <agentName> tag in the *Request.xml file.

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:

  • osso.conf, modified for the OSSO Agent

  • 11g WebGate: cwallet.sso

  • OAM Agents: ObAccessClient.xml, modified for the OAM WebGate

    The appropriate native configuration output file created during registration must be copied to the agent-installed location:

    11g WebGate: Copy ObAccessClient.xml (and cwallet.sso) to WebGate_instance_dir/webgate/config (for example, WebTier_Middleware_Home/Oracle_WT1/instances/instance1/config/OHS/ohs1/webgate /config)

    10g WebGate: Copy ObAccessClient.xml to WebGate_install_dir/webgate/config

    For mod_osso, copy osso.conf file to OHS_webserver_install_dir/oracle/product/11.1.1/as_1/instances/instance1/config/OHS/ohs1/ osso/

  • OAM Agents: Password.xml file and certificate files for Simple or Cert mode are also generated and must be copied.
 

outofband Client-Side Results: Depending on the input file you use (starting request or a generated agentName_Response.xml file) the following results occur:

  • input/starting_Request.xml: Created by the out-of-band administrator and used by the in-band administrator to generate a response file (agentName_Response.xml) based on the <agentName> tag. The response file is sent to the out-of-band administrator using any method.

  • input/agentName_Response.xml: Sent to the out-of-band administrator and used to create the agent's native configuration file in a directory based on the <agentName> tag in the response file. For example:

    osso.conf, modified for the OSSO Agent

    cwallet.sso for 11g WebGate

    ObAccessClient.xml, modified for the OAM Agent (WebGate)

    The appropriate native configuration output file created during registration must be copied to the agent-installed location:

    11g WebGate: Copy ObAccessClient.xml to WebGate_instance_dir/webgate/config (for example, WebTier_Middleware_Home/Oracle_WT1/instances/instance1/config/OHS/ohs1/webgate/config)

    10g WebGate: Copy ObAccessClient.xml to WebGate_install_dir/webgate/config

    For mod_osso, copy osso.conf file to OHS_webserver_dir/oracle/product /11.1.1/as_1/instances/instance1/config/OHS/ohs1/osso/

See Also:

About Remote Registration Requests

This topic describes the registration request files that are available for use with the registration tool, and the elements that are common between them:

OSSO Remote Registration Request

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.

See Also:

"Common Elements of Remote Registration Requests"

Example 6-1 OSSORequest.xml

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

Short, Simplified OAM Remote Registration Requests

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>

Common Elements of Remote Registration Requests

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>

OSSO-Specific Elements in a Remote Registration Request

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>

Full OAM Remote Registration Requests

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:

  • URLs—The URL cache maintains information about a URL, including if it is protected and the authentication scheme used if it is protected.

  • Authentication schemes—This cache stores authentication scheme information for a specific authentication scheme ID.

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:

  • v3.0: Most secure token using AES encryption standard for encrypting tokens exchanged between OAM 11g server and mod_osso. This is the default value. This was supported by OSSO 10.1.4.3 patchset.

  • v1.4: This is supported by OSSO 10g prior to OSSO 10.1.4.3 patchset. Uses DES encryption standard.

  • v1.2: This used to be version of tokens exchanged between OSSO partners prior to OSSO 10.1.4.0.1. Uses DES.

 
<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):

  • Open--No transport security

  • Simple--SSL v3/TLS v1.0 secure transport using dynamically generated session keys

  • Cert--SSL v3/TLS v1.0 secure transport using server side x.509 certificates

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>

<ipValidation>

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.

  • If there is a match, the WebGate logout handler is triggered.

  • If Logout URL is not configured the request URL is checked for "logout." and, if found (except "logout.gif" and "logout.jpg"), also triggers the logout handler

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 MaxSessionTime parameter to be interpreted as a number of minutes instead of the default (hours).

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 maxSessionTimeUnits. The effect of lowering Maximum Client Session Time does increase the frequency with which access clients close and re-open connections to the OAM Server, which increases network traffic. Therefore, the maxSessionTimeUnits value should be as high as possible within the limits of the firewall settings.

Default: hours

Possible values: minutes

 
<name>maxSessionTimeUnits</name>
<value>hours</value>

RetainDownstreamPostData

Adding this user-defined parameter and setting the value to true resolves a problem that occurs when WebGate for Apache 2.0 or Apache 2.2 prevents POST data from being read by downstream applications. Form-based authentication schemes using the "passthrough" challenge-parameter and policies using the "Query String Variable(s)" option are affected.

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:

  • The default value of leastComponentIdleTimeout instructs the WebGate to use the "most restrictive" timeout value for idle session timeout enforcement.

  • A value of currentComponentIdleTimeout instructs the WebGates to use the "current WebGate" timeout value for idle session timeout enforcement.

 
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: ContentLengthFor401Response 0.

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 1.0.

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:

  • To achieve Pass-through functionality

  • For form login (if form login action is other than /access/oblix/apps/webgate/bin/webgate.dll)

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>

About Out-of-Band Registration Responses

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.

Acquiring and Setting Up the Registration Tool

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

  1. Locate RREG.tar.gz file in the following path:

    WLS_home/Middleware/domain_home/oam/server/rreg/client/RREG.tar.gz

  2. Untar RREG.tar.gz file.

  3. In the oamreg script, in rreg/bin/oamreg, set the JAVA_HOME environmental variable to JDK 1.6 (Table 6-7).

  4. 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).

  5. Proceed with "Creating the Registration Request".

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.

See Also:

To create the registration request

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

  2. Copy the request file to a new name. For example:


    From: OAMRequest.xml
    To: myagent_request.xml

  3. In the Request file, modify information to reflect details for this agent and the resources to protect (Table 6-4 and Table 6-6):

  4. Proceed with:

Performing In-Band Remote Registration

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

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

  2. Provide the registration Administrator user name and password when asked.

  3. 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/

  4. 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.

  5. Finalize Agent Registration: Perform the following steps to finalize this agent registration:

    See Also:

    Chapter 17, "Managing OAM 10g WebGates with OAM 11g".

    1. 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:


      $WebTier_Middleware_Home/Oracle_WT1/instances/instance1/

      config/OHS/ohs1/webgate/config

    2. Restart the Managed Server that is hosting the OAM Agent.

  6. Proceed with "Validating Remote Registration and Resource Protection".

Performing Out-of-Band Remote Registration

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

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

  2. In-Band Administrator:

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

    2. Provide the Registration Administrator user name and password when asked.

    3. 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/

    4. Return the agentName_Response.xml file to the out-of-band Administrator along with any other artifacts. For example:

      agentName_Response.xml

  3. Out-of-Band Administrator: Updates the environment, as follows.

    1. 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/.

    2. 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:


      $WebTier_Middleware_Home/Oracle_WT1/instances/instance1/

      config/OHS/ohs1/webgate/config

    3. Restart the Web Server that is hosting the OAM Agent.

    4. Proceed with "Validating Remote Registration and Resource Protection".

Validating Remote Registration and Resource Protection

This section provides the following topics:

Validating Remote Registration

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

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

  2. Shared Components, Host identifier: Confirm that the host identifier is defined in the OAM Administration Console.

  3. Application Domain: Under the Policy Configuration tab, confirm there is a new default application domain, which is named after the registered Agent.

  4. Resources in the application domain are associated with the host identifier.

  5. Proceed with "Validating Authentication, Resource Protection, and Access After Remote Registration".

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

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

  2. On the Log In page, enter a valid username and password when asked, and click Login.

  3. 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

  4. 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.

  5. 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).

  6. Request Cancellation: Perform a partial log in and click Cancel to confirm that the resource is not accessed.

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

  8. 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.

  9. Various URL Patterns: Verify authentication for various URL patterns as you perform steps 1 through 5.

  10. 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.

    See Also:

    Chapter 9, "Managing Policies to Protect Resources and Enable SSO"

  11. 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.

  12. 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.