27 Managing OAM 10g Webgates with OAM 11g

The Oracle Fusion Middleware Installation Guide for Oracle Identity Management describes initial deployment of Oracle Access Manager 11g with the Oracle HTTP Server. However, when your enterprise includes Web server types other than Oracle HTTP Server you might want to use existing OAM 10g Webgates or install fresh OAM 10g Webgates for use with OAM 11g. Also, you might want to switch from using the pre-registered IAMSuiteAgent to using a 10g Webgate to protect Oracle Identity Management Consoles.

The following sections describe how to install fresh instances of OAM 10g Webgates for use with OAM 11g:

Existing OSSO 10g Customers: If OSSO is already in place as the enterprise solution for your existing Oracle deployment, Oracle Fusion Middleware continues to support this as a solution. Additionally, you can provision existing OSSO 10g mod_osso modules as agents for OAM 11g as described in Chapter 9.

About Replacing the IAMSuiteAgent with an OAM 10g Webgate

As described in Chapter 9, the IAMSuiteAgent is a Java agent filter that is pre-registered with OAM 11g out of the box. This agent provides SSO protection for Oracle Identity Management Consoles and resources in the Identity Management domain.

The following overview outlines the tasks that must be performed if you choose to move from the IAMSuiteAgent to an OAM 10g Webgate to protect Oracle Identity Management Consoles and resources in the Identity Management domain.

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

You can register these agents to use Oracle Access Manager 11g SSO using either the Oracle Access Manager Console or the remote registration tool. After registration, OAM 10g Webgates directly communicate with Oracle Access Manager 11g services through a JAVA-based OAM proxy that acts as a bridge.

The following overview outlines the tasks that must be performed to set up an existing OAM 10g Webgate to operate with OAM 11g.

Task overview: Setting up a legacy 10g Webgate to operate with OAM 11g

About Installing Fresh OAM 10g Webgates to Use With OAM 11g

You can install fresh OAM 10g Webgates for use with OAM 11g as described in this chapter. OAM 10g Webgates are available for a number of Web server platforms.

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.

Note:

When installing fresh OAM 10g Webgates for OAM 11g, Oracle recommends that you use the latest Webgates. Oracle also recommends that you install multiple Webgates for failover and load balancing.

There are several differences between installing an OAM 10g Webgate to operate in an OAM 11g deployment versus installing the 10g Webgate in an OAM 10g deployment. Table 27-1 outlines these differences.

Table 27-1 Installation Comparison with OAM 10g Webgates

10g Webgates in OAM 11g Deployments

10g Webgates in OAM 10g Deployments

Packages: OAM 10g Webgate installation packages are found on media and virtual media that is separate from the core components.

Using 10g Webgates with OAM 11g Servers is similar in operation and scope to a resource Webgate (one that redirects in contrast to the Authentication Webgate). With a 10g Webgate and 11g OAM Server, the 10g Webgate always redirects to the OAM 11g credential collector which acts like the authenticating Webgate.

The following overview lists the topics in this chapter that describe OAM 10g Webgate installation and registration tasks for OAM 11g in detail. You must complete all procedures for successful operation with OAM 11g.

Provisioning a 10g Webgate with OAM 11g

Whether you have a legacy OAM 10g Webgate or you are installing a fresh 10g Webgate instance to use with Oracle Access Manager 11g, you must provision Webgate to use OAM 11g authentication and authorization services.

You can use either the Oracle Access Manager Console or the remote registration tool to perform this task. The remote registration tool enables you to specify all Webgate parameters before registration using a template.

The following procedure walks through provisioning using the remote registration tool, in-band mode. In this example, OAMRequest_short.xml is used as a template to create an agent named my-10g-agent1, protecting /.../*, and declaring a public resource, /public/index.html. Your values will be different. You can use a full registration template to specify public, private, and excluded resources.

Before installing Webgate, ensure that your IIS Web server is not in lock down mode. Otherwise things will appear to be working until the server is rebooted and the metabase re-initialized, at which time IIS will disregard activity that occurred after the lock down.

If you are using client certificate authentication, before enabling client certificates for the Webgate you must enable SSL on the IIS Web server hosting the Webgate.

Setting various permissions for the /access directory is required for IIS Webgates only when you are installing on a file system that supports NTFS. For example, suppose you install the ISAPI Webgate in Simple or Cert mode on a Windows 2000 computer running the FAT32 file system. The last installation panel provides instructions for manually setting various permissions that cannot be set on the FAT32 fleshiest. In this case, these instructions may be ignored.

Each IIS Virtual Web server can have it's own Webgate.dll file installed at the virtual level, or can have one Webgate affecting all sites installed at the site level. Either install the Webgate.dll at the site level to control all virtual hosts or install the Webgate.dll for one or all virtual hosts.

You may also need to install the postgate.dll file at the computer level. The postgate.dll is located in the \Webgate_install_dir, as described in "Installing the Postgate ISAPI Filter". If you perform multiple installations, multiple versions of this file may be created which may cause unusual Oracle Access Manager behavior. In this case, you should verify that only one webgate.dll and one postgate.dll exist.

Removal: To fully remove a Webgate and related filters from IIS, you must do more than simply remove the filters from the list in IIS. IIS retains all of its settings in a metabase file. On Windows 2000 and later, this is an XML file that can be modified by hand. There is also a tool available, MetaEdit, to edit the metabase. MetaEdit looks like Regedit and has a consistency checker and a browser/editor. To fully remove a Webgate from IIS, use MetaEdit to edit the metabase.

ISA Proxy Servers

On the ISA proxy server, all ISAPI filters must be installed within the ISA installation directory. They can be anywhere within the ISA installation directory structure:

Starting Webgate 10g Installation

The following procedure walks through the steps, which are the same regardless of Web server type.

Installation options are identified and can be skipped if they do not apply to your environment. During Webgate installation, information is saved at specific points. You can cancel Webgate installation processing if needed. However, if you cancel Webgate installation after being informed that the Webgate is being installed, you must uninstall the component.

Note:

On HP-UX and AIX systems, you can direct an installation to a directory with sufficient space using the -is:tempdir path parameter. The path must be an absolute path to a file system with sufficient space.

To start Webgate 10g installation

On the computer to host Webgate 10g, log in as a user with Web server Administrator privileges.

Requesting or Installing Certificates for Secure Communications

Webgate Certificate Request: Generates the request file (aaa_req.pem), which you must send to a root CA that is trusted by the OAM 11g server. The root CA returns signed certificates, which can then be installed for Webgate.

Requested certificates must be copied to the \Webgate_install_dir\access\oblix\config directory and then the Webgate Web server should be restarted.

Install a Certificate During Installation: Specify the full paths to the following files, then click Next:

Webgate_install_dir\access\oblix\config

cacert.pem the certificate request, signed by the Oracle-provided openSSL Certificate Authority

password.xml contains the random global passphrase that was designated during installation, in obfuscated format. This is used to prevent other customers from using the same CA. Oracle Access Manager performs an additional password check during the initial handshake between the OAM Agent and OAM Server.

Specifying Webgate Configuration Details

You perform the following task using information provided during Webgate provisioning and registration with OAM 11g.

To provide Webgate configuration details

Provide the information requested for the Webgate as specified in the Access System Console.

Webgate ID—Enter the agent name that you supplied during registration.

Webgate password—Enter the password supplied during registration, if any. If no password was entered, leave the field blank.

Access Server ID—Enter the name of the OAM 11g Server with which this Webgate is registered, if desired, or use any name you choose.

Access Server Host Name—Enter the DNS host name for the OAM 11g Server with which this Webgate is registered

Port number—Enter the port on which the OAM Proxy is running. If a port was not entered during provisioning, the default port is 3004.

Click Next to continue.

Updating the Webgate Web Server Configuration

Your Web server must be configured to operate with the Webgate. Oracle recommends automatically updating your Web server configuration during installation. However, procedures for both automatic and manual updates are included.

Note:

To manually update your Web server configuration

Click No when asked if you want to proceed with the automatic update, then click Next.

You might receive special instructions to perform before you continue. Setting various permissions for the /access directory is required for IIS Webgates only when you are installing on a file system that supports NTFS. The last installation panel provides instructions for manually setting various permissions that cannot be set on the FAT32 file system. In this case, these instructions may be ignored.

Sun Web Servers—Be sure to apply the changes in the Web server Administration console before you continue.

A screen announces that the Web server configuration has been updated.

Installing Artifacts and Certificates

The ObAccessClient.xml file is one result of product of provisioning. After Webgate installation, you must copy the file to the Webgate installation directory path. If you received signed Webgate 10g certificates after installing Webgate, you can use the following procedure to install these as well.

Replacing the IAMSuiteAgent with an OAM 10g Webgate

Oracle Access Manager and Oracle Identity Manager are among the Oracle Fusion Middleware 11g components. During initial configuration with the WebLogic Server Configuration Wizard, the IAMSuiteAgent is registered with OAM 11g along with the IDM domain host identifier and an application domain named for the agent.

Oracle Fusion Middleware uses OAM 11g to protected Oracle Identity Management consoles out of the box using the IAMSuiteAgent.

To protect applications beyond containers, you can replace the IAMSuiteAgent with a 10g Webgate (to protect the same set of applications using the same application domain and policies as the pre-registered IAMSuiteAgent).

Provisioning a 10g Webgate to Replace the IAMSuiteAgent

Provisioning is the process of creating a Webgate registration in the Oracle Access Manager Console. The following procedure walks through provisioning using the remote registration tool, in-band mode.

See Also:

Chapter 10 for more information about the remote registration tool, processing, and request files

In this example, OAMRequest_short.xml is used as a template to create an agent named 10g4IDM, protecting /.../*, and declaring a public resource, /public/index.html. Your values will be different.

Note:

To use IAM Suite policies with the replacement Webgate, ensure that the Webgate registration is configured to use the IAMSuiteAgent Host Identifier and Preferred Host.

To reuse existing IAM Suite policies you can specify IAMSuiteAgent as the hostidentifier in the OAMReqRequest xml for the Webgate registration to set IAMSuiteAgent as the HostIdentifier and preferredHost. Alternatively, you can edit the Agent registration using the Oracle Access Manager Console.

To provision a 10g Webgate to replace the IAMSuiteAgent

Acquire the remote registration tool and set up the script for your environment. For example:

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

ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz

Untar RREG.tar.gz file to any suitable location. For example: rreg/bin/oamreg.

In the oamreg script, set the following environment variables based on your situation (client side or server side) and information in Table 10-7:

Installing a 10g Webgate to Replace the IAMSuiteAgent

After provisioning you must install the 10g Webgate to replace the IAMSuiteAgent. During the installation, you must provide some of the same information for the Webgate as you did when provisioning it.

Updating the WebLogic Server Plug-in

After provisioning and installing the 10g Webgate to replace the IAMSuiteAgent, the mod_wl_ohs.conf file requires specific entries to instruct the Webgate Web server to forward requests to the applications on the WebLogic Server.

Note:

The generic name of the WebLogic Server plug-in for Apache is mod_weblogic. For Oracle HTTP Server 11g, the name of this plug-in is mod_wl_ohs (the actual binary name is mod_wl_ohs.so). Examples show exact syntax for implementation.

Example 27-1 illustrates the areas that must be changed using sample entries. Entries for your environment will be different.

Confirming the AutoLogin Host Identifier for an OAM / OIM Integration

Skip this step if you do not have Oracle Access Manager 11g integrated with Oracle Identity Manager. 11g.

The AutoLogin functionality when Oracle Identity Manager is integrated with OAM 11g requires the 10g Webgate Web server host name and port in the list of host identifiers for the IAMSuiteAgent.

Note:

If you have a load balancer in front of the 10g Webgate Web server, you must also include the load balancer's host name and port during Step 3.

The agentBaseUrl parameter is used to update a given Host Identifier. However, if automatic policy creation is set to false, the remote registration utility does not create the application domain and does not honor the agentBaseUrl parameter.

The following procedure shows how to confirm (or configure) the AutoLogin host identifier for an Oracle Access Manager/Oracle Identity Manager integration. You values will be different.

OID (or OVD) Authenticator: Creates the Subject and populates it with the correct principals.

Depending on the store where your users are located, you configure either the Oracle Internet Directory Authenticator or the Oracle Virtual Directory Authenticator as the primary credential authenticator.

Default Authenticator: This default WebLogic Authentication provider allows you to manage users and groups in one place: the embedded WebLogic Server LDAP server. This Authenticator is used by the Oracle WebLogic Server to login administrative users:

When you configure multiple Authentication providers, you use the JAAS Control Flag for each provider to control how the Authentication providers are used in the login sequence. You can choose the following the JAAS Control Flag settings, among others:

REQUIRED—The Authentication provider is always called, and the user must always pass its authentication test. Regardless of whether authentication succeeds or fails, authentication still continues down the list of providers. The OAM Identity Asserter is required.

SUFFICIENT—The user is not required to pass the authentication test of the Authentication provider. If authentication succeeds, no subsequent Authentication providers are executed. If authentication fails, authentication continues down the list of providers. Both the Oracle Internet Directory (or Oracle Virtual Directory) and the Default Authenticator are sufficient.

OPTIONAL—When additional Authentication providers are added to an existing security realm, the Control Flag is set to OPTIONAL by default. You might need to change the setting of the Control Flag and the order of providers so that each Authentication provider works properly in the authentication sequence.

The user is allowed to pass or fail the authentication test of this Authentication provider. However, if all Authentication providers configured in a security realm have the JAAS Control Flag set to OPTIONAL, the user must pass the authentication test of one of the configured providers.

Oracle Access Manager JAR are WAR files for authentication providers are available when you install an Oracle Fusion Middleware product (Oracle Identity Management, Oracle SOA Suite, or Oracle WebCenter). If you have a Fusion Middleware application, you already have the files you need.

oamAuthnProvider.jar: Includes files for both the Oracle Access Manager Identity Asserter for single sign-on and the Authenticator for Oracle WebLogic Server 10.3.1+. A custom Oracle Access Manager AccessGate is also provided to process requests for Web and non-Web resources (non-HTTP) from users or applications.

oamauthenticationprovider.war: Restricts the list of providers that you see in the Oracle WebLogic Server Console to only those needed for use with Oracle Access Manager.

When you deploy the extension, the Administration Console creates an in-memory union of the files and directories in its WAR file with the files and directories in the extension WAR file. Once the extension is deployed, it is a full member of the Administration Console: it is secured by the WebLogic Server security realm, it can navigate to other sections of the Administration Console, and when the extension modifies WebLogic Server resources, it participates in the change control process For more information, see the Oracle Fusion Middleware Extending the Administration Console for Oracle WebLogic Server.

Setting Up Security Providers for the 10g Webgate

The following procedure requires the WebLogic Server Administration Console. This example illustrates setting up the Oracle Internet Directory provider with the OAM Identity Asserter and Default Authenticator. The steps are the same for OVD, should you need this.

Note:

If you have a Fusion Middleware application, you already have the files you need and you can skip Step 1 of the following procedure. With no Fusion Middleware application, however, you have a stand-alone Oracle WebLogic Server and must obtain the JAR and WAR files from Oracle Technology Network as described in Step 1.

Not Successful: Confirm that all providers have the proper specifications for your environment, are in the proper order, and that oamAuthnProvider.jar is in the correct location as described in "About Security Providers".

Disabling the IAMSuiteAgent

This step is optional, not required. The IDMDomain Agent detects when the Webgate has performed the authentication and then goes silent. However, if the agent must be disabled, then either the WLSAGENT_DISABLED system property or environment variable must be set to true for each one of the servers on which the agent should be disabled. This applies to both AdminServer and OAM Servers.

On the computer hosting the IAMSuiteAgent, perform one the following tasks:

Either set the WLSAGENT_DISABLED environment variable to true:

setenv WLSAGENT_DISABLED true

Or or pass DWLSAGENT_DISABLED=true as a System Property:

-DWLSAGENT_DISABLED=true

Restart the Web server.

Verification

Oracle recommends testing your environment using the 10g Webgate to ensure that all applications that were previously protected by the IAMSuiteAgent are now protected after configuring the 10g Webgate.

Deploying Applications in a WebLogic Container

This section provides information about deployments that currently have (or will have) applications deployed in a WebLogic container:

Removing a 10g Webgate from the OAM 11g Deployment

Use the following procedure to remove the 10g Webgate from the OAM 11g deployment, if needed.

Note:

Deleting an agent registration does not remove the associated host identifier, application domain, resources, or the agent instance.

Considerations

Web Server Configuration Changes: Web server configuration changes must be manually reverted after uninstalling the Webgate). For more information about what is added, see the appropriate chapter for your Web server.

Webgate IIS Filters: To fully remove a Webgate and related filters from IIS, you must do more than simply remove the filters from the list in IIS. IIS retains all of its settings in a metabase file. On Windows 2000 and later, this is an XML file that can be modified by hand. For more information, see "Removing a 10g Webgate from the OAM 11g Deployment".

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 uninstall the 10g Webgate

Turn off the Web server for the Webgate you will remove.

Note:

If you don't turn off the Web server, uninstall might fail and the backup folder will not be removed. If this happens, you need to manually remove the backup folder.

On the Webgate registration page in the Oracle Access Manager Console, click the Disable box beside the State option to disable the Webgate.