| Back | Next | Contents | Cams Administrator's Guide |
Cams Automatic Enterprise Sign-On (AESO) enables transparent user authentication into Cams by trusting an enterprise user identity established via some method outside of Cams. Cams AESO is generally used within a corporate Intranet to leverage an enterprise identity already established via a desktop login to a Windows Domain Controller, Kerberos, NIS, etc.
Scenarios where you may find Cams AESO useful include:
The nature of enterprise environments and the breadth of Cams AESO integration options nearly ensures that your configuration options will be unique. The information in the remainder of this document provides you with both general information and specific settings to configure popular native authentication types for use with Cams AESO. As always, if you have questions on how Cams AESO might best be used in your environment, please contact Cafésoft support.
Though Cams AESO can be used in many different environments, typical applications leverage the user identity from a desktop login (e.g. login to a Windows Domain, Kerberos Realm, or NIS) to transparently create a Cams web single sign-on session. Figure 1 shows how Cams AESO works in such an environment.
Figure 1 - Transparent login to Cams using a desktop identity and Cams AESO
Some of the benefits provided by Cams AESO include:
Increased user convenience. Depending on your selected native authentication method and configuration, users may be transparently authenticated with Cams based on their desktop identity. In some environments, users may still need to enter login credentials when accessing the web environment, but can use the same credentials used during desktop login.
Limited native authentication settings. Using Cams AESO, you only need to configured native authentication on one (or two for redundancy) web servers in your environment. If your enterprise environment is mostly Windows-based, then you can use an IIS web server and Integrated Windows Authentication with Cams AESO. Once a user is authenticated with Cams, he can access web applications and protected resources on any other Cams-enabled web servers in you environment, including Apache, Tomcat, JBoss, WebLogic, and others.
Centralized security administration. Your Cams access control policy provides the centralized rules specifying which web resources require user authentication, which roles are required, etc. Except for your selected native authentication settings, Cams login configuration and security event logging is also centralized in your Cams policy server.
Leverage other Cams features. Cams AESO can be used in conjunction with the full range of Cams features, for example, Cams Cross DNS Domain Single Sign-On (CDSSO) for access to web servers across cookie domains.
Cams AESO is implemented using compatible configuration settings in four distinct locations:
The following series of steps is recommended to simplify Cams AESO configuration:
Ensure the following Cams AESO prerequisites are met.
Cams AESO was implemented as a minor release within the Cams 3.0 distribution. Though AESO beta software was available in the late summer of 2008, production software was released in December of 2008. If necessary, obtain the latest Cams policy server, web agents and documentation or check the release notes for your current components to ensure Cams AESO is supported.
NOTE: You need only install updated Cams web agents on web servers where AESO login will be configured. Web servers that will not handle AESO authentication requests do not require a software upgrade.
Install the AESO-enabled Cams policy server and web agents.
In Step 2, you will configure native web server authentication in the web server(s) where AESO login will occur. To avoid possible interactions with the Cams web agent on your designated native authentication web server before the Cams web agent and policy server are fully configured, temporarily disable Cams AESO. To disable Cams AESO in a Cams web agent, set the following configuration value in cams-webagent.conf:
cams.aeso.enable=false
In this step, you'll need to configure native web server authentication for the Cams AESO URI, which is configured in cams-webagent.conf with the following property:
cams.aeso.uri=/cams/aeso
Later, when AESO is enabled in the Cams web agent, an HTTP GET request to this URI will be interpreted as a Cams AESO request. For AESO to work, the web server must authenticate the user when this URI is requested. After successful native authentication, the Cams web agent will be able to get the trusted user identity from web server's internal data structures and create a Cams SSO session. If properly configured, use of Cams AESO will be invisible to users.
Configuring native web server authentication differs based on web server, authentication type, and site-specific requirements. Please refer to section Native Web Server Authentication Reference to implement native web server authentication on the web server where Cams AESO login will be enabled. For convenience, links to information on popular options are provided below.
Cams AESO web agent configuration settings are needed only on web servers where native authentication will be implemented. When a Cams access control policy determines that users need to authenticate, their web browsers will be redirected to a URL on one of these web servers.
To minimize native configuration settings, it is recommended that you designate one or two web servers and their associated Cams web agent.
For Cams web agents in web servers where native authentication is implemented, enable Cams AESO by setting value value shown in Example 1.
|
cams.aeso.enabled=true |
Example 1 - The recommended Cams AESO login configuration entry value in cams-webagent.conf
The value of cams.loginconfig.entry in cams-webagent.conf files is sent by Cams web agents to Cams policy servers in access control requests. If an access control policy determines that user authentication is required, the camsLoginUrl associated with this login configuration entry is returned to the Cams web agent. The web agent then redirects the user's browser to the camLoginUrl with appended query parameters: cams_security_domain, cams_login_config and cams_original_url.
Though Cams AESO can be implemented using any login configuration entry defined in login-config.xml, including the default http, we recommend using aeso. The default system security domain login-config.xml file included with Cams policy servers supporting AESO contains an example <login-config-entry name="aeso"> element. By changing the cams.loginconfig.entry value in your cams-webagent.conf files, you'll be able to configure login modules for use with AESO without disturbing configuration settings you may already have for http.
In all cams-webagent.conf files in your environment, change/set the value shown in Example 2.
|
cams.loginconfig.entry=aeso |
Example 2 - The recommended Cams AESO login configuration entry value in cams-webagent.conf
For Cams web agents in web servers where native authentication is implemented, set the security domains that will use AESO as shown in Example 3.
NOTE: Multiple security domain names can be separated using commas.
|
cams.aeso.security_domains=system |
Example 3 - The recommended Cams AESO login config entry value in cams-webagent.conf
For Cams web agents in web servers where native authentication is implemented, you must configure the callback values the Cams web agent will send in authentication requests to the Cams policy server. These values are configured per-security domain. You may configure as many values as needed by the login modules configured for use with AESO in your Cams policy server(s). By default, the values shown in Example 4 for the system security domain are set in most cams-webagent.conf files:
|
# |
Example 4 - Default Cams AESO callback values in cams-webagent.conf for the "system" security domain
NOTE: Cams AESO login modules require a callback value named agent_secret, which is used to protect against user impersonation attacks. You must create a unique, secret value for your site and configure it as AESO callback value agent_secret in cams-webagent.conf and in login-config.xml in the corresponding security domain of each Cams policy server and for each Cams AESO login module. To create a unique value for your site, run one of the following scripts:
CAMS_HOME/bin/secretKeyGen.bat
or
CAMS_HOME/bin/secretKeyGen.sh
Use the generated value of cams.skey.key.
Configuration properties of the form:
cams.aeso.callback.names.<security_domain>=<cb_name>[,<cb_name_2>]
indicate the names of callback values that will be sent with Cam AESO authentication requests. For every callback value name, you must also configure a property that specifies where to get the callback value. Callback value specifications can be literal (a hard-coded value) or can reference namespace-qualified data within the web server's HTTP request by using a special curly bracket syntax. Examples include:
cams.aeso.callback.value.system.agent_secret=foobar
A callback value named agent_secret is assigned the literal (hard coded) value foobar.
cams.aeso.callback.value.system.username={http_request:REMOTE_USER}
A callback value named username is assigned the native authenticated user name from data within the HTTP request. This value is generally obtained by the Cams web agent from a platform-specific data structure within the HTTP request. The reference name http_request:REMOTE_USER is standard for all Cams web agents supporting AESO and should not be confused with the CGI-BIN environment variable REMOTE_USER (though it will usually have the same value).
cams.aeso.callback.value.system.auth_header={http_header:Authorization}
A callback value named auth_header will be set to the value of HTTP request header Authorization, which is a standard HTTP header used by Basic, Digest, Negotiate, NTLM and Kerberos client authentication. If the header is not present, the value is a zero length string.
cams.aeso.callback.value.system.my_cookie={http_cookie:MY_COOKIE,none}
A callback value named my_cookie will be set to the value of HTTP cookie MY_COOKIE. If a cookie by that name is not present in the HTTP request, the callback value is set to none.
Table 1 summarizes the available Cams AESO callback value reference namespaces and provides some useful examples.
| Namespace | Description |
|---|---|
| http_request: |
Used to access HTTP request values store in platform-specific data structures. For example, the native authenticated user name is accessed differently in Apache modules, IIS ISAPI filters and J2EE containers. Referenced names are case-insensitive. Examples: http_request:REMOTE_USERhttp_request:USER |
| http_header: |
Used to access HTTP request header values. Standard HTTP request headers are defined by the HTTP specification. HTTP clients send appropriate headers, which may vary based on the client type, the requested resource type, cookie state, authentication state, etc. Cams HTTP request headers are not available because the user has not yet been authenticated (in most cases) and the Cams web agent has not yet injected them into the request. Examples: http_header:Set-Cookiehttp_header:Authorization http_header:User-Agent |
| http_cookie: |
Used to access an HTTP cookie value (from within the standard Set-Cookie header). The cookie name is case-insensitive. A cookie value may be useful for transparently authenticating a user based on a third-party identity. Examples: http_cookie:MY_COOKIEhttp_cookie:CAMS_SID_MYCAMSCLUSTER_SYSTEM |
Table 1 - Standard Cams AESO Callback Value Reference Namespaces
You'll need to restart the web server to ensure the Cams web agent configuration setting is reloaded.
Cams AESO policy server settings are made in security domain-specific configuration files. Nearly all of the settings are in the login-config.xml file, but you must also edit your access control policy (access-control-policy.xml) file as you would for normal Cams login to ensure that resources that require user authentication are protected by appropriate <auth-acr> rules.
The login-config.xml file in the system security domain that ships with the Cams policy server contains a <login-config-entry> with name aeso. It contains sample configuration settings for each of the AESO-specific login modules. You must use Cams login modules specifically written to support AESO for reasons that are described later.
Though Cams AESO does not require that your login modules be configured under the aeso <login-config-entry> element, the instructions in this document recommend that you use it rather than the standard http <login-config-entry>. You can configure your AESO login modules under any <login-config-entry> element, just make sure that your cams-webagent.conf files contains the appropriate cams.loginconfig.entry property value and that your proactive login page use the correct cams_login_entry query parameter.
Cams AESO login modules may be stacked like other Cams login modules and assigned the standard JAAS flags to indicate if they are REQUIRED, OPTIONAL, SUFFICIENT or REQUISITE. Configure one or more Cams AESO login modules in your security domain login-config.xml file by referencing the following Cams AESO Login Configuration Settings Reference section for appropriate configuration information.
Use the same Cams access control rules with AESO as with standard Cams login. You'll need to make sure that web resources requiring user authentication are protected by appropriate permissions.
This section and detailed Cams AESO reference information for configuring specific web servers, Cams web agents and user directories. Reference information is organized into the following sections:
The following sections provide web server-specific information and hints for popular native authentication types with links to additional information. You should consult the vendor-specific information for specialized authentication types like smart cards, OTP tokens, biometrics, etc.
Contact Cafésoft support if you have questions on how other native authentication options might be integrated with Cams AESO.
The information and links below apply to Apache 2.0 and Apache 2.2 web servers.
The Kerberos Authentication protocol can be used with Apache web servers by using with the mod_auth_kerb Apache module. This module and configuration instructions are freely available at http://modauthkerb.sourceforge.net. Follow the instructions available at this site to download, compile, install and configure mod_auth_kerb for your Apache server.
This module can be used with the following Kerberos implementations:
Example 5 shows sample configuration settings used to force Kerberos authentication when the Cams AESO URI is requested.
NOTE: Your configuration options will vary based on site requirements.
LoadModule auth_kerb_module modules/mod_auth_kerb.so ... <Location /cams/aeso> AuthName "Kerberos Login" AuthType Kerberos Krb5Keytab /usr/local/apache2/conf/auth_kerb.keytab KrbAuthRealms EXAMPLE.COM KrbMethodNegotiate off KrbSaveCredentials off KrbVerifyKDC off Require valid-user </Location> |
Example 5 - Sample Cams AESO mod_auth_kerb settings in the Apache httpd.conf file
Though HTTP Basic and Digest authentication are not recommended for general use (because clear text or hashed login credentials are easily obtained via the HTTP Authorization header), they can be useful for HTTP clients that require them.
NOTE: If you choose to use HTTP Basic or Digest authentication, use them only over SSL-enabled connections to minimize the risk of user name/password interception.
Apache HTTP Basic and Digest authentication are available in Apache by using one of the following modules:
Example 6 shows sample configuration settings used to force HTTP Basic authentication when the Cams AESO URI is requested. The example shows use of a password file to store user names and passwords.
NOTE: Your configuration options will vary based on site requirements.
LoadModule auth_module modules/mod_auth.so ... <Location /cams/aeso> AuthName "HTTP Basic Login" AuthType Basic AuthUserFile user.passwd Require valid-user </Location> |
Example 6 - Sample Cams AESO HTTP Basic/mod_auth settings in the Apache httpd.conf file
The instructions in this section are specific to and enviroment using the following popular system components:
The high-level configuration steps required for an environment like this include:
All Unix/Linux-based Cams Apache web agents ship with a file named "mod_cams_client_cert_lookup.so". This Apache module installs with the web agent into the "modules" directory and works in conjunction with the normal Cams web agent module. It exports the client certificate (and values within the certificate) to the internal Apache HTTP request data structures where the agent can access them for use in Cams login requests. Example 7 shows the required and sample configuration settings for this module in the Apache httpd.conf file:
... # # Load the Cams web agent client X509 certificate helper module. # LoadModule CamsClientCertLookup_module modules/mod_cams_client_cert_lookup.so CamsClientCertLookup_setSSLEnvVarNames SSL_CLIENT_S_DN_Email CamsClientCertLookup_debug false ... |
Example 7 - Sample Cams AESO HTTP mod_ssl settings in the Apache ssl.conf file
The SSL environment variable configuration setting shows that a variable named "SSL_CLIENT_S_DN_Email" will be exported as an environment variable with for access by the Cams web agent module. The module will also automatically make the X.509 certificate available to the agent via the Apache HTTP request. You may also use the configuration value "all" or a comma-separated list of mod_ssl environment variables as specified in the mod_ssl documentation. The "SSL_CLIENT_S_DN_Email" environment variable will be assigned to a Cams callback value named "email_addr" in cams-webagent.conf and will be used in the AESOX509CertLoginModule to lookup the stored client certificate in the LDAP directory for comparison with the one provided by the client.
Before continuing with these AESO/X.509/LDAP configuration instructions, we recommend you read Configuring Apache 2.0 for SSL/TLS Mutual Authentication using an OpenSSL Certificate Authority, which provides a lot of context for configuring X.509 client certificates in the Apache environment. Though some of the information may not pertain to your environment, it will expose you to many options that you may not have considered and which may be useful. If your environment contains other system elements not documented here, please contact Cafésoft support for help.
mod_ssl is generally compiled into an Apache server configuration and is automatically loaded when the server is started. In some configurations, you may need to use a special startup command like: "apachectl -startssl" to ensure that mod_ssl is started. This module is usually configured in a file named "ssl.conf" (which is included within "httpd.conf") in the Apache "conf" directory.
Example 8 shows the important X.509 certificate configuration settings used to force X.509 client certfificate authentication when the Cams AESO URI is requested. NOTE: Your configuration options will probably vary based on site requirements.
... # Server Certificate: |
Example 8 - Sample Cams AESO HTTP mod_ssl settings in the Apache ssl.conf file
Beside the basic property settings needed to enable AESO login and set the default login configuration settings (described in Step 3 above), the callback value settings shown in Example 9 are also necessary. The "email_addr" callback value will be used to search for the user-specific LDAP entry where the X.509 certficiate is stored. Callback value "x509_client_cert" will be used to confirm the user identity by comparing it with the certificate stored in the LDAP directory. The "agent_secret" is used by the login module as protection against replay attacks orginating outside your environment.
|
# |
Example 9 - Sample AESO callback value settings for use with mod_ssl and the AESOX509CertLdapLoginModule
Details for configuring this Cams login module are provided in section AESO X.509 Certificate Ldap Login Module. After configuring the login module come back to the next section for configuration/testing hints.
Cams AESO supports Java 2 Enterprise Edition (J2EE) web servers including Tomcat, JBoss, WebLogic, WebSphere and others using the Cams Servlet Filter web agent.
NOTE: Cams AESO may be used with Tomcat 5.0, Tomcat 5.5 and Tomcat 6.0 web servers, but only when using the Cams Servlet Filter web agent. The Cams Tomcat-specific web agents do not support AESO because they use a custom Cams Realm, which does not support native authentication methods.
J2EE web servers generally support the follow authentication options:
NOTE: Though Cams AESO can support J2EE FORM-based login, Cams FORM-based login is recommended because it provides simpler configuration and more flexibility.
The Cams Servlet Filter web agent includes a web.xml J2EE deployment descriptor file pre-configured with a <security-constraint> element that enforces HTTP Basic authentication for a user with role everyone on the Cams AESO URL (e.g. /cams/aeso). Example 10 shows the portion of this file that defines the security constraint and J2EE login-config. Please consult your J2EE server documentation on how to configure server-specific authentication services to support the selected authentication type and user directory.
...
<!--
NOTE: The following security-constraint, login-config, and security-role
elements are provided as examples when Cams AESO is used. The
security-constraint applies only to requests ending with "/aeso"
within the current webapp context (e.g. /cams/aeso).
The example login-config setting shows how HTTP BASIC authentication
is configured. You may also use any other native authentication methods
including: DIGEST, FORM, and CLIENT-CERT (X.509 client certificate).
Consult your J2EE web server documentation for details on native
authentication methods and the Cams AESO documentation for more details.
-->
<security-constraint>
<display-name>Cams AESO URI Security Constraint</display-name>
<!--
If this webapp is deployed in the "cams" context, then the "aeso" url-pattern
will match the default Cams AESO URI: "/cams/aeso"
-->
<web-resource-collection>
<web-resource-name>Cams AESO URI</web-resource-name>
<url-pattern>/aeso</url-pattern>
</web-resource-collection>
<!--
Anyone with one of the listed roles may access this area.
NOTE: You will most likely need to change the role name "everyone" to a role
that is assigned to authenticated users at your site.
-->
<auth-constraint>
<role-name>everyone</role-name>
</auth-constraint>
</security-constraint>
<!--
The folloowing example uses HTTP "BASIC" authentication. Standard J2EE authentication
methods include: "FORM", "BASIC", "DIGEST", and "CLIENT-CERT".
-->
<login-config>
<auth-method>BASIC</auth-method>
<!--
<auth-method>DIGEST</auth-method>
<auth-method>CLIENT-CERT</auth-method>
-->
<realm-name>Example Realm</realm-name>
</login-config>
<!--
Use the following login-config for FORM-based authentication.
NOTE: uncomment this element and comment out other login-config elements.
<login-config>
|
Example 10 - Example security constraint and login configuration for /cams/aeso URL
The information and links below apply to IIS 5.0 and IIS 6.0 web servers.
Integrated Windows Authentication (IWA) is a convenient authentication option in Windows Domain local area network environments. This authentication type, when suitably configured, supports use of Windows desktop login credentials for transparent login to IIS.
To configure IIS with Integrated Windows Authentication for use with Cams AESO:
1. Open Windows Explorer by right clicking on your desktop Recycle Bin and selecting the Explore menu item.
2. Drill down to the Cams IIS web agent installation directory (default: c:\cams-webagent-iis\cams).
3. Select (left click) the cams directory, then select menu item: File/New->/Folder and create a folder named aeso.
4. Start the IIS Management Console (Start -> All Programs -> Cams IIS Web Agent -> IIS Management Console)
5. Drill down to and select (left click) the cams virtual directory. The aeso folder you created in step 3 should display as a child of the cams virtual directory.
6. In the IIS Management Console, right click on the aeso folder and select the Properties menu item.
7. In the aeso Properties dialog box, select the Directory Security tab.
8. In the Anonymous access and authentication control section, select the Edit... button.
9. In the Authentication Methods dialog box, uncheck (deselect) the Anonymous Access check box and check (select) the Integrated Windows Authentication check box. Select OK to save the changes.
10. In the aeso Properties dialog box, select OK to save the changes.
When Cams AESO is enabled in the IIS web agent, these configuration settings will ensure that Integrated Windows Authentication is invoked when /cams/aeso is accessed. After successful native authentication, the Cams IIS web agent will get the user identity from internal data structures and interact with a Cams policy server to create a Cams security session.
Integrated Windows Authentication requires a web browser supporting Negotiate (GSSAPI Kerberos) authentication, which is available in the following browsers.
IIS supports client certificate (X.509 certificate) authentication with a number of different configuration options. Client certificates can be used to add a higher level of identity assurance to less secure authentication methods like HTTP Basic, HTTP Digest and Integrated Windows Authentication. Client certificates can also be used with Account Mapping in which a single client certificate can be mapped to a single user identity (1 to 1 mapping) or multiple client certificates can be mapped to a single user identity (many to 1 mapping). A certificate can be mapped to a locally defined Windows account or to an account managed within a Windows domain (using Active Directory).
Cams AESO supports IIS client certificate authentication with the following configurations:
Using this configuration, IIS is responsible for authenticating the user with HTTP Basic, HTTP Digest, or Integrated Windows Authentication. IIS is also responsible for requiring a client certificate and ensuring the submitted certificate is signed by a trusted certificate authority (usually an enterprise certificate authority). By requiring entry of a user name and password (something a valid user knows) and a client certificate (something a valid user has), authentication is strengthened to two factors. Authentication can be further strengthened by using IIS Windows account mapping. Consult your IIS documentation for more details.
Cams AESO may be used for this configuration as it would be used for standalone
HTTP Basic, HTTP Digest, or Integrated Windows Authentication.
NOTE: Information in the client certificate is not required by Cams AESO
because the authenticated user name is already available to the Cams IIS web
agent via other means. To configure IIS for use with Cams AESO:
1. Follow the directions for configuring Cams AESO with HTTP Basic, HTTP Digest, or Integrated Windows Authentication (see one of the preceding sections).
2. In the aeso Properties dialog box, Directory Security tab, Secure Communications section, select the Edit ... button.
3. In the Secure Communications dialog box, select the Require secure channel (SSL) check box, the Require 128-bit encryption check box, and the Require client certificate radio button as shown in Figure 2.
Figure 2- Secure Communications settings for Cams AESO with Client Certificates
4. If desired, check the Enable client certificate mapping check box and select the Edit... button. Configure Windows user account mapping as described by your IIS documentation.
5. Click the OK button to apply the Secure Communications settings.
6. Click the OK button to apply the aeso Properties settings.
When Cams AESO is enabled in the IIS web agent, these configuration settings will ensure that Integrated Windows Authentication is invoked when /cams/aeso is accessed. Don't forget that you'll need to access the /cams/aeso URL with SSL so that a client certificate will be sent.
Before you can test AESO in this configuration, you'll also need to configure a Cams login module so that user existence can be confirmed and roles are assigned based on group memberships. In most enterprise scenarios, users are managed within Active Directory so you'll want to use the Cams AESO Active Directory login module. If group memberships are managed outside of Active Directory, you may use the AESO LDAP login module, AESO JDBC login module, AESO XML login module or customize the source code for one of these login modules to suit your needs.
To test, you can use the following URL after substituting your host name and Cams security domain name:
https://www.domain.com/cams/aeso?cams_security_domain=system&cams_login_config=aeso&cams_original_url=https://www.mysite.com/cams/camstest.aspx
If IIS and Cams are properly configured, you should be prompted by your web browser to select a client certificate that will be used to authenticate you. On successful native web server authentication and Cams login module authentication, you should be redirected to the /cams/camstest.aspx where you should see the Cams session cookie contents, the authenticated user name, assigned roles, etc. If there's an error, check your cams-webagent.log file and Cams Policy server system-trace.log file for details on what went wrong. Enable Cams debug flags, replicate the test scenario, and update your site configuration until Cams AESO works as desired.
Using this configuration, IIS is responsible for authenticating the user by mapping it to a user account managed within a Windows domain Active Directory. This configuration option may only be used on IIS systems that are members of a Windows domain. Furthermore, this configuration requires IIS security settings that apply to all hosted web sites (all virtual hosts), which can then be overridden on a host by host basis. Consult your IIS documentation for details on use of Windows directory service mapping before proceeding.
To configure Cams AESO when IIS authenticates the user using only a client certificate:
1. Open the IIS Manager and expand the tree until you see the Web Sites folder.
NOTE: this is the tree node above the Default Web Site and all other web sites (virtual hosts) managed under IIS. Right click on the Web Sites folder and select the Properties... menu item. A dialog box like the one shown in Figure 3 should be displayed. Select the Directory Security tab if necessary. Under the Secure communications section, check the Enable the Windows directory service mapper option. This is the key configuration option that enables IIS to map a client certificate to a user account managed under IIS.
Figure 3 - The Web Sites Properties, Directory Security Tab
2. In the Authentication and access control section, select the Edit... button. A dialog box like the one shown in Figure 4 should be displayed. In nearly all cases, you'll have public resources on your web sites that should be accessible without requiring user authentication so you should select the Enable anonymous access check box as shown.
NOTE: The anonymous user name will be specific to your IIS web server host. Uncheck all other authentication methods, then select the OK button. In the Web Sites Properties dialog box, select the OK button. Since the directory security settings apply to all web sites, you will likely be notified by a dialog box and prompted to choose the lower level directories whose policy should be overridden. You may leave the lower level directories configured as they are or override them with the higher level policy. If necessary, select the /cams/aeso directory if it appears in any of the web sites and apply the higher-level policy so that the Windows directory service mapper will be available.
Figure 4 - Enabling anonymous access to all web sites
3. Expand the Default Web Site, the cams virtual directory, and right click on the aeso folder. If the folder does not exist, start a Windows Explorer window (Right click on the Recycle bin and select the Explore menu item) and navigate to the cams directory corresponding to the virtual directory.
NOTE: This is the directory where your Cams web agent dll files are installed (by default at c:\cams-webagent-iis\cams). Create a new folder named aeso under cams, then refresh your IIS Manager console to make the aeso folder appear. You should now be able to right click on the aeso folder and select the Properties menu item.
Figure 5 - Selecting the Properties menu item on the aeso folder
4. Select the Directory Security tab in the aeso Properties dialog box.
Figure 6 - The Directory Security tab in the aeso Properties dialog box
5. Uncheck (deselect) all authentication methods (including anonymous access) for the aeso folder as shown in Figure 7.
NOTE: After client certificate settings are completed, these authentication settings will ensure that authentication succeeds only on successful client certificate account mapping. Select the OK button to apply changes.
Figure 7 - Clearing all authentication methods in the Authentication Methods dialog box
6. In the Secure Communications, Directory Service tab of the aeso Properties dialog box, select the Edit... button. A dialog box like the one shown in Figure 8 will be displayed. Check the Require secure channel (SSL) option, check the Require 128-bit encryption option, select the Require client certificates radio box and check the Enable client certificate mapping option.
Figure 8 - Secure Communication settings for Cams AESO with client certificate mapping
7. In the Secure Communications dialog box, select the Edit... button in the section that describes mapping of client certificates to Windows user accounts. The Account Mappings dialog box shown in Figure 8 will be displayed. If no mappings were previously defined, then none should exist. If mappings do exist, then delete all 1-to-1 mappings until the 1-to-1 tab looks like Figure 9.
Figure 9 - Clear all 1-to-1 mappings in the Account Mappings dialog box
8. If Many-to-1 mappings exist, then delete them until the Many-to-1 tab looks like Figure 10.
NOTE: Without explicit 1-to-1 or Many-to-1 mappings defined at the individual IIS server level (which are configured through these dialog boxes), IIS will attempt to map a client certificate to an Active Directory user. Select the OK button to apply changes.
Figure 10 - Clear all Many-to-1 mappings in the Account Mappings dialog box
8. Select OK in the Secure Communications dialog box to accept changes.
9. Select OK in the aeso Properties/Directory Security dialog box to accept changes.
This completes the configuration changes for IIS. You must now configure Name Mappings under Active Directory as follows:
10. Start the Active Directory Administrators Console and drill down to the user for whom you'd like to create a name mapping. Before creating the name mapping, you'll need access to the user's client certificate as a file. Right click on the user and select Properties as shown in Figure 11.
Figure 11 - Select Properties for user John Doe in the Active Directory console
11. When the user properties dialog box appears, select the Published Certificates tab as shown in Figure 12. If the user does not have a published certificate, you'll need to get one from your enterprise certificate authority.
NOTE: This is generally a service running on your Active Directory server host. If you are an Administrator for that system, open the Microsoft Management Console (Start/run.../mmc), and use the Certificate Authority, Certificates and Certificate Templates snap-ins. Following Microsoft instructions for managing user certificates.
Select the published user certificate, then select the Copy to File button. When prompted, save the certificate as a DER Encoded Binary X509 (*.cer) file and remember the location and the file name. Select OK to dismiss the user Properties dialog box.
Figure 12 - Saving a published certificate for user John Doe as a file
12. To create the name mapping from the user certificate to the user account, right click on the user and select the Name Mappings... menu item as shown in Figure 13.
Figure 13 - Selecting the Name Mappings menu item for user John Doe in Active Directory
13. In the Security Identity Mapping dialog box, select the X.509 Certificates tab. The dialog box contents should appear as shown in Figure 14.
Figure 14 - The Security Identity Mapping dialog box enabling X.509 certificate to user mapping
14. Select the Add... button, browse the file system and select the client certificate file you saved in Step 11. A dialog box like the one shown in Figure 15 will be displayed. Make sure the Use Subject for alternate security identity box is checked, then select the OK button to add the certificate.
Figure 15 - Name Mappings dialog box when adding a certificate for a user
15. After successful name mapping, the Security Identity Mapping dialog box should show the Mapped user account and the X.509 certificate information as shown in Figure 16. Select the OK button to accept the mapping.
Figure 16 - A successfully mapped X.509 certificate to a user account
Before you can test AESO in this configuration, you'll also need to configure a Cams login module so that user existence can be confirmed and roles assigned based on group memberships. Since users are managed within Active Directory and IIS is handling authentication a mapping to a user account, you'll want to use the Cams AESO Active Directory login module. If group memberships are managed outside of Active Directory, you may use the AESO LDAP login module, AESO JDBC login module, AESO XML login module or customize the source code for one of these login modules to suit your needs.
To test, the user must have the client certificate installed in his web browser. The user can then use the following URL (after substituting your host name and Cams security domain name) to test AESO:
https://www.domain.com/cams/aeso?cams_security_domain=system&cams_login_config=aeso&cams_original_url=https://www.mysite.com/cams/camstest.aspx
On successful login, you should be redirected to the Cams test page and should see the Cams session cookie name, assigned roles, etc.
This section contains information on configuring Cams AESO login modules, which work very much like normal Cams login modules, but are customized for AESO. If necessary, please read Cams Login Configuration for general information on Cams login module configuration before continuing with AESO login configuration.
If you are already familiar with the way normal Cams login modules work, the information in Table 2 will be useful as it summarizes the functional differences between similar AESO and non-AESO login modules.
| LoginModules | Functional Differences |
|---|---|
|
AESO XML login module vs XML login module |
The AESO version of this login modules does not perform a password comparison because a password is not likely to be present in AESO environments. If the asserted AESO user name is not present in the cams-users.xml file, then a LoginException (an error condition) is thrown instead of a FailedLoginException (invalid credentials). In other words, the asserted user must exist in cams-users.xml when using AESO or an error will be reported. The AESO version of this login module requires an agent_secret callback value sent from the web agent to protect against user impersonation attacks. |
|
AESO JDBC login module vs JDBC login module |
The AESO version of this login module does not perform a password comparison because a password is not likely to be present in AESO environments. If the asserted AESO user name is not present in the JDBC data source, then a LoginException (an error condition) is thrown instead of a FailedLoginException (invalid credentials). In other words, the asserted user must exist in the JDBC data source when using AESO or an error will be reported. The AESO version of this login module requires an agent_secret callback value sent from the agent to protect against user impersonation attacks. |
|
AESO LDAP login module vs LDAP login module |
The AESO version of this login module does not perform a password comparison because a password is not likely to be present in AESO environments. Also, because a user password is not present, the success or failure of an LDAP bind operation using the user DN and password cannot be used to determine existence of the asserted user. Instead, the AESO version of the login module requires use of a privileged LDAP account (specified with bindUsername and bindPassword configuration settings) to bind followed by an LDAP search for the asserted user name. The AESO version of this login module requires an agent_secret callback value sent from the agent to protect against user impersonation attacks. |
|
AESO Active Directory login module vs Active Directory login module |
The AESO version of this login module does not perform a password comparison because a password is not likely to be present in AESO environments. Also, because a user password is not present, the success or failure of an LDAP bind operation using the user DN and password cannot be used to determine existence of the asserted user. Instead, the AESO version of the login module requires use of a privileged LDAP account (specified using bindUsername and bindPassword configuration settings) to bind followed by an LDAP search for the asserted user name. Also, because a user password is not present, the LoginModule does not support the "Windows Impersonation" option by adding private credentials to the authenticated Subject private credential store. The AESO version of this login module requires an agent_secret callback value sent from the agent to protect against user impersonation attacks. |
Table 2 - Comparison of standard AESO versus non-AESO Cams login modules
The source code for all Cams login modules is available with the downloadable version of Cams documentation, so you can compare the login modules yourself and customize them to suit your needs.
The AESO login modules included with Cams are:
You use this login module with Cams AESO to confirm user identity and lookup group memberships stored in Microsoft Active Directory. Active Directory, like most directory servers, can be configured to support virtually any schema. The Cams AESO Active Directory login module provides support for the default Active Directory schema as shown in Example 7.
| Tree Structure | Active Directory Objects |
|---|---|
|
cn=Users,dc=domain,dc=com
|
Users:
Groups:
|
The AESO Active Directory login module expects to find user values stored in specific attributes to successfully perform:
Example 8 shows the sample configuration for the AESO Active Directory login module.
<login-module-entry
className="com.cafesoft.cams.auth.login.module.AESOActiveDirectoryLoginModule"
flag="REQUIRED">
<options>
<option name="debug" value="false"/>
<option name="host" value="host.domain.com"/>
<option name="port" value="389"/>
<option name="useSSL" value="false"/>
<option name="connectTimeout" value="3000"/>
<option name="domain" value=""/>
<option name="bindUsername" value=""/>
<option name="bindPassword" value=""/>
<option name="agentSecret" value="foobar"/>
<option name="baseDN" value="cn=Users,dc=domain,dc=com"/>
<option name="scope" value="ONE"/>
<option name="filter" value="(&(objectclass=user)(userPrincipalName={username}))"/>
<option name="defaultRoles" value=""/>
<option name="useRoleSearch" value="true"/>
<option name="useDomainInRoleSearch" value="true"/>
<option name="roleAttr" value="memberOf"/>
<option name="serviceId" value=""/>
</options>
|
The Active Directory login module options values are:
You use the AESO JDBC login module to confirm user identity and lookup group memberships stored in relational databases such as Oracle, DB2, Microsoft SQL, MySQL, Sybase or any other database with a JDBC driver. The AESO JDBC login module is flexible to support a wide range of database schemas without modification. Example 9 shows a JDBC login module configuration using the Sample User Database schema and values with the open source HSQLDB relational database.
NOTE: Though valid and recommended for initial testing, configuring the AESO JDBC login module to handle database connections as show in Example 9 requires opening and closing a database connection for each authentication request. Because this is an expensive use of resources, we recommend that you configure JDBC database connection pooling for production environments.
<Login-module-entry
className="com.cafesoft.cams.auth.login.module.AESOJdbcLoginModule"
flag="REQUIRED">
<options>
<option name="debug" value="false"/>
<option name="jdbcDriver" value="org.hsqldb.jdbcDriver"/>
<option name="jdbcUrl" value="jdbc:hsqldb:hsql://localhost/"/>
<option name="jdbcUsername" value="sa"/>
<option name="jdbcPassword" value=""/>
<option name="agentSecret" value="foobar"/>
<option name="userPreparedStatement"
value="select USER_NAME from USERS where USER_NAME = ?"/>
<option name="usernameColumn" value="USER_NAME"/>
<option name="rolePreparedStatement"
value="select ROLES.ROLE_NAME from USERS, ROLES, USER_ROLES
where USERS.USER_NAME = ?
and USERS.USER_ID = USER_ROLES.USER_ID_FK
and USER_ROLES.ROLE_ID_FK = ROLES.ROLE_ID"/>
<option name="roleColumn" value="ROLE_NAME"/>
</options>
</login-module-entry>
|
Example 9 - AESO JDBC login module configuration for the sample user database
The JDBC login module option values are (required unless otherwise specified):
NOTE: You must obtain and install the JDBC driver supplied by your database vendor. To use any JDBC driver with Cams, copy the driver's jar file(s) into the CAMS_HOME/lib directory. For example, if you want to use MySQL with the standard J2SDK installation, you would copy mysql-connector-java-3.0.15-ga-bin.jar to CAMS_HOME/lib. See your database vendor documentation for more information.
JDBC connection pooling is the recommended way to configure authentication with a relational database in production environments. To use JDBC connection pooling from the JDBC login module, you must:
<login-module-entry
className="com.cafesoft.cams.auth.login.module.AESOJdbcLoginModule"
flag="REQUIRED">
<options>
<option name="debug" value="false"/>
<option name="jdbcDriver" value="org.apache.commons.dbcp.PoolingDriver"/>
<option name="jdbcUrl" value="jdbc:apache:commons:dbcp:example-jdbc-pool"/>
<option name="agentSecret" value="foobar"/>
<option name="userPreparedStatement"
value="select USER_NAME from USERS where USER_NAME = ?"/>
<option name="usernameColumn" value="USER_NAME"/>
<option name="rolePreparedStatement"
value="select ROLES.ROLE_NAME from USERS, ROLES, USER_ROLES
where USERS.USER_NAME = ?
and USERS.USER_ID = USER_ROLES.USER_ID_FK
and USER_ROLES.ROLE_ID_FK = ROLES.ROLE_ID"/>
<option name="roleColumn" value="ROLE_NAME"/>
</options>
</login-module-entry>
|
Example 10 - Using pooled JDBC connections with the AESO JDBC login module
The AESO JDBC login module option values are configured as shown in Example 10 with the following differences:
You use this login module with Cams AESO to confirm user identity and lookup group memberships stored in the Sun ONE Directory Server, Red Hat Directory Server, OpenLDAP and any other LDAPv3 compliant user directory. LDAP directory schema will vary from site to site. This login module is flexible to support many variations of X.500 and DNS style schemas similar to those shown in Example 11.
| Tree Structure | LDAP Objects |
|---|---|
|
dc=domain,dc=com
|
Users:
Groups:
|
The AESO LDAP login module expects a schema similar to the one specified in Example 11 to successfully perform:
Your LDAP server may use a schema different from the one specified above. Also, your LDAP server's access control settings may effect integration with Cams. For example, for the AESO LDAP login module to return role information successfully, the LDAP server access control policy must allow the account corresponding to bindUsername, bindPassword to search the group tree to obtain role membership data.
Example 12 shows the sample entry for the AESO LDAP login module.
<Login-module-entry className="com.cafesoft.cams.auth.login.module.AESOLdapLoginModule" flag="REQUIRED"> <options> <option name="debug" value="false"/> <option name="host" value="host.domain.com"/> |
Example 12 - Cams LDAP login module login-config.xml sample
The AESO LDAP login module options values are:
The AESO X509 Certificate LDAP login module is quite flexible regarding LDAP schemas, though the following instructions show configuration settings appropriate for the schema described with the AESOLdapLoginModule. The AESOX509CertLdapLogin module works as follows:
Your LDAP server may use a schema different from the one specified above. Also, your LDAP server's access control settings may effect integration with Cams. For example, for the AESO LDAP login module to return role information successfully, the LDAP server access control policy must allow the account corresponding to bindUsername, bindPassword to search the group tree to obtain role membership data.
Example 13 shows the sample entry for the AESO X.509 Certificate LDAP login module.
<login-module-entry |
Example 13 - Cams AESO X.509 Certificate login module login-config.xml sample
The AESO X.509 Certificate LDAP login module options values are:
Example 14 shows the sample entry for the AESO XML login module. You use the AESO XML login module to access authentication credentials stored in a cams-users.xml directory, found by default in each security domain. This user directory is supplied with Cams for convenience and system-level use (e.g. Cams web agent authentication) and is not recommend for production sites with a large number of users.
The AESO XML login module does not process the contents of the cams-users.xml file directly. Instead, it makes use of a Cams service, which loads the XML file and reloads it when modifications are made. This Cams service (defined in security-domain.xml) caches user name, password, and role information in memory, greatly improving the efficiency of authentication making it ideal for small user communities that don't change and for authenticating Cams web agents. The path to Cams user directory and the XML handler that knows how to parse the file are specified in the service manager configuration.
<!-- In login-config.xml, register a cams-users.xml directory service --> <login-config-entry> ... <login-module-entry className="com.cafesoft.cams.auth.login.module.AESOXmlLoginModule" flag="REQUIRED"> <options> <option name="debug" value="false"/> <option name="serviceId" value="cams-user-repository"/> <option name="agentSecret" value="foobar"/> </options> </login-module-entry> ... <login-config-entry> |
Example 14 - Sample Cams AESO XML login module as defined in login-config.xml and by the associated security-domain.xml service
The AESO XML login module options values are:
The AESO XML login module authenticates users by looking up the user name. If the user name exists, login succeeds and and roles associated with the user in cams-users.xml are assigned.
See Security Domain Configuration - Cams XML User Repository Service for information on how to configure services.
Cams uses callback handlers to pass login credentials from the calling application to the login module. Cams AESO login modules use the standard Cams MapCallbackHandler, which flexibly takes all name/value pairs and makes them available to login modules by name.
To specify a callback handler for use with a Cams login module, each <login-config-entry> includes the following required tag:
<callback-handler
classname="com.cafesoft.cams.auth.callback.MapCallbackHandler"/>
At present, you must use the MapCallbackHandler with all AESO login modules.
Login parameters help define the login configuration. The Cams policy server
sends the required camsLoginUrl to a Cams web agent when an access check
requires user authentication. The Cams web agent then redirects the user's browser
to the URL indicated by camsLoginUrl. When Cams AESO is used, the URL
must reference the URL where the web agent handles AESO login requests. Here's
how the overall process works:
The value of camsLoginUrl can be an absolute or relative URL. The default relative URL (/cams/aeso) is converted to an absolute URL based on the HTTP request that triggers the login sequence.
Generally, we recommend that you configure a web server (or pair of redundant web servers when using a Cams policy server cluster) as authentication proxies to handle AESO login requests. This approach eases integration in heterogeneous environments or when many web servers are deployed. These authentication proxies can also be configured with digital certificates to enable secure transmission of the user credentials from browsers to the web server using https. Example 15 shows use of a fully-qualified, secure camsLoginUrl value. Any web server with a Cams web agent can be used as an authentication proxy.
<login-parameters> <login-parameter name="camsLoginUrl" value="https://www.domain.com/cams/aeso"/> </login-parameters> |
Example 15 - Cams AESO login parameters
NOTE: A Cams login page is not used with AESO since the native web server authentication is expected to prompt the user for credentials or transparently authenticate the user if possible.
© Copyright 1996-2009 Cafésoft LLC. All rights reserved.