| Oracle® Access Manager Installation Guide 10g (10.1.4.0.1) Part Number B25353-01 |
|
|
View PDF |
| Oracle® Access Manager Installation Guide 10g (10.1.4.0.1) Part Number B25353-01 |
|
|
View PDF |
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:
Upgrading to 10g (10.1.4.0.1) is described in the Oracle Access Manager Upgrade Guide. For an overview of Oracle Access Manager components, see the Introduction to Oracle Access Manager Introduction.
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. An AccessGate is an Oracle Access Manager access client that processes requests for Web and non-Web resources and is developed using the Software Developer Kit. The terms AccessGate and WebGate may be used interchangeably. Before you can install a WebGate, you must associate it with an Access Server.
Task overview: Adding an instance and installing a WebGate
Create an instance, as described in "Creating a WebGate Instance".
Associate the instance, as described in "Associating a WebGate and Access Server".
Install the WebGate, as described in "Installing the WebGate":
Complete the following procedures as needed:
Manually Configuring Your Web Server(if you did not do this automatically during installation)
Completing IIS WebGate Installations, if needed
Completing httpd.conf Updates, if needed
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 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 from a Earlier Release of Oracle Access Manager". Any caveats are identified and may be skipped when they do not apply to your environment. For more information, see "WebGate Guidelines".
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 follows the same process as described in this chapter.
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" |
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
Navigate to the Access System Console. For example:
http://hostname:port/access/oblix
where hostname refers to machine 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.
Click the Access System Console link, then log in as a Master Administrator.
The Access System Console main page appears.
Click Access System Configuration, then select Add New Access Gate.
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 machine 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.
Print this page, then click the Back button.
Continue with "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.
|
Note: If you are continuing from step 5 above, you may skip step 1. |
To assign an Access Server to the WebGate
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.
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.
Click the Add button to advance to the Add a new Access Server page.
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 server—Your_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".
Click the Add button to complete the association.
A page appears listing the Access Server associated with this WebGate.
Click the link to display a summary and print this page for use later.
Repeat step 3 through step 6 to associate another WebGate and Access Server, if needed.
Logout and continue with "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
The WebGate installation sequence is similar to those you have performed for other Oracle Access Manager components.
Log in as a user with Administrator privileges.
Locate the WebGate installer (including any Access System Language Packs you want to install) in the temporary directory you created.
Launch the WebGate installer for your preferred platform, installation mode, and Web server. For example:
Windows— Oracle_Access_Manager10_1_4_0_1_Win32_API_WebGate.exe
Solaris—./ Oracle_Access_Manager10_1_4_0_1_sparc-s2_API_WebGate
Linux—./ Oracle_Access_Manager10_1_4_0_1_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.
Dismiss the Welcome screen by clicking Next.
Respond to the question about administrator privileges based upon your platform. For example:
Specify the installation directory for the WebGate. For example:
\OracleAccessManager\WebComponent\
Language Pack—Choose a Default Locale and any other Locales to install, then click Next. For example:
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.
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
Choose Open, Simple, or Cert for the WebGate.
Click Next.
You are now asked to specify 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
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 that listens for this WebGate
|
Note: 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. |
Click Next to continue.
Perform the following operations according to the transport security mode you chose earlier:
Open or Simple—Skip to "Updating the WebGate Web Server Configuration".
Certificate—Complete your certificate sequence, then continue with "Updating the WebGate Web Server Configuration".
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.
|
WARNING: 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. |
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
Click Yes to automatically update your Web server, then click Next.
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.
A screen announces that the Web server configuration has been updated.
Sun Web Servers—Be sure to apply the changes in the Web server Administration console before you continue.
IIS Web Servers—You may receive special instructions to perform before you continue.
|
Note: Setting various permissions for the /access directory is required for IIS WebGates only when you are installing on a filesystem that supports NTFS . The last installation panel provides instructions for manually setting various permissions that cannot be set on the FAT32 filesystem. In this case, these instructions may be ignored. |
Stop and restart your Web server to enable configuration updates to take affect.
|
Note: With an IIS Web server, consider usingnet stop iisadmin and net start w3svc after installing the WebGate to help ensure that the Metabase does not become corrupted. |
Click Next and continue with "Finishing the WebGate Installation".
To manually update your Web server configuration
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.
Return to the WebGate installation screen and click Next.
Continue with "Manually Configuring Your Web Server".
The ReadMe information provides details about documentation and Oracle.
To finish the WebGate installation
Review the ReadMe information, then click Next to dismiss it.
Click Finish to conclude the installation.
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.
Continue with the appropriate procedures, as needed. For example:
Manually Configuring Your Web Server (if you did not do this automatically during installation)
Finish by "Confirming WebGate Installation".
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.
|
Note: If the manual configuration process was launched during WebGate installation, you can skip the step 1 in the following procedure. |
To manually configure your Web server for the WebGate
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.
Select from the following supported Web servers.
Follow all instructions that appear, which are specific to each Web server type, and:
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.
Some setups launch a new browser window or require you to launch a Command window to input information, so 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. |
Continue with one of the following, if needed:
On IIS, if you are using client certificate authentication you must enable SSL on the IIS Web server hosting the WebGate before enabling client certificates for WebGate. You must also ensure that various filters are installed in a particular order. In addition, you may need to install the postgate.dll as an ISAPI filter.
Task overview: Completing IIS WebGate installations includes
Use the following procedures as a guide, which reflects the sequence for IIS v5.
To enable SSL on the IIS Web server
Start the Internet Information Services console, if needed: Click Start, Programs, Administration Tools, Internet Information Services.
Expand the local computer to display your Web Sites.
Expand the Default Web Site or the appropriate Web site, then expand \access\oblix\apps\webgate\bin.
Right click cert_authn.dll and select Properties.
Select the File Security tab in the Properties panel.
In the Secure Communications sub-panel, click Edit.
In the Client Certificate Authentication sub-panel, click Accept Certificates and click OK.
Click OK in the cert_authn.dll Properties panel.
If you select client certificate authentication during setup, you must also add the cert_authn.dll as one of the ISAPI filters.
To add cert_authn.dll as an ISAPI filter
Start the Internet Information Services console, if needed: Click Start, Programs, Administration Tools, Internet Information Services.
Expand the local computer to display your Web Sites.
Right click the appropriate Web Site to display the Properties panel.
Click the ISAPI Filters tab, then click the Add button to display the Filter Properties panel.
Enter filter name "cert_authn".
Click the Browse button and navigate to the following directory:
\WebGate_install_dir\access\oblix\apps\webgate\bin
Select cert_authn.dll as the executable.
Click OK on the Filter Properties panel.
Click Apply on the ISAPI Filters panel.
Click OK.
Ensure the filters are listed in the correct order.
It is important to ensure that the WebGate ISAPI filters are included in the right order.
To order the WebGate ISAPI filters
Start the Internet Information Services console, if needed: Click Start, Programs, Administration Tools, Internet Information Services.
Expand the local computer to display your Web Sites.
Right-click the Web Site and select Properties.
Click Properties, select ISAPI filters.
Confirm the following .dll files appear.
For example:
Add any missing filters, if needed, then select a filter name and use the up and down arrows to arrange the filter order as shown in step 5.
|
WARNING: Confirm that there is only one webgate.dll and one postgate.dll filter. |
Following WebGate installation, you may need to install the postgate.dll manually. POST data is required for pass through during a form login on the IIS Web server when using the WebGate extension method (where the WebGate is the action of the form). In other words, if a form authentication scheme on the IIS Web server is configured with the passthrough option, and the target of the login form requires the data posted by the form, the WebGate extension method (where the WebGate DLL is the action of the form) cannot be used. The WebGate filter method (where the action of the form is a protected URL that is not the WebGate DLL) must be used instead, and the postdate DLL must be installed and enabled.POST data is used in an authorization decision that include rule parameters for the AzMan authorization plug-in. In this case, postgate.dll must be installed. The following procedures presume that you are familiar with the IIS Web server commands. Two procedures are provided:
On IIS 6 Web servers only, you must run the WWW service in IIS 5.0 isolation mode. This is required by the ISAPI postgate filter.
To set IIS 5.0 isolation on IIS 6 Web servers
Start the Internet Information Services console, if needed: Click Start, Programs, Administration Tools, Internet Information Services.
Expand the local computer to display your Web Sites.
Right-click the Web Site and select Properties.
Select the Service tab in the Web Site Properties window.
Check the box beside Run WWW service in IIS 5.0 Isolation Mode.
Click OK.
If you perform multiple WebGate installations on one machine, multiple versions of the postgate.dll file may be created which may cause unusual Oracle Access Manager behavior. There can only be one postgate.dll configured at the (top) Web Sites level of a machine. You may have multiple webgate.dlls configured at different levels from the top level Web Sites. However, they share the same postgate.dll. Install the filters in the following order:
The ISAPI Webgate filter should be installed after the sspifitt filter and before any others.
The postgate filter should be installed before the WebGate filter, only if needed.
All other Oracle Access Manager filters can be installed at the end.
|
Note: Before installation (or after uninstallation) the filters must be removed manually. If multiple copies of a filter are installed, this means that they were not manually removed before installing the new filters. |
The following procedures guide as you install and position the postgate ISAPI filter.
To install the postgate ISAPI filter
Start the Internet Information Services console, if needed: Click Start, Programs, Administration Tools, Internet Information Services.
Expand the local computer to display your Web Sites.
Right-click the Web Site and select Properties.
Select the ISAPI Filters tab in the Web Site Properties window.
Click the Add button to display the Filter Properties panel.
Enter the filter name "postgate".
Click the Browse button and navigate to the following directory:
\WebGate_install_dir\access\oblix\apps\webgate\bin
Select postgate.dll as the executable.
Click OK on the Filter Properties panel.
Click Apply on the ISAPI Filters panel.
To restart IIS and reposition the postgate ISAPI filter
Start the Internet Information Services console, if needed.
Right-click your local computer, then select All Tasks, select Restart IIS.
Select the ISAPI Filters tab on the Properties panel.
Select the postgate filter and move it above WebGate, using the up arrow.
For example:
Restart IIS or proceed with "Protecting a Web Site When the Default Site is Not Setup" next.
When you install a WebGate on an IIS Web server that does not have the "Default Web Site" configured, the installer does not create "Virtual Directory -> access", which must be done manually using the following procedure:
To protect a Web site (not the default site)
Start the Internet Information Services console, if needed
Select the name of the Web site to protect.
Right-click the name of the Web site to protect and select New -> Virtual Directory in the menu.
Click Next.
Select Alias: access, then click Next.
Directory: Enter the full path to the /access directory, then click Next.
Select Read, Run Scripts, and Execute, then click Next.
Click Finish.
Restart IIS. For example:
net start w3svcYou must complete the following procedure to update the Apache httpd.conf file after you finish the WebGate installation and automatic Web server updates conclude.
To update the WebGate section in httpd.conf
Locate the updated httpd.conf file on the machine hosting the WebGate.
Ensure the section that loads WebGate in the httpd.conf file appears as shown next (tailored for your environment, which will differ from the example). For example:
#*** BEGIN WEBGATE SPECIFIC ****
# The path to this library may need to be changed to suit your installation
LoadFile
"/home/usr/sparc-s2/obdevsun1_wp_apache/identity/oblix/lib/libgcc_s.so.1"
LoadFile
"/home/usr/sparc-s2/obdevsun1_wp_apache/identity/oblix/lib/libstdc++.so.5"
<IfModule mod_ssl.c>
ObWebGateInstalldir
"/home/usr/sparc-s2/obdevsun1_wp_apache/identity"
ObWebGateMode PEER
Obwebgateload obWebgateModule
"/home/usr/sparc-s2/obdevsun1_wp_apache/identity/oblix/apps/webgate/bin/webgatessl.so"
</IfModule>
<IfModule !mod_ssl.c>
ObWebGateInstalldir
"/home/usr/sparc-s2/obdevsun1_wp_apache/identity"
ObWebGateMode PEER
Obwebgateload obWebgateModule
"/home/usr/sparc-s2/obdevsun1_wp_apache/identity/oblix/apps/webgate/bin/webgate.so"
</IfModule>
<Location /access/oblix/apps/webgate/bin/webgate.cgi>
SetHandler obwebgateerr
</Location>
<Location "/oberr.cgi">
SetHandler obwebgateerr
</Location>
<LocationMatch "/*">
AuthType Oblix
require valid-user
</LocationMatch>
#*** END Oblix NetPoint Specific ****
Use the chmod -r username:groupname directory/file to change the User Name and Group Name of a directory or a file.
When you do this, you need to change the User and Group parameters in the httpd.conf file accordingly.
For more information, see:.
After WebGate installation and Web server updates, you can enable WebGate diagnostics to confirm that your WebGate is running properly.
To enable WebGate diagnostics
Make sure your Identity Server, WebPass Web server, and Access Server are running.
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 machine hosting the WebGate; port refers to the Web server instance port number.
The WebGate diagnostic page should appear. If it does not open, the WebGate is not functioning properly and should be uninstalled and reinstalled.At this point, you are ready to:
Configure Oracle Access Manager, as described in the Oracle Access Manager Identity and Common Administration Guide and Oracle Access Manager Access Administration Guide.
Customize Oracle Access Manager, as described in the Oracle Access Manager Customization Guide.
Integrate third-party products, as described in the Oracle Access Manager Integration Guide.
