| 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 configure the Apache v1.3 Web server for Oracle Access Manager. 10g (10.1.4.0.1) Web components (WebPass, Policy Manager, WebGate) also provides support for Oracle HTTP Server (OHS) 10g R2 (10.1.2).
|
Note: The Oracle HTTP Server (OHS) implementation is based on open source Apache v1.3. |
The following topics are included:
Apache v1.3, Oracle HTTP Server (OHS), and Stronghold Requirements
Updating Web Server Configuration for Oracle Access Manager Web Components
OHS is an Internet Web server extension that identifies Oracle Access Manager Web components that communicate with the Oracle HTTP Server (OHS). Oracle Access Manager 10g (10.1.4.0.1) provides WebPass, Policy Manager, and WebGate components that can be installed on a standalone Oracle HTTP Server on Linux and Windows platforms. You may use the OHS Web components for any application; however, there are some specific requirements you should be aware of:
An OHS WebGate must be installed on the Oracle Application Server to enable integration with Oracle single sign-on as described in the Oracle Access Manager Integration Guide.
OHS WebPass and OHS Access Manager (Policy Manager) components may be used with the Oracle Application Server. However, Apache WebPass and Apache Policy Manager are also supported for this application.
OHS 10g R2 (10.1.2) is based on Apache v1.3. See the Oracle HTTP Server Administrator's Guide 10 g R2 (10.1.2) for complete details about OHS, including:
Differences between the Oracle implementation and the open source Apache product on which it is based
Oracle HTTP Server directory structure, configuration files and syntax, modules, and directives
Managing server processes, network connections, and security features
Be sure to familiarize yourself with the following OHS Web component caveats. See also "Setting OHS Client Certificates".
When using Oracle Access Manager 10g (10.1.4.0.1) Web components for OHS, be sure to take these caveats into account for Linux:
The LD_ASSUME_KERNEL=2.4.19 environment variable must be set for Linux at runtime because the older Linux threading model is supported (not the native posix thread library (NPTL))
Policy Manager communication to the directory server in SSL mode on Linux is not supported
When installing Oracle Access Manager Web components for Apache or OHS on Linux, you are prompted to install as the same user under which the Web server is running. See the User and Group directive entries in the httpd.conf file.
This section explains how Apache's process-based architecture affects various Oracle Access Manager Web components:
For Identity Servers communicating with WebPass for Apache v1:
Each WebPass instance connects to the Identity Server.
Each connection takes up system sources, and each connection has n file descriptors.
Set the tuning parameters for Apache so that Apache does not need to start or stop processes too frequently. These settings would be similar with or without Oracle Access Manager.
With Policy Managers for Apache v1:
Each Web server process is an instance of the Policy Manager application.
Each application maintains its own connections to the directory server. This may not directly affect performance. However, there may be a limit on the directory server side that you may want to consider when other directory server clients are involved.
Multiple processes respond to a user's request (multiple HTTP events are triggered to build the frames).
Latency of responses cannot be predicted.
Fewer processes are better from a UI perspective, but this affects the number of concurrent users.
With WebGate for Apache v1:
There is no shared cache between processes.
Each process maintains its own connections to the Access Server.
Because each process has its own connection, you should limit the number of WebGate connections. This issue is partially affected by the performance of the systems running the Web servers and Access Servers.
Reverse proxy capability may be enabled for Apache Web servers on Solaris and Linux platforms.
Apache v1.3 is a process-based Web server. The Apache Web server creates a client process with the filters configured to process each request. As a result, each client process will have a WebGate included in it.
If the Apache Web server is configured to use 250 MaxClients (at peak load), there will be 250 WebGates in execution when all these processes execute. Each WebGate will use the connection configuration specified in the WebGate definition. For example, if the WebGate configuration has 4 connections to an Access Server, each of the client process will create 4 connections to the Access Server configured. So, at peak load, there would be 250 * 4 = 1000 connections to the Access Server.
At the Access Server, each connection corresponds to a Message Thread, which reads client requests from the sockets. At peak load, it would have 1000 threads just to process requests from 1 WebGate with the above configuration. If there were multiple Apache v1.3 Web servers are configured to go to an Access Server, this number would be the sum of connections from each such Web server. The effect of this would be a large number of threads in the Access Server.
As the number of threads in a process increase, the overhead with respect to CPU utilization, memory utilization increases. Some operating systems would start thrashing if the number of threads is overwhelming, which negatively impacts Access Server performance.
The Apache v1.3 Web server creates and destroys client processes based on the request load. It load balances the requests among the child processes, As a result, each child process will have, at most, 1 request to process for which it requires only one connection to one of the Access Servers.
You could configure 2-3 Access Servers for a WebGate so that the load on the Access Servers from this WebGate is balanced. For example:
In the case above:
However, connection 1 to AccessServer2 and AccessServer3 may not be used if, during the life of the child process only, 1 request is sent to WebGate1 from the Web server.
To summarize, in a multi-process Web server such as Apache v1.3, you need only one connection to an Access Server.
In the case of Apache v2, the Web server can be configured to operate in 2 mpm modes: worker_mpm, pre-fork_mpm. Worker_mpm creates threads in the Web server for load balancing requests. In this case ThreadsPerChild and MaxClients are used to determine how many processes are spawned. The maximum number of active child processes is determined by the MaxClients directive divided by the ThreadsPerChild directive. Each process will have a webgate in it. In pre-fork mpm case, it behaves like Apache v1.3, creating 1 child process per request. For more information, see Chapter 17, "Configuring Apache v2, IHS, and OHS Web Servers for Oracle Access Manager".
Oracle Access Manager 10g (10.1.4.0.1) HTML pages use UTF-8 encoding. Apache-based Web servers allow administrators to specify a default character set for all HTML pages sent out using the AddDefaultCharset directive. This directive overrides any character specified by the application generating the HTML pages. If the AddDefaultCharset directive enables a character set other than UTF-8, Oracle Access Manager HTML pages are garbled.
Oracle recommends that you specify the AddDefaultCharset directive in the Web server configuration file (httpd.conf) as follows to ensure the correct display of Oracle Access Manager 10g (10.1.4.0.1) HTML pages:
AddDefaultCharset Off
See your Web server documentation for more information about this directive.
In addition, your system must also meet these requirements to implement an Apache v1.3, OHS, or Stronghold Web server:
Dynamic Shared Object (DSO) support for WebGate and WebPass. On Apache, this means that mod_so must be enabled.
|
Note: DSO is required for all Oracle Access Manager plug-ins. |
Multi-threading is required for WebPass.
When WebGate and WebPass are installed on the same Web server, DSO and multi-threading for WebPass are required.
Building the Apache Web server requires access to the gcc and make commands in your path. Alternatively, you can use another ANSI-compliant C compiler.
Reverse proxy capability may be enabled for Apache Web servers on Solaris and Linux platforms.
When installing Oracle Access Manager Web components for Apache or OHS on Linux, you are prompted to install as the same user under which the Web server is running. See the User and Group directive entries in the httpd.conf file.
Recent versions of Apache v1.3 contain important security fixes. It is strongly recommended that you use the most recent release of Apache 1.3. For details, see:
The base Apache 1.3 Web server does not use SSL for browser connections (responding to https:// requests). An add-on module for SSL support known as mod_ssl is available at:
The Oracle Access Manager plug-ins for base Apache servers are different from those for Apache with mod_ssl (also referred to as using EAPI) in following:
Oracle Access Manager supports Apache with mod_ssl only.
|
Note: openssl is needed by mod_ssl when building Apache to support SSL. openssl should be part of the Apache server built with mod_ssl. |
No SSL-specific features of Oracle Access Manager operate with the version of Apache 1.3 known as Apache-SSL.
For complete details about OHS, see the Oracle HTTP Server Administrator's Guide 10g R2 (10.1.2). For Oracle Access Manager 10g (10.1.4.0.1) support details, see the Certify tab on the following site:
Navigate to http://metalink.oracle.com.
Log in to MetaLink as directed
Click the Certify tab.
Click View Certifications by Product.
Select the Application Server option and click Submit.
Choose Oracle Application Server and click Submit.
IHS (the IBM HTTP Server powered by Apache) is a variation of Apache 1.3. IHS uses a different implementation of SSL. Oracle Access Manager supports both the base IHS (non-SSL) and the IHS SSL plug-in interface.
For more information, see "Preparing for Installation" and "Downloading and Compiling the Base Apache Web Server".
This discussion applies only to Apache open source v1.3. You can download the latest version of Apache 1.3 from the Apache Web site:
The SSL plug-in mod_ssl is available from:
These sites point you to other sites for any additional software needed by Apache or mod_ssl (such as openssl). Instructions for compiling the Apache Web server are included with the software distribution.
In order for the Apache Web server to support Oracle Access Manager plug-ins, the module mod-so must be compiled into the server binary.
To compile Apache or Apache with mod_ssl with mod-so:
Include the configuration option before compiling:
--enable-module=so
Ensure the configuration meets other Oracle Access Manager requirements and compile.
The following URL contains information about the latest version of Apache and a link to pick up binary files for the Apache server:
The following links provide information on building an Apache release and source code:
For the latest support details, see OracleMetaLink or Oracle Technology Network (OTN) at the following sites:
If you do not find a solution for your problem, log a service request
Apache source code—http://www.apache.org/dist/httpd
Mod_SSL source code—http://www.modssl.org/source/
OpenSSL source code—http://www.openssl.org/source/
What is ApacheSSL—http://www.apache-ssl.org/#What_is_Apache-SSL
Compiling and Installing Apache 1.3—http://httpd.apache.org/docs/install.html
ApacheSSL build instructions for Win32—http://www.galatea.com/flashguides/apache-ssl-win32.xml
How to build an Apache Unix release—http://httpd.apache.planetmirror.com/dev/how-to-release.html
How to build a release of Apache for Windows—http://httpd.apache.planetmirror.com/dev/how-to-release-win32
Some operating systems require additional options during configuration. Some options listed here may be redundant for some releases of Apache 1.3 but are necessary for other releases.
The following are environment settings for the operating system configuration command for your platform:
Solaris:
CFLAGS=-D_REENTRANT LDFLAGS=-lpthreads
AIX:
CFLAGS=-D_REENTRANT LDFLAGS=-lpthreads
HP-UX:
CFLAGS=-D_REENTRANT LDFLAGS="-lcl -lpthreads"
On HP-UX, you need to use PA-RISC1 compile options (the default).Do not use PA-RISC2 (64-bit) options. When using PA-RISC2, you will receive load errors such as "missing symbol," "bad magic number," or "share object is garbled." Similar errors may also appear under any operating system when loading Apache EAPI (mod_ssl) compiled modules into a plain Apache server.
On AIX, you must set the environment variable AIXTHREAD_SCOPE to the value S (uppercase). Otherwise, there may be a segmentation fault when a worker process exits. This, however, does not affect the delivery of content, authentication, or authorization decisions by WebGate.
Also on AIX, you may wish to place the following directive in the httpd.conf file:
AcceptMutex fcntl
This directive is only supported in Apache 1.3.24 and later. It does not affect the delivery of content, authentication, or authorization decisions by WebGate. However, those familiar with the behavior of Apache on other platforms (through the /server-status URL) may prefer to use this setting.
Oracle Access Manager Web components (WebPass, Policy Manager, and WebGate), must be installed in a specific order. For example:
For more information, see "About the Installation Task".
During installation of Oracle Access Manager Web components (WebPass, Policy Manager, and WebGate), you can choose to update your Apache Web server configuration file (httpd.conf) manually or automatically. Oracle recommends that you update your Web server configuration file automatically. However, if you choose to update httpd.conf manually, instructions are provided.
When installing Oracle Access Manager Web components you are prompted for the location of the Web server configuration file. For Apache, enter the full path to httpd.conf. For example, the httpd.conf file may be found in the Apache_install_dir/conf directory.
If you later need to re-update the httpd.conf file (after Oracle Access Manager Web component installation and the initial Web server configuration update, refer to the config.htm file in Component_install_dir/oblix/apps/common/docs/config.htm, or use the ManageHttpConf program located in Component_install_dir/oblix/tools/setup/InstallTools/ManageHttpConf. Running ManageHttpConf without any options will print instructions on its use.
Apache 1.3 uses a process model for serving multiple http requests at once. This is different from the single process (thread) model employed by other Web servers, which manage several requests simultaneously in one process. Each subordinate Apache worker-process responds to an incoming http request independently of every other worker-process.
Several parameters in the Apache server configuration file (httpd.conf) affect how an Apache server decides to create or destroy worker processes. The following affect the performance of the server:
MaxServers: The number of simultaneous http requests that a system can handle depends on the maximum performance of the system.
Performance Tuning: Performance tuning for a system should be done using an http load generating tool such as the ab program supplied with Apache.
MaxSpareServers: Sets the desired maximum number of idle child server processes. An idle process is one which is not handling a request. If there are more than MaxSpareServers idle, then the parent process will kill off the excess processes.
To preserve as much state as possible in the server, set the MaxSpareServers to a high value. Setting this value to the maximum of 255 keeps all Apache worker-processes available indefinitely, but it does not provide an opportunity for worker-process recycling during low-load periods.
MaxClients: Sets the limit on the number of simultaneous requests that can be supported; more than this number of child server processes will not be created. Any connection attempts over the MaxClients limit will normally be queued, up to a number based on the ListenBacklog directive. Once a child process is freed at the end of a different request, the connection is then serviced.
MaxClientRequests: Apache provides a safety mechanism to prevent a worker process from slowly acquiring too many system resources to be efficient. Setting MaxClientRequests to a value greater than zero limits the number of requests that a worker process can respond to, after which that process exits, to be replaced by a new, fresh worker process as soon as the need arises. This safety mechanism is not unreasonable, but the start-up delay for Oracle Access Manager Web components (also known as plug-ins) is noticeable at the Web browser.
If you use this parameter, set it high enough for end users to rarely notice the startup delay. Oracle Access Manager plug-ins are designed to run under Web servers without this safety mechanism.
MinSpareServers: Sets the desired minimum number of idle child server processes. An idle process is one that is not handling a request. If there are fewer than MinSpareServers idle, then the parent process creates new children at a maximum rate of 1 every second. Use this with the Policy Manager.
|
Note: Setting this directive to some valuem ensures that you will always have at least n + m httpd processes running when you have n active client requests. |
Because of the fact that Oracle Access Manager plug-in initialization is deferred until the first request, using a high value for the MinSpareServers parameter provides minimal advantage. However, it is useful to keep this parameter as high as possible. For dedicated Web server systems, this should pose no great burden.
StartServer: As with the MinSpareServers parameter, the advantage of the StartServers parameter is limited by the delayed initialization of the Oracle Access Manager plug-ins.
Appropriate values for the preceding parameters depend on the expected load and the performance class of the systems involved, including the Access Server and LDAP server.
Apache servers on very high performance systems with high expected loads may be recompiled with a larger limit on the number of worker processes. These systems may see a greater performance impact on the StartServers and MinSpareServers parameters for dealing with sudden load spikes.
You may need to adjust operating system limits for the Access Server for proper operation. In particular, the maximum number of file descriptors available for any one Access Server may need to be increased beyond the default value. Configuring more than one connection between each Apache-based WebGate and an Access Server may quickly exceed this limit.
Policy Manager performance may be impacted by both Apache and Policy Manager configuration parameters. The following factors should be considered when tuning the Policy Manager for Apache:
The idle child processes ensure that a new incoming request is serviced immediately. The more spare child processes, the faster the ramp up.
Each child process opens separate connections to the directory server. The more child processes you have, the more directory server connections you have.
Assuming that each user is using one browser, there are four to five simultaneous requests to the Web server for images and js and HTML from the browser. Assuming that there are four simultaneous users, the total number of simultaneous requests to the Web server is 4 * 5 = 20.
Given these factors, Oracle recommends the following to maintain a balance between how fast a new user is serviced and the number of connections to the directory server:
MaxClients = 25
MinSpareServers = 4
MaxSpareServers = 5
|
Note: The Policy Manager does not open connections on Web Server startup. Instead, the Policy Manager creates connections on the first request. |
To help compensate for any delay when the Policy Manager creates connections, the Policy Manager may be configured such that all directory server connections for all directory server profiles are set to 1. In this case, the Apache configuration may be as follows:
MinSpareServers = 1
MaxSpareServers = 2
MaxServers = 2
In the preceding case, the Policy Manager responds in a reasonable time with some delay on the initial request.
When using the cert_decode and credential_mapping plug-ins, you must ensure that the Access System Client Certificate authentication scheme works properly with SSL-enabled OHS by adding +EarlierEnvVars and +ExportCertData to the existing SSL options in the OHS Web server configuration file. For example:
credential_mapping:
obMappingBase="o=company,c=us",obMappingFilter=
"(&(objectclass=InetOrgPerson)(mail=%certSubject.E%))"
ssl.conf must include:
SSLOptions +StdEnvVars +ExportCertData +EarlierEnvVars
To add ssl options
Locate and open the OHS Web server configuration file with a text editor. For example:
$ORACLE_HOME/Apache/Apache/conf/ssl.conf
In the ssl.conf file, add the following information to existing SSL options. For example:
SSLOptions +StdEnvVars +ExportCertData +EarlierEnvVars
Save the file and restart the Web server.
After installing the Oracle Access Manager Web component for OHS, you need to complete the following steps:
|
Note: As mentioned earlier, before installing Oracle Access Manager Web components for OHS, in the httpd.conf file change user and group to match the user that is installing the component. |
To tune OHS for Oracle Access Manager Web components
Shut down opmn.
In the opmn.xml file, adjust items as follows:
<ias-component id="HTTP_Server">
<process-type id="HTTP_Server" module-id="OHS2">
<environment>
<variable id="LD_ASSUME_KERNEL" value="2.4.19"/>
</environment>
<module-data>
<category id="start-parameters">
<data id="start-mode" value="ssl-disabled"/>
</category>
</module-data>
<process-set id="HTTP_Server" numprocs="1"/>
</process-type>
</ias-component>
In httpd.conf file on the Policy Manager, comment-out the following lines:
#LoadModule perl_module modules/mod_perl.so #LoadModule php4_module modules/mod_php4.so
The following discussions provide information specific to running the Apache server on Unix and Windows:
Starting and stopping an OHS Web server is the same procedure for both v1.3 and v2, on all platforms.
To start the OHS Web server
Locate and change to the following directory:
$ORACLE_HOME\opmn\bin\
From the command line, enter the following command:
opmnctl/startproc process-type=HTTP_Server
To stop the OHS Web server
Locate and change to the following directory:
$ORACLE_HOME\opmn\bin\
From the command line, enter the following command:
opmnctl/stopproc process-type=HTTP_Server
Typically, you perform a single step to start or stop the Apache Web server, as discussed in the following procedures:
To stop your Apache Web server on Unix:
Locate the Apache_install_dir/bin directory.
From the command line, use the apachectl stop command to stop the server:
./apachectl stop
The manner in which you start the apache Web server depends on the manner in which it is running: as a Windows service or as an application. See the procedures that follow.
To stop the Web server running as an application
in the Windows command line, hold down the Control key and then type the letter c.
To stop the Web server running as a Windows service
In the Windows Service window, locate the Web server service name.
Click the Stop icon.
To start the Web server running as a Windows service
Locate the Apache_install_dir/bin directory.
Enter the following command on the command line:
apache.exe –k start
To start the Web server running as an application
In the Windows Service window, locate the Web server service name.
Click the Start icon.
