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

10.1 Prerequisites

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 28 for information about registering and using 10g Webgates with Oracle Access Manager 11g

10.2 Introduction to Remote Partner Registration

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

10.2.1 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 Administrators in the Default System User Identity Store registered with Oracle Access Manager.

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

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

10.2.3 About Key Use, Generation, Provisioning, and Storage

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.

Figure 10-1 Key Generation

Key Generation
Description of "Figure 10-1 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.

10.2.4 About the Remote Registration Tool

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"


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

"Managing Agents Remotely"


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
  • 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/Access Client: 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/Access Client: 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/Access Client: 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/Access Client: 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/


10.2.5 About Remote Registration Request Files

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

10.2.5.1 OSSO Remote Registration Request

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>

10.2.5.2 Short, Simplified OAM Remote Registration Requests

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

10.2.5.3 Common Elements of Remote Registration Requests

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:

  • If the Agent Name exists, no error occurs and the registration does not fail. Instead, Oracle Access Manager creates the policies if they are not already in place.

  • If the host identifier exists, the unique Agent Base URL is added to the existing host identifier and registration proceeds.

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

10.2.5.4 OSSO-Specific Elements in a Remote Registration Request

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>

10.2.5.5 Full OAM Remote Registration Requests

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

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

  • 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 patch set.

  • v1.4: This is supported by OSSO 10g prior to OSSO 10.1.4.3 patch set. 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 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):

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


<allowManagementOperations>

This Agent Privilege function enables the provisioning of session operations per agent, as follows:

  • Terminate session

  • Enumerate sessions

  • Add or Update attributes for an existing session

  • List all attributes for a given session ID or read session

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>


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


<ipValidationExceptions>

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.

  • 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 16 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 16 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 16 for steps to configure logout for OAM 11g Webgates.

<logoutTargetUrlParamName>end_url
</logoutTargetUrlParamName>

User-Defined Parameter Names

Descriptions

  • Available for configuration in the remote registration request files only

  • Each parameter can have only one value.

  • User-defined parameters cannot be set using the Oracle Access Manager Console

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 30 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, 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>


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

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>


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

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

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.


To acquire the tool and update the script with your environment variables

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

    ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz 
    
  2. Untar RREG.tar.gz file, which creates directories beneath /client containing the required tool and templates.

  3. In the oamreg script (.../rreg/client/rreg/bin) set environment variables as follows:

    1. Set JAVA_HOME to JDK 1.6 (Table 10-7).

    2. Set OAM_REG_HOME to the exploded_dir_for_RREG.tar/rreg based on your environment (client side or server side Table 10-7).

  4. Proceed with "Creating the Registration Request".

10.4 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

  1. Locate the required *Request*.xml input file for the agent you want to register (Table 10-1).

    ORACLE_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 10-4 and Table 10-6):

  4. Proceed with:

10.5 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 Oracle Access Manager Console to register the Agent and add an Application domain, as described in Chapter 9 and Chapter 14, 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:

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


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

10.6 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/Access Client: $WG_install_dir/oblix/lib/ObAccessClient.xml

      11g Webgate/Access Client: $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".

10.7 Validating Remote Registration and Resource Protection

This section provides the following topics:

10.7.1 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 Oracle Access Manager Console. Out-of-band Administrators must test authentication and access remotely.

To validate agent and application registration

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

  2. Shared Components, Host identifier: Confirm that the host identifier is defined in the Oracle Access Manager 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".

10.7.2 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.example.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 Oracle Access Manager 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.

  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.

10.8 Introducing Remote Management Modes

This section provides the following topics:

10.8.1 About Remote Agent Management Modes

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:

10.8.1.1 OSSOUpdateAgentRequest.xml

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 values

10.8.1.2 OAM11GUpdateAgentRequest.xml

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

10.8.1.3 OAMUpdateAgentRequest.xml

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

10.8.2 About Remote Application Domain Management Modes

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:

  • Create an application domain

  • Create default protected, public, and excluded resource

  • Create host Port variations list

  • Create policies

  • Create resources with query string

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:

  • Update an application domain

  • Update default protected, public, and excluded resource

  • Update host Port variations list

  • Update policies

  • Update resources with query string

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

  • At least one protected URI is required

  • Only one product family is allowed per file

  • Comments begin with '#'

  • Keyword 'public_uris': list public URIs on separate lines after this key word.

  • Keyword 'protected_uris': list URIs to be protected on separate lines after this key word

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:

10.8.2.1 About the Create Policy Request File

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

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

10.8.2.2 About the Update Policy Request File

The UpdatePolicyRequest.xml 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

10.8.2.3 About <rregApplicationDomain> Elements

This section describes the unique remote management elements for Application Domains. These are found in the CreatePolicyRequest.xml and UpdatePolicyRequest.xml files as described in Table 10-10.

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>

10.9 Managing Agents Remotely

This section provides the following topics:

10.9.1 Performing Remote Agent Updates

Prerequisites

Review About Remote Agent Management Modes

To remotely update an Agent registration

  1. Set up the registration tool as described in, "Acquiring and Setting Up the Registration Tool".

  2. Create your update request using one of these templates:

  3. 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
    
  4. Provide the registration Administrator user name and password when asked.

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

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

  7. Finalize Agent Registration: Perform the following steps to finalize an OAM Agent registration:

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


      $WebTier_Middleware_Home/Oracle_WT1/instances/instance1/

      config/OHS/ohs1/webgate/config

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

10.9.2 Performing Remote Agent Validation

Prerequisites

Review About Remote Agent Management Modes

To remotely validate an Agent registration

  1. Set up the registration tool as described in, "Acquiring and Setting Up the Registration Tool".

  2. On the computer hosting the Agent, run the following command in agentValidate mode. For example:

    ./bin/oamreg.sh agentValidate agentname
    
  3. Provide the registration Administrator user name and password when asked.

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

10.9.3 Performing Remote Agent Removal

Prerequisites

Review About Remote Agent Management Modes

To remotely remove an Agent registration

  1. Set up the registration tool as described in, "Acquiring and Setting Up the Registration Tool".

  2. On the computer hosting the Agent, run the following command in agentDelete mode. For example:

    ./bin/oamreg.sh agentDelete agentname
    
  3. Provide the registration Administrator user name and password when asked.

  4. Read the messages on-screen to confirm:

    • Success: On-screen message confirms

      AgentDelete process completed successfully!

10.10 Creating or Updating an Application Domain Without an Agent

Prerequisites

Review About Remote Application Domain Management Modes

To create or update an application domain without an Agent

  1. Set up the registration tool as described in, "Acquiring and Setting Up the Registration Tool".

  2. Create your policy update request using one of these templates:

    • Create Policy Request File

    • Update Policy Request File

  3. 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
    
  4. Provide the registration Administrator user name and password when asked.

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