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

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

• OSSO Agents: mod_osso is part of the (still supported) 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 AccessGates:

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

• AccessGate is a custom access client created for use with non-Web applications. This custom access client must be specifically developed using the Software Developer Kit (SDK) and Oracle Access Manager APIs, either by you or by Oracle. An AccessGate is a form of access client that processes requests for Web and non-Web resources (non-HTTP) from users or applications.

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

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

Administrators can use either the OAM Administration Console or the remote registration tool to:

• Register a freshly installed OAM 11g Agent

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

• 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 B, "Co-existence Overview: OAM 11g and OSSO 10g".

About the Pre-Registered IDM Domain Agent

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

The IDM Domain agent is a domain-wide agent:

• Once deployed, the IDM Domain agent is installed on every server in the domain

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

• Configuration details are located under the 10g Webgates node (Policy Configuration tab) in the OAM Administration Console.

Certain IDM Domain Agent configuration elements are available in the WebLogic Administration Console (in the Security Provider section) and others in the OAM Administration 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 Access 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 IDMDomainAgent connection to the OAM Server through the NetPoint (now Oracle) Access Protocol (NAP or OAP).

Figure 5-2 illustrates the default Security Provider settings for the IDM Domain Agent.

Figure 5-1 IDM Domain Agent Configuration in the WebLogic Administration Console

OAM Administration Console, IDMDomainAgent Registration Page

The IDMDomainAgent registration page is like all other OAM agent registration pages.

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

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

Figure 5-2 illustrates the default configuration characteristics for the IDM Domain Agent.

Figure 5-2 IDM Domain Agent Default Characteristics

With few exceptions, all agent registration elements are the same. Table 5-3 outlines the differences. All elements are described in Table 5-6, "Expanded OAM 11g and 10g WebGate Agent Elements and Defaults".

Table 5-4 describes the resources protected by the IDM Domain Agent. Oracle recommends that you do not make any additions or changes. The WebLogic Administration Console (/console/.../*) and Fusion Middleware Enterprise Manager (/em/.../*) are not protected.

You can replace this agent with a 10g WebGate, as described in Chapter 17, "Managing OAM 10g WebGates with OAM 11g".

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.

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

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 Key Store on the server side.

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

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

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

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 Administration Console or custom WLST commands for OAM 11g.

For more information, see:

• Registering and Managing WebGate Agents Using the Administration Console

• Registering and Managing OSSO Agents Using the Administration Console

About File System Changes and Artifacts for Registered Agents

When you register an agent using the OAM Administration Console, a new file system directory is created for the Agent on the OAM Administration 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: 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: copy generated files to WebGate_install_dir/webgate/config

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 IDM Domain Agent 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. With OAM 11g, you can use the Administration 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

About the Create OAM Agent Page

This topic describes OAM Agent registration using the OAM Administration Console.

Figure 5-3 illustrates the Create OAM 11g Agent page, under the System Configuration tab in the Administration Console. The Create OAM 10g Agent page includes the same elements. The page requests minimal information to streamline registration. Required information is identified by the asterisk (*).

Figure 5-3 Create OAM 11g Agent Page

Description of "Figure 5-3 Create OAM 11g Agent Page"

The page includes named text fields where you enter requested information. Table 5-5 describes each of elements on the Create OAM Agent page. This is the same information that is requested when you use the remote registration tool with the simplified OAM request template as described in Chapter 6.

To help streamline Agent registration, additional elements are concealed and default values are applied. When you view or edit an Agent's page in the Administration Console, all elements and values are revealed, as shown in Figure 5-4. Most elements are the same as those you define when using the remote registration tool with the expanded OAM template, as described in Chapter 6.

Figure 5-4 OAM 11g Webgate Page with Defaults

Description of "Figure 5-4 OAM 11g Webgate Page with Defaults "

Table 5-6 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 OAM Administration Console as described here or the remote registration tool as described in Chapter 6.

Searching for a WebGate Agent Registration

Users with valid OAM Administrator credentials can perform the following procedure to search for an OAM Agent using the Administration Console.

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.

2. From the search type list, choose the relevant type (10g Webgates or 11g Webgates) to define your search.

3. In the text field, enter the exact name of the instance you want to find. For example:

   my_OAM_Agent
   

4. Click the Search button to initiate the search.

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

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

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

6. Click the Browse tab to return to the navigation tree when you finish with the Search results.

Registering a WebGate Agent

You can register a WebGate agent before you install it. Users with valid OAM Administrator credentials can perform the following task to register an OAM Agent using the Administration Console.

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 agent

1. Log in to the OAM Administration Console as usual.

2. From the OAM Administration Console Welcome page, Agent Configuration panel, click one of the following links to open a fresh page:

   • Add OAM 11g Agent

   • Add OAM 10g Agent (see also Chapter 17)

   Alternatively: From the System Configuration tab, expand the Agents node, the OAM Agents node, and either the 11g Webgates or 10g Webgates node, then click the Create command button in the tool bar.

3. On the Create: OAM Agent page, enter required details (those with an *) to register this OAM Agent, as shown in Table 5-5:

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

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

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

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 OAM Administration 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: 11gWebGate_instance_dir/webgate/config/ObAccessClient.xml
      (for instance WebTier_Middleware_Home/Oracle_WT1/instances1/config/
      OHS/ohs1/webgate/config/ObAccessClient.xml)
      
      10g WebGate: $WebGate_install_dir/oblix/lib/ObAccessClient.xml
      

   3. Restart the OAM Server that is hosting the Agent and proceed to Part III, "Single Sign-on, Policies, and Testing".

Viewing or Editing a WebGate Agent Registration

Users with valid OAM Administrator credentials can change any setting for a registered OAM Agent using the Administration 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.

Prerequisites

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

To view or modify details for a registered WebGate Agent

1. From the System Configuration tab, navigation tree, expand the following nodes as needed:

   
   Agents
   OAM Agents
   11g Webgates (or 10g Webgates)
   

2. Double-click the desired agent's name to display the registration page.

3. Modify Agent details, and Primary or Secondary Server details, as needed (see Table 5-5 and Table 5-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 17 if you are provisioning an OAM 10g WebGate.

   1. On the OAM Administration 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: 11gWebGate_instance_dir/webgate/config/ObAccessClient.xml
      (for instance, WebTier_Middleware_Home/Oracle_WT1/instances1/config/
      OHS/ohs1/webgate/config/ObAccessClient.xml)
      
      10g WebGate: $WebGate_install_dir/oblix/lib/ObAccessClient.xml
      

   3. Restart the OAM Server that is hosting the Agent and proceed to Part III, "Single Sign-on, Policies, and Testing".

   4. See Appendix E, "Securing Communication with OAM 11g", if needed.

Deleting a WebGate Agent Registration

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

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, navigation tree, expand the:

   
   Agents
   OAM Agents
   11g Webgates (or 10g Webgates)
   

2. Optional: Double-click the desired agent's name to view the registration, then 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: 11gWebGate_instance_dir/webgate/config/ObAccessClient.xml
      WebTier_Middleware_Home/Oracle_WT1/instances1/config/OHS/ohs1/
      webgate/
      
      10g WebGate: $WebGate_install_dir/oblix/lib/ObAccessClient.xml

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 interoperability between OAM and OSSO agents (using an OSSO agent to access a valid SSO session created for an OAM Agent, and vice versa).

About the Create OSSO Agent Page

This topic describes OSSO Agent registration using the Administration Console.

Figure 5-5 shows a Create OSSO Agent page, under the System Configuration tab in the Administration Console.

Figure 5-5 Create OSSO Agent Page

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

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

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 Administration Console, all elements and values are revealed.

Figure 5-6 shows the full Agent page as viewed in the Administration Console. The Confirmation window is still visible. All details specified, and defaults, are shown.

Figure 5-6 OSSO Agent Page and Confirmation Window

Description of "Figure 5-6 OSSO Agent Page and Confirmation Window"

Table 5-8 summarizes the expanded elements and defaults that are used by the OSSO Agent.

Searching for an OSSO Agent (mod_osso) Registration

Users with valid OAM Administrator credentials can perform the following procedure to search for an OSSO Agent using the Administration Console.

Prerequisites

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

To search for an OSSO Agent registration

1. Activate the System Configuration tab.

2. From the search type list, choose the OSSO agents type to define your search.

3. In the text field, enter the exact name of the instance you want to find. For example:

   my_OSSO_Agent
   

4. Click the Search button to initiate the search.

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

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

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

6. Click the Browse tab to return to the navigation tree when you finish with the Search results.

Registering an OSSO Agent (mod_osso)

Users with valid OAM Administrator credentials can perform the following procedure to register an OSSO Agent using the Administration Console.

Prerequisites

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

To register an OSSO Agent

1. Log in to the OAM Administration Console as usual.

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

3. Click the Create button in the tool bar.

4. On the Create: OSSO Agent page, enter required details, as shown in Table 5-7:

   • Agent Name

   • Agent Base URL

5. On the Create: OSSO Agent page, enter optional details as desired (Table 5-7):

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

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

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

   1. On the OAM Administration 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.

9. Proceed to Part III, "Single Sign-on, Policies, and Testing".

Viewing or Editing OSSO Agent (mod_osso) Registration

Users with valid OAM Administrator credentials can change any setting for a registered OSSO Agent using the Administration 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, navigation tree, expand the Agents node.

2. Expand the OSSO Agents node, and double-click the desired agent's name to display the registration page.

3. On the registration page, view or modify details as needed based on details in Table 5-7 and Table 5-8.

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

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

   1. On the OAM Administration 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 III, "Single Sign-on, Policies, and Testing":

Deleting an OSSO Agent (mod_osso) Registration

Users with valid OAM Administrator credentials can perform the following procedure to delete a registered OSSO Agent from the Administration Console.

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, navigation tree, expand the Agents node.

2. Expand the OSSO Agents node.

3. Optional: Double-click the desired agent's 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.