|Back | Next | Contents||Cams Web Agent Guide|
To ease integration, configuration, and management, some sites deploy a reverse proxy web single sign-on server. In this configuration, a reverse proxy server resides between the resource requesters (typically end users on the Internet) and your web and application servers. The reverse proxy is a broker that handles all incoming requests from the Internet for resources inside the firewall. This network topology makes a reverse proxy a natural policy enforcement point for all authentication and access control decisions.
You can configure a Cams policy server, a Cams Apache web agent, and Apache to implement a reverse proxy web security system. In this configuration, you no longer need to deploy Cams web agents in the web and applications servers that are protected by the reverse proxy (although you may still want to do so, especially if a system can be accessed directly by internal or external users). Using Apache as a reverse proxy also enables you to protect web and application servers for which a Cams web agent does not currently exist.
This document describes how you configure the Cams Apache web agent as a reverse proxy web single sign-on server. The document assumes that you have already installed and configured a Cams policy server and a Cams Apache web agent.
A reverse proxy is web server that delivers static and dynamic web pages sourced from other web and application servers. Previously requested web pages can also be cached on the reverse proxy to improve performance. To the end user and browser, all pages sourced from remote resource servers look like they originated at the reverse proxy.
Apache is a modular server. This implies that only the most basic functionality is included in the core server. Extended features are available through modules which can be optionally compiled or dynamically loaded into Apache. To configure Apache as a reverse proxy requires the mod_proxy module, which is an extension commonly found in many binary Apache distributions.
To see which modules are compiled into your Apache server, you can use the
-l command line option:
If the server is compiled to use dynamically loaded modules, then modules can be compiled separately and added at any time using the LoadModule directive. In this case, you should see the following uncommented lines in the load and available module lists of the httpd.conf file:
LoadModule proxy_module modules/libproxy.so
If the lines exist but are commented (with the "#" sign), uncomment them by removing the "#" sign and restart Apache to load mod_proxy.
If do not see any references to mod_proxy, you will need to obtain and install it before proceeding. Please consult the Apache documentation that came with your installation.
NOTE: Cams supports both Apache 1.3 and Apache 2.0 in the reverse proxy configuration. In Apache 2.0, caching features were removed from mod_proxy and moved into mod_cache for more generalized availability with other resources. Hence, Apache 2.0 requires installation and configuration of mod_cache in addition to mod_proxy.
Once mod_proxy (and mod_cache for Apache 2.0) is installed, configuring Apache as a reverse proxy is straight forward using mod_proxy's ProxyPass and ProxyPassReverse directives.
This directive allows remote servers to be mapped into the space of the local server; the local server does not act as a proxy in the conventional sense, but appears to be a mirror of the remote server resources.
Syntax: ProxyPass [path] !|url
Suppose the local server has address http://wibble.org/; then
ProxyPass /mirror/foo/ http://foo.com/
will cause a local request for the http://wibble.org/mirror/foo/bar
to be internally converted into a proxy request to http://foo.com/bar.
This directive lets Apache adjust the URL in the Location, Content-Location, and URI headers on HTTP redirect responses. This is essential when Apache is used as a reverse proxy to avoid by-passing the reverse proxy when HTTP redirects occur on the remote servers.
Syntax: ProxyPassReverse [path] url
Suppose, for example, that the local server has address http://wibble.org/; then
ProxyPass /mirror/foo/ http://foo.com/
ProxyPassReverse /mirror/foo/ http://foo.com/
will not only cause a local request for http://wibble.org/mirror/foo/bar to be internally converted into a proxy request to http://foo.com/bar (via the ProxyPass), but it also takes care of redirects that foo.com sends. When http://foo.com/bar is redirected by him to http://foo.com/baa Apache adjusts the redirect to http://wibble.org/mirror/foo/baa before forwarding the HTTP redirect response to the client.
NOTE: Using the trailing slash when the last name specified in the a path is a directory is recommended, as it instructs Apache that the file is a directory. However, it does create a problem if an HTTP request does not include the slash. See Trailing Slash Problem for more information.
You should ensure that Apache's native security is not imposing any security contraints on the proxy requests. Configuration is slightly different for Apache 1.3 and Apache 2.0. For example:
Apache 1.3<IfModule mod_proxy.c> ProxyRequests Off<Directory proxy:*> Order deny,allow Allow from all </Directory>
ProxyRequests Off<Proxy *> Order deny,allow Allow from all </Proxy>
Once you have configured the ProxyPass and ProxyPassReverse values for your site, then, restart Apache and test. To avoid confussion, you should configure and test the ProxyPass and ProxyPassReverse directives before you enable the Cams Apache web agent.
You may choose from three topologies when implementing Cams with a Apache reverse proxy server:
If you choose the Apache reverse proxy only, simply follow the normal Cams Apache web agent instructions using the URL space of the reverse proxy. If you choose to install Cams web agents in the web and application servers, make sure that you review this section in its entirety.
First, you must ensure that all Cams web agent configuration values in the web tier point to the URL space of the reverse proxy (not to the servers in the web tier). This ensures that all requests, including redirects by Cams web agents, pass through the reverse proxy server correctly. You should also select one server in your farm that will act as an authentication server. To do this, make sure that the cams-webagent.conf after.logout.url parameter for each Cams web agent are set to redirect to the authentication server in the URL space of the reverse proxy. For example:
In these example values, the requests for /cams/* resources are proxied by the Apache reverse proxy to a Tomcat J2EE server acting as the authentication server and using the cams webapp (any Cams web agent supported server could be used including Apache, Microsoft IIS, and other J2EE servers). Also, you need to change the camsLoginUrl in the Cams server's corresponding login-config.xml file to the fully qualified reverse proxy URL for the authentication server login page:
The corresponding Apache reserve proxy server ProxyPass directives for this example might be:
ProxyPass /cams http://tomcat6.mycompany.com:8080/cams
ProxyPassReverse /cams http://tomcat6.mycompany.com:8080/cams
... other proxy pass directives as required
WARNING: If you configure a Cams web agent on the Apache reverse proxy AND on web tier servers, you MUST disable Cams request headers on either the reverse proxy or the web tier servers. This is done in cams-webagent.conf for each Cams protected server by setting:
Each Cams web agent checks to make sure their are no CAMS_*
request headers in a request (to ensure the user isn't spoofing values). If
Cams request headers are enabled for the Apache reverse proxy, it injects CAMS_*
values into the request. The web server tier Cams web agent will detect CAMS_*
values in the request and redirect to a Cams error page, which will put Cams
into an infinite loop. The Cams web agents detects and breaks out of this condition
after a number of iterations but all access to resources on the web tier server
will be denied.
The permissions you setup in the Cams security domain protecting your Apache reverse proxy configuration map to the reverse proxy's URL space. You simply setup all permissions as if all resources were local to the reverse proxy. Extending the example above for wibble.org, you might define a Cams permission such as:
<permission desc="Allow access by authenticated employees"> <resource-pattern id="http://wibble.org:80/mirror/foo/"/> <acr-ref id="require employee role"/> </permission>
This permission would restrict access to employees for URL requests starting with http://wibble.org:80/mirror/foo/ (assuming that your network topology was setup to disallow direct access to http://foo.com/). Alternatively, you can use wildcards to make the permissions independent from the protocol, server, and port:
<permission desc="Allow access by authenticated employees"> <resource-pattern id="*://*:*/mirror/foo/"/> <acr-ref id="require employee role"/> </permission>
You can setup any other permission and rules as required to protect the content on the remote servers that are proxied through the Cams Apache reverse proxy web agent.
Every webmaster can sing a song about the problem of the trailing slash on URLs referencing directories. If they are missing, the server returns an error because requests for /mirror/foo instead of /mirror/foo/ cause the server to search for a file named foo. And because this file is a directory it complains. Actually, for browser requests the web server tries to fix the problem by automatically redirecting the request with a trailing slash. But, in some cases, such as the case of the Apache reverse proxy server, you need to fix the request yourself.
The solution to this subtle problem is to force the server to add the trailing slash automatically for URLs that will be reverse proxied. To do this correctly you must use an external redirect, so the browser can correctly request referenced resources such images or cascading style sheets. If you only do an internal rewrite, this would only work for the directory page, but would go wrong when images or style sheets are included in the page with relative URLs. For instance, a request for image.gif in /mirror/foo/index.html would become /mirror/image.gif without the external redirect. This would result in a file not found 404 error for image.gif.
To add the trailing slash for directories that could be exposed to this condition, you need to rewrite the URLs with another Apache module named mod_rewrite. As with mod_proxy, you must insure that mod_rewrite is installed to use these directives.
For example, the rewrite at request to http://www.wibble.org/mirror/foo to http://www.wibble.org/mirror/foo/, you would add the following lines to httpd.conf:
RewriteRule ^/mirror/foo$ foo/ [R]
See the mod_rewrite documentation for more configuration and usage information.