Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service
11g Release 1 (11.1.1)

Part Number E15478-07
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

9 Registering Partners (Agents and Applications) by Using the Console

Only a registered policy enforcement agent can communicate with OAM 11g authentication and authorization services. Administrator must register the agent that resides on the computer hosting the partner application to be protected. A partner application is one that delegates the authentication function to the SSO provider (Oracle Access Manager 11g) to spare users from re-authenticating when accessing multiple resources.

This chapter focuses on using the Oracle Access Manager Console to perform agent registration and management. This chapter includes the following topics:

Note:

To use the command-line to register a partner, see Chapter 10.

9.1 Prerequisites

Before you can perform tasks in this chapter ensure that the Oracle Access Manager Console and a managed OAM Server are running.

Following are the knowledge-based requirements for tasks in this chapter.

9.2 Introduction to Policy Enforcement Agents

This section provides information about access clients, known as policy-enforcement agents, and the registration process that is required to set up the trust mechanism between the agent and Oracle Access Manager 11g SSO.

9.2.1 About Policy-Enforcement Agents

With Oracle Access Manager 11g, each policy enforcement Agent acts as a filter for HTTP requests. Your deployment can include the following agents in any combination:

  • OAM Agents:

    • OAM 11g Webgates

    • OAM 10g Webgates

    • Programmatic Access Clients

  • OSSO Agents: mod_osso is part of the (still ) OracleAS 10g single sign-on (OSSO) solution that authenticates users at a central OSSO Server.

    After registering 10g mod_osso as an agent, OAM 11g gives mod_osso the redirect URL for the user based on the authentication scheme associated with the OAM policy defined for the resource.

    Note:

    The mod_osso module is an Oracle HTTP Server module that provides authentication to OracleAS applications.

Unless explicitly stated, details about OAM Agents apply equally to Webgates and Access Clients:

  • Webgate is out of an box access client. This Web server access client intercepts HTTP requests for Web resources and forwards these to the OAM 11g Server. Webgates for various Web servers are shipped with Oracle Access Manager.

  • Custom access clients created for use with non-Web applications must be specifically developed using the Software Developer Kit (SDK), either by you or by Oracle. An Access Client processes requests for Web and non-Web resources (non-HTTP) from users or applications.

Table 9-1 provides information about all agents for OAM 11g.

Table 9-1 Agents for OAM 11g

Agents Description

OSSO Agent (mod_osso 10g)

Following registration with OAM 11g, the mod_osso module:

  • Checks for an existing valid Oracle HTTP Server cookie

  • Redirects to the OAM Server if needed to contact the directory during authentication

  • Decrypts the encrypted user identity populated by the OSSO server

  • Sets the headers with user attributes

11g Webgates

After installation and registration with OAM 11g, 11g Webgates communicate with Oracle Access Manager 11g services using the OAM Proxy to "sanitize" the request and respond identically for all agents.

You can also register 11g Access Clients (Those created with the OAM 11g Access SDK).

10g Webgates

After installation and registration, OAM 10g Webgates directly communicate with Oracle Access Manager 11g services through a JAVA-based OAM proxy that acts as a bridge. OAM 10g Webgates include:

  • Freshly installed 10g Webgates for OAM 11g can support Web servers other than Oracle HTTP Server as described in Chapter 28.

  • Legacy 10g Webgates currently operating with OAM 10g and combined with OSSO as described in the 10g Oracle Access Manager Integration Guide.

  • Legacy 10g Webgates configured as the Identity Assertion Provider (IAP) for SSO (for applications using WebLogic container-based security with OAM 10g, as described in the Oracle Fusion Middleware Application Security Guide).

  • Legacy 10g Webgates currently operating with Web Applications coded for Oracle ADF Security and the OPSS SSO Framework as described in Appendix C.

  • Legacy 10g Java AccessGates.

See Also IAMSuiteAgent in this table.

Access Clients

Only authentication and authorization is (not policy modification) for Access Clients.

IAMSuiteAgent

The IAM Suite Agent provides single sign-on functionality for the IAM suite of consoles. The IAM Suite Agent and companion application domain (IAMSuite) replaces the earlier IDM Domain Agent and its companion application domain.

See Also: "About the Pre-Registered IAMSuiteAgent".


Table 9-2 provides a comparison of the agent types that are compatible with OAM 11g as well as the differences between OAM 11g and earlier agents (organized in columns).

See Also:

Table 9-2 Comparing Agent Types and Differences


OAM 11g OAM 10g OSSO 10g

Available SSO Agents

OAM Agents

  • 11g Webgate

  • 10g Webgate

  • IAMSuiteAgent

  • Programmatic Access Client

OSSO Agents

  • 10g mod_osso (partner)

Webgate and AccessGate

  • Resource Webgate (RWG)

  • Authentication Webgate (AWG)

With OAM 10g, Webgate installation included Web server configuration.

  • mod_osso

Remote Registration Tool

Use oamreg tool to register OAM 10g and 11g Agents with OAM 11g.

<OAM_HOME>/oam/server/rreg/ client/rreg/bin/oamreg

No equivalent for OAM 10g.

Use oamreg tool to register OSSO Agents with OAM 11g

Note: No remote registration equivalent before OAM 11g.

Login Forms

/oam/pages/css/login_page.css

No login forms provided and used with a 10g Webgate are relevant for OAM 11g.

unchanged

logout.html

See Chapter 16 for details about configuring logout for 10g and 11g Agents

logout.html requires specific details when using a 10g Webgate with OAM 11g. See Chapter 16.

There is no change required for OAM 11g with mod_osso (OSSO Agents).

Applications that use dynamic directives require no entry in mod_osso.conf. Instead, protection is written into the application as one or more dynamic directives.

Multiple network domain support

OAM 11g supports cross-network-domain single sign-on out of the box.

Oracle recommends you use Oracle Identity Federation for this situation.

OAM provides a proprietary multiple network domain SSO capability that predates Oracle Identity Federation. If this is implemented in your OAM 10g deployment, you can register OAM 10g Agents with OAM 11g to continue this support.

 

Cryptographic keys

Notes: The protocols used to secure information exchange on the Internet.

  • One per-agent secret key shared between 11g Webgate and OAM Server

  • One OAM Server key

Note: One key is generated and used per registered mod_osso or 11g Webgate. However, one single key is generated for all 10g Webgates.

There is just one global shared secret key per OAM deployment which is used by all the Webgates

  • One key per partner shared between mod_osso and OSSO server

  • OSSO server's own key

  • One global key per OSSO setup for the GITO domain cookie

Keys storage

  • Agent side: A per agent key is stored locally in the Oracle Secret Store in a wallet file

  • OAM 11g server side: A per agent key, and server key, are stored in the credential store on the server side

Global shared secret stored in the directory server only (not accessible to Webgate)

  • mod_osso side: partner keys and GITO global key stored locally in obfuscated configuration file

  • OSSO server side: partner keys, GITO global key, and server key are all stored in the directory server


Administrators can use either the Oracle Access Manager Console or the remote registration tool to:

  • Register a freshly installed OAM 11g Webgate

  • Provision a legacy (or freshly installed) OAM 10 Webgate for use with OAM 11g, as described in Chapter 28.

  • Register an OSSO 10g Agent (mod_osso)

  • Note:

    You can upgrade OracleAS 10g SSO, as described in the Oracle Fusion Middleware Upgrade Guide for Oracle Identity Management. During the upgrade, OSSO agents are registered with OAM 11g. See Appendix A, "Co-existence Overview: OAM 11g and OSSO 10g".

9.2.2 About the Pre-Registered IAMSuiteAgent

This agent, and the companion application domain, described in Chapter 14, are available with the patch set release. Oracle strongly recommends that you do not alter these definitions.

Note:

The original IDMDomainAgent is not available with this patch set. It remains as an artifact after you apply the patch set. However, all content is removed.

The IAMSuiteAgent provides single sign-on functionality for the IDM Administration Console. The IAMSuiteAgent is installed and pre-configured as part of the Oracle Access Manager 11g Server installation and configuration.

The IAMSuiteAgent is a domain-wide agent:

  • Once deployed, the IAMSuiteAgent is installed on every server in the domain

  • Unless disabled, every request coming into the WebLogic Application Server is evaluated and processed by the IAMSuiteAgent

  • Configuration details are located under the 10g Webgates node (Policy Configuration tab) in the Oracle Access Manager Console

Certain IAMSuiteAgent configuration elements are available in the WebLogic Administration Console (in the Security Provider section) and others in the Oracle Access Manager Console.

WebLogic Administration Console, Security Provider Settings

In the Security Provider section of the WebLogic Administration Console are five bootstrap configuration parameters.

While Oracle recommends that you retain these without making changes, there are circumstances where you might need to change one of the following parameters:

  • Primary OAM Server: You can replace this value with information for your actual OAM Server. The default value (localhost:5575) can be replaced with information for your actual OAM Server if more than one host is part of the IDM Domain.Agent Password: By default there is no password. However, you can add one here if you want to establish a password for the IAMSuiteAgent connection to the OAM Server through the NetPoint (now Oracle) Access Protocol (NAP or OAP).

Figure 9-1 illustrates the default Security Provider settings for the IAMSuiteAgent.

Figure 9-1 IAMSuiteAgent Configuration in the WebLogic Administration Console

IAMSuiteAgent Configuration, WebLogic Console
Description of "Figure 9-1 IAMSuiteAgent Configuration in the WebLogic Administration Console"

Oracle Access Manager Console, IAMSuiteAgent Registration

The IAMSuiteAgent registration page provides details about the agent, like all other OAM agent registration pages.

  • Security Mode: Open is the only security mode available for the IAMSuiteAgent. This cannot be changed.

  • Preferred Host: IAMSuiteAgent is the pre-configured host required by this agent

Note:

The Access Client Password here must match the Agent Password in the WebLogic Administration Console. If you changed the Agent Password, you must also change the Access Client Password.

Figure 9-2 shows the IAMSuiteAgent page. Notice the User Defined Parameter, which informs behavior to fall back to the container policy in the WebLogic Server and provides a redirect URL for logout.

Figure 9-2 IAMSuiteAgent Characteristics

IAMSuiteAgent Characteristics
Description of "Figure 9-2 IAMSuiteAgent Characteristics"

Table 9-3 outlines the differences between IAMSuiteAgent and 11g and 10g Webgates. All elements are described in Table 9-5, "Expanded OAM 11g and 10g Webgate Elements and Defaults".

Table 9-3 Comparing IAMSuiteAgent and 11g and 10g Webgates

Element 11g Webgate 10g Webgate IAMSuiteAgent

Primary Cookie Domain

N/A

x

x

Token Validity Period

x

N/A

N/A

Preferred Host

x

x

x

Logout URL

x

x

x

Logout Callback URL

x

N/A

N/A

Logout Redirect URL

x

N/A

N/A

Logout Target URL

x

N/A

N/A

Cache Pragma Header

Cache Control Header

x

x

x

x

x

x

User Defined Parameters

proxySSLHeaderVar=IS_SSL
URLInUTF8Format=true
client_request_retry_attempts=1
inactiveReconfigPeriod=10
proxySSLHeaderVar=IS_SSL
URLInUTF8Format=true

client_request_retry_attempts=1
inactiveReconfigPeriod=10
fallbackToContainerPolicy=true
logoutRedirectUrl=http://hostname.domain.com:14100/oam/server/logout
protectWebXmlSecuredPagesOnly=true

Deny on Not Protected

x

x

x


Figure 9-3 illustrates the resources protected by the IAMSuiteAgent, including the exact Authentication and Authorization policies. Oracle recommends that you do not make any additions or changes. The WebLogic Administration Console (/console) is protected.

Figure 9-3 Resources Protected by the IAMSuiteAgent

IAMSuiteAgent Protected Resources
Description of "Figure 9-3 Resources Protected by the IAMSuiteAgent"

You can replace this agent with a 10g Webgate, as described in Chapter 28, "Managing OAM 10g Webgates with OAM 11g".

9.2.3 About Registering Partners (Agents and Applications)

Only registered policy enforcement agents can communicate with an OAM Server, and process information when a user attempts to access a protected resource.

Administrators must register the OAM Agent or OSSO Agent that resides on the computer hosting the application to be protected. Agent registration can include partner registration by automatically creating an application domain and default policies.

Following registration, agent details appear in the Oracle Access Manager Console and are propagated to all Managed Servers in the cluster. If you choose to automatically create policies during agent registration, you can also view and manage the application domain and policies that were registered with the partner application.

Note:

Registering an Agent is also known as "registering a partner application" or "registering a partner application with OAM".

During registration, the Agent is presumed to be on the same Web server as the application it is protecting. However, the Agent can be on a proxy Web server and the application can be on a different host.

During Agent registration:

  • One key is generated per agent, accessible to the Webgate through a local wallet file on the client host, and to OAM Server through the Java Keystore on the server side.

    The Agent specific key must be accessible to Webgates through a secure local storage on the client machine. See Table 9-2.

  • A key is generated for the partner (application) during registration. (except for 10g Webgates).

  • An OAM application domain is created, named after the Agent, and populated with default authentication and authorization policies. The new application domain uses the same host identifier that was specified for the Agent during registration. For more information on application domains, see Chapter 14.

After registration, the agent can monitor attempts to access a Web site and use OAM Servers to provide authentication and authorization services before completing the request. Administrators can view, modify, or remove a registered agent using either the Oracle Access Manager Console or custom WLST commands for OAM 11g.

For more information, see:

9.2.4 About File System Changes and Artifacts for Registered Agents

When you register an agent using the Oracle Access Manager Console, a new file system directory is created for the Agent on the Oracle Access Manager Console host:

<MW_HOME>/user_projects/domains/<domain_name>/output/<agent_name>

This new directory includes generated files for the registered agent that must be copied in to the agent's installation directory.

11g Webgate/Access Client: Copy generated files 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 generated files to Webgate_install_dir/access/oblix/lib

mod_osso: Copy generated files to OHS_webserver_dir/oracle/product /11.1.1/as_1/instances/instance1/config/OHS/ohs1/osso/

Generated files include the following:

  • ObAccessClient.xml (for Webgates)

    The pre-registered IAMSuiteAgent does not use ObAccessClient.xml for bootstrap or configuration.

    With OAM 10g, ObAccessClient.xml was generated on the agent side when the configureWebgate tool was run. You can use the Oracle Access Manager Console or the remote registration tool to create ObAccessClient.xml.

  • cwallet.sso (for 11g Webgates, regardless of the transport security mode)

  • certificate and password files for secure communication, if needed. For example, password.xml file or aaa_cert.pem and aaa_key.pem files.

    Note:

    When editing an 11g Webgate registration, password.xml is updated only when the mode is changed from Open to Cert or Simple to Cert. In cert mode, once generated, password.xml cannot be updated. Editing the agent Key Password does not result in creation of a new password.xml.

  • osso.conf file (for OSSO Agents)

Before Webgate startup, copy the ObAccessClient file from the generated location to the Webgate installation directory on the computer hosting the Webgate instance.

During Webgate run time, the ObAccessClient file is updated automatically when a change is discovered during periodic update checks.

Simple Mode Global passphrase stored in a nominally encrypted file: password.xml

Cert Mode:

  • PEM keystore Alias

  • PEM keystore Alias Password

9.3 Registering and Managing OAM Agents Using the Console

This section describes how to manage OAM Agents using the Oracle Access Manager Console. Topics include:

9.3.1 About Creating and Editing Webgate Registration

The Create OAM nng Webgate page requests minimal information to streamline registration. Required details are identified by the asterisk (*). Compare the 11g Webgate page in Figure 9-4 with the Create OAM 10g Webgate page in Figure 9-5.

Figure 9-4 Create OAM 11g Webgate Page

Create OAM Agent Page
Description of "Figure 9-4 Create OAM 11g Webgate Page"

Whether you register an OAM 11g Webgate or 10g Webgate, the initial information requested is nearly the same, as shown in Figure 9-5.

Figure 9-5 Create OAM 10g Webgate Page

Create OAM 10g Webgate Page
Description of "Figure 9-5 Create OAM 10g Webgate Page"

Table 9-4 describes the Create page for 10g and 11g Webgates.

Table 9-4 Create Pages for OAM 10g and 11g Webgates

OAM Agent Element Description

Name

The unique identifying name for this Agent registration. This is often the name of the computer that is hosting the Web server used by Webgate.

A unique identifying name for each Agent registration is preferred. However:

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

Base URL

Optional

The host and port of the computer on which the Web server for the Webgate is installed. For example, http://my_host:port or https://my_host:port. The port number is optional.

Note: A particular Base URL can be registered once only. There is a one-to-one mapping from this Base URL to the Web server domain on which the Webgate is installed (as specified with the <hostidentifier> element). However, one domain can have multiple Base URLs.

Access Client Password

Optional

An optional, unique password for this Webgate, which can be assigned during this registration process.

When a registered Webgate connects to an OAM 11g Server, the password is used for authentication to prevent unauthorized Webgates from connecting to OAM 11g Servers and obtaining policy information.

Security

Level of communication transport security between the Agent and the OAM Server (this must match the level specified for the OAM Server):

  • 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. Choosing this option displays a field where you can enter the Agent Key Password.

    Agent Key Password: The private key file (aaa_key.pem) is encrypted using DES algorithm. The Agent Key Password is saved in obfuscated format in password.xml and is required by the server to generate password.xml. However, this password is not retained by the server. When editing an 11g Webgate registration, password.xml is updated only when the mode is changed from Open to Cert or Simple to Cert. In Cert mode, once generated, password.xml cannot be updated. Editing the Agent Key Password does not result in creation of a new password.xml.

Note: For more information on Simple and Cert modes, and encrypting the private key using the DES algorithm, see Appendix E.

Host Identifier

This identifier represents the Web server host.

See Also: "About Virtual Web Hosting".

User-defined Parameters

Parameters you can enter to enable specific Webgate behaviors:

See Also: "About User-Defined Webgate Parameters".

Virtual Host

Check the box beside Virtual Host if you installed a Webgate on a Web server that contains multiple Web site and domain names. The Webgate must reside in a location that enables it to protect all of the Web sites on that server.

See Also: "About Virtual Web Hosting".

Auto Create Policies

During agent registration, you can have authentication and authorization policies created automatically. This option is checked (enabled) by default.

Default: Enabled

Note: If you already have a domain and policies registered, you can simply add new resources to it. If you clear this option (no check), no application domain or policies are generated automatically.

IP Validation

Check the box beside IP Validation to ensure a client's IP address is the same as the IP address stored in the ObSSOCookie generated for single sign-on. In the IP Validation Exceptions box, enter any IP addresses to exclude from validation using standard notation for the addresses: for example, 10.20.30.123.

When enabled, the IP address stored in the ObSSOCookie must match the client's IP address. Otherwise, the cookie is rejected and the user must reauthenticate.

Default: Disabled

See Also: "About IP Address Validation for Webgates".

Agent Key Password

Requested for only Cert mode communication, this passphrase is used to encrypt the private key used for SSL communication between Webgate and the OAM Server in Simple and Cert modes.

Note: The Agent Key Password has no relationship to the Access Client Password described earlier within this table.

Simple Mode: In this mode, the agent key password is a global passphrase that must be the same on both the client and server. Once the OAM Server has this configured, the password can be retrieved during agent registration. However, the administrator must copy to the client side, the password.xml file generated during agent registration.

Cert Mode: In this mode, the agent key can be different on the client and server; it is no longer global. Administrators must enter the Agent Key Password to enable generation of a password.xml file during agent registration, which must be copied to the agent side. For certificate generation, you must encrypt the private key (used for SSL) using this password through openssl or other third-party tools to be placed inside aaa_key.pem. At runtime, Webgate retrieves the key from password.xml, and uses it to decrypt the key in aaa_key.pem.

  • If the key is encrypted, Webgate internally invokes the call back function to obtain the password.

  • If the key is encrypted and password.xml does not exist, Webgate cannot establish connections with the OAM Server.

  • If the key is not encrypted, there is no attempt to read password.xml.

For more information, see Appendix E.

Resource Lists

 

Protected Resource (URI) List

URIs for the protected application: /myapp/login, for example. Each URI for the protected application should be specified in a new row of the table for the Protected Resource List.

Default: 2 resources are protected by default.


/.../*
/

The default matches any sequence of characters within zero or more intermediate levels spanning multiple directories.

See Also: "About the Resource URL".

Public Resource (URI) List

Each public application should be specified in a new row of the table for the Public Resource List.

Add a field and enter URI values for the public applications and resources. Each URI should be specified in a new row of the table for the Public Resource List.


To help streamline Webgate registration, additional elements are concealed and default values are applied. When you view or edit a Webgate registration page in the console, all elements and values are revealed, as shown in Figure 9-6. Most elements are the same as those you define when using the remote registration tool with the expanded OAM template, as described in Chapter 10.

Figure 9-6 Confirmation Window and Expanded 11g Webgate Page with Defaults

OAM Agent Page with Expanded Details
Description of "Figure 9-6 Confirmation Window and Expanded 11g Webgate Page with Defaults "

Figure 9-7 Expanded OAM 10g Webgate Registration Page

Expanded OAM 10g Webgate Page
Description of "Figure 9-7 Expanded OAM 10g Webgate Registration Page"

Table 9-5 summarizes elements on an expanded registration. Additional settings revealed here are used by the OAM Proxy. ObAccessClient.xml is populated with values after agent registration, whether you use the Oracle Access Manager Console as described here or the remote registration tool as described in Chapter 10.

Table 9-5 Expanded OAM 11g and 10g Webgate Elements and Defaults

OAM Agent Element Description

Name

Name of this Webgate registration.

Access Client Password

Optional, unique password for the OAM Agent. When the agent connects to an OAM Server, it uses the password to authenticate itself to the server. This prevents unauthorized agents from connecting and obtaining policy information.

Primary Cookie Domain

10g Webgate only.

This parameter describes the Web server domain on which the OAM 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.

State

Set only in the Oracle Access Manager Console.

Specifies whether the OAM Agent is enabled or disabled.

Default = Enabled

Max Cache Elements

Number of elements maintained in the cache. Caches are the following:

  • Resource to Authentication Scheme—This cache maintains information about Resources (URLs), including whether it is protected and, if so, the authentication scheme used for protection.

  • (11g Webgate only) Resource to Authorization Policy—This cache maintains information about Resources and associated authorization policy—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 these caches.

Default = 100000

Cache Timeout (seconds)

Amount of time cached information remains in the Webgate caches (Resource to Authentication Scheme, Authentication Schemes, and 11g Webgate only Resource to Authorization Policy) when the information is neither used nor referenced.

Default = 1800 (seconds)

User Defined Parameters

11g Webgate only

  • Max Authorization Results Cache Elements—Number of elements maintained in the Authorization Result Cache. This cache maintains information about authorization results for associated user sessions. For example:

    maxAuthorizationResultCacheElems=10000
    

    Default = 100000

  • Authorization Results Cache Timeout—Number of elements maintained in the Authorization Result Cache. This cache maintains information about authorization results for associated user sessions. For example:

    authorizationResultCacheTimeout=60
    

    Default, when not specified = 15 (seconds)

See Also: "About User-Defined Webgate Parameters" and "Tuning 10g and 11g Webgate Caches".

Token Validity Period

11g Webgate only

Maximum valid time period for an agent token (the content of OAMAuthnCookie for 11g Webgate).

Default = 3600 (seconds)

Note: For OAM 10g Webgates, use Cookie Session Time to set the Token Validity Period.

Max Connections

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

Max Session Time

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 = 24 (hours)

A value of 0 disables this timeout setting.

Failover Threshold

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.

AAA Timeout Threshold

Number (in seconds) to wait for a response from the OAM Server. If this parameter is set, it is used as an application TCP/IP timeout instead of the default TCP/IP timeout.

Default = -1 (default network TCP/IP timeout is used)

A typical value for this parameter is between 30 and 60 seconds. If set to a very low value, the socket connection can be closed before a reply from OAM Server is received, resulting in an error.

For example, suppose an OAM Agent is configured to talk to one primary OAM Server and one secondary OAM Server. If the network wire is pulled from the primary OAM Server, the OAM Agent waits for the TCP/IP timeout to learn that there is no connection to the primary OAM Server. The Webgate tries to reestablish the connections to available servers starting with the primary OAM Server. Again, the OAM Agent waits for the TCP/IP timeout to determine if a connection can be established. If it cannot, the next server in the list is tried. If a connection can be established to another OAM Server (either a primary or secondary), the requests are re-routed. However this can take longer than desired.

When finding new connections, OAM Agent checks the list of available servers in the order specified in its configuration. If there is only one primary OAM Server and one secondary OAM Server specified, and the connection to the primary OAM Server times out, the OAM Agent still tries the primary OAM Server first. As a result, the OAM Agent cannot send requests to an OAM Server for a period greater than twice the setting in the OAM Server Timeout Threshold.

If the OAM Server takes longer to service a request than the value of the timeout threshold, the 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. Also, other OAM Server may also take longer to process the request than the time specified on the threshold. In these cases, the OAM Agent can continue to retry the request until the OAM Server is shut down.

Idle Session Timeout

10g Webgates only

Default: 3600

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.

Preferred Host

Specifies how the hostname appears in all HTTP requests as users attempt to access the protected Web server. The hostname within the HTTP request is translated into the value entered into this field regardless of the way it was defined in a user's HTTP request.

The Preferred Host function prevents security holes that can be inadvertently created if a host's identifier is not included in the Host Identifiers list. However, it cannot be used with virtual Web hosting. For virtual hosting, you must use the Host Identifiers feature.

Defaults to Name (of Webgate registration)

Logout URL

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.

Default =

Note: This is the standard OAM 10g Webgate configuration parameter used to trigger initial logout.

See Also: Chapter 16 for additional steps required for configuring logout for OAM 10g Webgates registered with OAM 11g.

Additional Logout for 11g Webgate Only

For OAM 11g Webgate single sign-off behavior, specific logout elements and values automate the redirect to a central logout URL, callback URL, and end_URL. This replaces 10g Webgate single sign-off only through a customized local logout page.

Logout Callback URL

11g Webgate 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:

Default = /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.

When the request URL matches the Logout Callback URL, Webgate clear its cookies and streams an image .gif in the response. This is similar to OSSO agent behavior.

When Webgate redirects to the server logout page, it records an "end" URL as a query parameter (end_url=http://host:port/..."), which becomes the landing page that the OAM 11g Server redirects back to after logout.

Other OAM 11g services support the central logout page on the server. The end_url relies on the target URL query parameter passed from OPSS integrated applications.

Logout Redirect URL

11g Webgate only

This parameter is automatically populated after agent registration completes.By default, this is based on the OAM Server host name with a default port of 14200. For example:

Default = http://OAMServer_host:14200/oam/server/logout

The Logout URL triggers the logout handler, which removes the OAMAuthnCookie_<host:port>_<random number> and requires the user to re-authenticate the next time he accesses a resource protected by Oracle Access Manager.

See Also: Chapter 16, "Configuring Centralized Logout for 11g Webgate with OAM 11g Server"

Logout Target URL

11g Webgate only

The value is the name for the query parameter that the OPSS applications passes to Webgate during logout; the query parameter specifies the target URL of the landing page after logout completes.

Default: end_url

See Also: Chapter 16, "Configuring Centralized Logout for 11g Webgate with OAM 11g Server"

User-defined Parameters

Parameters you can enter to enable specific Webgate behaviors:

Defaults:

proxySSLHeaderVar=IS_SSL
URLInUTF8Format=true
client_request_retry_attempts=1
inactiveReconfigPeriod=10

See Also: "About User-Defined Webgate Parameters".

Sleep for

The frequency (in seconds) with which the OAM Server checks its connections to the directory server. For example, if you set a value of 60 seconds, the OAM Server checks its connections every 60 seconds from the time it comes up.

Default: 60 (seconds)

Cache Pragma Header

Cache Control Header

Webgate only (not Access Clients)

These settings apply only to Webgates and control the browser's cache.

By default, both parameters are set to no-cache. This prevents Webgate from caching data at the Web server application and the user's browser.

However, this may prevent certain operations such as downloading PDF files or saving report files when the site is protected by a Webgate.

You can set the Access Manager SDK caches that the Webgate uses to different levels. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html section 14.9 for details.

All of the cache-response-directives are allowed. For example, you may need to set both cache values to public to allow PDF files to be downloaded.

Defaults: no-cache

See Also: "Tuning 10g and 11g Webgate Caches".

IP Validation

Check the box beside IP Validation to ensure a client's IP address is the same as the IP address stored in the ObSSOCookie generated for single sign-on. In the IP Validation Exceptions box, enter any IP addresses to exclude from validation using standard notation for the addresses: for example, 10.20.30.123.

When enabled, the IP address stored in the ObSSOCookie must match the client's IP address. Otherwise, the cookie is rejected and the user must reauthenticate.

Default: Disabled

See Also: "About IP Address Validation for Webgates".

Deny on Not Protected

Webgates only (not Access Clients)

Oracle recommends enabling Deny On Not Protected.

When enabled, this element denies access to all resources to which access is not explicitly allowed by a rule or policy. Enabling this can limit the number of times the Webgate queries the OAM Server, and can improve performance for large or busy application domains.

  • 11g Webgate: Always enabled, and cannot be changed

  • 10g Webgate: Can be disabled.

Important: DenyOnNotProtected overrides Host Identifiers and Preferred Host. Oracle recommends enabling DenyOnNotProtected. Otherwise security holes can occur in large installations with multiple Host Identifiers, virtual hosts, and other complex configurations.

Allow Management Operations

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

  • Terminate session

  • Enumerate sessions

  • Add or Update attributes for an existing session

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

Default: Disabled

Note: Only privileged agents can invoke session management operations. When this parameter is enabled, session management requests (listed above) are processed by the OAM Server. If disabled, such requests are rejected for the agent.

Primary Server List

Identifies Primary Server details for this Agent. The default is based on the OAM Server:

  • Server Name

  • Host Name

  • Host Port

  • Max Number (maximum connections this Webgate will establish with the OAM Server (not the maximum total connections the Webgate can establish with all OAM Servers).)

Secondary Server List

Identifies Secondary OAM Server details for this agent, which must be specified manually:

  • Server Name

  • Host Name

  • Host Port

  • Max Number (maximum connections this Webgate will establish with the OAM Server (not the maximum total connections the Webgate can establish with all OAM Servers).)


9.3.2 About User-Defined Webgate Parameters

To implement user-defined parameters, you must enter them in the Webgate registration page as shown in Table 9-6.

See Also:

Table 10-6, "Elements Common to Full Remote Registration Requests" for details about User-defined Webgate parameters in remote registration requests.

Table 9-6 User-Defined Webgate Parameters

Parameter Description

UrlInUTF8Format=true

In an environment that uses Oracle HTTP Server 2, this parameter must be set to true to display latin-1 and other character sets.

ProxySSLHeaderVar=IS_SSL

Uses when the Webgate is located behind a reverse proxy, SSL is configured between the client and the reverse proxy, and non-SSL is configured between the reverse proxy and the Web server. It ensures that URLs are stored as https rather than http. The proxy ensures that URLs are stored in https format by setting a custom header variable indicating whether it is servicing an SSL or non-SSL client connection.

The value of the ProxySSLHeaderVar parameter defines the name of the header variable the proxy must set. The value of the header variable must be "ssl" or "nonssl".

If the header variable is not set, the SSL state is decided by the SSL state of the current Web server.

Default: IS_SSL

client_request_retry_attempts=1

Webgate-to-OAM Server timeout threshold specifies how long (in seconds) the Webgate waits for the OAM Server before it considers it unreachable and attempts the request on a new connection.

If the OAM Server takes longer to service a request than the value of the timeout threshold, the Webgate abandons the request and retries the request on a new connection.

Default: 1

Note: The new connection that is returned from the connection pool can be to the same OAM Server, depending on your connection pool settings. Also, other OAM Servers may also require more time to process the request than the time specified on the timeout threshold. In some cases, the Webgate can retry the request until the OAM Servers are shut down. You can configure a limit on the number of retries that the Webgate performs for a non-responsive server using the client_request_retry_attempts parameter.

InactiveReconfigPeriod=10

The Webgate update thread reads the shared secret from the OAM Server every 1 minute when Webgate is active. The OAM Server server returns the shared secret in its own cache (the OAM Server cache).

Default: 10 (minutes)

See Also: "Changing the Webgate Polling Frequency".

fallbackToContainerPolicy=true

Used for the IAMSuiteAgent. When set to false, user access to the resource is denied and an HTTP response code, 403 is returned.

When set to 'true' the request goes through to the container and uses whatever policy (related to J2EE authentication/authorization) is configured on the container to grant or deny the user access.

Default: true

logoutRedirectUrl=

http://host.domain.com:14100/oam/server/logout

protectWebXmlSecuredPagesOnly=true

Used for the IAMSuiteAgent. After the user is authenticated, this parameter is used for all subsequent requests to determine if the Agent should validate the incoming request. When set to:

false: The Agent always validates the incoming request

true: The default. The Agent determines whether to validate the incoming request based on the following:

  • If the application specifies 'CLIENT-CERT' as part of the construct: "<auth-method>" in its web.xml, the Agent validates the incoming request.

  • If the application does not specify 'CLIENT-CERT' as part of the construct: "<auth-method>" in its web.xml, the Agent does not validate the incoming request. Instead, the Agent lets the request go through to the application.

SSODomains

Specifies legitimate Web servers within the Oracle Access Manager installation to control where the obrar.cgi redirect is sent. Each value describes one or more Web servers. You can provide a relatively short list using domain names and IP addresses with wild cards that cover all your installation's Web servers.

See Also: "About SSODomains Parameter".

maxAuthorizationResultCacheElems

Max Authorization Results Cache Elements—Number of elements maintained in the Authorization Result Cache. This cache maintains information about authorization results for associated user sessions. For example:

maxAuthorizationResultCacheElems=10000

Default = 100000

See Also: "Tuning 10g and 11g Webgate Caches".

authorizationResultCacheTimeout

Authorization Results Cache Timeout—Number of elements maintained in the Authorization Result Cache. This cache maintains information about authorization results for associated user sessions. For example:

authorizationResultCacheTimeout=60

Default, when not specified = 15 (seconds)

See Also: "Tuning 10g and 11g Webgate Caches".


About SSODomains Parameter

Oracle recommends applying the SSODomains user-defined parameter to all Webgate registration to completely mitigate any security risk.

Without this parameter, the host always matches (same as previous Webgate behavior.

If SSODomains is specified but empty, then the host never matches. This allows you to specify that a Webgate will not service any obrareq.cgi requests. Oracle recommends this for all Webgates that are not intended to be authentication servers (as indicated by authentication scheme challenge redirect URLs).

Syntax

ssoDomains = ssoDomainSpec | ssoDomains ssoDomainSpec 
   ssoDomainsSpec = domainSpec | ipSpec 
   domainSpec = domain[:port]
   domain = domainName | domainName.domain 
   domainName = usual_DNS_name
   ipSpec = ipPart.ipPart,ipPart,ipPart[:port]
   ipPart = ipComponent | ipWildCard 
   ipComponent = usual_IPaddress_component
   ipWildCard = * 
   port = 12345 

Guidelines:

domainName = the usual DNS name, alphanumeric characters plus '-', "_', and so on.

ipComponent = the usual IPaddress component, 1-3 digits

ipWildCard = "*"

port = the usual port number, 1-5 digits

For each spec in the SSODomains parameter:

  • If the spec has a port, it must match the host port. If the host does not have an explicit host, the default (80 for HTTP, 443 for HTTPS) is used.

  • If the host is an IP address and the spec is an ipSpec, match each ipPort of the host and spec from left to right. A wild card "*" in the ipSpec matches all values for the corresponding host. For example, a spec of 130.35.*.* matches a host of 130.35.12.45 but not 130.36.12.45.

  • If the host is an DNS name and the spec is a domainSpec, match each domainName of the host and spec from right to left, until the spec has been completely matched. For example, a spec of company.com matches target.company.com and target.us.company.com but not www.badsite.com.

  • Continue until a spec matches the host or all specs have been tested.

The right hand parameter in the obrareq.cgi URL is (usually) taken from the original target URL from the user. The user may specify the host as a fully-qualified domain name (the preferred form), an IP address, or a partially or unqualified domain name. The SSODomains spec must take into account the host formats that might be used, hence the need for IP addresses as well as domain names. Note also that partially and unqualified domain names can be specified as domainSpecs.

The burden of covering all hostname variations in the SSODomains parameter can be lessened by configuring Preferred HTTP Hosts for the target Webgates. If SSODomains is also configured for the target Webgate (preferably with no domains to prevent the Webgate from being used for authentication), the (patched) target Webgate will use the preferred host for the right-hand parameter in the obrareq.cgi URL. Consequently the SSODomain for the authenticating Webgate only needs to cover the domains for the preferred hosts.

One good strategy is to include in the SSODomains specs the Primary HTTP Cookie domains defined for each configured Webgate, on the theory the ObSSOCookie will be available to every web server in those domains.

If the right-hand parameter in an obrareq.cgi request does not match any spec in the SSODomains, Webgate returns the following error:

Bad Oracle NetPoint Request 
The URL /obrareq.cgi is reserved for use by Oracle NetPoint and has been 
used with incorrect parameters.

Webgate also logs a WARNING "The rh parameter of a received /obrareq.cgi URL is not allowed by the Webgate's SSODomains parameter" with the right-hand parameter and the SSODomains values. This means that either someone, potentially an attacker, is misusing the obrareq.cgi URL, or a legitimate obrareq.cgi redirection is not adequately covered by the SSODomains parameter.

9.3.3 About IP Address Validation for Webgates

IP address validation is specific to Webgates. It determines if a client's IP address is the same as the IP address stored in the ObSSOCookie generated for single sign-on. The IPValidation parameter turns IP address validation on and off. If IPValidation is true, the IP address stored in the ObSSOCookie must match the client's IP address, otherwise, the cookie is rejected and the user must reauthenticate. By default, IPValidation is false.

The IP Validation parameter can cause problems with certain Web applications. For example, Web applications managed by a proxy server typically change the user's IP address, substituting the IP address of the proxy. This prevents single sign-on using the ObSSOCookie.

Note:

The IP Validation Exceptions parameter lists IP addresses that are exceptions to this process.

If IPValidation is true, the IP address can be compared to the IP Validation Exceptions list. If the address is found on the exceptions list, it does not need to match the IP address stored in the cookie. You can add as many IP addresses as needed. These addresses are the actual IP addresses of the client, not the IP addresses that are stored in the obSSOCookie. If a cookie arrives from one of the exception IP addresses, the Access System ignores the address stored in the ObSSOCookie cookie for validation. For example, the IP addresses in the IP Validation Exceptions parameter can be used when the IP address in the cookie is for a reverse proxy.

To configure single sign-on between Webgate and an access client that does not have the client IP address at authentication, the IP validation option can be explicitly turned off (set IP Validation to false). When the IP Validation parameter is set to false, the browser or client IP address is not used as a part of the ObSSOCookie. However, Oracle recommends that you keep IP validation on whenever possible.

9.3.4 Searching for an OAM Agent Registration

Figure 9-8 shows the OAM Agent (Webgates) Search controls, defaults, and the empty Search Results table. From this page you can create a new OAM 11g Webgate or 10g Webgate registration, or search for a specific Webgate or group of Webgates (all 11g Webgates, for instance).

Figure 9-8 Webgate Search Controls and Create Agent Buttons

Webgate Search Controls
Description of "Figure 9-8 Webgate Search Controls and Create Agent Buttons"

If you do not know the exact name, you can use a wild card (*) in the search string. From the search results table, you can choose an name to open and view or edit the registration page.

The controls available on this page are described in Table 9-7.

Table 9-7 OAM Agent Search Controls

Control Description

Create 11g Webgate

Click to open a fresh 11g Webgate registration page.

Create 10g Webgate

Click to open a fresh 10g Webgate registration page.

Name

Enter the name (or partial name and wild card (*)) as defined on the registration page. For example: entering a* could return Agent_WebGate_AccessDebugNew in the result table.

Version

Choose a Webgate version to narrow the search and results:

  • 11g

  • 10g

Preferred Host

Enter all (or part of with a wild card (*)) hostname as it appears in HTTP requests. For example: iam* could return IAMSuiteAgent in the result stable.

State

Choose a Webgate version to narrow the search and results:

  • Enabled

  • Disabled

Primary Server

Enter the entire (or partial with a wild card (*)) Primary Server name.

Secondary Server

Enter the entire (or partial with a wild card (*)) Secondary Server name.


Prerequisites

The Webgate must be a registered agent of Oracle Access Manager 11g.

To search for an OAM Agent registration

  1. Activate the System Configuration tab, Access Manager Settings section.

  2. Expand the SSO Agents node, and double-click the OAM Agents node.

  3. Find All Enabled: Select Version All, State All, and click the Search button.

  4. Find a Version: From the Agent version list, choose 10g or 11g to define your search.

  5. Find a Name: In the text field, enter the exact name of the instance you want to find. For example:

    my_OAM_Agent
    
  6. Click the Search button to initiate the search.

  7. Click the Search Results tab to display the results table, and then:

    • Edit or View: Click the Edit command button in the tool bar to display the configuration page.

    • Delete: Click the Delete button in the tool bar to remove the instance; confirm removal in the Confirmation window.

    • Detach: Click Detach in the tool bar to expand the table to a full page.

    • Reconfigure Table: Select a View menu item to alter the appearance of the results table.

  8. Apply any changes (or dismiss the page) when you finish.

9.3.5 Registering a Webgate or Programmatic Access Client

You can register a Webgate before you install it. You can register a programmatic Access Client the same as a Webgate. Users with valid Administrator credentials can perform the following task to register an OAM Agent using the Oracle Access Manager Console.

Note:

During agent registration, at least one OAM Server instance must be running in the same mode as the agent. Otherwise, agent registration fails.

After agent registration, you can change the communication mode of the OAM Server if needed. Communication between the agent and server continues to work as long as the Webgate mode is at least at the same level as the OAM Server mode or higher. See Appendix E.

Prerequisites

Confirm that at least one OAM Server is running in the same mode as the agent to be registered.

To register a Webgate or programmatic Access Client

  1. From the Oracle Access Manager Console Welcome page, SSO Agent panel, click one of the following to open a fresh page:

    • New OAM 11g Agent

    • New OAM 10g Agent (see also Chapter 28)

    Alternatively: From the System Configuration tab, Access Manager Settings section, expand the SSO Agents node, double-click OAM Agents node, and then click the desired Create ... Webgate button in the upper-right corner.

  2. On the Create: OAM Agent page, enter required details (those with an *) to register this OAM Agent (Table 9-4).

  3. Protected Resource List: In this table, enter individual resource URLs to be protected by this OAM Agent, as shown in Table 9-4.

  4. Public Resource List: In this table, enter individual resource URLs to be public (not protected), as shown in Table 9-4.

  5. Confirm that the Auto Create Policies box is checked (or clear the box to disable this function if you do not want a new application domain).

  6. Click Apply to submit the registration (or close the page without applying changes).

  7. Check the Confirmation window for the location of generated artifacts and then close the window.

  8. In the navigation tree, confirm the Agent name is listed.

    Note:

    If you are provisioning an OAM 10g Webgate, skip Step 9 for now and go to Chapter 28.

  9. Perform the following steps to copy the artifacts to the Webgate installation directory (or install Webgate and then copy these artifacts):

    1. On the Oracle Access Manager Console host, locate the updated OAM Agent ObAccessClient.xml configuration file (and any certificate artifacts). For example:

      $DOMAIN_HOME/output/$Agent_Name/ObAccessClient.xml

    2. On the OAM Agent host, copy artifacts (to the following Webgate directory path). For example:


      11g Webgate/Access Client: 11gWebgate_instance_dir/webgate/config/ObAccessClient.xml
      (for instance WebTier_Middleware_Home/Oracle_WT1/instances1/config/
      OHS/ohs1/webgate/config/ObAccessClient.xml)

      10g Webgate/Access Client: $Webgate_install_dir/oblix/lib/ObAccessClient.xml
    3. Proceed to Part IV, "Managing Oracle Access Manager SSO, Policies, and Testing".

9.3.6 Viewing or Editing an OAM Agent Registration

This procedure is the same whether you are editing a Webgate or Access Client registration. Users with valid Administrator credentials can change any setting for a registered OAM Agent using the Oracle Access Manager Console, as described in the following procedure. For example, you might want to revise the timeout threshold or other settings used by the OAM Proxy.

After changes, updated details are propagated through a runtime configuration update process. There is usually no need to copy the artifacts over to Webgate configuration area.

Note:

Artifacts need only be copied to the Webgate directory path if the agent name, access client password, or security mode is changed.

Prerequisites

The agent must be registered and available in the Oracle Access Manager Console.

To view or modify details for a registered Webgate

  1. From the System Configuration tab, Access Manager Settings section, expand the SSO Agents node.

    1. Double-click OAM Agents node name to display the Search page.

    2. Find the Registration: See "Searching for an OAM Agent Registration".

    3. Click the Agent name in the results table to open the page.

  2. Modify Agent details, and Primary or Secondary Server details, as needed (Table 9-5).

  3. User Defined Parameters: Modify these as desired (Table 9-6).

  4. Click Apply to submit changes and dismiss the Confirmation window (or close the page without applying changes).

  5. Perform the following steps to copy artifacts if needed:

    Note:

    Artifacts need only be copied to the Webgate directory path if the agent name, or agent client password, or security mode is changed. See Chapter 28 if you are provisioning an OAM 10g Webgate.

    1. On the Oracle Access Manager Console host, locate the updated OAM Agent ObAccessClient.xml configuration file (and any certificate artifacts). For example:

      $DOMAIN_HOME/output/$Agent_Name/ObAccessClient.xml

    2. On the OAM Agent host, copy artifacts (to the following Webgate directory path). For example:


      11g Webgate/Access Client: 11gWebgate_instance_dir/webgate/config/ObAccessClient.xml
      (for instance, WebTier_Middleware_Home/Oracle_WT1/instances1/config/
      OHS/ohs1/webgate/config/ObAccessClient.xml)

      10g Webgate/Access Client: $Webgate_install_dir/oblix/lib/ObAccessClient.xml
    3. Proceed to Part IV, "Managing Oracle Access Manager SSO, Policies, and Testing".

    4. See Appendix E, "Securing Communication for Oracle Access Manager 11g", if needed.

9.3.7 Deleting Webgate Registration

Users with valid Administrator credentials can perform the following procedure to delete a registered OAM Agent from the Oracle Access Manager Console.

Note:

Deleting an agent registration remove only the registration (not the associated host identifier, application domain, resources, or the agent itself).

Prerequisites

Evaluate the application domain, resources, and policies associated with this agent and ensure that these are configured to use another agent or that they can be removed.

To delete an OAM agent registration

  1. From the System Configuration tab, Access Manager Settings section, expand the SSO Agents node.

    1. Double-click OAM Agents node to display the Search page.

    2. Find the Registration: See "Searching for an OAM Agent Registration".

  2. Optional: Click the Agent name in the results table to open the page, confirm it is the right agent to remove, and close the page.

  3. Click the desired agent's name, click the Delete button in the tool bar, and confirm the removal in the Confirmation window.

  4. Confirm the Agent name is no longer listed in the navigation tree.

  5. Remove Webgate Instance: Perform the following steps and also refer to "Removing a 10g Webgate from the OAM 11g Deployment", if needed.

    1. Shut down the Web server.

    2. Remove Webgate software using the utility provided in the following directory path:

      $Webgate_install_dir/oui/bin

      Windows: setup.exe -d
      Unix: runInstaller -d
      
    3. Revert to the httpd.conf version before updates for Webgate. For example:

      Copy: httpd.conf.ORIG

      To: httpd.conf

    4. Restart the Web server.

    5. On the agent host, manually remove the Webgate instance directory. For example:

      11g Webgate/Access Client:


      11gWebgate_instance_dir/webgate/config/ObAccessClient.xml

      WebTier_Middleware_Home/Oracle_WT1/instances1/config/OHS/ohs1/
      webgate/

      10g Webgate/Access Client:  
      $Webgate_install_dir/oblix/lib/ObAccessClient.xml

9.4 Tuning 10g and 11g Webgate Caches

This section provides the following topics:

9.4.1 Introducing Webgate Caches

Webgate caches various information related to resources, authentications and authorizations to improve performance. It uses the cached information to avoid trips to 11g Server for requesting same information. Table 9-8 are the caches used by Webgate to maintain this information.

Table 9-8 Webgate Caches

Cache Type Description

Resource to Authentication Scheme

This cache maintains information related to authentication schemes being used.

Default: 100000 elements

See Also: "Tuning Maximum Cache Elements" and "Tuning Cache Timeout Values".

Authentication Scheme

This cache maintains information related to authentication schemes being used.

Default: 25 elements

Typically Authentication Scheme cache elements require less than 2 Kb of memory per element.

See Also: "Tuning Cache Timeout Values".

Resource to Authorization Policy

11g Webgate only

This cache maintains information related to resources accessed and associated authorization policy.

Default: 100000 elements

See Also: "Tuning Maximum Cache Elements" and "Tuning Cache Timeout Values".

Authorization Result

11g Webgate only

This cache maintains information related to authorizations associated with user sessions.

Default: 1000 elements

See Also: "Tuning Authorization Result Cache" and "Tuning Authorization Result Cache Timeout".


About the 11g Webgate Diagnostics Page

This page displays useful information related to currently effective Cache configuration parameters. It also displays runtime information about the caches that include information on the number of cached elements, number of hits and misses so far, and current memory usage of individual caches. The page is found at the following URL:

http://webserver:port/ohs/modules/webgate.cgi?progid=1

Note:

Changes to Webgate parameters are not reflected on Webgate until the next configuration refresh. For 11g Agents, the default configuration refresh interval is 10 minutes.

Tuning Maximum Cache Elements

By default, the Resource to Authentication Scheme and Resource to Authorization Policy caches are created to store 100000 elements. Typically, elements of these caches require less than 1 Kb of memory per element. Therefore, with 100000 elements in each of these caches, typical memory requirement for the caches will be 100000 Kb or 100 Mb each.

Considering memory requirements and your deployment, the Web Server being used and number of unique URLs in your application, you might want to increase or decrease the maximum number of elements to be cached.

Note:

Increase or decrease the Maximum Cache Elements parameter value as needed. If this is set to a value of -1, all Webgate caches are disabled.

For both 10g and 11g Webgates, you can tune the maximum number of elements to be cached property, by changing the Maximum Cache Elements parameter. Updates to this parameter require a Webgate restart.

  1. Locate and open the desired 10g or 11g Webgate registration page in the Oracle Access Manager Console.

  2. Set the Maximum Cache Elements parameter as desired.

  3. Restart Webgate Web server.

Tuning Authorization Result Cache

By default, the Authorization Result cache is created to store 1000 elements. Authorization Result cache elements store the user session identifier, authorization policy identifier, and associated authorization result including any processed policy responses. Therefore, Authorization Result cache elements are bulky and generally require more than 2Kb of memory per element.

Considering memory requirements and the number of concurrent user sessions in your deployment, you might want to increase the number of elements to be cached.

  1. Locate and open the desired 11g Webgate registration page in the Oracle Access Manager Console.

  2. In User Defined Parameters, add or update maxAuthorizationResultCacheElems as desired.

  3. Restart Webgate Web server.

Tuning Cache Timeout Values

By default, the following caches are created with a timeout value of 1800 seconds or 30 minutes:

  • Resource to Authentication Scheme

  • Authentication Scheme

  • Resource to Authorization Policy

Elements in these caches are stored with an expiry time that forces these caches to be flushed on expiry.

Considering the frequency of updates to Authentication Schemes, and Authentication and Authorization Policies in your deployment, you might want to increase or decrease the default timeout value.

  1. Locate and open the desired 10g or 11g Webgate registration page in the Oracle Access Manager Console.

  2. Set the Cache Timeout parameter as desired.

  3. Restart Webgate Web server.

Tuning Authorization Result Cache Timeout

By default, the Authorization Result Cache timeout value is set at 15 seconds. Elements in the Authorization Result Cache is stored with an expiry time that forces it to be flushed on expiry. A low timeout value ensures that authorization results are cached for a small amount of time only.

Considering average length of user sessions and frequency with which user sessions are created and destroyed, you might want to change the default timeout value. Unlike other caches and parameters, updates to this parameter do not require Webgate restart. Instead, the updated value is dynamically picked up by 11g Webgate and enforced immediately.

Note:

If authorizationResultCacheTimeout is set to 0, Authorization Cache is disabled.

  1. Locate and open the desired 11g Webgate registration page in the Oracle Access Manager Console.

  2. In User Defined Parameters, add or update authorizationResultCacheTimeout as desired.

  3. Restart Webgate Web server.

9.4.2 Reducing Network Traffic Between Components

The Webgate-to-OAM Server configuration polling reduces the traffic between both the Webgate and OAM Server and the OAM Server and the registered data stores for Oracle Access Manager.

Process overview: Webgate-to-OAM Server configuration polling

  1. When the Webgate is inactive for 60 seconds, it reduces the frequency of polling for its configuration information.

    The polling frequency is determined by the parameter InactiveReconfigPeriod, which is a user-defined parameter that is set in the Webgate configuration page. The value for InactiveReconfigPeriod is specified in minutes. Within ten seconds of resuming activity, the Webgate performs reconfiguration polling once a minute.

  2. At startup, the Webgate checks the bootstrap configuration to see if any important parameters have changed.

    This makes the re-initialization process unnecessary in most cases and reduces the transient OAM Server load.

  3. Webgate and Access client configurations are cached in the OAM Server.

    The default cache timeout is 59 seconds. This should cause no modifications to the system behavior on non-Apache Access clients. The Apache Web server with Webgate avoids unnecessary hits to the directory server. The caching parameters can be set in the Webgate registration page.

    • Max Cache Elements sets the maximum size of the cache (default 9999)

    • Cache Timeout determines the maximum lifetime of any element in the cache (default 59 seconds)

There are two ways to reduce off-time network traffic between both the Webgate and OAM Server and the OAM Server and the database:

  • Changing the default configuration cache timeout for Webgate and Access client configurations that are cached in the OAM Server, as described in Step 3.

  • Changing Webgate polling frequency for configuration information, as described next.

9.4.3 Changing the Webgate Polling Frequency

One way to reduce off-time network traffic between both the Webgate and OAM Server and between the OAM Server and the database is to change the Webgate polling frequency using the InactiveReconfigPeriod parameter.

The default is 1 minute. When the Webgate is inactive for more than 60 seconds (for example, when no authentication requests are being processed), it reduces the frequency of polling for its configuration information. Within ten seconds of resuming activity, the Webgate resumes reconfiguration polling once every minute:

  • If set to -2, Webgate never polls.

  • If set to a value greater than 0 it polls at the specified interval.

  • If set to -1 and Webgate is inactive and has been for 1 minute, then Webgate does not poll. Webgate resumes reconfiguration polling when it returns to an active state.

For example, the OAM Server reads the shared secret from the directory at an interval of 10 minutes and this cached value is returned to Webgate. In the idle state the Webgate reads the shared secret from the OAM Server using the InactiveReconfigPeriod value. If this value is not set, the Webgate polls the OAM Server for the shared secret value at an interval of 1 minute even though the updated shared secret value will be returned only after 10 minutes.

To change the configuration polling frequency

  1. Locate the desired Webgate registration page using instructions in "Searching for an OAM Agent Registration".

  2. Add the InactiveReconfigPeriod parameter as a user-defined parameter on the Webgate registration page.

  3. Specify the value for InactiveReconfigPeriod in minutes.

  4. Apply your changes to the Webgate registration page.

9.5 Registering and Managing OSSO Agents Using the Console

This section describes how to manage OSSO Agent registrations (mod_osso) using the Oracle Access Manager Console. For details, see:

9.5.1 About OSSO Agents and the OSSO Proxy

An OSSO Agent is any mod_osso module deployed on an Oracle HTTP Server that is acting as a partner application for the OSSO server and protecting resources.

The OSSO Proxy supports inter-operability between OAM and OSSO agents (using an OSSO agent to access a valid SSO session created for an OAM Agent, and vice versa).

OSSO Proxy Supports Description

SSO login

From an OSSO Agent to the OAM Server (and OSSO-specific tokens)

SSO logout

From the OSSO Agent to the OAM Server

OSSO Agent requests and protocols

OSSO Proxy translates the OSSO protocol into a protocol for Oracle Access Manager 11g services.


9.5.2 About the Create OSSO Agent Page

This topic describes OSSO Agent registration using the Oracle Access Manager Console.

Note:

Before you register an OSSO Agent, ensure that the Oracle HTTP Server is installed on the client computer and that the Web server is configured for mod_osso.

Figure 9-9 shows a Create OSSO Agent page, under the System Configuration tab in the Oracle Access Manager Console.

Figure 9-9 Create OSSO Agent Page

Create OSSO Agent Page
Description of "Figure 9-9 Create OSSO Agent Page"

On the Create OSSO Agent page, required information is identified by the asterisk (*). Table 9-9 describes the required and optional details that you can specify when you register a new agent.

Table 9-9 Create OSSO Agent Page Elements

Element Description

Name

The identifying name for this mod_osso Agent.

Token Version

The default version of the token is 3.0; the following options are available:

  • 1.2

  • 1.4

  • 3.0

Base URL

Required for OSSO agents.

The required protocol, host, and port of the computer on which the Web server for the agent is installed. For example, http://host.example.domain.com:port or https://example.domain.com:port.

Note: The host and port are used as defaults for the expanded registration. See Table 9-10.

Admin ID

Optional administrator log in ID for this mod_osso instance. For example, SiteAdmin.

Admin Info

Optional administrator details for this mod_osso instance. For example, Application Administrator.

Host Identifier

The host identifier is filled in automatically based on the Agent name

Auto Create Policies

During agent registration, you can have authentication and authorization policies created automatically. This option is checked (enabled) by default.

The OSSO Proxy requires an application domain that includes a resource with the generic URL (/.../*) protected by a policy based on the LDAP scheme (default). This is why a generic URL is used at the server side.

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


To help streamline Agent registration, several elements are concealed and default values are used during registration with the console. When you view an agent's registration page in the Oracle Access Manager Console, all elements and values are revealed.

Figure 9-10 shows the full Agent page as viewed in the console. The Confirmation window is still visible. All details specified, and defaults, are shown.

Figure 9-10 OSSO Agent Page and Confirmation Window

Expanded OSSO Agent Page
Description of "Figure 9-10 OSSO Agent Page and Confirmation Window"

Table 9-10 summarizes the expanded elements and defaults that are used by the OSSO Agent.

Table 9-10 Expanded OSSO Agent Elements

Element Description

Site Token

The Application Token used by the partner when requesting authentication. This cannot be edited.

Success URL

The redirect URL to be used upon successful authentication. By default, osso_login_success on the fully qualified host and port specified with the Base URL are used. For example:

Default: http://example.domain.com:7001/osso_login_success

Failure URL

The redirect URL to be used if authentication fails.By default, osso_login_failure on the fully qualified host and port specified with the Agent Base URL are used:

Default: http://example.domain.com:7001/osso_login_failure

Start Date

First month, day, and year for which log in to the application is allowed by the server.

Default: The date the Agent was registered.

Home URL

The redirect URL to be used for the Home page after authentication. By default, the fully qualified host and port specified with the Agent Base URL are used:

Default: http://example.domain.com:7001

Logout URL

The redirect URL to be used when logging out. This redirects the user to the global logout page on the server: osso_logout_success. By default, the fully qualified host and port specified with the Agent Base URL are used:

Default: http://example.domain.com:7001/osso_logout_success

See Also: "Introduction to OAM 11g Centralized Logout".


9.5.3 Refining the Search for an OSSO Agent (mod_osso) Registration

When you first open the OSSO Agents node, the Search form appears. The Results table lists all OSSO Agents. If there are too many to quickly locate the one you want, you can use the controls to refine your search.

Note:

At the top of the Search page is the Create OSSO Agent button.

There are only two element on which you can refine an OSSO Agent search: The Agent Name that assigned during registration or the Agent ID assigned by the system.

Prerequisites

The OSSO Agent must be registered and available in the Oracle Access Manager Console.

To search for an OSSO Agent registration

  1. Activate the System Configuration tab, Access Manager section.

  2. Expand the SSO Agents node, and open the OSSO Agents node.

  3. In the Name field, enter some criteria for your search (with or without including the wild card (*)). For example:

    my*
    
  4. Click the Search button to initiate the search.

  5. In the Search Results table:

    • Edt or View: Click the Edit command button in the tool bar to display the configuration page.

    • Delete: Click the Delete button in the tool bar to remove the instance; confirm removal in the Confirmation window.

    • Detach: Click Detach in the tool bar to expand the table to a full page.

    • Reconfigure Table: Select a View menu item to alter the appearance of the results table.

  6. Apply any changes (or dismiss the page) when finished.

9.5.4 Registering an OSSO Agent (mod_osso)

Users with valid Administrator credentials can perform the following procedure to register an OSSO Agent using the Oracle Access Manager Console.

Prerequisites

Ensure that the Oracle HTTP Server is installed and running on the client computer, and is configured for mod_osso.

See Also:

To register an OSSO Agent

  1. From the Oracle Access Manager Console Welcome page, Agent Configuration panel, click the following link to open a fresh page:

    • Add OSSO Agent

    Alternatively: From the System Configuration tab, expand the Agents node and the OSSO Agents node, then click the Create button in the tool bar.

  2. Click the Create button in the tool bar.

  3. On the Create: OSSO Agent page, enter required details, as shown in Table 9-9:

    • Name

    • Base URL

  4. Select the desired Token Version, and enter optional details as desired (Table 9-9).

  5. Click Apply to submit the registration (or close the page without applying changes).

  6. In the Confirmation window, check the path to generated artifacts and then close the window. For example:

    Artifacts are generated in following location : /.../base_domain/output/OSSO1
    
  7. Copy the updated osso.conf file to the OSSO Agent host:

    1. On the Oracle Access Manager Console host, locate the updated OSSO Agent osso.conf file. For example:

      $DOMAIN_HOME/output/$Agent_Name/osso.conf

    2. On the OSSO Agent host, copy osso.conf to the mod_osso directory path.

      $OHS_dir/osso.conf


      for instance, WebTier_Middleware_Home/Oracle_WT1/instances1/config/
      OHS/ohs1/config/osso.conf
    3. Restart the OAM Server that is hosting the OSSO Agent.

  8. Proceed to Part IV, "Managing Oracle Access Manager SSO, Policies, and Testing".

9.5.5 Viewing or Editing OSSO Agent (mod_osso) Registration

Users with valid Administrator credentials can change any setting for a registered OSSO Agent using the Oracle Access Manager Console, as described in the following procedure. For example, you might want to revise the end date or add administrator information.

Prerequisites

Ensure that the Oracle HTTP Server is installed and running on the client computer, and is configured for mod_osso.

To view or modify an OSSO Agent registration

  1. From the System Configuration tab, Access Manager section, expand the SSO Agents node.

  2. Double-click the OSSO Agents node.

  3. Find the Agent: "Refining the Search for an OSSO Agent (mod_osso) Registration"

  4. In the Search Results table, click the desired Agent name to open the registration page.

  5. On the registration page, view or modify details as needed (Table 9-9 and Table 9-10).

  6. Click Apply to submit the changes (or close the page without applying changes), and close the Confirmation window.

  7. Copy the updated osso.conf file to the OSSO Agent host:

    1. On the Oracle Access Manager Console host, locate the updated OSSO Agent osso.conf file. For example:

      $DOMAIN_HOME/output/$Agent_Name/osso.conf

    2. On the OSSO Agent host, copy osso.conf to the mod_osso directory path.

      $OHS_dir/osso.conf


      for instance, WebTier_Middleware_Home/Oracle_WT1/instances1/config/
      OHS/ohs1/config/osso.conf
    3. Restart the OAM Server that is hosting the OSSO Agent and proceed to Part IV, "Managing Oracle Access Manager SSO, Policies, and Testing":

9.5.6 Deleting an OSSO Agent (mod_osso) Registration

Users with valid Administrator credentials can perform the following procedure to delete a registered OSSO Agent from the Oracle Access Manager Console.

Note:

Deleting an agent registration removes only the registration (not the associated host identifier, application domain, resources, or the agent instance itself).

Prerequisites

Evaluate the application domain, resources, and policies associated with this agent and ensure that these are configured to use another agent or that they can be removed.

To delete an OSSO Agent registration

  1. From the System Configuration tab, Access Manager Settings section, expand the SSO Agents node, nd open the OSSO Agents node.

  2. Click Search and choose the desired name (or refine your search as needed).

  3. Optional: Double-click the desired name to display the registration page; confirm this is the agent to remove, and close the page.

  4. Click the Agent name, click the Delete button in the tool bar, and confirm removal in the Confirmation window.