6 Oracle Adaptive Access Manager Proxy

Oracle Adaptive Access Manager Universal Installation Option (UIO) reverse proxy deployment option offers login risk-based multifactor authentication to Web applications without requiring any change to the application code.

The proxy's main function is to redirect user traffic from the application login flow to the Oracle Adaptive Access Manager login flow.

The UIO Proxy is available for the Apache Web server and Microsoft Internet Security and Acceleration (ISA) Server. In this chapter the Oracle Adaptive Access Manager Proxy for Apache will be referred to as the UIO Apache Proxy; and the Oracle Adaptive Access Manager Proxy for Microsoft ISA will be referred to as the UIO ISA Proxy.

This chapter:

• Explains the use and configuration of the UIO Proxy.

• Provides instructions for both Microsoft Internet Security and Acceleration (ISA) Server and Apache Web server implementations.

The intended audience is for integrators who configure the UIO Proxy to add multifactor authentication to Web applications. An understanding of HTTP request/response paradigm is required to understand the material presented in this document.

The chapter contains the following sections:

• Introduction

• Installing UIO ISA Proxy

• Installing UIO Apache Proxy

• Setting Up Rules and User Groups

• Setting Up Policies

• Configuring the UIO Proxy

• Interception Process

• Configuring Redirection to the Oracle Adaptive Access Manager Server Interface

• Application Discovery

• Samples

For information on configuring OAAM Server, the client-facing multifactor authentication Web application specific to the UIO Proxy deployment, refer to Chapter 8, "Customizing the OAAM Server."

6.1 Introduction

The Introduction section of this chapter contains the following topics:

• Important Terms

• Architecture

• References

6.1.1 Important Terms

For your reference, important terms are defined in this section.

Microsoft ISA

From the Microsoft Web site: "the Internet Security and Acceleration (ISA) Server is the integrated edge security gateway that helps protect IT environments from Internet-based threats while providing users with fast and secure remote access to applications and data."

Universal Installation Option

The Universal Installation Option is the Oracle Adaptive Access Manager integration strategy that does not require any code modification to the protected Web applications. The Universal Installation Option involves placing the UIO Proxy in front of the protected Web applications

Proxy

A proxy is a server that services the requests of its clients by forwarding requests to other servers. This chapter is concerned with the Web proxy, where the proxy handles Web Protocols, mainly HTTP.

Forward Proxy

A forward proxy is an intermediate server that sits between the client and the origin server. To get content from the origin server, the client sends a request to the proxy naming the origin server as the target, and the proxy then requests the content from the origin server and returns it to the client. The client must be specially configured to use the forward proxy to access other sites.

Reverse Proxy

A reverse proxy appears to the client just like an ordinary Web server. No special configuration on the client is necessary. The client makes ordinary requests for content in the name-space of the reverse proxy. The reverse proxy then decides where to send those requests and returns the content as if it were itself the origin. The UIO Proxy running in the Microsoft Internet Security and Acceleration (ISA) Server is an example of a reverse proxy.

OAAM Server

OAAM Server is the Web application component of Oracle Adaptive Access Manager. The UIO Proxy redirects the client browser to OAAM Server for tracking and authentication purposes as defined by the UIO Proxy XML configuration.

6.1.2 Architecture

The following diagrams show a typical UIO Proxy deployment.

The first diagram shows a Web application before the UIO Proxy is deployed to provide multifactor authentication.

Figure 6-1 Before the Oracle Adaptive Access UIO Proxy

The second diagram shows various components added after the UIO Proxy deployment.

Figure 6-2 After UIO Proxy Deployment

The UIO Proxy intercepts the HTTP traffic between the client (browser) and the server (Web application) and performs the appropriate actions, such as redirecting the traffic to OAAM Server, to provide multifactor authentication and authorization. OAAM Server, in turn, communicates with OAAM Admin to assess the risk, and then takes the appropriate actions, such as permitting the login, challenging the user, blocking the user, and other actions.

6.1.3 References

For information on installing and configuring the Microsoft ISA server, refer to the refer to the relevant Microsoft documentation on Microsoft ISA Server setup. Web publishing rule creation and listener creation are explained further in this document.

For more information about the Apache HTTP Server, refer to the Apache HTTP Server 2.2 documentation at:

http://httpd.apache.org/docs/2.2

6.2 Installing UIO ISA Proxy

The UIO ISA Proxy uses the API provided by Microsoft ISA Server to monitor the HTTP traffic and perform various actions. Refer to the Microsoft ISA Server setup documentation for the details on installing and configuring the ISA server. For a successful installation of the UIO Proxy, a .NET framework 2.0 or better should to be installed. Install all the recommended updates from Microsoft on the machine.

Install Microsoft ISA Server 2006 Standard Edition and create Web publishing rules for the Web applications before installing the UIO Proxy.

This section provides:

• Information on creating Web publishing rules and listeners so that Web applications and OAAM Server can be accessible from the Internet.

  • Section 6.2.1, "UIO Proxy Web Publishing Configuration."

• Instructions on installation and programming information for the UIO ISA Proxy.

  • Section 6.2.2, "Registering the UIO ISA Proxy DLL."

  • Section 6.2.3, "Settings to Control the UIO Proxy."

6.2.1 UIO Proxy Web Publishing Configuration

The purpose of this section is to explain the creation of Web publishing rules and listeners in Microsoft ISA for Adaptive Access Manager applications. It is intended for integrators who install and configure Microsoft ISA to support multiple Web applications.

6.2.1.1 Web Listener Creation

For details on creating a Web listener, refer to the relevant Microsoft documentation. This section provides an outline.

1. For the Web Listener Name, enter Bharosa Proxy Listener.

2. Select SSL secure connection as the type of connection the Web listener establishes with clients.

3. For the Web Listener IP Addresses, choose external, internal, and local host.

4. Choose a single certificate for the Web Listener and select the certificate.

5. Specify that you do not want authentication for how clients validate their credentials.

6.2.1.2 Web Publishing Rule Creation

In a typical deployment, Web applications and OAAM Server run on machines in an internal network and are not directly accessible from the Internet.

In the case of the UIO ISA Proxy, only the UIO Proxy machine, which runs Microsoft ISA Server, is accessible from the Internet.

Publish the following via Web publishing rules in the Microsoft ISA Server:

• OAAM Server

• Web applications

You need to set two (at least) rules: one for the main application and another for OAAM Server.

For detailed instructions on publishing rules, refer to the relevant Microsoft documentation. The following tips are provided for your reference.

6.2.1.2.1

Web Publishing Rule Creation for OAAM Server

To create a new Web publishing rule for OAAM Server you must access Microsoft ISA Server's Web publishing rule wizard and follow the on-screen instructions.

1. For the name of the rule, enter a name such as Bharosa OAAM Server.

2. Choose to allow incoming requests matching the rule conditions.

3. Choose to publish a single Web site or a load balancer in front of several servers.

4. Choose SSL as a connection option if the Web application is listening on SSL; otherwise, choose the non-secured connection option.

5. For the internal site name, provide the machine name where the Web server runs.

   Translate the public name into the internal name.

6. If the IP address or the machine name of the Web application to be published is known, select the option to use the computer name or IP address and provide that information.

7. If you want to include all files and subfolders within a folder, enter /* for the name of the file or folder you want to publish. If you need to publish more than one file or folder, enter only the first file/folder instead. The remaining files can be entered later by editing the rule. Later you enter the path you entered here for your public details.

8. For your Web listener, select Bharosa Proxy Listener.

9. For authentication delegation, select no delegation and that client cannot authenticate directly.

10. Make sure you are able to apply the rule to requests from all users.

Check the properties for your newly created rule by accessing the rule properties.

1. If more than one file or folders need to be published, add all paths.

2. If you have more than one domain name to access the application, add all the domain names.

6.2.1.2.2 Web Publishing Rule Creation for Protected Web Applications

To create a new Web publishing rule for Web applications, you must access Microsoft ISA Server's Web publishing rule wizard and follow the onscreen instructions.

1. For the name of the rule, enter a name such as Online Banking Application.

2. Choose to allow incoming requests matching the rule conditions.

3. Choose to publish a single Web site or a load balancer in front of several servers.

4. Choose SSL as a connection option if the Web application is listening on SSL; otherwise, choose the non-secured connection option.

5. For the internal site name, provide the machine name where the Web server runs.

6. If the IP address or the machine name of the Web application to be published is known, select the option to use the computer name or IP address and provide that information.

7. If you want to include all files and subfolders within a folder, enter /* for the name of the file or folder you want to publish. If you need to publish more than one file or folder, enter only the first file/folder instead. The remaining files can be entered later by editing the rule. Later you enter the path you entered here for your public details.

8. For your Web listener, select Bharosa Proxy Listener.

9. For authentication delegation, select no delegation and that client cannot authenticate directly.

10. Make sure you are able to apply the rule to requests from all users.

Check the properties for your newly created rule by accessing the rule properties.

1. If more than one file or folders need to be published, add all paths.

2. If you have more than one domain name to access the application, add all the domain names.

6.2.2 Registering the UIO ISA Proxy DLL

The UIO ISA Proxy is installed as a Web filter in Microsoft ISA Server. To install the UIO ISA Proxy, follow these steps:

1. Copy the BharosaProxy.dll to the Microsoft ISA Server installation directory, which is by default, %ProgramFiles%\Microsoft ISA Server.

2. Open the command prompt and navigate to the Microsoft ISA Server installation directory

3. Register the BharosaProxy.dll with the following command:

   regsvr32 .\BharosaProxy.dll
   

6.2.3 Settings to Control the UIO Proxy

Various aspects of the UIO ISA Proxy can be controlled using the registry values. All UIO ISA Proxy settings are stored under HKLM\SOFTWARE\Bharosa\Proxy key. Changes to most of the registry values are picked up by the UIO Proxy immediately without requiring a proxy restart.

6.2.3.1 Configuration files

During startup (and during config reload), the proxy loads the configuration from the files listed under the HKLM\SOFTWARE\Bharosa\Proxy\ConfigFiles key.

• The type of each value under this key should be REG_DWORD.

• The name of each value under this key should be the filename containing the UIO Proxy configuration.

• The filename can either be fully qualified or relative to the location of the BharosaProxy.dll.

• The proxy loads a configuration file only if the data has a nonzero value. This can be used to dynamically load and unload proxy configuration files.

• The files is loaded in the lexicographic order of the filenames in the registry.

• Changes under the ConfigFiles key are not effective until either the proxy is restarted or HKLM\SOFTWARE\Bharosa\Proxy\ReloadConfig is set to 1.

6.2.3.2 Configuration Reload

The proxy configuration can dynamically be changed while the proxy is running; new configuration files can be added and currently loaded files can be updated or removed. These changes are not applied until the ReloadConfig registry value is set to a nonzero value. When setting ReloadConfig to a nonzero value, the proxy loads configuration files. After loading the files, the proxy resets the ReloadConfig value to 0.

Note that the new configuration is used only for new client (browser) connections. Clients already connected continue to use the previous configuration.

6.2.3.3 Session ID Cookie

The UIO ISA Proxy uses a cookie to associate multiple requests from a client. The name of this cookie can be configured in the registry value, SessionIdCookieName (of type REG_SZ). If this value is not present or empty, the UIO ISA Proxy uses the cookie name, BharosaProxy_SessionId.

6.2.3.4 Configuring Session Id Cookie attributes via Global Variables

The attributes of the Session Id Cookie can be configured using global variables listed in Table 6-1.

Table 6-1 Session Id Cookie Attributes via Global Variables

Cookie Attribute	Global Variable Name	Description
expires	SessionCookie_ExpiryInMinutes	expires attribute is added to the session cookie if this global variable is set to value greater than 0.This variable specifies the number of minutes the session cookie should be persisted by the client browser.
HttpOnly	SessionCookie_IsHttpOnly	HttpOnly attribute is added to the session cookie if this global variable is set to value greater than 0
secure	SessionCookie_IsSecure	secure attribute is added to the session cookie if this global variable is set to value greater than 0.
domain	SessionCookie_DomainLevelCount	domain attribute is added to the session cookie if this global variable is set. For example, to set the cookie domain as.mydomain.com for an application at test.myserver.mydomain.com, set this global variable to 2. The value should be greater than 1. If a lower value is specified, the proxy uses 2 as the value.

6.2.3.5 Session Inactive Interval

Sessions in the UIO ISA Proxy are removed after a certain period of inactivity. This period, in seconds, is specified in the MaxSessionInactiveInterval registry value. If this value is not specified, the UIO ISA Proxy removes a session after 1200 seconds (30 minutes) of inactivity. This value should be set to at least a few seconds higher than the Web application session timeout value.

6.2.3.6 Settings for Troubleshooting

Trace messages from the UIO ISA Proxy can be used for troubleshooting any issues with the proxy configuration and operation. Trace settings, like trace level and destinations, can be controlled using the registry values under HKLM\SOFTWARE\Bharosa\Proxy. Registry values are shown in Table 6-2.

Table 6-2 Settings for Troubleshooting

Name	Type	Description
TraceFilename	REG_SZ	Full path to the file in which the trace messages should be written to
TraceFileMaxLength	REG_DWORD	Maximum length of the trace file in bytes. Once the trace file reaches this size, the proxy renames the file by adding the timestamp to the filename and create a new trace file to write subsequent trace messages.
TraceToFile	REG_DWORD	Trace messages are written to file only if this value is nonzero.
TraceToDebugTerminal	REG_DWORD	Trace messages are written to debug the terminal only if this value is nonzero. Tools like DbgView can be used to view these trace messages in real time.
TraceLevel	REG_DWORD	Each trace level (debug, info, warning, error) has an integer value associated. The registry value should be set to the sum of desired the trace level values. FATAL 0x1, ERROR 0x2, WARN 0x4 INFO 0x8, DEBUG 0x10, HTML 0x80, FLOW 0x80000
IgnoreUrlMappings	REG_DWORD	If this value is nonzero, the proxy ignores all the interceptors defined in the UIO Proxy configuration. Essentially this places the UIO ISA Proxy in pass-through mode.
CaptureTraffic	REG_DWORD	The proxy does not handle (save, inspect) the HTTP traffic for URLs that don't have interceptors defined in the configuration. But during application discovery process, it is necessary back up of all the HTTP traffic through the proxy. On such occasion, this registry value should be set to nonzero.

6.3 Installing UIO Apache Proxy

To install the UIO Apache Proxy, a new Apache Hypertext Transfer Protocol Daemon (httpd) has to be installed into which the UIO Apache Proxy is installed. This Apache httpd uses the mod_proxy, a module that implements the proxy/gateway/cache, to reverse-proxy (proxy on behalf of the backend application that has to be protected).

The Installation section contains information for installing the UIO Apache Proxy for Windows and Linux platforms.

The installation procedure involves:

• Ensuring that the Apache httpd requirements are met

  See Section 6.3.2, "Apache httpd Requirements."

• Copying the UIO Proxy dlls and supported dlls to specific directories in Apache

  See Section 6.3.3, "Copying the UIO Apache Proxy and Supported Files to Apache."

• Configuring memcache (for Linux only)

  See Section 6.3.4, "Configuring Memcache (for Linux only)."

• Editing the httpd.conf to activate the UIO Proxy

  See Section 6.3.5, "Configuring httpd.conf."

  As part of this section, information is also provide on optionally installing the mod_proxy_html, which is needed to rewrite the HTML links in a proxy situation, to ensure that links work for the users outside the proxy

• Modifying the settings of the UIO Proxy using application configuration XML files

  Section 6.3.6, "Modifying the UIO Apache Proxy Settings."

The post-installation procedures involve:

• Section 6.4, "Setting Up Rules and User Groups."

  Creating a new user to run the UIO Apache Proxy process (on Linux only)

• Section 6.5, "Setting Up Policies."

6.3.1 UIO Proxy Files for Windows and Linux

The UIO Apache Proxy binaries for Windows and Linux are different. Since the UIO Proxy is in C/C++, the same binary do not work on different platforms (unlike Java).

The files are located under $ORACLE_HOME/oaam/oaam_proxyplatform_specific_file.

6.3.1.1 Windows

For Windows, the binary files are listed in Table 6-3.

Table 6-3 Windows Binary Files

Name	Description
mod_uio.so	UIO Apache Proxy module
log4cxx.dll	Apache Log4cxx library
libxml2.dll	XML/HTML Parser
apr_memcache.dll	APR Memcache client library.

The data files are listed in Table 6-4.

Table 6-4 Windows Data files

Name	Description
UIO_Settings.xml	UIO Apache Proxy Settings XML file
UIO_log4j.xml	UIO Apache Proxy Log4j (log4cxx) configuration XML file
TestConfig.xml	UIO Apache Proxy Sample application configuration file
UIO_Settings.rng	Relax NG grammar for UIO_Settings.xml
UIO_Config.rng	Relax NG grammar for application configuration XML files

6.3.1.2 Linux

For Linux, the binary files are listed in Table 6-5.

Table 6-5 Linux Binary Files

Name	Description
mod_uio.so	UIO Apache Proxy module
liblog4cxx.so.0.10.0.0	Apache Log4cxx library
libxml2.so.2.6.32	XML/HTML parser
libapr_memcache.so.0.0.1	APR Memcache client library.

The data files are listed in Table 6-6.

Table 6-6 Linux Data Files

Name	Description
UIO_Settings.xml	UIO Apache Proxy Settings XML file
UIO_log4j.xml	UIO Apache Proxy Sample Log4j (log4cxx) configuration XML file
TestConfig.xml	UIO Apache Proxy Sample application configuration files
UIO_Settings.rng	Relax NG grammar for UIO_Settings.xml
UIO_Config.rng	Relax NG grammar for application configuration XML files

6.3.2 Apache httpd Requirements

The pre-installation steps involved for downloading or building the Apache httpd, depend on the platform, Windows or Linux, and on whether certain requirements are met.

6.3.2.1 Windows

You can download the latest Apache httpd (2.2.8) build for Windows from the Apache Web site.Ensure that:

• the Apache httpd (2.2.8) build is version 2.2.8

• the mod_proxy support is enabled (the standard installation contains the mod_proxy)

• the mod_ssl support is enabled

6.3.2.2 Linux

Instructions to build the Apache httpd are available on the Apache Web site. When you build Apache, ensure that

• the Apache httpd (2.2.8) build is version 2.2.8

• the mod_so is enabled (for dynamically loading modules)

• the mod_proxy is enabled

• the mod_ssl support is enabled

6.3.3 Copying the UIO Apache Proxy and Supported Files to Apache

Instructions are provided in this section for copying the UIO Apache Proxy and support files to specific directories in Apache for both Windows and Linux platforms.

6.3.3.1 Windows

Table 6-7 summarizes:

• The directories you have to copy the UIO Apache Proxy files to after installation

• The tree structure of the UIO Apache Proxy libraries and configuration files, assuming that you installed the files in C:\Apache2.2

• The directories the UIO Apache Proxy binary files go into are listed in Table 6-7.

Table 6-7 Directories for Windows UIO Proxy Binary Files

Directories	File Descriptions
C:\Apache2.2\modules\mod_uio.so	UIO Apache Proxy module
C:\Apache2.2\bin\log4cxx.dll	Apache Log4cxx library
C:\Apache2.2\bin\libxml2.dll	XML/HTML Parser
C:\Apache2.2\bin\apr_memcache.dll	APR Memcache library.

The data files are put in the directories summarized in Table 6-8.

Table 6-8 Directories for Windows UIO Proxy Data Files

Directories	File Descriptions
C:\OAAMUIO\UIO_Settings.xml	UIO Apache Proxy settings XML file
C:\OAAMUIO\UIO_log4j.xml	UIO Apache Proxy Log4j (log4cxx) configuration XML file
C:\OAAMUIO\TestConfig.xml	UIO Apache Proxy application configuration files (any number)
C:\OAAMUIO\UIO_Settings.rng	Relax NG grammar for UIO_Settings.xml
C:\OAAMUIO\UIO_Config.rng	Relax NG grammar for application configuration XML files
C:\OAAMUIO\logs\uio.log	UIO Apache Proxy log

If you want to change the location of the various configuration files, refer to the "Configuring httpd.conf" section.

6.3.3.2 Linux

After the installation of the Apache httpd, you must copy the UIO Apache Proxy binary files into (assuming Apache httpd is installed in /usr/local/apache2) the directories shown in Table 6-9.

Table 6-9 Directories for Linux UIO Proxy Binary Files

Directories	Description
/usr/local/apache2/modules/mod_uio.so	UIO Apache Proxy Module
/usr/local/apache2/lib/liblog4cxx.so.0.10.0.0	Apache Log4cxx Library
/usr/local/apache2/lib/libxml2.so.2.6.32	XML/HTML Parser
/usr/local/apache2/lib/libapr_memcache.so.0.0.1	APR Memcache client library.

Then, create soft links to the libraries as follows:

cd /usr/local/apache2/lib
ln -s liblog4cxx.so.10.0.0 liblog4cxx.so.10
ln -s libxml2.so.2.6.32 libxml2.so.2
ln -s libapr_memcache.so.0.0.1 libapr_memcache.so.0

Also, ensure that the binary files have executable permission.

Apache httpd is typically run as root so that it creates a parent process that listens on port 80, and it spawns handler processes that run as the user given in the User directive in httpd.conf.

For this reason, create a user called oaamuio that is the checkpoint user for the UIO Apache Proxy. The proxy configuration and log files are accessible by this user. Ensure that only this user can access the log files. Assuming /home/oaamuio is the home directory for this user, the directory structure looks like the one presented in Table 6-10.

The UIO Apache Proxy data files should follow the directory structure shown in Table 6-10.

Table 6-10 Directories for Linux UIO Proxy Data Files

Directories	Description
/home/oaamuio/uio/UIO_Settings.xml	UIO Apache Proxy settings XML file
/home/oaamuio/uio/UIO_log4j.xml	UIO Apache Proxy Log4j (log4cxx) configuration XML file
/home/oaamuio/uio/TestConfig.xml	UIO Apache Proxy application configuration files (any number)
/home/oaamuio/uio/UIO_Settings.rng	Relax NG grammar for UIO_Settings.xml
/home/oaamuio/uio/UIO_Config.rng	Relax NG grammar for application configuration XML files
/home/oaamuio/uio/logs/uio.log	UIO Apache Proxy log

If you want to change the location of the various configuration files, refer to the "Configuring httpd.conf" section.

The run-time user of httpd should have the appropriate permissions to access all these files.

6.3.4 Configuring Memcache (for Linux only)

This is an optional configuration that may be needed for Linux deployment of UIO Apache Proxy. The UIO Apache Proxy maintains a session for the user where it keeps local state such as session level variables for the user. On Windows, there is always a single process for Apache httpd server running and so this session information is local to the process. On Linux, you could have multiple Apache httpd server processes running which means the session information cannot be kept local to the process but needs to be centralized. In this case, memcached is used to hold the session information. The following description is to identify when you must use memcached to hold the UIO Apache Proxy session information.

Apache httpd ships with a selection of Multi-Processing Modules (MPMs) which are responsible for binding to network ports on the machine, accepting requests, and dispatching children to handle the requests. On Linux: httpd can run with two different MPMs: httpd with prefork MPM (single-threaded) or with worker MPM (multi-threaded). The MPM is built into the httpd and is not a run-time option.

With prefork MPM, httpd maintains a pool of single-threaded processes, where each request is handled by a single process. In this case, you must configure UIO Apache Proxy to use memcached.

With worker MPM, httpd maintains a pool of multithreaded processes, where every process could be handling multiple requests at a time. In this case, you can configure Apache httpd to launch a single process and avoid using memcached. However, the default configuration launches multiple processes and if you want to keep that unchanged, then you must configure UIO Apache Proxy to use memcached. Here is an example of httpd.conf example that can be used to configure a worker MPM to launch a single process.

# Following forces worker MPM to run 1 process (make sure mod_cgid is
# not loaded, otherwise it starts one more httpd process).
# Basically ThreadLimit=MinSpareThreads=MaxSpareThreads=MaxClients=ThreadsPerChild
# and StartServers=1. Setting MaxRequestsPerChild to 0 ensures that the process is not 
# bounced.
 
<IfModule mpm_worker_module>
 
ThreadLimit 150
StartServers 1
MinSpareThreads 150
MaxSpareThreads 150
MaxClients 150
ThreadsPerChild 150
MaxRequestsPerChild 0
 
</IfModule>

On Windows, httpd MPM is always in multi-threading mode with a single process.

On Linux, in the case where the httpd runs multiple process (irrespective of single or multithreaded), the UIO Apache Proxy session data must be maintained in a common store (database or cache) so that multiple processes can access the session data. The UIO Proxy uses memcache (a memory based very fast cache) to store the session data.

At startup, the UIO Proxy autodetects whether httpd is running with a single process or multiple processes. If httpd is running with multiple processes (which is the case with prefork or worker mpm on Linux), it tries to connect to the memcache daemon using default connection parameters (that are defined in Section 6.3.6.1, "UIO_Settings.xml"). On Windows, by default, the UIO Proxy uses local sessions. It does not connect to the memcache daemon; however it can also be configured to maintain session data in the memcache daemon (explained in Section 6.3.6.1, "UIO_Settings.xml").

For the scenarios where the UIO Apache Proxy is connecting to memcache daemon, you must install memcache on your system using the instructions from the memcache Web site and run the memcache daemon(s) before running the Apache httpd.

Install memcache using instructions at:

http://www.danga.com/memcached

You may already have a binary installation available from your Linux distribution. The UIO Apache Proxy has been tested with version 1.2.5 of memcache.

6.3.5 Configuring httpd.conf

This section provides information on how to edit the httpd.conf file to activate the UIO Apache Proxy. The httpd.conf file is the main configuration file used by the Apache HTTP Server.

6.3.5.1 Basic Configuration without SSL

In the sample installation, the Apache httpd has been installed in c:\ProgramFiles\Apache2.2 or /usr/local/apache2.

To ensure that http.conf is correctly set up in your environment, follow these steps:

1. Ensure that the following lines are uncommented to enable mod_proxy.

   LoadModule proxy_module modules/mod_proxy.so
   LoadModule proxy_http_module modules/mod_proxy_http.so
   

2. Add the following line to the end of the LoadModule group of lines to activate the UIO Apache Proxy.

   LoadModule uio_module modules/mod_uio.so
   

3. Add a line to point to the UIO_Settings.xml file that has the settings for the UIO Apache Proxy.

   Note:

   This should be an absolute path to the UIO_Settings.xml file.

   On Windows (all paths should be with forward slashes),

   UioProxySettingsFile c:/OAAMUIO/UIO_Settings.xml
   

   On Linux,

   UioProxySettingsFile /home/oaamuio/uio/UIO_Settings.xml
   

4. Disable mod_proxy's forward-proxying capability since it is not needed.

   ProxyRequests Off
   <Proxy *>
         Order deny,allow
         Allow from all
   </Proxy>
   

5. Enable the mod_proxy configuration to reverse-proxy to oaam_server and the target application is being protected by OAAM.

   ProxyPass /oaam_server/ 
   http://<FQDN_oaam_server>:<oaam_server_port>/oaam_server/
   ProxyPassReverse /oaam_server/ http://<FQDN_oaam_server>:<oaam_server_port>/oaam_server/
    
   ProxyPass /<target_app>/ http://<FQDN_target_app>:<target_app_port>//<target_appl>
   ProxyPassReverse /<target_app>/ http://<FQDN_target_app>:<target_app_port>/<target_app>
   

6. Set the user/group of httpd using User and Group directives to oaamuio.

The actual settings for #4 and #5 are installation-specific. They are only examples of the settings you must set. For information on setting details, refer to the Apache Web site.

With the changes described and by properly setting up UIO_Settings.xml, you should be able to access OAAM Server (oaam_server) and target application and run Phase One scenarios. The URL for the target application is:

http://<apache-host>:<apache-port>/<target_app>

So far in this chapter, the configuration to the proxy has been performed without using SSL.

6.3.5.2 Configuration with SSL

To enable SSL, refer to the Apache Web site for Tomcat and for Apache procedures.

Note that the UIO Apache Proxy requires mod_ssl to be part of httpd. This ensures that the OpenSSL library is linked in and is properly configured for the UIO Apache Proxy to generate session ids. You need to ensure that mod_ssl is loaded and you do not need to perform any configuration if you are not using SSL.

mod_proxy_html module (optional)

Optionally, you may need to install the mod_proxy_html (http://apache.webthing.com/mod_proxy_html/) Apache module. This module is needed only if the protected application has Web pages that have hard-coded URL links to itself. If the application has relative URLs, you do not need this module.

From their Web site, the executive summary of this module is as follows:

mod_proxy_html is an output filter to rewrite HTML links in a proxy situation, to ensure that links work for users outside the proxy. It serves the same purpose as Apache's ProxyPassReverse directive does for HTTP headers, and is an essential component of a reverse proxy.

For example, if a company has an application server at appserver.example.com that is only visible from within the company's internal network, and a public Web server www.example.com, they may wish to provide a gateway to the application server at http://www.example.com/appserver/. When the application server links to itself, those links need to be rewritten to work through the gateway. mod_proxy_html serves to rewrite <a href="http://appserver.example.com/foo/bar.html">foobar</a> to <a href="http://www.example.com/appserver/foo/bar.html">foobar</a> making it accessible from outside."

6.3.6 Modifying the UIO Apache Proxy Settings

6.3.6.1 UIO_Settings.xml

<UIO_ProxySettings xmlns="http://bharosa.com/">
 
 
 <!-- Log4jProperties location="/home/oaamuio/uio/UIO_log4j.xml"/ -->
       <Log4jProperties location="f:/oaamuio/uio/UIO_log4j.xml"/>
       <Memcache ipaddress="127.0.0.1" port="11211" maxconn="10"/>

       <GlobalVariable name='one" value="something"/>
 
       <ConfigFile location="/home/oaamuio/uio/TestConfig1.xml" enabled="true"/>
       <ConfigFile location="/home/oaamuio/uio/TestConfig2.xml" enabled="false"/>
 
       <ConfigFile location="f:/oaamuio/uio/TestConfig1.xml" enabled="false"/>
 
       <Setting name="GarbageCollectorInterval_ms" value="60000"/>
       <Setting name="MaxSessionInactiveInterval_sec" value="1200"/>
       <Setting name="CachedConfigExpiry_sec" value="120"/>
       <Setting name="SessionIdCookieName_str" value="SessionId"/>

       <Setting name="SessionCookie_ExpiryInMinutes" value="0"/>       <Setting name="SessionCookie_IsHttpOnly" value="0"/>       <Setting name="SessionCookie_IsSecure" value="1"/>       <Setting name="Profiling" value="0"/>
       <Setting name="IgnoreUrlMappings" value="0"/>
       <Setting name="CaptureTraffic" value="0"/>
 
       
<!-- Enable AutoLoadConfig for Windows or Single-process Linux.
 Do not use for Multiple-process Linux when in production.
-->
<Setting name="AutoLoadConfig" value="1"/>
 
<!-- Setting name="UseMemcache" value="1"/ -->

       </UIO_ProxySettings>

Log4jProperties

Set the location of log4j.xml file that defines the logging configuration for the UIO Apache Proxy. The location should be an absolute path; it cannot be ServerRoot relative. On Linux, you have to ensure that the httpd process can access the directory.

When using httpd in a multiprocessing mode, do not use FileAppender; use SocketAppender instead to log the logs from the different processes. Refer to the log4j documentation on the Internet for more information.

GlobalVariable

GlobalVariable is a global variable that is used in the application configuration. You can have any number of such name-value pairs.

ConfigFile

ConfigFile is the absolute path to an application configuration. You can have any number of such configurations. Again, you need to make sure, on Linux, that the httpd process has the permissions to access these files. Refer to "Configuring the UIO Proxy" to understand how to perform a configuration for an application.

Memcache

Memcache has the IP address and port of a memcache server. You can have multiple Memcache elements in the settings file if you have multiple memcache servers running. If you have a single local memcache running, you do not need to have this element at all. By default, the UIO Apache Proxy tries to connect to memcache on IP address 127.0.0.1 and port 11211.

Settings

These are flags to control the behavior of the UIO Apache Proxy. Various settings are listed in Table 6-11.

Table 6-11 OAAM UIO Proxy Settings.

Flags	Description
MaxSessionInactiveInterval_sec	UIO Apache Proxy maintains a session for every user passes through the proxy. This setting sets the expiry time of this session after the user becomes inactive. It is in seconds (default is 30 minutes) For example, <Setting name="MaxSessionInactiveInterval_sec" value="1800"/>
GarbageCollectorInterval_ms	Interval for running session expiry thread (default = 5 minutes) For example, <Setting name="GarbageCollectorInterval_ms" value="300000"/>
FileWatcherInterval_ms	Interval for checking if the settings or any config file has changed (default = 1minute) For example, <Setting name="FileWatcherInterval_ms" value="60000"/> (After modifying the configuration XML file, even though the proxy updates the configuration on the fly, it is advisable to restart the httpd server.)
SessionIdCookieName_str	Name of the cookie used by UIO Apache Proxy to maintain its session (default = OAAM_UIOProxy_SessionId For example, <Setting name="SessionIdCookieName_str" value="SessionId"/>
SessionCookie_DomainLevelCount	Domain level for the UIO Apache Proxy session cookie. Does not affect any other cookie. For example, <Setting name="SessionCookie_DomainLevelCount" value="2"/>
SessionCookie_ExpiryInMinutes	The value of this setting is used to compute the expiry time that is put in the expires attribute of the Set-Cookie header of the UIO Apache Proxy session cookie. Default is zero which means the expires attribute is not added.
SessionCookie_IsHttpOnly	If set to 1, the UIO Apache Proxy session cookie is marked as HTTP only in the Set-Cookie Header. Affects only this cookie. Default is not to mark the cookie as HTTP only. On a supported browser, a HttpOnly cookie is only used when transmitting HTTP (or HTTPS) requests, but the cookie value is not available to client side script, hence mitigate the threat of cookie theft via Cross-site scripting.
SessionCookie_IsSecure	If set to 1, UIO Apache Proxy session cookie is marked as secure in the Set-Cookie header. It does not affect any other cookie. The default is not to mark the cookie as secure. A secure cookie is only used when a browser is visiting a server via HTTPS, that will make sure that cookie is always encrypted when transmitting from client to server, and therefore less likely to be exposed to cookie theft via eavesdropping.
IgnoreUrlMappings	Ignore the application configuration XML files; the proxy behaves as a flow-through proxy For example, <Setting name="IgnoreUrlMappings" value="0"/>. The value of 0 disables this mode and the value of 1 enables capture traffic mode. The value of 1 will make the proxy act as flow-through and the value of 0 will enable the configuration XML interceptors.
CaptureTraffic	Capture the HTTP traffic - headers and content in the log files. This mode is for debugging purpose. Note that it captures the headers and contents as is and could contain customer's personal data. Use this mode with caution and only for debugging/test. For example, <Setting name="CaptureTraffic" value="0"/>. Value of 1 enables capture traffic and 0 disables it.
MaxReqBodyBytes	Maximum request body that can be processed by the proxy and request body bigger than this value will be truncated. This is necessary when the application has POSTs with big files getting uploaded. For example, <Setting name="MaxReqBodyBytes" value="10240"/>
UseMemcache	Force the use of memcache even when httpd is running in single process mode. Has no effect when running in multiple process mode. Applies at startup and requires restarting httpd for change to apply. For example, <Setting name="UseMemcache" value="1"/>". Value of 1 enables use of memcache for a single process httpd. Value of 0 is ignored.
CachedConfigExpiry_sec	Expiry time for unused config XML data in memory, if multiple config XML configurations have been loaded into memory. This happens when config XML files are automatically loaded when they are modified. (Default = 60 minutes). For example, <Setting name="CachedConfigExpiry_sec" value="3600"/>
AutoLoadConfig	Set to 1 to enable auto-loading of config XML files when they are modified by user. Set to 0 to turn this feature off. You can enable this feature when using single-process mode of httpd. Do not enable this feature for multiple process mode of httpd for production use, since individual processes could have different versions of the config XML files. For example, <Setting name="AutoLoadConfig" value="1"/>. Value of 1 enables auto-load and 0 disables it.
Setting name	Enables internal profiling for various operations such as per interception phase and prints that out in the logs in microseconds. It should be used only for debugging and profiling in non-production environments as this may impact performance. The logs appear at INFO level and also at TRACE level

6.3.6.2 UIO_log4j.xml

For actual log4j format details, refer to log4j manual available on the Internet. Apache::log4cxx is a C++ implementation of the log4j framework and the XML file format is common to log4cxx and log4j.

Available UIO Apache Proxy Log4j loggers are listed below.

Table 6-12 UIO Apache Proxy Log4j Loggers

Loggers	Description
config.reader	The UIO_Config XML file loading related classes use this logger.
settings.reader	The UIO_Settings XML file loading classes use this logger.
config.datastore	The UIO_Config XML file loading related classes use this logger.
config	The UIO_Config XML file loading related classes use this logger.
config.reader.populator	The UIO_Config XML file loading related classes use this logger.
condition	All conditions defined in UIO_Config.xml use this logger.
filter	All filters defined in UIO_Config.xml use this logger.
action	All actions defined in UIO_Config.xml use this logger.
interceptor	All actions defined in UIO_Config.xml use this logger.
requestcontext	HTTP request processing is performed by classes that use this logger.
proxy	HTTP request processing is performed by classes that use this logger.
htmlpage	HTML page related processing is performed by classes that use this logger.
httpreqimpl	HTTP request processing is performed by classes that use this logger.
container	HTTP request processing is performed by classes that use this logger.
sessions	UIO Proxy session management related classes use this logger.
http	Logger that is used to log all HTTP traffic when CaptureTraffic setting is turned on.
distsessions	UIO Proxy session management related classes use this logger.

Note:

The logger documentation is provided for completeness and to enable the deployment engineer to make better sense of the logs. Typically for a debugging scenario turn on the log level to DEBUG and do not try to filter by any loggers.

6.3.6.3 Application configuration XMLs

These XML files are the application configuration files that are defined in the ConfigFile element of UIO_Settings.xml file.

6.4 Setting Up Rules and User Groups

For information on setting up rules and user groups, refer to the Oracle Fusion Middleware Installation Guide for Oracle Identity Management.

6.5 Setting Up Policies

To set up policies for the UIO Proxy, import the out-of-the-box policies. Information about importing policies is available in the Oracle Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager.

6.6 Configuring the UIO Proxy

The proxy intercepts all HTTP traffic between the client browser and the Web application and performs actions specified in the configuration files. The UIO ISA Proxy uses the XML Schema Definition which is described in the BharosaProxy.xsd and the UIO Apache Proxy uses the XML Relax NG definition which is in the UIO_Config.rng file in the proxy distribution.

6.6.1 Elements of the UIO Proxy Configuration File

The following sections describe various elements of the proxy configuration file.

6.6.1.1 Components of Interceptors

Interceptors are the most important elements in the proxy configuration. Authoring the proxy configuration file deals mostly with defining interceptors.

There are two types of interceptors: request interceptors and response interceptors. As the names suggest, request interceptors are used when the proxy receives HTTP requests from the client browser and response interceptors are used when the proxy receives HTTP response from the server, for example, Web application or OAAM Server.

There are four components to an interceptor and all of them are optional.

1. List of URLs - the interceptor will be evaluated if the interceptor URL list contains the current request URL or if the URL list is empty. The URLs must be an exact match; there is no support for regular expressions. For a request interceptor, this is the set of URLs for which the request interceptor will be executed in the request portion of the HTTP request, for example, on the way from the client to the server. For a response interceptor, the URL is that of the HTTP request; the response interceptor will be executed in the response portion of the HTTP request, for example, while getting the response from the server to the client. If the URL has query parameters, then they should not be listed. You can use conditions to check for any query parameters.

2. List of conditions - conditions can inspect the request/response contents, such as checking for the presence of an HTTP header/parameter/cookie, and so on, or testing whether a header/parameter/cookie has a specific value or not. Filters and action defined in the interceptor will be executed only if all the conditions specified are met or if no condition is specified.

3. List of filters - filters perform an action that might modify the request/response contents or modify some state information in the proxy. For example, a filter can add/remove HTTP headers, save HTTP header/parameter/cookie value in a proxy variable, and so on.

4. Action - after executing the filters the interceptor will perform the action, if one is specified. Actions can be one of the following:

   1. a redirect the client to a different URL

   2. send a saved response to the client

   3. perform a HTTP get on server

   4. perform a HTTP post on server

   5. send a saved request to the server

Table 6-13 Components of Interceptors

Interceptor	Attributes	Description
RequestInterceptor	id, desc, post-exec-action, isGlobal, enabled	RequestInterceptor defines an interceptor that will be run during the request phase. It has an id, description. Optionally it has a post-exec-action that takes the values continue, stop-intercept, stop-phase-intercept; the default is continue. Optionally it has isGlobal which takes the values true or false and is false by default. It also takes the enabled attribute which is also optional and is true by default.
ResponseInterceptor	id, desc, post-exec-action, isGlobal, enabled	ResponseInterceptor defines an interceptor that is run during the response phase of the HTTP request. The attributes of this element are similar to that of RequestInterceptor. This element contains zero or more RequestUrl elements, zero or more conditions elements, zero or more filter elements, zero or one target element. The RequestUrl element has a single URL element for which this interceptor will execute. The URl must be an exact match. There is no regular expression or pattern support for the URL. Instead of the RequestUrl element there is a ResponseUrl element which has similar meaning. All else is similar to the RequestInterceptor.

6.6.1.2 Conditions

Conditions are used in the proxy to inspect HTTP request/response or the state information saved in the proxy (variables). Each condition evaluates to either true or false. Conditions are evaluated in the order they are listed in the configuration file until a condition evaluates to false or all conditions are evaluated. Table 6-14 lists conditions that can be defined in an interceptor.

Table 6-14 Conditions Defined in an Interceptor

Condition name	Attributes	Description
HeaderPresent	enabled, name	Checks the presence of the specified header in request/response. The header name should be terminated by a colon (":"). Example: <HeaderPresent name="userid:"/>
ParamPresent	enabled, name	Checks the presence of the specified parameter in the request. Example: <ParamPresent name="loginID"/>
QueryParamPresent	enabled, name	Checks the presence of the specified query parameter in the URL. Example: <QueryParamPresent name="TraceID"/>
VariablePresent	enabled, name	Checks whether the specified proxy variable has been set. Example: <VariablePresent name="$userid"/>
RequestCookiePresent	enabled, name	Checks the presence of the specified cookie in the request Example: <RequestCookiePresent name="SESSIONID"/>
ResponseCookiePresent	enabled, name	Checks the presence of the specified cookie in the response Example: <ResponseCookiePresent name="MCWUSER"/>
HeaderValue	enabled, name, value, mode, ignore-case	Checks whether the specified request/response header value matches the given value. The header name should be terminated by a colon (":"). Example: <HeaderValue name="Rules-Result:" value="allow"/>
ParamValue	enabled, name, value, mode, ignore-case	Checks whether the specified request parameter value matches the given value. Example: <ParamValue name="cancel" value="Cancel"/>
QueryParamValue	enabled, name, value, mode, ignore-case	Checks whether the specified URL query parameter value matches the given value. Example: <QueryParamValue name="requestID" value="Logout"/>
VariableValue	enabled, name, value, mode, ignore-case	Checks whether the specified proxy variable value matches the given value. Example: <VariableValue name="%REQUEST_METHOD" value="post"/>
RequestCookieValue	enabled, name, value, mode, ignore-case	Checks whether the specified request cookie value matches the given value. Example: <RequestCookieValue name="CurrentPage" value="/onlineserv/" mode="begins-with" ignore-case="true"/>
ResponseCookieValue	enabled, name, value, mode, ignore-case	Checks whether the specified response cookie value matches the given value. Example: <ResponseCookieValue name="CurrentPage" value="/onlineserv/" mode="begins-with" ignore-case="true"/>
HttpStatus	enabled, status	Checks whether the status code of the response matches the given value. Example: <HttpStatus status="302"/>
HtmlElementPresent	enabled, name, attrib-name1, attrib-value1, attrib-name2, attrib-value2, … attrib-name9, attrib-value9,	Checks presence of a html element to match the specified conditions: <name attrib-name1="attrib-value1" attrib-name2="attrib-value2" …/> Example: <HtmlElementPresent name="form" attrib-name1="name" attrib-value1="signon"/>
PageContainsText	enabled, text	Checks whether the response contains the given text. Example: <PageContainsText text="You have entered an invalid Login Id"/>
NotVariableValue	enabled, name, value, mode, ignore-case	Checks whether the specified proxy variable value does not match the given value. Example: <NotVariableValue name="$Login-Status" value="In-Session"/>
And	enabled	Evaluates to true only if all the child conditions evaluate to true. Example: <And> <PageContainsText text="Your password must be"/> <PageContainsText text="Please re-enter your password"/> </And>
Or	enabled	Evaluates to true if one of the child conditions evaluates to true. Example: <Or> <ParamValue name="register" value="Continue"/> <ParamValue name="cancel" value="Cancel"/> </Or>
Not	enabled	Reverses the result of the child condition(s). Example: <Not> <HttpStatus status="200"/> </Not>

Attribute id is optional and is used only in trace messages. If no value is specified, the condition name (like HeaderPresent) will be used.

Attribute enabled is optional and the default value is true. This attribute can be used to enable/disable a condition. The value of this attribute can be set to the name of a global variable; in such case, the condition will be enabled or disabled according to the value of the global variable.

Attribute value can be set to the name of a proxy variable. In such a case, the proxy will evaluate the variable at checkpoint and use that value in the condition.

Attribute mode can be set to one of the following: begins-with, ends-with, contains.

Attribute ignore-case can be set to one of the following: true, false.

6.6.1.3 Filters

Filters are used in the proxy to modify HTTP request/response contents or modify the state information saved in the proxy (variables). Filters are executed in the order they are listed in the configuration file. Table 6-15 lists filters that can be defined in an interceptor.

Table 6-15 Filters Defined in an Interceptor

Filter name	Attributes	Description
AddHeader	enabled, name, value	Adds the specified header with a given value to request/response. The header name should be terminated by a colon (":"). Example: <AddHeader name="userid:" value="$userid"/>
SaveHeader	enabled, name, variable	Saves the specified request/response header value in the given proxy variable. The header name should be terminated by a colon (":"). Example: <SaveHeader name="userid:" variable="$userid"/>
RemoveHeader	enabled, name	Removes the specified header from request/response. The header name should be terminated by a colon (":"). Example: <RemoveHeader name="InternalHeader:"/>
AddParam	enabled, name, value	Adds a request parameter with a specified name and value. Example: <AddParam name="loginID" value="$userid"/>
SaveParam	enabled, name, variable	Saves the specified request parameter value in to the given proxy variable. Example: <SaveParam name="loginID" variable="$userid"/>
AddRequestCookie	enabled, name, value	Adds the specified cookie with a given value to request Example: <AddRequestCookie name="JSESSIONID" value="$JSESSIONID"/>
SaveRequestCookie	enabled, name	Saves the specified request cookie value in the given proxy variable
AddResponseCookie	enabled, name	Adds the specified cookie with a given value to response Example: <AddResponseCookie name="JSESSIONID" value="$JSESSIONID"/>
SaveResponseCookie	enabled, name	Saves the specified response cookie value in the given proxy variable. Example: <SaveResponseCookie name="JSESSIONID" variable="$JSESSIONID"/>
SaveHiddenFields	enabled, form, variable, save-submit-fields	Saves all the hidden, submit fields value, in the given form if the form name is specified to the given proxy variable. To not save submit fields, set save-submit-fields attribute to false. Example: <SaveHiddenFields form="pageForm" variable="%lg_HiddenParams"/>
AddHiddenFieldsParams	enabled, variable	Adds request parameters for each hidden field saved in the variable. Example: <AddHiddenFieldsParams variable="%lg_HiddenParams"/>
SetVariable	enabled, name, value	Sets the proxy variable with the given name to the specified value. Example: <SetVariable name="$Login-Status" value="In-Session"/>
UnsetVariable	enabled, name	Removes the proxy variable with the given name. Example: <UnsetVariable name="$Login-Status"/>
ClearSession	enabled, name	Removes all session variables in the current session. Example: <ClearSession/>
SaveQueryParam	enabled, name, variable	Saves the specified query parameter in the given proxy variable. Example: <SaveQueryParam name="search" variable="$search"/>
SaveRequest	enabled, variable	Saves the entire request content in the given proxy variable. This includes all headers and the body, if present. Example: <SaveRequest variable="$billPayRequest"/>
SaveResponse	enabled, variable	Saves the entire response content in the given proxy variable. This includes all headers and body, if present. Example: <SaveResponse variable="$BillPay-Response"/>
ReplaceText	enabled, find, replace	Updates the response by replacing the text specified in find attribute with the value given in replace attribute. Example: <ReplaceText find="string-to-find" replace="string-to-replace"/>
ProcessString	enabled, source, find, action, count, search-str, start-tag, end-tag, ignore-case, replace, encoding	This filter can be used to extract a sub-string from a string (such as request, response contents) and save it to a proxy variable. This filter can also be used to dynamically format strings. The find attribute has two values: string and sub-string. It defines the find mode as applying to the entire string or to sub-string. The sub-string is defined by the start-tag and end-tag. If the find value is sub-string, then only start-tag and end-tag values are used; otherwise, they are ignored. The action attribute has 3 values: extract, replace and eval. The value of 'extract' means it will copy the content bracketed by start-tag and end-tag over to the variable. The value of replace is used to perform a find and replace operation. eval is used to find and evaluate the variable in line. The attribute encoding is optional and can take a value of base64 if you want the resulting string to be base64 encoded. This attribute is supported only on UIO Apache Proxy. See the following examples in Section 6.6.1.4, "Filter Examples - ProcessString" on how to use this filter.
FormatString	enabled, variable, format-str, encoder, param-0, param-1, …, param-n	This filter provides functionality similar to the sprintf() C library function: to store a formatted string in a variable. Optionally, the string stored in the variable can be encoded in base64 format. Refer to the example in Section 6.6.1.5, "Filter Examples - FormatString" on using this filter to create a HTTP Basic Authentication header. FormatString is not supported in the UIO Apache Proxy. As it ProcessString provides all the required functionality.

6.6.1.4 Filter Examples - ProcessString

Find the sub-string between the given start-tag and end-tag in the source string, extract the sub-string found and save extracted sub-string in the given variable. The action of 'extract' will extract the first matching start-tag and end-tag pair.

<ProcessString source="%RESPONSE_CONTENT"
    find="sub-string"
    start-tag="var traceID = '" end-tag="';"
    action="extract"
    variable="$TRACE_ID"/>

Find the given search-string in the source string, replace it with the replace string and save the updated string in the given variable. You can also use the count attribute to specify behavior in case there are multiple matches. The attribute 'count' can take values all, once or a number.

<ProcessString 
      source="/bfb/accounts/accounts.asp?TraceID=$TRACE_ID"
      find="string" search-str="$TRACE_ID"
      action="replace"
      replace="$TRACE_ID"
      variable="%POST_URL"/>

Find the sub-string between the given start-tag and end-tag in the source string, replace it (including the start and end tags) with the evaluated value of the sub string found and save the updated string in the given variable. You can use the attribute count to specify the behavior in case of multiple matches. This attribute can take the value of 'all', 'once' or a number.

<ProcessString 
         source="/cgi-bin/mcw055.cgi?TRANEXIT[$UrlSuffix]"
         find="sub-string" start-tag="[" end-tag="]"
         action="eval"
         variable="%LogoffUrl"/>

You can specify the attribute ignore-case as true or false and it can be applied to any of the above examples and accordingly the search operation will be case sensitive or not. You can specify encoding attribute optionally and it will encode the resulting string before storing in to the variable. This attribute can take only base64 value. If you do not specify this attribute then the resulting string is stored as is.

The encoding attribute is supported only on UIO Apache Proxy. On UIO ISA Proxy you will have to use FormatString if you want to encode the result in base 64.

6.6.1.5 Filter Examples - FormatString

Here is an example to create a HTTP Basic Authentication response header in variable $AuthHeaderValue, using the user name/password in variables %userid and %password:

<FormatString variable="%UsernamePassword"
              format-str="{0}:{1}"
              param-0="%userid"
              param-1="%password"
              encoder="Base64"/>
 
<FormatString variable="$AuthHeaderValue"
              format-str="Basic {0}"
              param-0="%UsernamePassword"/>

6.6.1.6 Actions

An interceptor can optionally perform one of the following actions after executing all the filters. No further interceptors will be attempted after executing an action.

redirect-client

Often the proxy would need to redirect the client to load another URL; redirect-client is the action to use in such cases. The proxy will send a 302 HTTP response to request the client to load the specified URL. It takes has 2 attributes: url which contains the URL to which the proxy should re-direct the user and display-url which is optional.

If the display-url attribute is specified in the interceptor, the proxy will send a HTTP 302 response to the browser to load the URL specified in display-url attribute. When the proxy receives this request, it will perform a HTTP-GET on the server to get the URL specified in the url attribute.

send-to-client

Often a response from the server would have to be saved in the proxy and sent to the client later after performing a few other HTTP requests; send-to-client is the action to use in such cases. The proxy will send the client the contents of specified variable. It has two attributes: html which contains the variable that has the saved content that you want send back to the user and optional attribute display-url.

If the display-url attribute is specified in the interceptor, the proxy will send a HTTP 302 response to the browser to load the URL specified in display-url attribute. When the proxy receives this request, it will send the response specified in the interceptor.

get-server

Sometimes the proxy would need to get a URL from the server; get-server is the action to use in such cases. The proxy will send a HTTP-GET request for the specified URL to the server. It has two attributes: url which is the URL to perform the get on and the display-url which is optional.

If the display-url attribute is specified in the interceptor or if this action is specified in a response interceptor, the proxy will send a HTTP 302 response to the browser. When the proxy receives this request it will perform a HTTP-GET on the server to get the URL specified in the url attribute.

post-server

Sometimes the proxy would need to post to a URL in the server; post-server is the action to use in such cases. The proxy will send a HTTP-POST request for the specified URL to the server. It has two attributes: url that has the URL to which the post needs to be sent and optional display-url.

If display-url attribute is specified in the interceptor or if this action is specified in a response interceptor, the proxy will send a HTTP 302 response to the browser. When the proxy receives this request it will perform a HTTP-POST to the server to the URL specified in the url attribute.

send-to-server

In certain situations the request from the client needs to be saved in the proxy and sent to the server later after performing a few other HTTP requests; send-to-server is the action to use in such cases. The proxy will send the contents of the specified variable to the server. It has two attributes: html which contains the variable that has the saved content and the optional display-url attribute.

If the display-url attribute is specified in the interceptor, then the proxy will send out a HTTP 302 redirect response to the browser. This will cause the browser to request for the display-url and then the proxy will send out the saved request to the server. If you use this action in a response interceptor, then display-url is mandatory; without this, the action will fail.

6.6.1.7 Variables

The proxy variables can store string data in the proxy memory. Variables can be used in conditions, filters and actions. For example, SaveHeader filter can be used to save the value a specific header in the given proxy variable. This variable value could later be used, for example, to add a parameter to the request. Variables can also be used in conditions to determine whether to execute an interceptor or not.

The proxy variables are of 3 types, depending upon the life span of the variable. The type of variable is determined by the first letter of the variable name, which can be one of: %, $, @.

All types of variables can be set using filters like SetVariable, SaveHeader, SaveParam, SaveResponse, and other filters.

All types of variables can be unset/deleted by the UnsetVariable filter. The ClearSession filter can be used to remove all session variables.

Request variables

Request variables: these variable names start with %. These variables are associated with the current request and are deleted at the completion of the current request. Request variables are used where the value is not needed across requests.

Session variables

Session variables: these variable names start with $. These variables are associated with the current proxy session and are deleted when the proxy session is cleaned up. Session variables are used where the value should be preserved across requests from a client.

Global variables

Global variables: these variable names start with @. These variables are associated with the current proxy configuration and are deleted when the proxy configuration is unloaded. Global variables are used where the value needs to be preserved across requests and across clients.

Global variables can be set at the proxy configuration load time using SetGlobal in the configuration file. In the UIO ISA Proxy, global variables can also be set by adding registry values under key HKLM\Software\Bharosa\Proxy\Globals. The name of each entry under this key should be the variable name, starting with @. And the data of the entry should be the value of the variable. The registry-type of the value can be REG_DWORD, REG_SZ or REG_EXPAND_SZ.

Pre-defined variables

The UIO Proxy supports the following pre-defined request variables:

Table 6-16 Pre-defined Variables Supported by the UIO Proxy

Variable name	Description
%RESPONSE_CONTENT	This variable contains the contents of the entire response from the Web server for the current request. Forthe UIO Apache Proxy, %RESPONSE_CONTENT has been deprecated. Please use SaveResponse, SaveHeader, SaveResponseCookie, and ReplaceText filters instead.
%REQUEST_CONTENT	This variable contains the contents of the entire request from the client. For the UIO Apache Proxy, %REQUEST_CONTENT has been deprecated. You can use SaveRequest, SaveHeader, and SaveRequestCookie filters instead.
%QUERY_STRING	This variable contains the query string, starting with ?, for the current request URL.
%REQUEST_METHOD	HTTP method verb for the request: GET, POST, and so on.
%REMOTE_HOST	Hostname of the client or agent of the client. (For the UIO Apache Proxy, you need to enable the hostname lookup by using the Apache directive 'HostnameLookups On'.)
%REMOTE_ADDR	IP address of the client or agent of the client.
%HTTP_HOST	The content of HTTP Host header
%URL	URL for the current request

6.6.1.8 Application

A single proxy installation can be used to provide multifactor authentication for multiple Web application that run in one or more Web servers. In the UIO Proxy configuration, an application is a grouping of interceptors defined for a single Web application.

Request and response interceptors can be defined outside of an application in the proxy configuration file. These interceptors are called "global" interceptors and will be evaluated and executed prior to the interceptors defined in the applications.

6.6.2 Interception Process

An HTTP messages consist of requests from the client to server and responses from the server to client. HTTP is transaction oriented. A request from client to server will have a single response from the server to client. The request has a set of headers followed by, optionally, a request body. Similarly the response has headers and, optionally, a body. Since the proxy is sitting in between the client and the target application, it can modify the request headers, body and response headers and body of any HTTP request, using the configuration XML. Note that a response could be a normal 200 OK response or it could be a redirect response 302 or any other HTTP status response. In all these cases, the response is for that request and will trigger the response interceptors for the same request. An example, if the request is for the URL /doLogin.do, and the response is a redirect (302) with the location of /loginPage.jsp then all the request and response interceptors will be triggered for the URL /doLogin.do. The next HTTP request is a HTTP GET on /loginPage.jsp and this will cause all the request and response interceptors for /loginPage.jsp to be triggered.

When a request arrives, the proxy evaluates request interceptors defined for the URL in the order they are defined in the configuration file. Similarly when on receiving response from the Web server, the proxy evaluates response interceptors defined for the URL of the HTTP request in the order defined in the configuration file.

If the conditions in an interceptor evaluate to true, the proxy will execute that interceptor i.e. execute the filters and action. After executing an interceptor, the proxy will continue with the next interceptor only if the following conditions are met:

• no action is specified for the current interceptor

• post-exec-action attribute for the current interceptor is continue

It is highly recommended that the post-exec-action attribute be specified for interceptors that do not define an action. For global interceptors (for example, the interceptors defined outside of any application), the default value of post-exec-action attribute is continue. The stop-phase-intercept value of post-exec-action on a request interceptor stops the request interception but continues with response interception while stop-intercept stops the interception completely for that request. For non-global interceptors, the default value is continue if no action is specified and stop-phase-intercept if an action is specified.

As mentioned earlier the proxy configuration can contain multiple applications. While finding the list of interceptors to evaluate for a URL, only the following interceptors are considered:

• global interceptors that are defined outside of any application

• interceptors defined in the application associated with the current session

Each session will be associated with at most one application. If no application is associated with the current session (yet) when the proxy finds an interceptor in an application for the URL, it will associate the application with the current session.

If the current session already has an application associated, and if no interceptor is found in that application for the URL, the proxy will then look for intercepts in other applications. If an interceptor is found in another application for the URL, a new session will be created and the request will be associated with the new session.

6.6.3 Configuring Redirection to the Oracle Adaptive Access Manager Server Interface

The UIO Proxy redirects the user to OAAM Server pages at appropriate times, for example to collect the password using OAAM Server, to run risk rules. HTTP headers are used to exchange data between the UIO Proxy and OAAM Server. The following table lists OAAM Server pages referenced in the proxy configuration along with the details of HTTP headers used to pass data. It also lists the expected action to be taken by the proxy on the given conditions.

Table 6-17 OAAM Server Interface

URL	Condition	Action
Any request to OAAM Server page	On receiving request	Set header "BharosaAppId". OAAM Server will use this header value to select appropriate customizations (UI, rules, and elements).
loginPage.jsp or login.do	On receiving request to application login page	Redirect to this URL to use the Oracle Adaptive Access Manager login page instead of the application's login page.
password.do	Response contains headers userid, password (could be more depending upon the application)	Save the credentials from the response headers and post to the application To put an URL with an "&" into a target action so that the xml parser does not have an error, you must escape it: &
login.do	Phase-1 only: After validating the credentials entered by the user.	Redirect to this URL to update the status in Oracle Adaptive Access Manager and run appropriate risk rules.
login.do	Phase-1 only: On receiving the request.	Set "userid" header to the userid entered by the user. Set "Login-Status" header to one of the following: success, wrong_password, invalid_user, user_disabled, system_error. Set the "OAAM ServerPhase" header to "one". A "?" is accepted in a URL specified in a target action. In a target action URL, you would have the "?" and any parameters after it Setting "Login-Status" to success will update the session status for the user in OAAM to success and run post-authentication rules. wrong_password, invalid_user, user_disabled, system_error will update the session status in OAAM to the status passed and the user will be taken to the login page with the appropriate error messaging
updateLoginStatus.do	Phase-2 only: After validating the credentials entered by the user.	Redirect to this URL to update the status in Oracle Adaptive Access Manager and run appropriate risk rules
updateLoginStatus.do	Phase-2 only: On receiving request	Set "Login-Status" header to one of the following: success, wrong_password, invalid_user, user_disabled, system_error Setting "Login-Status" to success will update the session status for the user in Oracle Adaptive Access Manager to success and run post-authentication rules. wrong_password, invalid_user, user_disabled, system_error will update session status in Oracle Adaptive Access Manager to the status passed and the user will be taken to the login page with appropriate error messaging
updateLoginStatus.do challengeUser.do registerQuestions.do userPreferencesDone.do	Response header "Rules-Result" has value "allow"	The Oracle Adaptive Access Manager rules evaluated to permit the login. The proxy can permit access to the protected application URLs after this point.
registerQuestions.do	Response header "Rules-Result" has value "block"	Either the application did not accept the login credentials or the Oracle Adaptive Access Manager rules evaluated to block the login. The proxy should log off the session in the application, if login was successful. Then a Login Blocked message should be sent to the browser.
changePassword.do	Response contains headers "password", "newpassword" and "confirmpassword"	Save the passwords from the response headers and post to the application
loginFail.do	To display error message in OAAM Server page, like to display login blocked message	Redirect to this URL with appropriate "action" query parameter, like loginFail.do?action=block In most cases control is not given to the proxy via a response header in a block situation. Instead, the user is taken to the following URL with a query parameter "action" set to the error code "block". This presents the user with the OAAM Server login page with a message stating the reason they are there. /error.do?action=block Alternatively it is possible to get the same result with the following URLs. /loginFail.do?action=block /loginPage.jsp?action=block
logout.do	On completion of application session logout	Redirect to this URL to log out the OAAM Server session
logout.do	On receiving response	Redirect to application logout URL to log off the application session, if it is not already off
resetPassword.do	Response contains headers "newpassword" and "confirmpassword"	Save the passwords from the response headers and post to the application
getUserInput.do	Response contains headers "BH_UserInput"	Save the user input and take appropriate action (like post to application, etc.)
changeUserId.do	On receiving request	Add "newUserId" header
changeUserId.do	On receiving response	Redirect to the appropriate application page or send back the saved application response
updateForgotPasswordStatus.do	Phase-2 only: After validating the forgot- password-credentials entered by the user.	Redirect to this URL to update the status in Oracle Adaptive Access Manager and run appropriate risk rules.
updateForgotPasswordStatus.do	Phase-2 only: On receiving request	Set "BH_FP-Status" header to one of the following: success, wrong_password, invalid_user, user_disabled, system_error.
updateForgotPasswordStatus.do challengeForgotPasswordUser.do	Response header "BH_FP-Rules-Result" has value "allow"	The Oracle Adaptive Access Manager rules evaluated to permit the forgot-password flow. The proxy can permit continuation to the forgot-password flow to reset the password or allow the user login, depending on the application.
updateForgotPasswordStatus.do challengeForgotPasswordUser.do	Response header "BH_FP-Rules-Result" has value "block"	Either the application did not accept the forgot-password credentials or the Oracle Adaptive Access Manager rules evaluated to block the forgot-password flow. A login blocked message should be sent to the browser.
Any request to OAAM Server page	If the proxy needs to get a property value from OAAM Server. On receiving request	"BH_PropKeys" request header should be set to list of property names (separated by a comma). OAAM Server will return the values in multiple response headers, one for each property. The return response header names will be of format: "BH_Property-<name>"

6.7 Application Discovery

Two flags in the settings are used for application discovery. One flag instructs the proxy to ignore its configuration XML and act as a reverse-proxy only. The other flag instructs the proxy to capture all the HTTP traffic and print it to the logs. The first flag is used for application discovery to capture the HTTP traffic and analyze it. The second flag would be kept on during the configuration XML development phase to debug the configuration XML itself.

Application discovery is the process of studying an existing Web application to author the proxy configuration to add multifactor authentication using the UIO Proxy. A few logins attempts to the application would be made via the proxy to capture the HTTP traffic in each attempt. The captured HTTP traffic would then be analyzed to author the proxy configuration. The UIO Proxy should be set up to dump all the HTTP traffic to a file. Then a few logins/login attempts to the application should be made via the proxy. The captured HTTP traffic should then be analyzed to author the proxy configuration.

6.7.1 Application Information

For the application discovery process it is preferable to work with the Web application in the customer's test environment, rather than the production application being used by users. If the test environment is not available, the live application can be used.

The following information is needed from the client for the application discovery process:

1. URL to log in to the application.

2. Test user account credentials, including the data required in the forgot password scenario. It will be best to get as many test accounts as possible, preferably at least five accounts, for uninterrupted discovery and testing. Note that during the discovery process some accounts could become disabled, due to multiple invalid login attempts.

3. Contact (phone, email) to enable/reset test accounts

6.7.2 Setting Up the UIO ISA Proxy

The Microsoft ISA server should be set up to publish the Web application under discovery, for example, creating a Web site publishing rule with appropriate parameters. During the application discovery process, the application will be accessed via Microsoft ISA, which hosts the UIO ISA Proxy. Refer to the Microsoft ISA configuration document for details of setting up Microsoft ISA.

The UIO ISA Proxy settings (registry values under HKLM\SOFTWARE\Bharosa\Proxy key) should be set as given in Table 6-18 for the proxy to capture the HTTP traffic to the specified file. This HTTP traffic captured will later be used for analysis to author the proxy configuration.

Table 6-18 Setting up the proxy

Setting	Value
IgnoreUrlMappings	1
CaptureTraffic	1
TraceFilename	<filename>
TraceLevel	0x87
TraceToFile	1

It might be useful to capture the HTTP traffic for each scenario (for example, successful login attempt, wrong password, wrong user name, disabled user, and other scenarios) in separate files. TraceFilename setting should be updated to the desired filename before the start of the scenario.

After application discovery is performed, the proxy settings should be set as given in Table 6-19 to restore the default UIO ISA Proxy behavior.

Table 6-19 Proxy settings after application discovery

Setting	Value
IgnoreUrlMappings	0
CaptureTraffic	0
TraceFilename	<filename>
TraceLevel	0x7
TraceToFile	1

6.7.3 Setting Up the UIO Apache Proxy

For application discovery, the HTTP traffic needs to be captured through the proxy.

Table 6-20 shows the settings (in UIO_Settings.xml) to enable this mode of operation.

Table 6-20 Settings for Capturing HTTP

Settings	Value
IgnoreUrlMappings	1
CaptureTraffic	1

The IgnoreUrlMappings setting is used to disable URL interception of the HTTP traffic through the proxy.

The CaptureTraffic setting captures the HTTP traffic through the logger name HTTP set to log level of info.

It might be useful to capture the HTTP traffic for each scenario (like successful login attempt, wrong password, wrong user name, disabled user, and so on) in separate files. The log file name setting should be updated to the desired filename before the start of the scenario.

After application discovery is performed, the proxy settings should be set, as shown in Table 6-21, to restore the default UIO Apache Proxy behavior.

Table 6-21 Settings to restore default proxy behavior

Settings	Value
IgnoreUrlMappings	0
CaptureTraffic	0

6.7.4 Scenarios

Collect information for the following scenarios during the discovery process.

You must create interceptors in the TestConfig.xml file that look for certain URLs and conditions in the HTTP traffic. The proxy listens to the HTTP traffic and when it sees a URL that matches a URL in its TestConfig.xml file, it evaluates the interceptors that have a URL match and it evaluates the conditions block in the interceptor. If they match, the UIO Proxy executes the filter block and condition block.

Login

1. URL that starts the login process

2. URL that contains the login form

3. Names of the input fields like user name, password used to submit the credentials

4. URL to which the login form submits the credentials

5. Identifying successful login. The HTTP traffic dump needs to be studied carefully to derive this information. Here are few ways applications respond on successful login:

   1. by setting a specific cookie in the credential submit response

   2. by redirecting to a specific URL (like account summary, Welcome page, and so on)

   3. by responding with specific text

6. Identifying failure login with the reason for failure. This would often be derived by looking for certain text in the response to credential submit request.

Logout

1. URL that starts the logout process

2. URL that completes the logout process. In most cases the logout completes on receiving the response to the logout start URL.

Change password

1. URL that starts the change password process

2. URL that contains the change password form

3. Names of the input fields like password, new-password, confirm-password used to submit the change password request

4. URL to which the change password form submits the passwords

5. Identifying the status (success/failure) of the change password request. This would often be derived by looking for certain text in the response.

Reset password

Follows the same process as Change password.

Change LoginId

1. URL to which the login-id change is posted to the application

2. Names of the input fields like new-login used to submit the change password request.

3. Identifying the status (success/failure) of the change login-id request. On successful change login-id request, the changeUserId.do page in OAAM Server should be called to update the login-id in the Oracle Adaptive Access Manager database.

Forgot password

Forgot-password options provided by the application must be reviewed for understanding. Most applications ask for alternate ways to identity the user (account number/PIN, SSN/PIN, question/answer, and other ways); some applications provide more than one option. Some applications let the user reset the password after successfully entering alternate credentials; others send a new password to the user by mail/email; and some other applications would require the user to call customer care. For each of the supported scenarios, the following data should be captured:

1. URL that starts the forgot-password process

2. URL that contains the forgot-password form

3. Names of the input fields and URLs to submit the forgot-password request

4. Identifying the status (success/failure) of the forgot-password request.

6.8 Samples

The proxy configuration to add multifactor authentication to the BigBank Web application is shown below. The BigBank web application is a sample application which shows a login flow. The example will demonstrate the integration of the UIO Proxy into the login flow of an application.

For ISA proxy use:

<?xml version="1.0" encoding="utf-8"?>
<BharosaProxyConfig xmlns="http://bharosa.com/"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://bharosa.com/ BharosaProxy.xsd ">

For Apache proxy use:

<?xml version="1.0" encoding="utf-8"?>
<BharosaProxyConfig xmlns="http://bharosa.com/">
 
  <RequestInterceptor id="AddAppIdToOAAMServerRequests-BigBank"
                      desc="Add BharosaAppId header to each request to oaam_server"
                      post-exec-action="continue">
    <Conditions>
      <VariableValue name="%URL"
                     value="/oaam_server/"
                     mode="begins-with"
                     ignore-case="true"/>
    </Conditions>
 
    <Filters>
      <AddHeader name="BharosaAppId:" value="BigBank"/>
    </Filters>
  </RequestInterceptor>
 
    <SetGlobal name="@Phase1Enabled" value="false"/>
    <SetGlobal name="@Phase2Only"    value="true"/>
 
  <Application id="BigBank">
 
    <!-- In phase one, we use BigBank's login form to collect username/password -->
    <!-- In phase two, we use oaam_server login forms to collect username and password -->
 
    <!-- Disable this interceptor after phase one is retired -->
    <RequestInterceptor id="Phase1BigBankLoginPostRequest"
                        desc="get the loginid from the post parameters"
                        post-exec-action="continue" enabled="@Phase1Enabled">
      <RequestUrl url="/bigbank/login.do"/>
 
      <Conditions>
        <VariableValue name="%REQUEST_METHOD" value="POST"/>
      </Conditions>
 
      <Filters>
        <ClearSession/>
        <SetVariable name="$WebUIOPhase" value="one"/>
        <SaveParam   name="userid"       variable="$userid"/>
      </Filters>
    </RequestInterceptor>
 
    <!-- Enable this interceptor after phase one is retired -->
    <RequestInterceptor id="Phase2RedirectBigBankLoginPageRequest"
                        desc="Redirect BigBank login page requests to Bharosa login page"
                        enabled="@Phase2Only">
      <RequestUrl url="/bigbank"/>
      <RequestUrl url="/bigbank/"/>
      <RequestUrl url="/bigbank/loginPage.jsp"/>
      
      <Target action="redirect-client" url="/oaam_server/login.do"/>
    </RequestInterceptor>
 
    <RequestInterceptor id="Phase2BharosaLoginPageRequest"
                        desc="Phase-2 loginid post request"
                        post-exec-action="continue">
      <RequestUrl url="/oaam_server/login.do"/>
 
      <Conditions>
        <VariableValue name="%REQUEST_METHOD" value="POST"/>
        <ParamPresent  name="userid"/>
        <Not>
          <ParamPresent name="password"/>
        </Not>
      </Conditions>
 
      <Filters>
        <ClearSession/>
        <SetVariable name="$WebUIOPhase" value="two"/>
      </Filters>
    </RequestInterceptor>
 
    <ResponseInterceptor id="Phase2PasswordPageResponse"
                         desc="Save the userid, decoded password from Bharosa Password Page response">
      <ResponseUrl url="/oaam_server/password.do"/>
 
      <Conditions>
        <HeaderPresent name="userid:"/>
        <HeaderPresent name="password:"/>
      </Conditions>
 
      <Filters>
        <SaveHeader name="userid:"   variable="$userid"/>
        <SaveHeader name="password:" variable="$password"/>
      </Filters>
 
      <Target action="redirect-client"
              url="/bigbank/loginPage.jsp"
              display-url="/bigbank/GetLoginPage"/>
    </ResponseInterceptor>
 
    <ResponseInterceptor id="GetBigBankLoginPageResponse"
                         desc="Save values of all hidden fields; then post login crdentials">
      <ResponseUrl url="/bigbank/GetLoginPage"/>
 
      <Filters>
        <SaveHiddenFields variable="%LoginPageHiddenParams"/>
 
        <AddHiddenFieldsParams variable="%LoginPageHiddenParams"/>
        <AddParam              name="userid"   value="$userid"/>
        <AddParam              name="password" value="$password"/>
      </Filters>
 
      <Target action="post-server" url="/bigbank/login.do"/>
    </ResponseInterceptor>
 
    <ResponseInterceptor id="InvalidLoginResponse"
                         desc="Invalid login response from BigBank">
      <ResponseUrl url="/bigbank/login.do"/>
 
      <Conditions>
        <PageContainsText text="You have entered an invalid Login Id"/>
      </Conditions>
 
      <Filters>
        <SetVariable  name="$Login-Credentials-Status" value="invalid_user"/>
        <SetVariable  name="$Login-Continue-Url"       value="%URL"/>
        <SaveResponse variable="$Submit-Credentials-Response"/>
      </Filters>
 
      <Target action="redirect-client" url="/oaam_server/UpdateLoginStatusPage"/>
    </ResponseInterceptor>
 
    <ResponseInterceptor id="WrongPasswordResponse"
                         desc="Invalid login response from BigBank">
      <ResponseUrl url="/bigbank/login.do"/>
 
      <Conditions>
        <PageContainsText text="We do not recognize your password"/>
      </Conditions>
 
      <Filters>
        <SetVariable name="$Login-Credentials-Status" value="wrong_password"/>
        <SetVariable name="$Login-Continue-Url"       value="%URL"/>
        <SaveResponse variable="$Submit-Credentials-Response"/>
      </Filters>
 
      <Target action="redirect-client" url="/oaam_server/UpdateLoginStatusPage"/>
    </ResponseInterceptor>
 
    <ResponseInterceptor id="LoginSuccessResponse"
                         desc="Login success response from BigBank">
      <ResponseUrl url="/bigbank/activity.do"/>
      <!-- ResponseUrl url="/bigbank/login.do"/ -->
 
      <Conditions>
        <NotVariableValue name="$Login-Status" value="In-Session"/>
        <PageContainsText text="/bigbank/images/success.gif"/>
      </Conditions>
 
      <Filters>
        <SetVariable name="$Login-Credentials-Status" value="success"/>
        <SetVariable name="$Login-Continue-Url"       value="%URL"/>
        <SaveResponse variable="$Submit-Credentials-Response"/>
        <AddHeader name="Login-Status:" value="$Login-Credentials-Status"/>
      </Filters>
 
      <!-- Target action="redirect-client" url="/oaam_server/UpdateLoginStatusPage"/ -->
      <Target action="get-server" url="/oaam_server/updateLoginStatus.do"/>
    </ResponseInterceptor>
 
    <RequestInterceptor id="Phase1UpdateLoginStatusPageRequest"
                        desc="Update Bharosa Tracker with the login status">
      <RequestUrl url="/oaam_server/UpdateLoginStatusPage"/>
 
      <Conditions>
        <VariableValue name="$WebUIOPhase" value="one"/>
      </Conditions>
 
      <Filters>
        <AddHeader name="WebUIOPhase:"  value="$WebUIOPhase"/>
        <AddHeader name="userid:"       value="$userid"/>
        <AddHeader name="Login-Status:" value="$Login-Credentials-Status"/>
      </Filters>
 
      <!-- Any interceptors for /bigbank/login.do will not run because we are doing get-server. -->
      <Target action="get-server" url="/oaam_server/login.do"/>
    </RequestInterceptor>
 
    <RequestInterceptor id="Phase2UpdateLoginStatusPageRequest"
                        desc="Update Bharosa Tracker with the login status">
                                                <!--post-exec-action="continue" --> 
      <RequestUrl url="/oaam_server/UpdateLoginStatusPage"/>
 
      <Filters>
        <AddHeader name="Login-Status:" value="$Login-Credentials-Status"/>
      </Filters>
 
      <Target action="get-server" url="/oaam_server/updateLoginStatus.do"/>
    </RequestInterceptor>
 
    <ResponseInterceptor id="AllowLoginResponse"
                         desc="Tracker returned 'allow' - continue with login">
      <ResponseUrl url="/oaam_server/UpdateLoginStatusPage"/>
      <ResponseUrl url="/oaam_server/updateLoginStatus.do"/>
      <ResponseUrl url="/oaam_server/challengeUser.do"/>
      <ResponseUrl url="/oaam_server/registerQuestions.do"/>
      <ResponseUrl url="/oaam_server/userPreferencesDone.do"/>
 
      <Conditions>
        <HeaderValue name="Rules-Result:" value="allow"/>
      </Conditions>
 
      <Filters>
        <SetVariable name="$Login-Status" value="In-Session"/>
      </Filters>
 
      <Target action="send-to-client" html="$Submit-Credentials-Response"
              display-url="$Login-Continue-Url"/>
    </ResponseInterceptor>
 
    <ResponseInterceptor id="Phase1FailLoginResponse" desc="BigBank failed the login">
      <ResponseUrl url="/oaam_server/UpdateLoginStatusPage"/>
      <ResponseUrl url="/oaam_server/updateLoginStatus.do"/>
      <ResponseUrl url="/oaam_server/challengeUser.do"/>
      <ResponseUrl url="/oaam_server/registerQuestions.do"/>
      <ResponseUrl url="/oaam_server/userPreferencesDone.do"/>
 
      <Conditions>
        <VariableValue    name="$WebUIOPhase"              value="one"/>
        <NotVariableValue name="$Login-Credentials-Status" value="success"/>
        <HeaderValue      name="Rules-Result:"             value="block"/>
      </Conditions>
 
      <Filters>
        <UnsetVariable name="$Login-Status"/>
      </Filters>
 
      <Target action="send-to-client" html="$Submit-Credentials-Response"
              display-url="$Login-Continue-Url"/>
    </ResponseInterceptor>
 
    <ResponseInterceptor id="FailLoginResponse" desc="BigBank failed the login">
      <ResponseUrl url="/oaam_server/UpdateLoginStatusPage"/>
      <ResponseUrl url="/oaam_server/updateLoginStatus.do"/>
      <ResponseUrl url="/oaam_server/challengeUser.do"/>
      <ResponseUrl url="/oaam_server/registerQuestions.do"/>
      <ResponseUrl url="/oaam_server/userPreferencesDone.do"/>
 
      <Conditions>
        <HeaderValue      name="Rules-Result:"             value="block"/>
        <NotVariableValue name="$Login-Credentials-Status" value="success"/>
      </Conditions>
 
      <Filters>
        <UnsetVariable name="$Login-Status"/>
      </Filters>
 
      <Target action="redirect-client" url="/oaam_server/loginPage.jsp?action=invalid_user"/>
    </ResponseInterceptor>
 
    <ResponseInterceptor id="BlockLoginResponse"
                         desc="BigBank passed login but tracker returned 'block' - fail the login">
      <ResponseUrl url="/oaam_server/UpdateLoginStatusPage"/>
      <ResponseUrl url="/oaam_server/updateLoginStatus.do"/>
      <ResponseUrl url="/oaam_server/challengeUser.do"/>
      <ResponseUrl url="/oaam_server/registerQuestions.do"/>
      <ResponseUrl url="/oaam_server/userPreferencesDone.do"/>
 
      <Conditions>
        <HeaderValue name="Rules-Result:" value="block"/>
      </Conditions>
 
      <Filters>
        <UnsetVariable name="$Login-Status"/>
      </Filters>
 
      <!-- /bigbank/LoginBlockedPage isn't a real page.  The request will be intercepted and redirected. -->
      <Target action="redirect-client" url="/bigbank/LoginBlockedPage"/>
    </ResponseInterceptor>
 
    <RequestInterceptor id="LoginBlockedPageRequest"
                        desc="logoff the session in BigBank">
      <RequestUrl url="/bigbank/LoginBlockedPage"/>
 
      <Target action="get-server" url="/bigbank/logout.do"/>
    </RequestInterceptor>
 
    <ResponseInterceptor id="Phase1LoginBlockedPageResponse"
                         desc="BigBank approved login; but Bharosa blocked the login"
                         post-exec-action="stop-intercept">
      <ResponseUrl url="/bigbank/LoginBlockedPage"/>
 
      <Conditions>
        <VariableValue name="$WebUIOPhase" value="one"/>
      </Conditions>
 
      <Filters>
        <ClearSession/>
      </Filters>
 
      <Target action="redirect-client" url="/oaam_server/loginFail.do?action=block"/>
    </ResponseInterceptor>
 
    <ResponseInterceptor id="Phase2LoginBlockedPageResponse"
                         desc="BigBank approved the login; but Bharosa blocked the login">
      <ResponseUrl url="/bigbank/LoginBlockedPage"/>
 
      <Filters>
        <ClearSession/>
      </Filters>
 
      <Target action="redirect-client" url="/oaam_server/loginPage.jsp?action=block"/>
    </ResponseInterceptor>
 
    <ResponseInterceptor id="LogoutPageResponse"
                         desc="Bharosa logout selected; logoff the session in BigBank">
      <ResponseUrl url="/oaam_server/logout.do"/>
 
      <Target action="redirect-client" url="/bigbank/logout.do"/>
    </ResponseInterceptor>
 
    <ResponseInterceptor id="Phase1LogoffPageResponse"
                         desc="Logoff - clear Bharosa proxy session"
                         post-exec-action="stop-intercept">
      <ResponseUrl url="/bigbank/logout.do"/>
 
      <Conditions>
        <VariableValue name="$WebUIOPhase" value="one"/>
      </Conditions>
 
      <Filters>
        <ClearSession/>
      </Filters>
    </ResponseInterceptor>
 
    <ResponseInterceptor id="Phase2LogoffPageResponse"
                         desc="Logoff - clear Bharosa proxy session">
      <ResponseUrl url="/bigbank/logout.do"/>
 
      <Filters>
        <ClearSession/>
      </Filters>
 
      <!-- Target action="redirect-client" url="/oaam_server/loginPage.jsp"/ -->
    </ResponseInterceptor>
 
  </Application>
</BharosaProxyConfig>

6.8.1 Descriptions for Interceptors

Descriptions of the various interceptors that are defined in the sample configuration are summarized in Table 6-22.

Table 6-22 Sample Configuration Interceptors

Interceptor ID	Type	Explanation
AddAppIdTobharosauioRequests-BigBank	Request	Set headers for all requests for OAAM Server. Invoked by any request to OAAM Server.
Phase1BigBankLoginPostRequest	Request	Get login ID from post parameters, set Phase One, save user ID. Invoked by request for /bigbank/login.do when Phase one is enabled.
Phase2RedirectBigBankLoginPageRequest	Request	Redirect login page from application to OAAM Server. Invoked when Phase Two is enabled and application login page is requested
Phase2BharosaLoginPageRequest	Request	Set Phase Two and save variables. Invoked by request for OAAM Server login.do
Phase2PasswordPageResponse	Response	Save ID/Password in header, redirect client to BigBank loginpage. Invoked by response from OAAM Server's password.do.
GetBigBankLoginPageResponse	Response	Save all hidden fields values, then post login credential to BigBank. Invoked by response from /bigbank/GetLoginPage.
InvalidLoginResponse	Response	Actions to take when getting invalid login response from BigBank.
WrongPasswordResponse	Response	Actions to take when getting wrong password response from BigBank.
LoginSuccessResponse	Response	Actions to take when getting login success response from BigBank.
Phase1UpdateLoginStatusPageRequest	Request	Set Phase One and add headers. Invoked by request for OAAM Server to update status after getting login response from BigBank.
Phase2UpdateLoginStatusPageRequest	Request	Add header and update OAAM Server with login status. Invoked by request for oaam_server/updateLoginStatusPage.
AllowLoginResponse	Response	Set variables and direct client to the next page to continue with the login. Invoked when receiving login success response from OAAM Server.
Phase1FailLoginResponse	Response	Set login status and direct client to next page. Invoked in Phase One when BigBank failed the login and the response sent back from OAAM Server.
FailLoginResponse	Response	Set login status and redirect client to theOAAM login block page. Invoked when BigBank failed the login and Phase One is not enabled.
BlockLoginResponse	Response	Set Block status and redirect client to BigBank login blocked page. Invoked when BigBank passed login but OAAM Server decided to block.
LoginBlockedPageRequest	Request	Redirect client to BigBank logout page. Invoked by request for BigBank Login Blocked page.
Phase1LoginBlockedPageResponse	Response	Clear session and redirect client to the OAAM Login Blocked page, then stop intercept. Used in Phase One, invoked by response from BigBank Login Blocked page.
Phase2LoginBlockedPageResponse	Response	Clear session and redirect client to OAAM Login Blocked page. Used when Phase One is not enabled, invoked by response from BigBank Login Blocked page.
LogoutPageResponse	Response	Redirect client to BigBank logout page. Invoked by response from OAAM logout page.
Phase1LogoffPageResponse	Response	Clear session when getting response from BigBank logout page. Used when Phase One enabled.
Phase2LogoffPageResponse	Response	Clear session when getting response from BigBank logout page. Used when Phase Two enabled.

6.8.2 Flow for BigBank without UIO Proxy

The following is the flow of the BigBank application without the UIO Proxy for login and logout.

6.8.2.1 Login

The Login without UIO Proxy flow is shown below.

Figure 6-3 Login Flow - Without UIO Proxy

6.8.2.2 Logout

The Logout without UIO Proxy flow is shown below.

Figure 6-4 Logout - Without UIO Proxy

6.8.3 Flow for First-time User to Log In and Log Out of BigBank with UIO Proxy

This section provides details for the flows for first time users who log in to the BigBank application through the UIO Proxy. The regular flow, including the login phase, registration phase/skip registration phase, and logout phase, and the deviation flow (block login) are covered. Interceptors defined in Configure xml that are used in each step in the flow will be listed.

Note: For the proxy, the only messages shown are ones whenthe interceptors match request/response. Normal messages that the proxy passes betweenthe client and Oracle Adaptive Access Manager/application are skipped to simplify the scenario.

The regular flow (four phases) consists of the login, registration, skip registration, and logout phases.

Login phase:

Figure 6-5 Flow for Getting Login Page

1. Client requests Login page for the application (http://proxyhost:port/bigbank).

2. The proxy intercepts the request, and sets the headers. Then, the proxy redirects the client to oaam_server/login.do.

   The request is intercepted by two interceptors: AddAppIdTobharosauioRequests-BigBank and Phase2RedirectBigBankLoginPageRequest.

   Note: AddAppIdTobharosauioRequests-BigBank sets the HTTP headers and variables. It will intercept any request for the OAAM Server and the proxy will try other interceptors to see if there are more matches after this interceptor.

   Phase2RedirectBigBankLoginPageRequest redirects the client from the BigBank Login page to oaam_server/login.do.

3. The client requests to get login.do at the OAAM Server (http://proxyhost:port/oaam_server/login.do).

4. OAAM Server redirects to Jump page to fingerprint the client device.

5. OAAM Server gets fingerprinting from the client browser.

6. OAAM Server responds after getting the fingerprint with the Login page.

   Figure 6-6 OAAM Server responds after getting the fingerprint with the Login page

   
   

7. The client posts the user name to the OAAM Server (http://proxyhost:port/oaam_server/login.do).

   Other than the AddAppIdTobharosauioRequests-BigBank interceptor, the request is intercepted at the proxy by the Phase2BharosaLoginPageRequest interceptor. The proxy sets WebUIOPhase to two.

8. The OAAM Server responds.

9. The OAAM Server gets fingerprints.

10. The OAAM Server responds after getting fingerprints, with the Password Collection page which has a strong authentication device.

    Figure 6-7 Fingerprint and password collection

    
    

11. The client submits the password to the OAAM Server (http://proxyhost:port/oaam_server/password.do)

12. The OAAM Server responds.

    The response is intercepted by Phase2PasswordPageResponse. The proxy saves the headers which contain the Login ID and the password that have been collected by the OAAM Server so far and redirects the client to /bigbank/GetLoginPage.

13. The proxy redirects the client to GetLoginPage.

14. The client sends a request to BigBank for GetLoginPage (http://proxyhost:port/bigbank/GetLoginPage).

15. BigBank sends back a response.

    The response is intercepted at the proxy by GetBigBankLoginPageResponse. The proxy saves the parameters and performs a Post-server action for /bigbank/login.do. This is the normal authentication flow for the BigBank application.

16. The proxy queues the interceptor and redirects client to bigbank/login.do.

17. The client requests for login.do (http://proxyhost:port/bigbank/login.do).

18. The request is intercepted by the proxy. The proxy executes the queued interceptor (GetBigBankLoginPageResponse) and changes the request method from GET to POST.

19. BigBank responds, redirect the client to activity.do. This is the normal authentication flow for the BigBank application.

20. The client requests for activity.do (http://proxyhost:port/bigbank/activity.do).

21. BigBank sends a login success response.

    The response is intercepted at the proxy by LoginSuccessResponse. The proxy sets the login status to success and performs a get server action for /oaam_server/updateLoginStatus.do

22. The proxy redirects the client to updateLoginStatus.do.

23. The client sends a request to OAAM Server to update the status

    http://proxyhost:port/oaam_server/updateLoginStatus.do).

24. OAAM Server does a post authentication check and returns the result.

    The response is intercepted at the proxy by AllowLoginResponse.

25. The proxy takes the send-to-client action. It sets the display-url variable so that the client will request this URL after receiving the response.

26. The client sends a request to OAAM Server for the first-time user to get the Registration page (http://proxyhost:port/oaam_server/registerQuestions.do).

27. The Response page has two options for the users: skip and register.

    Registration Flow (client chooses to register):

    Figure 6-8 Flow for first-time user to register questions/answers with OAAM Server

    
    

28. The client chooses to register (Post to http://proxyhost:port/oaam_server/registerQuestions.do).

29. OAAM Server responds with instructions.

30. The client clicks Continue on the instruction page. (http://proxyhost:port/oaam_server/registerQuestions.do).

31. OAAM Server responds with the Question page.

32. The client selects Questions/Answers and submits them to the OAAM Server (http://proxyhost:port/oaam_server/registerQuestions.do).

33. OAAM Server updates the information and responds.

34. The proxy performs a send-to-client to the Next page.

    The response is intercepted at the proxy by the AllowLoginResponse interceptor. The proxy takes the sends to Client action by specifying the Next page after successful authentication. The client will then be redirected to the application page on the next step.

35. The client requests the Next page through the proxy (http://proxyhost:port/bigbank/activity.do).

36. The application page (activity.do) is sent back to the client through the proxy. This is where the login process ends.

    Logout Phase:

    Figure 6-9 Flow for users to log out of BigBank

    
    

37. The client clicks Log out (http://proxyhost:port/bigbank/logout.do).

38. The application sends back a response and redirects the client to bigbank/loginPage.jsp.

    The response is intercepted by Phase2LogoffPageResponse, which clears the session variables.

39. The client requests for the BigBank Login page (http://proxyhost:port/bigbank/loginPage.jsp).

40. The proxy intercepts the request and redirects the client to OAAM Server.

41. The client makes a request to OAAM Server for login.do (http://proxyhost:port/oaam_server/login.do).

42. OAAM Server redirects to the Jump page to fingerprint the client device.

43. OAAM Server fingerprints the client browser.

44. OAAM Server responds after fingerprinting with the Login page.

    Skip Registration phase: Client chooses to skip registration of questions. This phase happens after Login phase in regular flow.

    Figure 6-10 Flow occurs after user chooses to skip registration with OAAM Server

    
    

45. The client chooses to skip the registration (Post to http://proxyhost:port/oaam_server/registerQuestions.do).

46. OAAM Server responds.

47. The proxy intercepts the response and redirects the client.

    The response is intercepted by AllowLoginResponse. The proxy uses send-to-client to specify the next step for the client.

48. The client requests for the page specified by the proxy (http://proxyhost:port/bigbank/activity.do).

49. The BigBank application sends back a response.

    Deviation flow - Block login: happens when OAAM Server decides to block client after post authentication check. This flow replaces step 15-19 in login phase of regular flow.

    Figure 6-11 Deviation flow: user blocked by OAAM Server

    
    

50. OAAM Server decides to block the user after post authentication check.

    The response is an interceptor by the BlockLoginResponse interceptor. This interceptor redirects the client to the application Block page: /bigbank/BlockLoginPage

51. The proxy redirects the client to loginBlockPage of BigBank.

52. The client requests for BigBank BlockLoginPage (http://proxyhost:port/bigbank/loginPage.jsp?action=block).

53. The request is intercepted by LoginBlockedPageRequest by the proxy. The proxy accepts the get-server action for the Logout page: /bigbank/logout.do. This action ends the session at BigBank.

54. The application responds.

    The response is intercepted by Phase2LoginBlockedPageResponse. The proxy clears the session and redirects the client to the OAAM Login Block page.

55. The proxy redirects the client to the OAAM Login Block page.

56. The client requests the Block page from OAAM Server (http://proxyhost:port/oaam_server/loginPage.jsp?action=block).

57. OAAM Server responds with Blocked page

6.9 Upgrading the UIO Apache Proxy

Oracle Adaptive Access Manager patches may contain updates for the UIO Apache Proxy for Microsoft Windows and Linux (rhel4). Follow the instructions in this chapter to replace the mod_uio.so and related .dlls (on MS Windows) and .so (on Linux) libraries with those released as part of this patch release.

6.9.1 UIO Apache Proxy Patch Installation Instructions

Installation of a patch is similar to installing the UIO Proxy package. A patch will contain only the modified files. It is good practice to back up all your existing files since the patch will overwrite some or all of the files.

General instructions are given below. A patch contains only the modified files; so if a file is not available in the patch, skip that step. The steps are to be performed manually by the patch installer.

For both MS Windows and Linux:

1. Shut down the instance of Apache that you are updating

   Note:

   Ensure that you are using Apache httpd, version 2.2.8 with mod_ssl.

2. Back up existing files: binary, .rng and .xml files

3. Unzip patch_oaam_win_apache_uio.zip (for Windows) or patch_oaam_rhel4_apache_uio.zip (for Linux), which are located in the oaam_uio directory.

4. Copy the binary files from the patch (additionally on Linux, you need to set soft-links to .so files appropriately).

5. Copy UIO_Settings.rng and UIO_Config.rng files from the patch.

6. Compare your existing UIO_Settings.xml and UIO_log4j.xml files with those given in the patch and verify that you have the correct settings. Refer to the sections that apply to this patch and ensure that you have the correct settings. The same also applies to your configuration XML files.

7. Start Apache and run your sanity tests

   • For Windows,

     • The binary files are: mod_uio.so, log4cxx.dll, libxml2.dll, apr_memcache.dll (apr_memcache.dll was introduced in 10.1.4.5.bp1)

     • The configuration files are: UIO_Settings.rng, UIO_Config.rng, UIO_Settings.xml, UIO_log4j.xml and application configuration XML files

   • For Linux,

     • The binary files are: mod_uio.so, liblog4cxx.so.0.10.0.0, libxml2.so.2.6.32, libapr_memcache.so.0.0.1

     • The binary configuration files are: UIO_Settings.rng, UIO_Config.rng, UIO_Settings.xml, UIO_log4j.xml and application configuration XML files

6.9.2 UIO Apache Proxy Patch Backout Instructions

Restore the files that you had backed up before you installed the patch.

6.10 Upgrading the UIO ISA Proxy Server

To upgrade the UIO ISA Proxy Server:

1. Stop the Microsoft ISA Server with the following command:

   net stop fwsrv
   

2. Back up the current UIO ISA Proxy Server DLL. The DLL should usually be at: %ProgramFiles%\Microsoft ISA Server\BharosaProxy.dll.

3. Overwrite the existing DLL with the one from the patch.

4. Start Microsoft ISA Server with the following command:

   net start fwsrv