|Back | Next | Contents||Cams Web Agent Guide|
Windows impersonation enables a server application to temporarily be the client to access secure Windows resources. The Cams IIS web agent uses this feature to enable just in time sign-on (JITSO), where Cams authenticated users are granted single sign-on access to internally developed and commercial web applications that require Windows authorization. This feature is especially useful to extend Cams single sign-on services to Microsoft web applications such as Outlook Web Access (OWA) and SharePoint Portal Server (SPS).
NOTE: Windows impersonation was implemented by Microsoft starting with IIS 6.0. The infrastructure required for this feature is not supported in IIS 5.x.
This following sections describe how Windows impersonation with Cams works and how to configure Cams components with IIS to implement single sign-on.
HTTP Basic Authorization is a scheme within the HTTP protocol that enables a web browser, or other client program, to provide user name and password credentials to access HTTP resources that require authorization. With HTTP Basic Authorization, the browser prompts the user (with a dialog box) to enter a user name and password, which, if validated by the web server, is retained by the client and sent with each subsequent request to the same web server. In other words, the web server validates each HTTP request that requires authorization using the same credentials, but the client is not prompted each time because the credentials are cached by the client after the initial validation.
With Cams JITSO the user name and password credentials used to authenticate a user with Cams are saved in the user's Cams session and then reinserted into each HTTP request by the Cams web agent as it arrives at the web server, or just in time. The following describes the Cams JITSO using HTTP Basic Authorization header insertion with IIS sequence:
Table 1 summarizes the Cams components that must be configured to provide Cams JITSO using HTTP Basic Authorization header insertion with Microsoft IIS.
|Login module||Setting the option addPrivateCredentials to true adds a java.net.PasswordAuthentication object that contains the user name and password credentials authenticated by Cams to the Subject's private credentials set.|
|HTTP Basic Authorization Managed Session Event Handler||
A Cams managed session event handler:
that looks for the java.net.PasswordAuthentication object within a Subject's private credential set on Cams session creation. If found, it formats a valid HTTP Basic Authorization header value and adds it to the Cams session. The namespace and name of the created attribute and a list of excluded users (e.g., cams-web-agent) are configurable.
|Cams IIS Web Agent||
If the HTTP Basic Authorization header feature is enabled, the requested URL has a file path (URI) starting with a configured prefix, and the authenticated user has the specified session attribute, an HTTP Basic Authorization header is added to the HTTP request.
Table 1 - Cams components that implement Basic Authorizition header insertion with IIS
This section describes the steps required to install and configure the Cams JITSO using Basic Authorization Header insertion. The instructions assume you are using the system security domain. If you are using a different security domain, substitute the system for your security domain name. The examples assume you have resources that are secured by Microsoft Windows file and web server security access using the /secure URI. You might setup a simple test case following these instructions and then change or add your web resource URIs upon success.
In a text editor, open the file:
Customize the login module to access your Active Directory and enable the addPrivateCredentials option. Example 1 shows configuration of the UnboundID Active Directory login module.
Example 1- Enable private credentials addition for the UnboundID Active Directory login module in login-config.xml
For more information on customizing the Active Directory login module, please see the Cams Administrator's Guide - Login Configuration.
In a text editor, open the file:
Insert the following <session-event-handler> elements as the last component in the <session-manager-service> ... </session-manager-service> XML block. Configured as shown, this component will add a session attribute named basic_authorization in the private namespace for users who have password authentication object in their Subject's private credential set. As an optimization, certain users are excluded with a comma-delimited list. You are recommended to minimally include the user name for Cams web agents (e.g., cams-web-agent) if this component is deployed in the system security domain. Additional users, including those defined in Active Directory can be added to this list as required.
<session-manager-service ...> ... <!-- On session creation (after successful authentication), add a session attribute for use by Cams agents configured to insert a Cams JITSO using HTTP Basic Authorization header. --> <session-event-handler className="examples.session.HttpBasicAuthManagedSessionEventHandler" debug="false"> <param-list> <param name="session-attr-namespace" value="private"/> <param name="session-attr-name" value="basic_authorization"/> <param name="excluded-users" value="cams-web-agent,admin,guest"/> </param-list> </session-event-handler> </session-manager-service>
Example 2- Configure the HttpBasicAuthManagedSessionEventHandler component in security-domain.xml
NOTE: If the login configuration uses a directory other than Active Directory, then you may need to map the authenticated user to a user name and password valid on the target IIS web server system. One way to do this is to modify the HTTP Basic Authorization managed session event handler to lookup the Active Directory user name and password for the Cams authenticated user in an SQL database table. You can then add the retrieved credentials to the Cams user session. The source code for this component is available in the Cams documentation download in the examples.zip file.
In a text editor, open the file:
To ensure use of Cams single sign-on for access to the target resources secured by Windows, your Cams access control policy must be configured to require user authentication. For example, if target IIS web server resources secured by Windows security are accessed from your IIS web server via the /secure URI, then a Cams permission and access control rule like those shown in Example 3 are sufficient to enforce user authentication.
... <!-- Require Cams authentication to access to web resources using Windows impersonation --> <permission desc="Require an authenticated Cams user"> <resource-pattern id="*://*:*/secure*"/> <acr-ref id="Authenticated User Rule"/> </permission> ... <!-- Access control rule to require a Cams authenticated user --> <auth-acr id="Authenticated User Rule"> </auth-acr> ...
Example 3 - Configure the Cams access control policy to require user authentication in access-control-policy.xml
Install the Cams IIS web agent in your target IIS web servers hosting homegrown, OWA, SPS or other Microsoft web applications. You must make these changes for each target IIS web server with a Cams IIS web agent that must support Windows impersonation.
In a text editor, open the file:
Modify the properties shown in Example 4. Be sure to set the URI prefixes by editing the value of cams.basic.auth.insertion.uri-list. Example 4 shows setting cams.basic.auth.insertion.uri-list to /secure, which ensures that HTTP Basic Authorization header injection is done for HTTP requests to URI patterns that start with /secure (do not supply a wildcard character at the end of each prefix). Also, the session attribute namespace and name must match the values set by the HTTP Basic Authorization managed session event handler.
Example 4 - Configure the Cams IIS web agent for Cams JITSO using Basic Authorization header insertion in cams-webagent.conf
NOTE: We recommend you define the cams.basic.auth.insertion.uri-list URI patterns as narrowly as possibly to minimize HTTP Basic Authorization header injection to only those web applications for which it is required. Generally, you also want to disable case sensitivity (cams.basic.auth.insertion.uri-list.case-sensitive=false) because IIS is not a case sensitive web server.
You must ensure that target web resources are secured using Windows file system security to only grant access by the desired users and groups. This may already be set by default for applications such as OWA and SPS. You must also set IIS to protect web resources using Microsoft HTTP Basic Authorization. See Figure 1, which shows settings on the IIS Management Console's Authentication Methods dialog for a selected resource. To navigate to this dialog:
Figure 1 - Target IIS resources must be protected using Basic Authorization.
As you can see, anonymous access is disabled. Usually, additional authentication methods such as Integrated Windows authentication are not be selected, but can be. Selection of the Default domain and Realm is not required unless the Windows domain or other operating system authentication controller used to authenticate the user or group is ambiguous.
The configuration changes you've made require that you restart each Cams policy server node in your cluster. You must also then restart each IIS web server containing a Cams IIS web agent for the changes in cams-webagent.conf to take effect.
After your Cams policy server(s) and IIS web server(s) restart, access a URL for a target resource on an IIS web server, such as:
You should be prompted for authentication by Cams. Upon successful authentication by Cams, you should be redirected to the originally requested URL without addition requests for credentials by IIS via a popup dialog box in your browser.
This section provides a sequence of debugging measures to ensure that individual components are configured and working correctly.
First, confirm that the login module is adding the password authentication token to the Subject private credential set. Enable the debug flag as shown in Example 5 for the UnboundID Active Directory login module in login-config.xml.
Example 5 - Enabling the Active Directory login module debug flag in login-config.xml
After restarting your Cams policy server and authenticating, you should see DEBUG statements that show the Active Directory login module adding a java.net.PasswordAuthentication instance to the private credentials in the log file CAMS_HOME/logs/system-trace.log as shown in Example 6.
... [DEBUG] [ActiveDirectoryLoginModule] User entered username = johndoe
Example 6 - Sample authentication DEBUG messages from the Active Directory login module component in CAMS_HOME/logs/system-trace.log
Second, ensure that the HTTP Basic Authorization managed session event handler is adding the private credentials to the Cams user session. Enable the debug flag as shown in Example 7 for the examples.session.HttpBasicAuthManagedSessionEventHandler configured in security-domain.xml.
<session-manager-service ...> ... <!-- On successful session creation (after successful authentication), Add a session attribute for use by Cams agents configured to insert a "just in time" HTTP Basic Authorization header. --> <session-event-handler className="examples.session.HttpBasicAuthManagedSessionEventHandler" debug="false"> <param-list> <param name="session-attr-namespace" value="private"/> <param name="session-attr-name" value="basic_authorization"/> <param name="excluded-users" value="cams-web-agent,admin,guest"/> </param-list> </session-event-handler> </session-manager-service>
Example 7 - Enabling the HttpBasicAuthManagedSessionEventHandler debug flag in security-domain.xml
After restarting your Cams policy server and authenticating, you should see DEBUG statements that show the HTTP Basic Authorization managed session event handler adding an HTTP Basic Authorization attribute in the log file CAMS_HOME/logs/system-trace.log as shown in Example 8.
[DEBUG] ... handling ManagedSessionEvent:
Example 8 - Sample DEBUG messages from the HttpBasicAuthManagedSessionEventHandler component CAMS_HOME/logs/system-trace.log
Third, ensure that the Cams IIS web agent is insert the HTTP Basic Authorization header into the HTTP request. Enable the debug flag as shown in Example 9 for the Cams IIS Web Agent in file cams-webagent.conf.
... cams.debug=true ...
Example 9 - Enabling the Cams IIS web agent debug flag in cams-webagent.conf
After restarting your Cams IIS Web Agent, authenticating and requesting a URI configured for HTTP Basic Authorization header insertion, you should see DEBUG statements that show the Cams IIS web agent inserted an HTTP Basic Authorization header in log file CAMS_WEBAGENT_HOME/logs/cams-webagent.log as shown in Example 10.
[DEBUG] Basic Authorization insertion (start)
Example 10 - Sample DEBUG messages from the Cams IIS web agent component in CAMS_WEBAGENT_HOME/logs/cams-webagent.log
WARNING: If Windows impersonation succeeds, HTTP request headers related to HTTP Basic authorization are populated by IIS including: LOGON_USER, HTTP_AUTHORIZATION, AUTH_USER, AUTH_PASSWORD and AUTH_TYPE. LOGON_USER and AUTH_USER display the Windows user identity. Both the HTTP_AUTHORIZATION and AUTH_PASSWORD provide the user's password in cleartext (the former base-64 encoded) and should never be displayed or accessed without good reason.