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

Note:

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.

28.1 Prerequisites

Review the latest certification matrix from Oracle Technology Network to locate the latest Webgates for your deployment:

http://www.oracle.com/technology/products/id_mgmt/coreid_acc/pdf/oracle_access_manager_certification_10.1.4_r3_matrix.xls

Ensure that your Oracle Access Manager Console is running and get familiar with:

28.2 Introduction to OAM 10g Agents for OAM 11g

This section provides the following topics:

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

Details for each of the tasks in the following overview are located in "Replacing the IAMSuiteAgent with an OAM 10g Webgate".

28.2.2 About Legacy OAM 10g Deployments and Webgates

Oracle Access Manager 11g Servers support OAM 10g Webgates, which can include:

  • Legacy 10g Webgates currently operating with OAM 10g as described here.

  • Legacy 10g Webgates configured as the Identity Assertion Provider (IAP) for SSO (for applications using IAP 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.

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

  1. Provisioning a 10g Webgate with OAM 11g

  2. Configuring Centralized Logout for 10g Webgate with OAM 11g

  3. Optional: Deploying Applications in a WebLogic Container

28.2.3 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 28-1 outlines these differences.

Table 28-1 Installation Comparison with OAM 10g Webgates

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

  2. Provisioning: Before installation, provision Webgate with OAM 11g as described in "Provisioning a 10g Webgate with OAM 11g".

  3. Associating with OAM Server: Occurs during Webgate registration (task 2 of this sequence).

  4. Installing: Install the 10g Webgate in front of the application (or for Fusion Middleware, in front of the WebLogic Server).

  5. Language Packs: 10g Webgate Language Packs are supported with OAM 11g.

  6. Web Server Configuration: Copy OAM 11g generated files to the Webgate installation directory path to update the Web server configuration.

  7. Certificate Installation: Copy files to the Webgate installation directory path.

  8. Forms: 10g forms provided with 10g Webgates cannot be used with OAM 11g Servers.

    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.

  9. Single Log Out: Configure using information in Chapter 16, "Configuring Centralized Logout for OAM 11g".

  10. Multi-Domain Support: Does not apply with OAM 11g.

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

  2. Provisioning: Before installation, you create a Webgate instance in the Access System Console.

  3. Associating with AAA: Before installation, you associated the Webgate with an Access Server in the Access System Console.

  4. Installing: Using 10g Webgate packages.

  5. Language Packs: 10g Webgate Language Packs could be installed during Webgate installation (or later).

  6. Web Server Configuration: Automatic during Webgate installation (or manually after Webgate installation).

  7. Certificate Installation: You copied files to the Webgate installation directory path.

  8. Forms: Were provided for use in 10g deployments.

  9. Centralized Log Out for OAM 10g.

  10. Multi-Domain Support: Could be configured for OAM 10g.


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.

Task overview: Provisioning and installing a 10g Webgate for OAM 11g

  1. Provisioning a 10g Webgate with OAM 11g

  2. Locating and Downloading 10g Webgates for Use with OAM 11g

  3. Configuring Centralized Logout for 10g Webgate with OAM 11g

  4. Optional: Deploying Applications in a WebLogic Container

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

See Also:

To provision a 10g Webgate for OAM 11g

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

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

      ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz 
      
    2. Untar RREG.tar.gz file to any suitable location. For example: rreg/bin/oamreg.

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


      OAM_REG_HOME = exploded_dir_for_RREG.tar/rreg
      JAVA_HOME = Java_location_on_the_computer
  2. Create the registration request:

    1. Locate OAMRequest_short.xml and copy it to a new file. For example:

      $OAM_REG_HOME/input/OAMRequest_short.xml/
      

      Copy: OAMRequest_short.xml

      To: my-10g-agent1.xml

    2. Edit my-10g-agent1.xml to include details for your environment. For example:

      <OAMRegRequest>
          <serverAddress>http://sample.us.example.com:7001</serverAddress>
          <hostIdentifier>my-10g</hostIdentifier>
          <agentName>my-10g-agent1</agentName>
                        <protectedResourcesList> 
              <resource>/myapp/</resource> 
              <resource>/myapp/.../*</resource> 
                        </protectedResourcesList> 
                        <publicResourcesList> 
              <resource>/public/index.html</resource> 
                        </publicResourcesList> 
                        <excludedResourcesList> 
              <resource>/excluded/index.html</resource> 
                        </excludedResourcesList> 
          <autoCreatePolicy>true</autoCreatePolicy>
          <primaryCookieDomain>.us.example.com</primaryCookieDomain>
          <logOutUrls>
            <url>/oamsso/logout.html</url>
          </logOutUrls>
      </OAMRegRequest>
      
  3. Provision the agent. For example:

    1. Locate the remote registration script.


      Linux: rreg/bin/oamreg.sh

      Windows: rreg\bin\oamreg.bat

    2. From the directory containing the script, execute the script using inband mode. For example:

      $ ./bin/oamreg.sh inband input/my-10g-agent1.xml

      Welcome to OAM Remote Registration Tool!
      Parameters passed to the registration tool are:
      Mode: inband
      Filename: ...
      
    3. When prompted, enter the following information using values for your environment:

      Enter your agent username: userame
         Username:  userame
      Enter agent password: ********
      Do you want to enter a Webgate password?(y/n)
          n
      iv.     Do you want to import an URIs file?(y/n)
          n
      
    4. Review the final message to confirm that this was a successful registration:

      Inband registration process completed successfully! Output artifacts are 
      created in the output folder"
      
  4. Log in to the Oracle Access Manager Console and review the new registration:

    1. From the System Configuration tab, Access Manager Settings section, expand the following nodes:


      SSO Agents
      OAM Agents
      10g Agents
    2. Double-click the agent's name to display the registration page and review the details.

      If you will install a fresh Webgate for this registration, you must enter the following details during the installation. For example:

      Agent Name—Enter this as the Webgate ID during Webgate installation.

      Access Client Password—Enter this as the Webgate password during Webgate installation. If no password was entered, you will leave the field blank.

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

    3. OAM Proxy Port—From the System Configuration tab, Common Configuration section, double click Server Instances and locate the port on which the OAM Proxy is running.

  5. Ignore the Obaccessclient.xml file that is created as a result of provisioning for the time being.

  6. Add resources to the application domain

  7. Proceed as needed for your environment:

28.4 Locating and Installing the Latest OAM 10g Webgate for OAM 11g

Use the procedures in this section if you need to install a fresh OAM 10g Webgate for use with OAM 11g. Otherwise, skip this section and proceed to "Configuring Centralized Logout for 10g Webgate with OAM 11g".

Task overview: Installing the Webgate includes

  1. Preparing for a Fresh 10g Webgate Installation with OAM 11g

  2. Locating and Downloading 10g Webgates for Use with OAM 11g

  3. Starting Webgate 10g Installation

  4. Specifying a Transport Security Mode

  5. Specifying Webgate Configuration Details

  6. Requesting or Installing Certificates for Secure Communications

  7. Updating the Webgate Web Server Configuration

  8. Finishing Webgate Installation

  9. Installing Artifacts and Certificates

  10. Confirming Webgate Installation

28.4.1 Preparing for a Fresh 10g Webgate Installation with OAM 11g

Table 28-2 outlines the requirements that must be met before starting an OAM 10g Webgate installation.

Table 28-2 Preparing for 10g Webgate Installation with OAM 11g

About the ... Description

Latest Supported Webgates

Always use the latest supported 10g (10.1.4.3) Webgates with OAM 11g. However, if the desired 10g (10.1.4.3) Webgate is not provided, use the next latest Webgate (10g (10.1.4.2.0).

See Also: "Locating and Downloading 10g Webgates for Use with OAM 11g"

Location for installation

Consider:

  • Webgate in front of the application server.

  • Applications using WebLogic Server container-managed security: In front of the WebLogic Application Server in which your application is deployed

User Accounts

The account that is used to install the Webgate is not the account that runs the Webgate:

  • The 10g Webgate should be installed using the same user and group as the Web server.

  • Unix: You can be logged in as root to install the Webgate. The Webgate can be installed using a non-root user if the Web server process runs as a non-root user

Root Level versus Site Level

  • The Webgate can be installed at the root level or the site level.

  • Installing Webgate on multiple virtual sites amounts to only one instance of Webgate.

Transport Security Mode

Ensure that at least one OAM Server is configured to use the same mode as the agent to be installed.

See Also Appendix E

Computer Level or Virtual Web Server Level

The Webgate can be configured to run at either the computer level or the virtual Web server level. Do not install at both the computer level and the virtual Web server levels.

Oracle HTTP Server Web Server:

The 10g Webgate for Oracle HTTP Server is based on open source Apache. Webgate package names include:

  • OHS (based on Apache v1.3)

  • OHS2 (based on Apache v2)

  • OHS11g (based on Apache v2.2 and is not the subject of this chapter)

Apache Web Servers

Oracle Access Manager 11g provides a single package for components that support Apache with or without SSL enabled:

  • The APACHE2_Webgate supports v2 with or without SSL (and with or without reverse proxy enabled on Solaris and Linux). See also Chapter 29

  • The APACHE22_Webgate supports v2.2 with or without SSL (and with or without reverse proxy enabled on Solaris and Linux). See also Chapter 29

Note: For SSL-enabled communication, Oracle Access Manager supports Apache with mod_ssl only, not Apache-SSL. mod_ssl is a derivative of, and alternative to, Apache-SSL.

IBM HTTP Server (IHS) v2 Web Servers:

IHS2_Webgate is powered by Apache v2 on IBM-AIX. Oracle Access Manager supports IHS v2 and IHS v2 Reverse Proxy servers with or without SSL enabled.

For details, see Chapter 29.

Domino Web Servers:

Before you install the OAM 10g Webgate with a Domino Web server, you must have properly installed and set up the Domino Enterprise Server R5.

See Also: Chapter 32, "Configuring Lotus Domino Web Servers for 10g Webgates".

IIS Web Servers

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.

See Also: Chapter 30, "Configuring the IIS Web Server for 10g Webgates"

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:

  1. Before installing the Webgate on the ISA proxy server:

    Check for general ISAPI filter with ISA instructions on:

    http://msdn.microsoft.com/library/default.asp?url=/library/en-us/isa/isaisapi_5cq8.asp
    

    Ensure that the internal and external communication layers are configured and working properly.

  2. During installation you will asked if this is an ISA installation; be sure to:

    Indicate that this is an ISA proxy server installation, when asked.

    Specify the ISA installation directory path as the Webgate installation path.

    Use the automatic Web server update feature to update the ISA proxy server during Webgate installation.

  3. After Webgate installation, locate the file configureISA4webgate.bat, which calls a number of scripts and the process to configure the ISA server filters that must be added programmatically.

See Also: Chapter 31, "Configuring the ISA Server for 10g Webgates"


28.4.2 Locating and Downloading 10g Webgates for Use with OAM 11g

Use the following procedure to obtain an OAM 10g Webgate, if needed. Be sure to choose the appropriate installation package for your Web server.

To find and download OAM 10g Webgates

  1. Review the latest Oracle Access Manager 10g certification information on the Oracle Technology Network at:

    http://www.oracle.com/technology/products/id_mgmt/coreid_acc/pdf/oracle_access_manager_certification_10.1.4_r3_matrix.xls
    
  2. Go to Oracle Fusion Middleware 11gR1 Software Downloads at:

    http://www.oracle.com/technology/software/products/middleware/htdocs/fmw_11_download.html
    
  3. Click Accept License Agreement, at the top of the page.

  4. From the Access Manager Webgates (10.1.4.3.0) row, click the download link for the desired platform and follow on-screen instructions.

  5. Store the Webgate installer in the same directory with any 10g Access System Language Packs you want to install.

  6. Proceed to "Starting Webgate 10g Installation".

28.4.3 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

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

  2. Stop the Web server instance.

  3. Launch the Webgate installer for your preferred platform, installation mode, and Web server. For example:

    GUI Method

    Windows— Oracle_Access_Manager10_1_4_3_0_Win32_API_Webgate.exe

    Console Method

    Solaris—./ Oracle_Access_Manager10_1_4_3_0_sparc-s2_API_Webgate

    Linux—./ Oracle_Access_Manager10_1_4_3_0_linux_API_Webgate

    where API refers to the API used by your Web server (ISAPI for IIS Web servers, for example).

  4. Dismiss the Welcome screen by clicking Next.

  5. Respond with administrator privileges when asked.

  6. Specify the installation directory for the Webgate. For example:

    \OracleAccessManager\WebComponent\

  7. Linux or Solaris: Specify the location of the GCC runtime libraries on this computer.

  8. Language Pack—Choose a Default Locale and any other Locales to install, then click Next.

  9. Record the installation directory name in the preparation worksheet if you haven't already, then click Next to continue.

    The Webgate installation begins, which may take a few seconds. On Windows systems, a screen informs you that the Microsoft Managed Interfaces are being configured.

    The installation process is not yet complete. You are asked to specify a transport security mode. At this point, you cannot go back to restate information.

  10. Specify the location where you unzipped the previously downloaded GCC libraries, if needed.

28.4.4 Specifying a Transport Security Mode

Transport security between at least one OAM Server must match.

See Also:

Appendix E

To specify a transport security mode

  1. Choose Open, Simple, or Cert for the Webgate.

  2. Click Next.

    You are now asked to specify Webgate configuration details.

  3. Proceed according to your specified transport security mode:

28.4.5 Requesting or Installing Certificates for Secure Communications

If your OAM 11g environment uses Open mode transport security, you can skip to "Updating the Webgate Web Server Configuration".

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.

See Also:

Appendix E

To request or install certificates for Webgate 10g

  1. Indicate whether you are requesting or installing a certificate, then click Next and continue. For example:

    • Requesting a certificate, proceed with step 2.

    • Installing a certificate, skip to step 3.

  2. Request a Certificate:

    • Enter the requested information, then click Next and issue your request for a certificate to your CA.

    • Record certificate file locations, if these are displayed.

    • Click Yes if your certificates are available and continue with step 3. Otherwise, skip to "Updating the Webgate Web Server Configuration".

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

    • aaa_key.pem contains your private key (generated by openSSL).

    • aaa_cert.pem signed certificates in PEM format.

    • Proceed to "Updating the Webgate Web Server Configuration".

28.4.6 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

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

  2. Click Next to continue.

28.4.7 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

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

  2. Review the screen that appears to assist you in manually setting up your Webgate Web server, and see "Manually Configuring Your Web Server".

  3. Return to the Webgate installation screen, click Next, and proceed to "Provisioning a 10g Webgate with OAM 11g".

To automatically update your Web server configuration

  1. Click Yes to automatically update your Web server then click Next (or click No and see "Manually Configuring Your Web Server"):

    • Most Web servers—Specify the absolute path of the directory containing the Web server configuration file.

    • IIS Web Servers—The process begins immediately and may take more than a minute. For more information, see Chapter 30, "Configuring the IIS Web Server for 10g Webgates".

      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.

  2. Click Next and continue with "Finishing Webgate Installation".

28.4.7.1 Manually Configuring Your Web Server

If, during Webgate installation, you declined automatic Web server updates, you must perform the task manually.

Note:

If the manual configuration process was launched during Webgate installation, you can skip Step 1 in the following procedure.

To manually configure your Web server for the Webgate

  1. Launch your Web browser, and open the following file, if needed. For example:

    \Webgate_install_dir\access\oblix\lang\langTag\docs\config.htm

    where \Webgate_install_dir is the directory where you installed the Webgate.

    Note:

    If you choose manual IIS configuration during 64-bit Webgate installation, you can access details in the following path

    Webgate_install_dir\access\oblix\lang\en-us\docs\dotnet_isapi.htm

  2. Select from the supported Web servers and follow all instructions, which are specific to each Web server type, as you:

    • Make a back up copy of any file that you are required to modify during Webgate set up, so it is available if you need to start over.

    • Ensure that you return to and complete all original setup instructions to enable your Web server to recognize the appropriate Oracle Access Manager files.

      Note:

      If you accidentally closed the window, return to step 1 and click the appropriate link again. Some setups launch a new browser window or require you to launch a Command window to input information.

  3. Continue with "Finishing Webgate Installation".

28.4.8 Finishing Webgate Installation

The ReadMe information provides details about documentation and Oracle.

Note:

If you are installing a 64-bit IIS Webgate, see "Finishing 64-bit Webgate Installation" in Chapter 30.

To finish the Webgate installation

  1. Review the ReadMe information, then click Next to dismiss it.

  2. Click Finish to conclude the installation.

  3. Restart your Web server to enable configuration updates to take affect.

    • IIS Web Servers—Consider using net stop iisadmin and net start w3svc after installing the Webgate to help ensure that the Metabase does not become corrupted.

    • Security-Enhanced Linux: Run the chcon commands for the Webgate you just installed on this platform.

  4. Proceed with following topics, as needed, then return to "Installing Artifacts and Certificates":

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

To install artifacts (and certificates) for Webgate 10g

  1. Gather Webgate 10g provisioning artifacts (and certificate files, if needed). For example:

    • ObAccessClient.xml

    • password.xml (if needed)

    • aaa_key.pem (your private key generated by openSSL).

    • aaa_cert.pem (signed certificates in PEM format)

  2. Copy the files to the Webgate host: Webgate_install_dir\access\oblix\config.

  3. Restart the Webgate Web server.

28.4.10 Confirming Webgate Installation

After Webgate installation and Web server updates, you can enable Webgate diagnostics to confirm that your Webgate is running properly.

To review Webgate diagnostics

  1. Confirm OAM 11g components are running.

  2. Specify the following URL for Webgate diagnostics. For example:

    Most Web Servers—http(s)://hostname:port/access/oblix/apps/webgate/bin/webgate.cgi?progid=1

    IIS Web Servers—http(s)://hostname:port/access/oblix/apps/ webgate/bin/webgate.dll?progid=1

    where hostname refers to the name of the computer hosting the Webgate; port refers to the Web server instance port number.

  3. The Webgate diagnostic page should appear.

28.5 Configuring Centralized Logout for 10g Webgate with OAM 11g

OAM 10g agents provide out of the box support for logout in a single DNS domain. To support logout across multiple DNS domains, 10g agents required customization.

With OAM 11g, session management is centralized in the OAM Server is maintained by the OAM Server and Logout support across different DNS domains is supported out of the box. OAM 11g:

  • Clears the ObSSOCookie for the agent

  • Clears the session in the server

With an OAM 11g Server and an OAM 10g Webgate, the application must always invoke /oamsso/logout.html, which:

  • Sets the ObSSOCookie to logged out (by invoking logout on the Webgate)Constructs end_url (as a URL) and redirects to the server logout URL (/oam/server/logout)

For more logout information, see "Configuring Centralized Logout for 10g Webgate with OAM 11g Servers".

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

Task overview: Replacing the IAMSuiteAgent with an OAM 10g Webgate

  1. Provisioning a 10g Webgate to Replace the IAMSuiteAgent

  2. Installing a 10g Webgate to Replace the IAMSuiteAgent

  3. Updating the WebLogic Server Plug-in

  4. Optional: Confirming the AutoLogin Host Identifier for an OAM / OIM Integration

  5. Optional: Configuring OAM Security Providers for WebLogic

  6. Optional: Disabling the IAMSuiteAgent

  7. Verification

28.6.1 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

  • Chapter 9 if you prefer using the Oracle Access Manager Console

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

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

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

      ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz 
      
    2. Untar RREG.tar.gz file to any suitable location. For example: rreg/bin/oamreg.

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


      OAM_REG_HOME = exploded_dir_for_RREG.tar/rreg
      JAVA_HOME = Java_location_on_the_computer
  2. Create the registration request and ensure that the autoCreatePolicy parameter is set to false:

    1. Locate OAMRequest_short.xml and copy it to a new file. For example:

      WLS_home/Middleware/domain_home/oam/server/rreg/bin/oamreg/ 
      

      Copy: OAMRequest.xml

      To: 10g4IAM.xml

    2. Edit 10g4IAM.xml to include details for your environment. For example, if you are changing from the IAMSuiteAgent to a 10g Webgate Agent your request might look like the following:

      <OAMRegRequest>
          <serverAddress>http://sample.us.example.com:7001</serverAddress>
          <hostIdentifier>10g4IAM</hostIdentifier>
          <agentName>10g4IAM</agentName>
          <autoCreatePolicy>false</autoCreatePolicy>
          <primaryCookieDomain>.us.example.com</primaryCookieDomain>
          <logOutUrls><url>/oamsso/logout.html</url></logOutUrls>
          ...retain defaults for remaining elements...
          ...
          ...
      </OAMRegRequest>
      
  3. Provision the agent. For example:

    1. Locate the remote registration script.


      Linux: rreg/bin/oamreg.sh

      Windows: rreg\bin\oamreg.bat

    2. From the directory containing the script, execute the script using inband mode. For example:

      $ ./bin/oamreg.sh inband input/10g4IAM.xml

      Welcome to OAM Remote Registration Tool!
      Parameters passed to the registration tool are:
      Mode: inband
      Filename: ...
      
    3. When prompted, enter the following information using values for your environment:

      Enter your agent username: userame
         Username:  userame
      Enter agent password: ********
      Do you want to enter a Webgate password?(y/n)
          n
      iv.     Do you want to import an URIs file?(y/n)
          n
      
    4. Review the final message to confirm that this was a successful registration:

      Inband registration process completed successfully! Output artifacts are 
      created in the output folder"
      
  4. Log in to the Oracle Access Manager Console and review the new registration:

    1. From the System Configuration tab, Access Manager Settings section, expand the following nodes:


      SSO Agents
      OAM Agents
      10g Agents
    2. Double-click the agent's name to display the registration page and review the details (if you are installing a fresh Webgate, you must enter the following details during installation). For example:

      Agent Name—Enter this as the Webgate ID during Webgate installation.

      Access Client Password—Enter this as the Webgate password during Webgate installation. If no password was entered, you will leave the field blank.

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

    3. OAM Proxy Port—From the System Configuration tab, Common Configuration section, double-click Server Instances and locate the port on which the OAM Proxy is running.

  5. Ignore the ObAccessClient.xml file that is created as a result of provisioning.

  6. Proceed to "Updating the WebLogic Server Plug-in".

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

Prerequisites

Provisioning a 10g Webgate to Replace the IAMSuiteAgent

Task overview: Installing the Webgate includes

  1. Locating and Installing the Latest OAM 10g Webgate for OAM 11g

  2. Replacing the IAMSuiteAgent: Proceed to "Updating the WebLogic Server Plug-in".

28.6.3 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 28-1 illustrates the areas that must be changed using sample entries. Entries for your environment will be different.

Example 28-1 Updates for the 10g Webgate in mod_wl_ohs.conf

<IfModule weblogic_module>
   <Location /oamconsole>
         SetHandler weblogic-handler
         WebLogicHost hostname.us.sample.com
         WebLogicPort    6162
   </Location>
   <Location apmmconsole>
         SetHandler weblogic-handler
         WebLogicHost hostname.us.sample.com
         WebLogicPort    6162
   </Location>
...

</IfModule>

Note:

You need similar Location entries for each of the URIs for all the applications that were earlier accessed directly on the WebLogic Server.

Prerequisites

Installing a 10g Webgate to Replace the IAMSuiteAgent

To update the mod WebLogic configuration for your environment

  1. Locate the mod_wl_ohs.conf file in the following path:

    <OHS-INSTANCE_HOME>/config/OHS/<INSTANCE_NAME>/mod_wl_ohs.conf
     
    
  2. Edit the file to include a Location element for each application URI that was previously accessed directly on the WebLogic Server (see Example 28-1).

  3. Save the file.

  4. Restart the Web server.

  5. Proceed to the following task, as needed:

28.6.4 Confirming the AutoLogin Host Identifier for an OAM / OIM Integration

This topic describes how to confirm (or configure) Oracle Identity Manager (OIM) automatic login functionality when you have Oracle Access Manager integrated with OIM.

Note:

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.

Prerequisites

Updating the WebLogic Server Plug-in

To configure the AutoLogin Host Identifier for an OAM / OIM Integration

  1. From the Policy Configuration tab navigation tree, expand the Shared Components and Host Identifiers nodes, if needed, and select IAMSuiteAgent:


    Shared Components
    Host Identifiers
    IAMSuiteAgent
  2. In the Operations panel, confirm that all host name and port combinations are listed for this Host Identifier.

  3. In the Operations panel, confirm that the host and port of the Web server on which the 10g Webgate is (or will be) configured is listed. If not, add the entry:

    1. Click + button on the Operations panel.

    2. Host Name: Enter the 10g Webgate Web server host name in the Operations panel Host Name column.

    3. Port: Enter the 10g Webgate Web server port number in the Operations panel Port column.

    4. Load Balancer: If you have a load balancer in front of the 10g Webgate Web server, add the load balancer's host name and port in the Operations panel.

    5. Click Apply on the Host Identifier page.

  4. Proceed to "Configuring OAM Security Providers for WebLogic".

28.6.5 Configuring OAM Security Providers for WebLogic

This section describes how to configure the WebLogic Security Providers to ensure Single Sign On using OAM 11g and the 10g Webgate.

Note:

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

Refer to following topics for more information on setting up the security providers for the OAM 10g Webgate.

28.6.5.1 About Security Providers

To complete the Oracle Access Manager 11g SSO configuration when a 10g Webgate is replacing the IAMSuiteAgent requires configuring the following security providers in a WebLogic Server domain:

  • OAM Identity Asserter: Uses token-based authentication and asserts the OAM SSO header and token.

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

See Also:

"Configuring Authentication Providers" in Oracle Fusion Middleware Securing Oracle WebLogic Server for a complete list of Authentication providers and details about configuring the Oracle Internet Directory provider to match the LDAP schema for user and group attributes.

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.

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

Prerequisites

Updating the WebLogic Server Plug-in

To set up providers in a WebLogic Server domain for OAM 10g Webgate with OAM 11g

  1. No Oracle Fusion Middleware Application: Obtain the Oracle Access Manager provider:

    1. Log in to Oracle Technology Network at:

      http://www.oracle.com/technology/software/products/middleware/htdocs/111110_fmw.html   
      
    2. Locate the oamAuthnProvider ZIP file with Access Manager Webgates (10.1.4.3.0):

      oamAuthnProvider<version number>.zip  
      
    3. Extract and copy oamAuthnProvider.jar to the following path on the computer hosting Oracle WebLogic Server:

      BEA_HOME/wlserver_10.x/server/lib/mbeantypes/oamAuthnProvider.jar 
      
  2. With Oracle Fusion Middleware Application Installed:

    1. Locate oamauthenticationprovider.war in the following path:

      ORACLE_INSTANCE/modules/oracle.oamprovider_11.1.1/oamauthenticationprovi
      der.war
      
    2. Copy oamauthenticationprovider.war to the following location:

      BEA_HOME/wlserver_10.x/server/lib/console-ext/autodeploy/oamauthentication
      provider.war  
      
  3. Log in to the WebLogic Server Administration Console and click Security Realms, Default Realm Name, and click Providers.

  4. OAM Identity Asserter: Perform the following steps to add this provider:

    1. Click Authentication, click New, and then enter a name and select a type:

      Name: OAM ID Asserter

      Type: OAMIdentityAsserter

      OK

    2. In the Authentication Providers table, click the newly added authenticator.

    3. Click the Common tab, set the Control Flag to REQUIRED, and click Save

  5. OID Authenticator: Perform the following steps to add this provider.

    1. Click Security Realms, Default Realm Name, and click Providers

    2. Click New, enter a name, and select a type:

      Name: OID Authenticator

      Type: OracleInternetDirectoryAuthenticator

      OK

    3. In the Authentication Providers table, click the newly added authenticator.

    4. On the Settings page, click the Common tab, set the Control Flag to SUFFICIENT, and then click Save.

    5. Click the Provider Specific tab and specify the following required settings using values for your own environment:

      Host: Your LDAP host. For example: localhost

      Port: Your LDAP host listening port. For example: 6050

      Principal: LDAP administrative user. For example: cn=orcladmin

      Credential: LDAP administrative user password.

      User Base DN: Same searchbase as in Oracle Access Manager.

      All Users Filter: For example: (&(uid=*)(objectclass=person))

      User Name Attribute: Set as the default attribute for username in the LDAP directory. For example: uid

      Group Base DN: The group searchbase (same as User Base DN)

      Do not set the All Groups filter as the default works fine as is.

      Save.

  6. Default Authenticator: Perform the following steps to set up the Default Authenticator for use with the Identity Asserter:

    1. Go to Security Realms, Default Realm Name, and click Providers.

    2. Click Authentication, Click DefaultAuthenticator to see its configuration page.

    3. Click the Common tab and set the Control Flag to SUFFICIENT.

    4. Save.

  7. Reorder Providers:

    1. Click Security Realms, Default Realm Name, Providers.

    2. On the Summary page where providers are listed, click the Reorder button

    3. On the Reorder Authentication Providers page, select a provider name and use the arrows beside the list to order the providers as follows:

      OAM Identity Asserter (REQUIRED)

      OID Authenticator (SUFFICIENT)

      Default Authenticator (SUFFICIENT)

    4. Click OK to save your changes

  8. Activate Changes: In the Change Center, click Activate Changes

  9. Reboot Oracle WebLogic Server.

  10. Proceed as follows:

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

You can disable the agent in one of two ways:

  • Either set the WLSAGENT_DISABLED environment variable to true

  • Or pass WLSAGENT_DISABLED as a System Property

Prerequisites

Configuring OAM Security Providers for WebLogic, if needed.

To disable the IAMSuiteAgent

  1. 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
      
  2. Restart the Web server.

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

28.7 Deploying Applications in a WebLogic Container

For details about this topic, see the Oracle Fusion Middleware Application Security Guide.

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

28.8 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

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

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

  3. Language Packs: Remove installed Language Packs (except the one selected as the default Administrator language (locale)) as follows:

    • Locate the appropriate Language Pack file in the component's uninstall directory. For example:


      Webgate_install_dir\uninstIdentityLP_fr-fr
      \uninstaller.exe
    • Run the Language Pack Uninstaller program to remove the files.

    • Repeat this process to remove the same Language Pack from associated components.

    • Stop and restart Webgate Web server to re-initialize proper language support.

    • Repeat this process to remove each Language Pack (except the one selected as the default Administrator language (locale)).

  4. Perform the following steps to remove 10g Webgate configuration data:

    • If you have only one instance of an Oracle Access Manager component, complete step 4 to remove it.

    • If you have multiple instances of a component, see also step 5.

  5. Locate and run the Uninstaller program for the specific component to remove Oracle Access Manager files. For example:

    Webgate_install_dir\access\_uninstWebgate\uninstaller.exe

    Note:

    On UNIX systems, use uninstaller.bin

  6. Multiple Instances: If you have multiple Webgate instances and want to remove one or all of them, you must use a specific method for your platform:

    • Windows: The last component can be uninstalled from Add/Remove programs. Others can be uninstalled by running the uninstall program from the \access \uninstComponent directory.

    • UNIX: You must always run uninstaller.bin.

  7. Remove Oracle Access Manager-related updates to your Web server configuration. For details about specific Web servers, see Chapter 29, Chapter 30, Chapter 31, Chapter 32.

  8. Restart the Web server.

  9. Remove the Webgate_install_dir directory if it remains, especially if you plan to reinstall it.