Skip Headers
Oracle® Access Manager Installation Guide
10g (
Go to Documentation Home
Go to Book List
Book List
Go to Index
Go to Feedback page
Contact Us


9 Installing the WebGate

This chapter explains how to install WebGate and how to configure the WebGate to work with the Web server. This chapter covers the following topics:

9.1 About WebGate Installation

A WebGate is a Web server plug-in that is shipped out-of-the-box with Oracle Access Manager. The WebGate intercepts HTTP requests from users for Web resources and forwards them to the Access Server for authentication and authorization. WebGate installation packages are found on media and virtual media that is separate from the core components. For more information, see "Obtaining the Latest Installers, Patch Set, Bundle Patch, and Certified Agents".


An AccessGate is an Oracle Access Manager access client that processes requests for Web and non-Web resources. AccessGates are developed using the Software Developer Kit. The terms AccessGate and WebGate may be used interchangeably.

Before you can install any WebGate, you must associate it with an Access Server.

Task overview: Adding an instance and installing a WebGate

  1. Create an instance, as described in "Creating a WebGate Instance".

  2. Associate the instance, as described in "Associating a WebGate and Access Server".

  3. Install the WebGate, as described in "Installing the WebGate"

  4. Perform the following tasks as needed:

  5. Finish by "Confirming WebGate Installation", which is a good practice.

Installing the WebGate is similar to installing the WebPass. There are no directory server details to specify and the WebGate Web server configuration must be updated. Separate Web server-specific installation packages are provided for the WebGate on various platforms. Be sure you choose the one for your environment.


You can install WebGate against the same Web server instance as WebPass and or Policy Manager. This enables you to have WebGate protect all Identity and Policy Manager URLs from un-authenticated access. For details about protecting resources, see Oracle Access Manager Access Administration Guide.

You must complete all procedures for a successful installation. Information is saved at certain points during the installation process. If you cancel the installation after being informed that the WebGate is being installed, you must uninstall the component, as described in "Upgrading an Earlier Release". Any caveats are identified and may be skipped when they do not apply to your environment.

9.1.1 About Installing Multiple WebGates

Oracle recommends you install multiple WebGates for failover and load balancing. Oracle recommends you use the cloning feature to facilitate installation on multiple systems, as described in Chapter 15, "Replicating Components".

Installing multiple WebGates with multiple Web server instances follows the same process as described in this chapter.

You can install multiple WebGates with a single IIS Web server instance, as described in Chapter 19. You can install WebGates with the ISA Server, as described in Chapter 20.

9.2 WebGate Prerequisites Checklist

Before you begin installing the WebGate, confirm that you have completed the tasks in Table 9-1. Failure to complete all prerequisites may adversely affect your Oracle Access Manager installation.

Table 9-1 WebGate Prerequisites Checklist

Checklist WebGate Prerequisites

Review and complete all prerequisites and requirements that apply to your environment, as described in Part I, "Installation Planning and Prerequisites"

Complete all activities in Part II, "Identity System Installation and Setup".

Install, set up, and confirm that you have a working Policy Manager, as described in Chapter 7, "Installing the Policy Manager".

Install and confirm that you have a working Access Server as described in Chapter 8, "Installing the Access Server"

Linux and Solaris: Install the GCC runtime libraries to this computer.

Oracle HTTP Server 11g WebGate: Can be used as any other WebGate and is required to support enterprise-level SSO with Oracle Fusion Middleware 11g as described in the Oracle Fusion Middleware Security Guide 11g Release 1 (11.1.1).

WebGate for Oracle HTTP Server with Oracle Application Server: See "Oracle HTTP Server Web Server Configuration File Issue".

Review Web server specific details in the following topics, as needed:

9.3 Creating a WebGate Instance

Before you install an AccessGate or WebGate, you must define an instance of the new WebGate using the Access System Console. The WebGate ID you specify in the Access System Console must be unique and cannot contain spaces, a colon ":", the pound sign "#", or non-English keyboard characters.

To define a WebGate instance in the Access System Console

  1. Navigate to the Access System Console. For example:


    where hostname refers to computer that hosts the Web server; port refers to the HTTP port number of the WebPass Web server instance; /access/oblix connects to the Access System Console.

    The Access System main page appears.

  2. Click the Access System Console link, then log in as a Master Administrator.

    The Access System Console main page appears.

  3. Click Access System Configuration, then select Add New Access Gate.

  4. Specify the following parameters for your WebGate (also known as an AccessGate) and click Save:

    • AccessGate Name—A unique, descriptive name for this WebGate/AccessGate. Do not include spaces in the name.

    • Description—This is optional; you can add it later. This is case insensitive; if you change capitalization of information in this field it will not be accepted unless you include new information.

    • Hostname—The name of the computer where the WebGate/AccessGate will be installed.

    • Port—The port the WebGate Web server is listening to. For more information, see "WebGate Prerequisites Checklist".

    • AccessGate Password and Re-type AccessGate Password—This is an optional, unique password to verify and identify the component regardless of the transport security mode. This should differ for each WebGate instance.

    • Transport Security—The level of transport security between the Access Server and associated WebGates. The default value is Open. For details see, "Securing Oracle Access Manager Component Communications". You can change the mode later, as described in the Oracle Access Manager Identity and Common Administration Guide.

    • Preferred HTTP Host—This parameter is now required before WebGate installation. It defines how the host name appears in all HTTP requests as users attempt to access the protected Web server. The host name in the HTTP request is translated into the value entered into this field, regardless of the way it was defined in a user's HTTP request.

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

    Details for your WebGate appear and you are asked to associate an Access Server or Access Server cluster with this AccessGate (also known as a WebGate). Buttons at the bottom of this page help you modify the specifications, List Access Servers, or go back to the previous page.

  5. Print this page, then click the Back button.

  6. Continue with "Associating a WebGate and Access Server".

9.4 Associating a WebGate and Access Server

Each Access Server functions as either a primary server or secondary server in association with a WebGate/AccessGate. If this is the only Access Server you are associating with this WebGate it should be a primary server. Multiple primary servers share incoming requests as they arrive. Secondary servers become active only if the primary servers go down. When you have multiple Access Servers, define at least one primary Access Server for this WebGate and define other Access Servers as either primary or secondary servers.

The number of connections identifies the number of Access Servers this WebGate can connect to, and the relative priority of the Access Servers for requests that come through the WebGate. For example, if you have two primary Access Servers and specify 2 connections for the first and 1 connection for the second, the first would receive two requests for every one the second receives. The default is 1. The number of requests the WebGate receives at one time is controlled by the Maximum Connections parameter in the AccessGate Configuration page.


If you are continuing from step 5 in the previous procedure, you can skip step 1.

To assign an Access Server to the WebGate

  1. Navigate to the Details for AccessGate page, if needed: Access System Console, Access System Configuration, AccessGate Configuration, WebGate_Link.

    You may associate this WebGate with an individual Access Server or with a cluster of Access Servers. For information about clusters, see the Oracle Access Manager Access Administration Guide.

  2. On the Details for AccessGate page, click the List Access Servers (or List Clusters) button at the bottom of the page.

    A page appears saying that there are no primary or secondary Access Servers currently configured for this WebGate.

  3. Click the Add button to advance to the Add a new Access Server page.

  4. Select an Access Server from the Select Server list, specify a priority, and define the number of Access Servers (connections) to which this WebGate can connect.

    For example:

    Select serverYour_Choice Select priority—Primary Server Number of connections—1

    If the Access Server you want is not listed, you may need to configure it. For details, see "Creating an Access Server Instance in the System Console".

  5. Click the Add button to complete the association.

    A page appears listing the Access Server associated with this WebGate.

  6. Click the link to display a summary and print this page for use later.

  7. Repeat step 3 through step 6 to associate another WebGate and Access Server, if needed.

  8. Logout and continue with "Installing the WebGate".

9.5 Installing the WebGate

Once you have created a WebGate instance and associated it with an Access Server, you are ready to install the WebGate. Refer to your completed installation preparation worksheets as you complete the following procedures:

Task overview: Installing the WebGate includes

  1. "Starting the Installation"

  2. "Specifying a Transport Security Mode"

  3. "Specifying WebGate Configuration Details"

  4. "Updating the WebGate Web Server Configuration"

  5. "Finishing the WebGate Installation"

9.5.1 Starting the Installation

The WebGate installation sequence is similar to those you have performed for other Oracle Access Manager components.

Be sure to choose the appropriate installation package for your Web server and review Web server-specific details as described in Table 9-1.

To start the installation

  1. Log in as a user with Administrator privileges.

  2. Locate the WebGate installer (including any Access System Language Packs you want to install) in the temporary directory you created.

  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. For example ISAPI for IIS Web servers.

    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.

  4. Dismiss the Welcome screen by clicking Next.

  5. Respond to the question about administrator privileges based upon your platform.

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


  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 is installed, which may take a few seconds. On Windows systems, a screen appears informing 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.

9.5.2 Specifying a Transport Security Mode

Transport security between all Access System components (Policy Managers, Access Servers, and associated WebGates) must match: either all open, all Simple mode, or all Cert.

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.

9.5.3 Specifying WebGate Configuration Details

It's a good idea to refer to the printed pages from your Access System Console as you complete the following procedure. During this sequence, you are asked to provide details about your WebGate and its associated Access Server.

To provide WebGate configuration details

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

    • WebGate ID—The unique ID specified in the Access System Console

    • WebGate password—The password you defined in the Access System Console (if no password was entered, leave the field blank)

    • Access Server ID—The Access Server ID associated with this WebGate

    • DNS hostname—For the Access Server associated with this WebGate

    • Port number—On which the Access Server listens for this WebGate


      If you specified the Simple transport security mode, you are also asked for the Global Network Protocol pass phrase. If you specified Cert mode, you are asked for the password phrase.

  2. Click Next to continue.

  3. Perform the following operations according to the transport security mode you chose earlier:

    If you requested certificates and they are not ready during this installation, be sure to copy them to the \WebGate_install_dir\access\oblix\config directory and restart the WebGate when they arrive.


The certificate request for WebGate generates the certificate-request file aaa_req.pem. You need to send this WebGate certificate request to a root CA that is trusted by the AAA server. The root CA returns the WebGate certificates, which can then be installed either during or after WebGate installation.

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

To automatically update your Web server configuration

  1. Click Yes to automatically update your Web server, then click Next.

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

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

  3. IIS Web Servers—You may 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.

  4. Stop and restart your Web server to enable configuration updates to take affect.


    With an IIS Web server, consider using net stop iisadmin and net start w3svc after installing the WebGate to help ensure that the Metabase does not become corrupted.

  5. Click Next and continue with "Finishing the WebGate Installation".

To manually update your Web server configuration

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

    ReadMe information appears and a new screen also appears to assist you in manually setting up your Web server for the WebGate.

  2. Return to the WebGate installation screen and click Next.

  3. Continue with "Manually Configuring Your Web Server".

9.5.5 Finishing the WebGate Installation

The ReadMe information provides details about documentation and Oracle.

To finish the WebGate installation

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

  2. Click Finish to conclude the installation.

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

    See Also:

    "SELinux Issues".

  4. Restart your Web server now or at a later time.

    With an IIS Web server, consider using net stop iisadmin and net start w3svc after installing the WebGate to help ensure that the Metabase does not become corrupted.

  5. Continue with the appropriate procedures, as needed. For example:

  6. Finish by "Confirming WebGate Installation".

9.6 Manually Configuring Your Web Server

During WebGate installation you are asked if you want to automatically update your Web server installation. If you selected No, you must do this manually.


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:


    where \WebGate_install_dir is the directory where you installed the WebGate.


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


  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.


      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 one of the following, if needed:

9.7 Confirming WebGate Installation

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

To enable WebGate diagnostics

  1. Make sure your components are running (Identity Server, WebPass Web server, Policy Manager and Web server, Access Server, and WebGate Web server).

  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. For more information, see Chapter 19, "Installing Web Components for the IIS Web Server".

  3. The WebGate diagnostic page should appear.

    • Successful: If the WebGate diagnostic page appears, the WebGate is functioning properly and you can dismiss the page.

    • Unsuccessful: If the WebGate diagnostic page does not open, the WebGate is not functioning properly. In this case, the WebGate should be uninstalled and reinstalled. For more information, see Chapter 22, "Removing Oracle Access Manager" then return to this chapter.

If the installation is successful, you are ready to: