Back | Next | Contents Cams Web Agent Guide

Cams Single Sign-on using IIS Windows Impersonation

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.

Cams JITSO using HTTP Basic Authorization Header Insertion with IIS Overview

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:

  1. On successful Cams user authentication, the user name and password are saved by a Cams login module (Active Directory is usually the user store).
  2. On Cams session creation, a Cams policy server managed session event handler retrieves the saved credentials, formats a standard base-64 encoded HTTP Basic Authorization header value and adds it to the user session for access by Cams web agents.
  3. When an authenticated user accesses an HTTP resource protected by a Cams IIS web agent with HTTP Basic Authorization header insertion activated, the Cams IIS web agent checks a list of URI prefixes to determine if HTTP Basic Authorization header insertion should be attempted. If the URI matches and the user has the specified session value, then a HTTP Basic Authorization header is added to the HTTP request.
  4. During the ISAPI authentication processing stage, the Cams IIS web agent retrieves the HTTP Basic Authorization header, base-64 decodes it and sets the user name and password. If these credentials correspond to a valid Windows user, then IIS will impersonate that Windows identity for the remainder of the HTTP request.

Table 1 summarizes the Cams components that must be configured to provide Cams JITSO using HTTP Basic Authorization header insertion with Microsoft IIS.

Component Description
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:

examples.session.HttpBasicAuthManagedSessionEventHandler

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

Configuring Cams JITSO using Basic Authorization 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.

Step 1 - Configure the login module to add private credentials

In a text editor, open the file:

CAMS_HOME/conf/domains/system/login-config.xml

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.

<login-module-entry
className="com.cafesoft.cams.auth.login.module.UnboundIDActiveDirectoryLoginModule"
flag="REQUIRED">
<options> <option name="debug" value="false"/>
<option name="ldapPoolServiceId" value="unboundid-ldap-connection-pool"/> <option name="baseDN" value="cn=Users,dc=domain,dc=com"/> <option name="scope" value="ONE"/> <option name="filter" value="(&amp;(objectclass=user)(userPrincipalName={username}))"/> <option name="attribute" value="memberOf"/> <option name="groupNameServiceId" value="unboundid-active-directory-group-name"/> <option name="domain" value="domain.com"/> <option name="useDomainInRoleSearch" value="true"/> <option name="addPrivateCredentials" value="false"/> </options>
</login-module-entry>

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.

Step 2 - Configure the HTTP Basic Authorization Managed Session Event Handler

In a text editor, open the file:

CAMS_HOME/conf/domains/system/security-domain.xml

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.

Step 3 - Configure your Cams access control policy

In a text editor, open the file:

CAMS_HOME/conf/domains/system/access-control-policy.xml

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

Step 4 - Install and configure the Cams IIS web agent

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:

CAMS_WEBAGENT_HOME/conf/cams-webagent.conf

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.

...

#
#--- Cams JITSO using HTTP Basic Authorization Header Insertion
#
# cams.basic.auth.insertion.enabled
# Toggle Cams HTTP Basic Authorization header insertion on/off [true|false].
#
# cams.basic.auth.insertion.uri-list
# Comma-delimited list of URI prefixes for which Basic Authorization headers
# will be inserted.
# # cams.basic.auth.insertion.uri-list.case-sensitive
# Toggle case sensitive URI prefix matching on/off [true|false]. #
# cams.basic.auth.insertion.session-attr.namespace
# Cams session attribute namespace containing the Basic Authorization
# header attribute value.
#
# cams.basic.auth.insertion.session-attr.name
# Cams session attribute name in which to look for the Basic Authorization
# header value.
#

cams.basic.auth.insertion.enabled=true
cams.basic.auth.insertion.uri-list=/secure
cams.basic.auth.insertion.uri-list.case-sensitive=false
cams.basic.auth.insertion.session-attr.namespace=private
cams.basic.auth.insertion.session-attr.name=basic_authorization
...

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:

  1. Open the IIS Management Console
  2. Navigate in the tree menu in the left panel to a web server
  3. Right click a target resource in the right panel (a file or directory or virtual directory like /secure)
  4. Select Properties from the popup menu
  5. Click the File Security tab in the properties dialog
  6. Click the Edit button in the Authentication and Access Control group.

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.

Step 5 - Restart your Cams policy and IIS web server(s)

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.

Step 6 - Test

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:

http://localhost/secure/default.htm

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.

Troubleshooting

This section provides a sequence of debugging measures to ensure that individual components are configured and working correctly.

Login module component debug

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.

<login-module-entry
className="com.cafesoft.cams.auth.login.module.UnboundIDActiveDirectoryLoginModule"
flag="REQUIRED">
<options> <option name="debug" value="true"/>
<option name="ldapPoolServiceId" value="unboundid-ldap-connection-pool"/> <option name="baseDN" value="cn=Users,dc=domain,dc=com"/> <option name="scope" value="ONE"/> <option name="filter" value="(&amp;(objectclass=user)(userPrincipalName={username}))"/> <option name="attribute" value="memberOf"/> <option name="groupNameServiceId" value="unboundid-active-directory-group-name"/> <option name="domain" value="domain.com"/> <option name="useDomainInRoleSearch" value="true"/> <option name="addPrivateCredentials" value="false"/> </options>
</login-module-entry>

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
[DEBUG] [ActiveDirectoryLoginModule] Added CSUserPrincipal 'johndoe' to principal List
[DEBUG] [ActiveDirectoryLoginModule] Adding Password authentication method
[DEBUG] [ActiveDirectoryLoginModule] Adding java.net.PasswordAuthentication instance to private credentials ...

Example 6 - Sample authentication DEBUG messages from the Active Directory login module component in CAMS_HOME/logs/system-trace.log

HTTP Basic Authorization managed session event handler component debug

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: 
class=examples.session.HttpBasicAuthManagedSessionEventHandler
[DEBUG] ... checking list of excluded users
[DEBUG] ... looking for PasswordAuthentication in private credentials set
[DEBUG] ... found PasswordAuthentication token
[DEBUG] ... adding session attribute namespace=private,
name=basic_authorizationBasic Z1nQ2gojokoyYmFabquY

[DEBUG] ... handled ManagedSessionEvent:
class=examples.session.HttpBasicAuthManagedSessionEventHandler

Example 8 - Sample DEBUG messages from the HttpBasicAuthManagedSessionEventHandler component CAMS_HOME/logs/system-trace.log

Cams IIS web agent component debug

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)
[DEBUG] Basic Authorization insertion (cont): Request URI matches uri-list
[DEBUG] Basic Authorization insertion (cont):
Found session-attr private:basic_authorization=Basic Z1nQ2gojokoyYmFabquY
[DEBUG] Inserting Basic Authorization header
[DEBUG] Adding header, Authorization=Basic Z1nQ2gojokoyYmFabquY, to agentRequest

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.

Back | Next | Contents