Back | Next | Contents Cams Administrator's Guide

Automatic Enterprise Sign-On (AESO) Configuration

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:

  • Windows Domain Login. Use IIS Integrated Windows Authentication with the Cams IIS web agent and Cams AESO. Transparently login to Cams as the current desktop user. Lookup and assign roles using queries to the Windows Domain Active Directory.
  • Kerberos Realm Login. Use the Apache web server, mod_auth_kerb with the Cams Apache web agent and Cams AESO. mod_auth_kerb may be configured to use the Kerberos protocol to authenticate users to an MIT Kerberos KDC, a Heimdal Kerberos KDC, or a Windows Domain. Transparently login to Cams as the current desktop user. Lookup and assign roles using filters to search an LDAP server, Active Directory, etc.
  • Smart Card Login. Smart cards, like the US military Common Access Card (CAC), generally contain one or more X.509 client certificates providing access to various network services. Client software installed on user workstations prompts users to insert a smart card into a locally attached card reader. The client software integrates with the locally installed web browser software and sends the selected X.509 certificate to the web site. Cams AESO supports smart card Login by sending the X.509 certificate or other artifacts of the user login to a Cams policy server. Users are generally verified by a filter to search Active Directory or an LDAP-based directory, which also often stores group membership information used to assign roles.
  • One Time Password (OTP) Login. Cams AESO supports OTP login using RSA SecurID, Digipass and other devices by sending the authenticated user name and/or other artifacts of the user login to a Cams policy server. Users are generally verified by a filter to search Active Directory or an LDAP-based directory, which also often stores group membership information used to assign roles.
  • Biometric Login. Login using fingerprint readers and other devices. Cams AESO supports biometric login by sending the authenticated user name and/or other artifacts of the user login to a Cams policy server. Users are generally verified by a filter to search Active Directory or an LDAP-based directory, which also often stores group membership information used to assign roles.
  • Third Party Application Login. For web application environments with other third-party web sso solutions (such as CA SiteMinder, Oracle Access Manager, IBM Tivoli Access Manager, etc.), existing web portals, or web applications that are identity silos (embedded user directory, group management, etc.), Cams AESO can be used to transparently create a Cams web SSO session based on an existing application session cookie, HTTP header value, or other authenticated user artifacts.
  • HTTP Basic or Digest Login. Use any web server with a Cams web agent and Cams AESO to transparently create a Cams session based on HTTP Basic or HTTP Digest user authentication. Lookup and assign roles using an associated Active Directory, LDAP server, or the Cams XML user repository.

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.

Cams AESO Overview

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

  1. A user authenticates to their desktop environment. The Desktop Login Controller shown in Figure 1 may be Windows Domain Controller, a Kerberos Key Distribution Center (KDC), etc.
  2. The user accesses a web site protected by Cams and if authentication is required, the user's browser is redirected to a web server where a Cams web agent is installed and the Cams AESO feature is enabled.
  3. The web server is also configured with the desired native authentication type (e.g. Negotiate, NTLM, Kerberos, Basic, Digest, X.509 certificate, etc.) for the Cams AESO URI (e.g. /cams/aeso). The user must successfully login via the native authentication type before Cams will attempt transparent AESO login. For web servers configured to use the desktop identity (e.g. Windows Domain login, Kerberos login, etc.), users will not be prompted for additional credentials.
  4. After successful native login, the AESO-enabled Cams web agent obtains the user identity tokens from the HTTP request. These might include the authenticated user name, HTTP request header values, etc. The actual user identity tokens available depend on the type of web server and the type of native user authentication configured. More details for each web server environment are provided in the detailed configuration section of this document. The user identity tokens are sent to the Cams policy server as an authentication request.
  5. One or more AESO-aware Cams login modules validate the user identity and assign roles, usually based on group memberships. For example, if the upstream web server authenticates the user with Kerberos, then the authenticated user name is present in the authentication request. The user name may be used in a Cams AESO login module that performs an LDAP filter to search for roles to assign. Unlike non-AESO Cams login, where a password, certificate or some other user-provided secret is present, the Cams AESO login generally trusts the user identity provided by the upstream web server.
  6. If AESO is properly configured, Cams authentication succeeds and a session is created. The session identifier is returned to the Cams web agent.
  7. The Cams web agent returns a Cams session cookie to the browser and redirects it the web page that originally triggered user login.
  8. The user's web browser attempts to access the protected web page, which may be hosted on a different web server. Since a Cams session cookie is available, the cookie is sent with the HTTP request. The Cams policy server will then grant or deny access based on the user identity, assigned roles, etc. and the Cams access control policy in place.

Cams AESO Benefits

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 Configuration

Cams AESO is implemented using compatible configuration settings in four distinct locations:

  1. The web server(s) where native authentication is provided. Use web server-specific configuration settings to implement native authentication. You need only configure native authentication on one or two web servers in your environment where users will be redirected if login is required.
    NOTE:
    Getting native authentication working on designated web servers is a prerequisite for Cams AESO implementation.
  2. The Cams web agent where native authentication is implemented. In addition to enabling the Cams AESO feature, you'll need to configure the security domains for which AESO is enabled and the callback values sent from the Cams web agent to the Cams policy server (per security domain). The location of data used to populate callback values is sometimes web server-specific, native authentication type-specific and environment-specific. Examples are provided later in this document and sample values are available in cams-webagent.conf files.
  3. A security domain access control policy. No special permissions are needed for Cams AESO login as compared to other forms of Cams login. You'll simply need to make sure that web resources requiring user authentication are designated with appropriate permissions and access control rules, just as you would for normal Cams form-based login.
  4. A security domain login configuration. Configure one or Cams login modules specially designed for use with AESO. Unlike normal Cams login where a password, certificate, or some other credential is generally available during user authentication, these tokens are not always available in Cams AESO login. Instead, Cams AESO login modules are designed to trust the identity established by native authentication, to verify the user exists and to assign roles according to the directory(s) where user information is stored.

The following series of steps is recommended to simplify Cams AESO configuration:

  • Step 1 - Make sure your Cams software contains AESO support. Download and upgrade your environment if necessary.
  • Step 2 - Configure native web server authentication. Typical native authentication methods include: Kerberos, Integrated Windows Authentication, HTTP Basic, HTTP Digest, X.509 client certificate and variations using smart cards. This must be completed before enabling AESO in Cams web agents and policy server components.
  • Step 3 - Configure AESO in Cams web agents where native authentication will be provided.
  • Step 4 - Configure AESO in Cams security domain configuration file: login-config.xml.

Step 1 - Prerequisites

Ensure the following Cams AESO prerequisites are met.

Step 1A - Ensure Cams Software Supports AESO

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.

Step 1B - Disable AESO in Cams 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

Step 2 - Configure Native Web Server Authentication

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.

Step 3 - Configure Cams AESO Web Agent Settings

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.

Step 3A - Enable Cams AESO in cams-webagent.conf

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

Step 3B - Set the cams.loginconfig.entry 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

Step 3C - Set the cams.aeso.security_domains 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

Step 3D - Configure the callback values that will be sent with Cams AESO authentication requests

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:

#
#--- Cams AESO callback parameters (auth tokens) for 'system' security domain
#

cams.aeso.callback.names.system=username,agent_secret
cams.aeso.callback.value.system.username={http_request:REMOTE_USER}
cams.aeso.callback.value.system.agent_secret=foobar

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_USER
http_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-Cookie
http_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_COOKIE
http_cookie:CAMS_SID_MYCAMSCLUSTER_SYSTEM

Table 1 - Standard Cams AESO Callback Value Reference Namespaces

Step 3E - Restart the web server containing the Cams web agent

You'll need to restart the web server to ensure the Cams web agent configuration setting is reloaded.

Step 4 - Configure Cams AESO Policy Server Settings

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.

Step 4A - AESO Login Configuration Settings

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.

Step 4B - AESO Access Control Policy Settings

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.

Cams AESO Configuration Reference

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:

Native Web Server Authentication Reference

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.

Apache Web Server Native Authentication Options

The information and links below apply to Apache 2.0 and Apache 2.2 web servers.

Apache: Kerberos Authentication using mod_auth_kerb

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

Configuration/Testing Hints
  • Create a temporary HTML file in your Apache document tree and use it for Kerberos authentication testing. For example, if you create a aesotest.html file at the top of the document tree, then change the Location directive to <Location /aesotest.html>.
  • Test Kerberos authentication using your web browser. For example: https://www.domain.com/aesotest.html
  • Check your Apache error_log file for mod_auth_kerb configuration errors and reconfigure as necessary.
  • On successful Kerberos login, your Apache access_log file should display the authenticated user name for /aesotest.html.
  • After you've successfully configured Kerberos, change the Location directive back to <Location /cams/aeso>
Apache: HTTP Basic or Digest Authentication

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:

  • mod_auth - user authentication using text files.
  • mod_auth_digest - user authentication using MD5 Digest Authentication.
  • mod_auth_ldap - allows an LDAP directory to be used to store the database for HTTP Basic authentication.
  • mod_auth_dbm - provides for user authentication using DBM files.

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

Configuration/Testing Hints
  • Create a temporary HTML file in your Apache document tree and use it for HTTP Basic or Digest authentication testing. For example, if you create a aesotest.html file at the top of the document tree, then change the Location directive to <Location /aesotest.html>.
  • Test authentication using your web browser. For example: https://www.domain.com/aesotest.html
  • Check your Apache error_log file for configuration errors and reconfigure as necessary.
  • On successful login, your Apache access_log file should display the authenticated user name for /aesotest.html.
  • After you've successfully configured native authentication, change the Location directive back to <Location /cams/aeso>.
Apache: X.509 Client Certificate Authentication

The instructions in this section are specific to and enviroment using the following popular system components:

  • Apache 2.0 or Apache 2.2.
  • mod_ssl, which is the most popular technology used to SSL-enable Apache web servers. This module can be configure to provide server authentication to clients and client authentication to the server. NOTE: If you use a different SSL-enablng technology or have access client X.509 certiificates via a front-end SSL firewall/load-balancer, please contact Cafésoft support for help.
  • An LDAPv3 compliant directory server like: OpenLDAP, ApacheDS, Sun DS, Active Directory, etc.
  • User X.509 client certificates stored in binary DER format in the LDAP directory server.

The high-level configuration steps required for an environment like this include:

  1. Configuring the Cams Client Cert Lookup module
  2. Configuring mod_ssl for Client Certificate Authentication
  3. Configuring the Cams Apache web agent for AESO using Client Certificates
  4. Configuring the AESO X.509 LDAP LoginModule
Configuring the Cams Client Cert Lookup Module

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.

Configuring mod_ssl for Client Certificate Authentication

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:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. Keep
# in mind that if you have both an RSA and a DSA certificate you
# can configure both in parallel (to also allow the use of DSA
# ciphers, etc.)

SSLCertificateFile conf/certs/server/certificates/www.example.com.crt # Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)

SSLCertificateKeyFile conf/certs/server/keys/www.example.com.key # Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.

SSLCACertificateFile conf/certs/CA/exampleCA.crt # # For the Cams AESO URI: # 1. require SSL # 2. require client verification # 3. set the certificate chain verification depth # 4. validate the common name in the subject DN # 5. export the mod_ssl "SSL environment variables # <Location /cams/aeso> SSLRequireSSL SSLVerifyClient require
SSLVerifyDepth 2 SSLRequire %{SSL_CLIENT_S_DN_CN} eq "Example Inc" SSLOptions +StdEnvVars +ExportCertData </Location> ...

Example 8 - Sample Cams AESO HTTP mod_ssl settings in the Apache ssl.conf file

Configuring the Cams Apache web agent for AESO using Client Certificates

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.

#
#--- Cams AESO callback parameters (auth tokens) for 'system' security domain
#

cams.aeso.callback.names.system=x509_client_cert,email_addr,agent_secret
cams.aeso.callback.value.system.x509_client_cert={http_request:x509_client_cert}
cams.aeso.callback.value.system.email_addr={http_header:SSL_CLIENT_S_DN_Email}
cams.aeso.callback.value.system.agent_secret=foobar

Example 9 - Sample AESO callback value settings for use with mod_ssl and the AESOX509CertLdapLoginModule

Configuring 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.

Configuration/Testing Hints
  • Test authentication using your web browser. For example: https://www.example.com/cams/aeso?cams_security_domain=system&cams_login_config=aeso&cams_original_url=https://www.example.com/cgi-bin/camstest.pl
  • Check your Apache error_log file for configuration errors and reconfigure as necessary.
  • On successful login, the camstest.pl page will display the Cams session cookie and Cams request headers.
  • Enable cams.debug=true in your cams-webagent.log file if necessary and enable debug=true in the login module option and collect/analyze the log files to make sure all necessary callback values are sent by the agent, recieved by the Cams Policy Server, and processed correctly by the login module.

J2EE Web Server Native Authentication Options

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:

  • Form-based authentication
  • HTTP Basic authentication
  • HTTP Digest authentication
  • X.509 Client Certificate authentication

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>
<auth-method>FORM</auth-method>
<form-login-config>
<form-login-page>/j2eelogin.jsp</form-login-page>
<form-error-page>/fail_login.html</form-error-page>
</form-login-config>
</login-config> -->
<!-- Security roles referenced by this web application. --> <security-role> <role-name>everyone</role-name> </security-role> ...

Example 10 - Example security constraint and login configuration for /cams/aeso URL

IIS Web Server Native Authentication Options

The information and links below are divided into two sections: one for IIS 5.0 and IIS 6.0 web servers and another for IIS 7.0 and 7.5 web servers.

IIS: Integrated Windows Authentication (IIS 5.0, 6.0)

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.

Internet Explorer
  1. Open Internet Explorer
  2. Select menu item: Tools/Internet Options...
  3. Select the Advanced tab, then check the Enable Integrated Windows Authentication setting in the Security section.
  4. In the Internet Options dialog box, select the Security tab.
  5. Select the Local Intranet icon.
  6. Select the Sites button.
  7. Select the Advanced button.
  8. Add the local web sites where Integrated Windows Authentication is supported.
Firefox 2 (and later)
  1. Open Firefox
  2. In the address bar type: about:config
  3. After the config page loads, in the filter box type: network.automatic
  4. Modify network.automatic-ntlm-auth.trusted-uris by double clicking the row and entering the web URL where Windows authenticated is allowed. For example: https://www.domain.com
  5. Multiple sites can be added by comma delimiting them such as https://www.domain.com, https://www.other_domain.com
IIS: Client Certificate Authentication

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:

  1. Using mixed HTTP and client certificate authentication. In this configuration you may use HTTP Basic, HTTP Digest, or Integrated Windows Authentication and Client Certificate Authentication. Client certificates may or may not be mapped to Windows user accounts by IIS. The Cams AESO Active Directory login module is usually used to confirm user existence and to lookup group memberships and assign roles.
  2. Using only a client certificate to authenticate the user. IIS must be configured to map the client certificate to a user account managed within Active Directory. The Cams AESO Active Directory login module is used to confirm user existence and to lookup group memberships and assign roles.
  3. Using anonymous access with Cams client certificate authentication. IIS is configured for Anonymous access and a Cams login module uses information within the required client certificate to confirm user existence and to lookup group memberships and assign roles. An existing Cams login module (like AESOX509LdapLoginModule) may be used or a custom login module may be required.

    NOTE: Since the web server is not authenticating the user, this configuration is not technically an Enterprise Sign-On scenario. Using Cams AESO with IIS may make sense, however, if your site manages user accounts in a third-party user directory or a relational database. Contact Cafésoft support for more details.
IIS: Using Cams AESO with mixed HTTP and client certificate authentication

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.

IIS: Using Cams AESO with only a client certificate to authenticate the user

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.

IIS: Windows Authentication (IIS 7.0, 7.5)

Windows Authentication (WA) 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 Windows Authentication for use with Cams AESO:

1. Open Windows Explorer by clicking on the folder icon in the Windows taskbar.

2. Drill down to the Cams IIS web agent installation folder (default: c:\cams-webagent-iis\cams).

3. Select (left click) the cams folder, 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 top-level cams application folder. The aeso folder you created in step 3 should display as a child within the cams application folder.

6. Select (left click) on the aeso folder.

7. In the IIS Manager Features View, double click on the Authentication icon.

8. In the Authentication configuration for the aeso folder, right click on the Anonymous Authentication entry and select the Disable menu item.

9. Right click on the Windows Authentication entry and select the Enable menu item.

When Cams AESO is enabled in the IIS web agent, these configuration settings will ensure that 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.

Windows Authentication requires a web browser supporting Negotiate (GSSAPI Kerberos) authentication, which is available in the following browsers.

Internet Explorer
  1. Open Internet Explorer
  2. Select menu item: Tools/Internet Options...
  3. Select the Advanced tab, then check the Enable Integrated Windows Authentication setting in the Security section.
  4. In the Internet Options dialog box, select the Security tab.
  5. Select the Local Intranet icon.
  6. Select the Sites button.
  7. Select the Advanced button.
  8. Add the local web sites where Integrated Windows Authentication is supported.
Firefox 2 (and later)
  1. Open Firefox
  2. In the address bar type: about:config
  3. After the config page loads, in the filter box type: network.automatic
  4. Modify network.automatic-ntlm-auth.trusted-uris by double clicking the row and entering the web URL where Windows authenticated is allowed. For example: https://www.domain.com
  5. Multiple sites can be added by comma delimiting them such as https://www.domain.com, https://www.other_domain.com

AESO Login Configuration Settings Reference

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.

AESO Login Modules

The AESO login modules included with Cams are:

AESO Active Directory Login Module

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

dn=user_1_DN

dn=user_2_DN

dn=user_n_DN

dn=group_1_DN

dn=group_2_DN

dn=group_n_DN

Users:

top

person

organizationalPerson

user

Groups:

top

group


Example 7 - Default schema and objects supported by the Active Directory login module

The AESO Active Directory login module expects to find user values stored in specific attributes to successfully perform:

  1. Authentication - The Active Directory user principal names (UPN) such as name@domain.com is required. The AESO Active Directory login module attempts to bind to Active Directory using a privileged account bindUsername and bindPassword. If successful, an LDAP search is performed to confirm existence of the asserted user. If the user exists at a specified LDAP distinguished name (DN), then login is successful. If not, then a LoginException is thrown and an error is reported.

  2. Role Assignment - Once successful login, the Cams AESO Active Directory login module then maps roles based upon the configured role attribute. Two methods of Active Directory group lookup are available:

    1. The user's Active Directory memberOf attribute can be configured for simplicity. This attribute contains references to most groups to which the user belongs (excluding the user's primary group and any nested group memberships). Many sites find this to be sufficient. The individual group names are fully qualified distinguished names and are exploded by the Active Directory login module to obtain the group common name, which is found in the left most component (e.g. the group name for distinguished name cn=group,cn=users,dc=domain,dc=com would be group).

    2. Alternately, the user's Active Directory tokenGroups attribute contains a complete list of all groups to which a user belongs. This is an Active Directory computed attribute, meaning it is not stored in Active Directory but dynamically created when queried. Use of this attribute requires configuration of a Cams Active Directory group name service. The tokenGroups attributes are returned as Active Directory security identifiers (SIDs), which must be resolved to their common names. For performance reasons, the Cams Active Directory group name service looks up all group SIDs and their associated names at Cams server startup or whenever a new group is found. The resulting cache is available for quick reference by the AESO Active Directory login module during user authentication.

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="(&amp;(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>
</login-module-entry>

Example 8 - Cams AESO Active Directory login module login-config.xml sample

The AESO Active Directory login module options values are:

  • debug - Enables/disables debugging for the login module.
  • host - The DNS host name or IP address of the Active Directory server.
  • port - The Active Directory server connection port (389 by default, 636 for SSL). Note that the Active Directory login module may also connect to the Global Catalog (port 3268 by default).
  • useSSL - (Optional) A flag that enables/disables use of SSL for connections. Use true to enable SSL, false to disable use of SSL. If not specified, false is the default.
    NOTE:
    You must also import a trusted certificate chain for Active Directory into the Cams keystore at CAMS_HOME/conf/cams-keystore.jks. For complete instructions on how to do this, please see Using SSL when accessing LDAP user directories.
  • connectTimeout - (Optional) The number of milliseconds to wait to establish a Active Directory server connection before timing out the request. This value provides a way to interrupt an attempted connection, which can take nearly 1 minute to fail in cases where the Active Directory host is unavailable due to a network outage.
    NOTE: To prevent a Cams web agent authentication request timeout from occurring, make sure the connectTimeout value is less than the connection.authentication.timeout value found in a Cams web agent's cams-webagent.conf file.
  • bindUsername - (Required) The user name for an Active Directory account with permission to search Active Directory for user and group information.
  • bindPassword - (Required) The password for the bindUsername account.
  • agentSecret - (Required) A unique value that should be generated for your site and configured in both this value and the agent_secret AESO callback value configured in Cams web agents. This value is checked to ensure that an authentication request was received by a trusted Cams web agent via AESO and not through another mechanism (like Cams form-based login). NOTE: You should use the Cams secret key generator script (CAMS_HOME/bin/camsKeyGen.bat or CAMS_HOME/bin/camsKeyGen.sh) to generate a unique value for your site.
  • baseDN - The base distinguished name for the user search. Always in the format cn=Users,dc=domain,dc=com for Active Directory's default schema, where the values domain and com correspond to the domain configured for the particular directory.
  • scope - Specifies the search scope to use. Valid values are BASE (search is done only at the base dn tree node), ONE (search is done only at the first child tree node of the base dn), and SUB (search is done at the base dn node and all child nodes). This value should be set to ONE for most Active Directory sites.
  • filter - The filter to use to search for a user's roles. The userPrincipleName will be substituted for the value "{username}".
    NOTE: Search filters often contain an ampersand character ("&"). To prevent a search filter ampersand from being interpreted by the Cams XML parser as a XML tag, you must substitute the value "&amp;" for any ampersands in the filter.
  • roleAttr - The name of the attribute that contains the group names to be mapped to Cams roles. Use memberOf for convenience (returns all user group memberships except the user's primary group and any nested groups). Use tokenGroups to return all groups of which the user is a member. Use of tokenGroups requires configuration of the Cams Active Directory group name service (see the optional serviceId configuration value).
  • domain - (Optional) The Active Directory domain to use. If this value is present and the user name does not end with @domain, then append "@" and the value of domain to the user name before attempting the userPrincipalName search. For example, if domain is example.com and the user name is jdoe, then a search for userPrincipalName jdoe@example.com will be tried.
  • defaultRoles - (Optional) - A comma-delimited list of roles that will be assigned to the user on successful login (in addition to roles that may be assigned based on a role search). Use an empty value or remove the option settings if no default roles are desired.
  • rolesInACRLibrary - (Optional) Limits roles that saved in the user session to a comma-delimited list of one or more roles defined in the access control rules library for this security domain. This option is useful when the role search returns many roles that are not used by the access control policy for the security domain.
  • useRoleSearch - (Optional) A value of true (default) indicates that a role search will be attempted [true|false]. This option is useful for sites configuring Cams for single sign-on (sometimes to a SharePoint or OWA server using Cams Windows Impersonation) and not role-based access control.
  • useDomainInRoleSearch - (Optional) A value of true (default) indicates that the optionally supplied domain used for authentication will be included in the role search filter's {username} substitution value [true|false]. This option is useful for sites that have migrated from an NT domain to Active Directory where accounts may not have a userPrincipalName attribute. In such cases, configuring this value to false and using a role search filter that searches on the sAMAccountName attribute instead of the userPrincipalName is suggested.
  • serviceId - (Optional) The unique identifier of the Cams Active Directory group name service (configured in security-domain.xml). This configuration value is required if you set the roleAttr configuration value to tokenGroups.
AESO UnboundID Active Directory Login Module

WARNING: Use of this Cams components, which uses the UnboundID LDAP SDK for Java, requires use of Java JRE 1.5 or greater for the Cams policy server.

You use this login module with Cams AESO to confirm user identity and lookup group memberships stored in Active Directory. Active Directory, like most directory servers, can be configured to support virtually any schema. The Cams AESO UnboundID Active Directory login module provides support for the default Active Directory schema as shown in Example 8. This login module improves upon the AESO Active Directory login module using the UnboundID LDAP SDK for Java for implementation, which enables additional features to be configured, such as:

Server Sets - The UnboundID LDAP SDK for Java provides a mechanism that can be used to manage connections across multiple servers for failover and load balancing called Server Sets. The following Server Set implementations are available:

  • A single server set, which contains a reference to a single server. It is primarily used for cases in which a server set may be needed, but only a single server is to be used.
  • A round robin server set, in which each subsequent connection will be established to the next server in the specified list. If a given server isn't available, then it will be skipped and the server set will move to the next server in the list.
  • A failover server set, in which all attempts to create a connection will be tried against the first server in the list, and will only try the second if the first is unavailable, and only try the third if both the first and second are unavailable, etc.

Connection Pooling - The UnboundID LDAP SDK for Java provides an enhanced connection pooling mechanism. A Cams UnboundID LDAP Connection Pool Service can be configured in security-domain.xml to enable Cams UnboundID components to share LDAP connections. This greatly improves overall system efficiency and reduces the load Cams components place on your LDAP server. For more information on configuring this service, see Cams UnboundID Connection Pool Service.

Simplified LDAPS - Similar to how browsers negotiate SSL sessions with a web server, UnboundID LDAP SDK for Java provides SSL utilities that trust the digital certificate sent by your LDAP server to create an LDAPS connection. You must still configure your LDAP server with a digital certificate to enable LDAPS connections, but do not need to import the digital certificate into the Cams keystore.

The AESO UnboundID Active Directory login module expects to find user values stored in specific attributes to successfully perform:

  1. Authentication - The Active Directory user principal names (UPN) such as name@domain.com is required. The AESO UnboundID Active Directory login module binds to Active Directory using a connection from an UnboundID LDAP Connection Pool Service. If successful, an LDAP search is performed to confirm existence of the asserted user. If the user exists at a specified LDAP distinguished name (DN), then login is successful. If not, then a LoginException is thrown and an error is reported.

  2. Role Assignment - After successful login, the Cams AESO UnboundID Active Directory login module maps roles based upon the configured role attribute. Two methods of Active Directory group lookup are available:

    1. The user's Active Directory memberOf attribute can be configured for simplicity. This attribute contains references to most groups to which the user belongs (excluding the user's primary group and any nested group memberships). Many sites find this to be sufficient. The individual group names are fully-qualified distinguished names and are exploded by the Active Directory login module to obtain the group common name, which is found in the left most component (e.g. the group name for distinguished name cn=group,cn=users,dc=domain,dc=com would be group).

    2. Alternately, the user's Active Directory tokenGroups attribute contains a complete list of all groups to which a user belongs. This is an Active Directory computed attribute, meaning it is not stored in Active Directory but dynamically created when queried. Use of this attribute requires configuration of a Cams Active Directory group name service. The tokenGroups attributes are returned as Active Directory security identifiers (SIDs), which must be resolved to their common names. For performance reasons, the Cams UnboundID Active Directory group name service looks up all group SIDs and their associated names at Cams server startup or whenever a new group is found. The resulting cache is available for quick reference by the AESO Active Directory login module during user authentication.

Example 9 shows the sample configuration for the AESO UnboundID Active Directory login module.

<login-module-entry
className="com.cafesoft.cams.auth.login.module.AESOUnboundIDActiveDirectoryLoginModule"
flag="REQUIRED">
 <options>
  <option name="debug"        value="false"/>
  <option name="agentSecret"           value="foobar"/>
<option name="ldapPoolServiceId" value="unboundid-ldap-connection-pool"/>
<option name="defaultRoles" value="role1,role2,role3..."/>
<option name="useRoleSearch" value="true"/>
<option name="baseDN" value="cn=Users,dc=subdomain,dc=domain,dc=com"/>
<option name="scope" value="SUB"/>
<option name="filter" value="(&amp;(objectclass=user)(userPrincipalName={username}))"/>
<option name="attribute" value="memberOf"/>
<option name="useDomainInRoleSearch" value="true"/>
<option name="domain" value="host.domain.com"/>
<option name="roleRegexPattern" value="role1|role2|role3..."/> </options>
</login-module-entry>

Example 8 - Cams AESO UnboundID Active Directory login module login-config.xml sample

The AESO UnboundID Active Directory login module options values are:

  • debug - Enables/disables debugging for the login module.
  • agentSecret - (required) A unique value that should be generated for your site and configured in both this value and the agent_secret AESO callback value configured in Cams web agents. This value is checked to ensure that an authentication request was received by a trusted Cams web agent via AESO and not through another mechanism (like Cams form-based login). NOTE: You should use the Cams secret key generator script (CAMS_HOME/bin/camsKeyGen.bat or CAMS_HOME/bin/camsKeyGen.sh) to generate a unique value for your site.
  • ldapPoolServiceId - (required) The name of the service ID configured in security-domain.xml for a configured UnboundID LDAP Connection Pool Service. The connection pooling service uses the services LDAP connection parameters.
  • defaultRoles - (optional) - A comma-delimited list of roles that will be assigned to the user on successful login (in addition to roles that may be assigned based on a role search). Use an empty value or remove the option settings if no default roles are desired.
  • useRoleSearch - (optional) A value of true (default) indicates that a role search will be attempted [true|false]. This option is useful for sites configuring Cams for single sign-on only and not using Cams for access controls.
  • baseDN - (conditional) The base distinguished name for the user search. Always in the format cn=Users,dc=domain,dc=com for Active Directory's default schema, where the values domain and com correspond to the domain configured for the particular directory. Required if role search is used.
  • scope - (conditional) Specifies the search scope to use. Valid values are BASE (search is done only at the base dn tree node), ONE (search is done only at the first child tree node of the base dn), and SUB (search is done at the base dn node and all child nodes). This value should be set to ONE for most Active Directory sites. Required if role search is used.
  • filter - (conditional) The filter to use to search for a user's roles. The userPrincipleName will be substituted for the value "{username}". Required if role search is used.
    NOTE: Search filters often contain an ampersand character ("&"). To prevent a search filter ampersand from being interpreted by the Cams XML parser as a XML tag, you must substitute the value "&amp;" for any ampersands in the filter.
  • attribute - (conditional) The name of the attribute that contains the group names to be mapped to Cams roles. Use memberOf for convenience, which returns all user group memberships except the user's primary group and any nested groups. Use tokenGroups to return all groups of which the user is a member. Use of tokenGroups requires configuration of the Cams Active Directory group name service (see the optional serviceId configuration value). Required if role search is used.
  • groupNameServiceId - (conditional) The unique identifier of the Cams Active Directory group name service (configured in security-domain.xml). This configuration value is required if you set the attribute configuration value to tokenGroups.
  • useDomainInRoleSearch - (optional) A value of true (default) indicates that the domain supplied as a configuration option will be included in the role search filter's {username} substitution value [true|false]. This option is useful for sites that have migrated from an NT domain to Active Directory where accounts may not have a userPrincipalName attribute. In such cases, configuring this value to false and using a role search filter that searches on the sAMAccountName attribute instead of the userPrincipalName is suggested.
  • domain - (optional) The Active Directory domain to use. If this option is supplied then append "@" and this value to the user name before attempting the userPrincipalName search. For example, if the domain value is example.com and the user entered user name is jdoe, then a search for jdoe@example.com will be tried.
  • roleRegexPattern - (optional) Limits roles saved in user sessions to those that match a regular expression pattern. This option is useful when a role search returns many user roles that are not referenced in the Cams access control policy for the security domain. For access control polices with a limited number of roles a regular expression separating role names with the pipe ("|") character is suggested.
AESO JDBC Login Module

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 10 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 10 - AESO JDBC login module configuration for the sample user database

The AESO JDBC login module option values are (required unless otherwise specified):

  • debug - Enables/disables debugging for the login module.
  • jdbcDriver - The fully qualified Java class name for your database's JDBC driver.
    NOTE: For greatest efficiency and performance, we strongly recommend that you configure JDBC connection pooling in production environments.
  • jdbcUrl - The JDBC URL used to access the database (see the JDBC driver documentation).
  • jdbcUsername - (Optional) The user name to access the database.
  • jdbcPassword - (Optional) The password to access the database.
  • agentSecret - (Required) A unique value that should be generated for your site and configured for both this value and the agent_secret AESO callback value configured in Cams web agents. This value is checked to ensure that an authentication request was received by a trusted Cams web agent via AESO and not through another mechanism (like Cams form-based login).
    NOTE:
    You should use the Cams secret key generator script (CAMS_HOME/bin/camsKeyGen.bat or CAMS_HOME/bin/camsKeyGen.sh) to generate a unique value for your site.
  • userPreparedStatement - The SQL prepared statement used to select the user's user name from the database. For example: select USER_NAME from USERS where USER_NAME = ?. The user name entered by the user at login will be substituted for the ?. Any valid query for your database should work, including use of stored procedures.
  • usernameColumn - The table column name that will be returned with the result set from the userPreparedStatement where the user name is found.
  • accountExpiredPreparedStatement - (Optional) The SQL prepared statement to determine if a user account has expired. The result set must return a value of 1 if the account has expired, or 0 if it has not. For example: select count(*) from USERS where USER_NAME = ? and ACCOUNT_DISABLED > 0. The user name entered by the user at login will be substituted for the ?. Any valid query for your database should work, including use of stored procedures. This prepared statement is executed conditionally after the user name has been validated.
  • rolePreparedStatement - The SQL prepared statement used to select the user's groups and/or roles from the database. For example: 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. The user name entered by the user at login will be substituted for the ?. Any valid query for your database should work, including use of stored procedures.
  • roleColumn - The table column name that will be returned with the result set from the rolePreparedStatement where the user's groups and/or roles are found. All values returned will be assigned as roles to the user.
  • defaultRoles - (Optional) A comma-delimited list of roles to be assigned to each successfully authenticated user.

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.

Using JDBC Connection Pooling

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:

  1. Setup a Cams JDBC connection pool service
  2. Configure the AESO JDBC login module to use the Jakarta/Commons JDBC Connection pooling driver as shown in Example 11
<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 11 - 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:

  1. jdbcDriver - use org.apache.commons.dbcp.PoolingDriver.
  2. jdbcUrl - must start with jdbc:apache:commons:dbcp: and must end with the poolName as configured in the JDBC connection pooling service in security-domain.xml.
  3. jdbcUsername and jdbcPassword - You do not need to supply these options as database authentication credentials are supplied in the JDBC connection pooling service configuration.
AESO LDAP Login Module

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 12.

Tree Structure LDAP Objects

dc=domain,dc=com

ou=people

dn=user_1_DN

dn=user_2_DN

dn=user_n_DN

ou=groups

dn=group_1_DN

dn=group_2_DN

dn=group_n_DN

Users:

top

person

organizationalPerson

inetOrgPerson

Groups:

top

groupOfUniqueName


Example 12 - Sample DNS style LDAP schema and objects supported by the LDAP login module

The AESO LDAP login module expects a schema similar to the one specified in Example 11 to successfully perform:

  1. Authentication - The AESO LDAP login module binds to the LDAP directory using a privileged user account (bindUsername, bindPassword). The account must have permissions to search user and group information. After a successful LDAP bind, an LDAP search is executed for an attribute containing the user name from a configured userBaseDN. This is accomplished by an LDAP search filter that substitutes the user name that the user enters when prompted for authentication against the {username} parameter in curly brackets in the userFilter option value (see below). For example, if your configured userBaseDN option value is:

    ou=people,dc=domain,dc=com

    and your configured userFilter option value is:

    uid={username}

    and you enter johnsmith as the user name, then Cams will search for attribute uid with value johnsmith starting the userBaseDN. If that attribute is found, login succeeds, otherwise a login error is reported. The userScope option may be used to limit the search depth. Valid values are BASE, ONE, and SUB, which correspond to levels relative to the userBaseDN (same level, one level below, all sub levels respectively).

  2. Role Assignment - After authentication succeeds the Cams AESO LDAP login module performs a role search to retrieve and assign the user roles. Sites often use group attributes for role assignments (though they really are different). You must specify the role base distinguished name, search scope, search filter and role attribute name that will be used to find the roles.

    NOTE: If your LDAP server does not provide groups or roles, then it is valid to specify a role filter that succeeds but returns nothing or to disable the role search using a useRoleSearch value of false. See Programming Cams JAAS Login Modules.

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 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"/>
<option name="port" value="389"/> <option name="useSSL" value="false"/> <option name="connectTimeout" value="3000"/> <option name="bindUsername" value="uid=camslogin,ou=people,dc=domain,dc=com"/> <option name="bindPassword" value="password"/> <option name="agentSecret" value="foobar"/> <option name="userBaseDN" value="ou=people,dc=domain,dc=com"/> <option name="userScope" value="ONE"/> <option name="userFilter" value="uid={username}"/> <option name="userAttrName" value="uid"/> <option name="defaultRoles" value=""/> <option name="useRoleSearch" value="true"/> <option name="roleBaseDN" value="ou=groups,dc=domain,dc=com"/> <option name="roleScope" value="ONE"/> <option name="roleFilter" value="(uniqueMember=uid={username},ou=people,dc=domain,dc=com)"/> <option name="roleAttrName" value="cn"/> </options> </login-module-entry>

Example 13 - Cams LDAP login module login-config.xml sample

The AESO LDAP login module options values are:

  • debug - Enables/disables debugging for the login module.
  • host - The LDAP server host name or IP address.
  • port - The LDAP server port number.
  • useSSL - (Optional) A flag that enables/disables use of SSL for connections. Use true to enable SSL, false to disable use of SSL. If not specified, false is the default.
    NOTE:
    You must also import a trusted certificate chain for your LDAP server into the Cams keystore at CAMS_HOME/conf/cams-keystore.jks. For complete instructions on how to do this, please see Using SSL when accessing LDAP user directories.
  • connectTimeout - (Optional) The number of milliseconds to wait to establish a LDAP server connection before timing out the request. This value provides a way to interrupt an attempted connection, which can take nearly 1 minute to fail in cases where the LDAP server host is unavailable due to a network outage (and may cause Cams web agents to timeout while waiting for an authentication request).
    NOTE: To prevent a Cams web agent authentication request timeout from occurring, make sure the connectTimeout value is less than the connection.authentication.timeout value found in a Cams web agent's cams-webagent.conf file.
  • bindUsername - (Required) The user name or DN for an account with permission to search the LDAP server for user and group information.
  • bindPassword - (Required) The password for the bindUsername account.
  • agentSecret - (Required) A unique value that should be generated for your site and configured both for this value and the agent_secret AESO callback value configured in Cams web agents. This value is checked to ensure that an authentication request was received by a trusted Cams web agent via AESO and not through another mechanism (like Cams form-based login).
    NOTE:
    You should use the Cams secret key generator script (CAMS_HOME/bin/camsKeyGen.bat or CAMS_HOME/bin/camsKeyGen.sh) to generate a unique value for your site.
  • userBaseDN - The base DN for the user search.
  • userScope - The LDAP search scope to use for user searches. Valid values are BASE (search is done only at the base dn tree node), ONE (search is done only at the first child tree node of the base dn), and SUB (search is done at the base dn node and all child nodes).
  • userFilter - The LDAP filter used to search for the attribute containing the user name. The user name entered by the user at login will be substituted for the value "{username}".
  • userAttrName - The name of the attribute used to store the user name.
  • userFilter - The LDAP filter used to search for the attribute containing the user name. The user name entered by the user at login will be substituted for the value "{username}".
  • defaultRoles - (Optional) A comma-delimited list of roles to be assigned to each successfully authenticated user.
  • useRoleSearch - (Optional) Used to enable true or disable false the LDAP search that assigns roles. If not specified, the default is true.
  • roleBaseDN - The base DN for the role search.
  • roleScope - Specifies the LDAP search scope to use for role searches relative to roleBaseDN. Valid values are BASE (search is done only at the base dn tree node), ONE (search is done only at the first child tree node of the base dn) and SUB (search is done at the base dn node and all child nodes).
  • roleFilter - The filter to use to search for a users roles. The user name entered by the user at login will be substituted for the value "{username}".
    NOTE:
    Search filters often contain an ampersand character ("&"). To prevent a search filter ampersand from being interpreted by the Cams XML parser as tag, you must substitute the value "&amp;" for any ampersands in the filter.
  • roleAttrName - The name of the attribute used to store the role names (usually only one name is supplied but this can be a comma-delimited list).
AESO X.509 Certificate Ldap Login Module

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:

  1. Authentication - The AESO X509 certificate LDAP login module binds to the LDAP directory using a privileged user account (bindUsername, bindPasshword). The account must have permissions to search user and group information. After a successful LDAP bind, an LDAP search is executed for a configurable set of attributes from a userBaseDN and userSearchFilter. The user-specific LDAP entry is usually found using a search filter that matches the user email address. The attributes returned from the user search are stored in the login module so they can be referenced from other configuration settings to set the authenticated user "subject name" and to construct a user-specific LDAP filter to search for user roles (see Role Assignment).

  2. Role Assignment - After authentication succeeds the Cams AESO X.509 Certificate LDAP login module performs a role search to retrieve and assign the user roles. Sites often use group attributes for role assignments (though they really are different). You must specify the role base distinguished name, search scope, search filter and role attribute name that will be used to find the roles. This configuration options may reference callback values and/or attribute values returned from the user LDAP search.

    NOTE: If your LDAP server does not provide groups or roles, then it is valid to specify a role filter that succeeds but returns nothing or to disable the role search using a useRoleSearch value of false. See Programming Cams JAAS Login Modules.

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 14 shows the sample entry for the AESO X.509 Certificate LDAP login module.

<login-module-entry
className="com.cafesoft.cams.auth.login.module.AESOX509CertLdapLoginModule"
flag="REQUIRED">
<options>
<option name="debug" value="false"/>
<option name="host" value="host.example.com"/>
<option name="port" value="389"/>
<option name="useSSL" value="false"/>
<option name="connectTimeout" value="3000"/>
<option name="bindUsername" value=""/>
<option name="bindPassword" value=""/>
<option name="agentSecret" value="foobar"/> <!-- Callback value config settings --> <option name="agentSecret" value="foobar"/> <option name="cbValueNS" value="cb"/> <option name="cbValuesRequired" value="x509_client_cert,email_addr,agent_secret"/> <option name="cbValueX509Cert" value="x509_client_cert"/> <!-- User search/assignment config settings --> <option name="userResultsNS" value="user"/>
<option name="userBaseDN" value="ou=people,dc=example,dc=com"/>
<option name="userAttrNames" value="uid,userCertificate"/>
<option name="userCertAttr" value="userCertificate"/>
<option name="userFilter" value="(mail={cb:email_addr})"/>
<option name="userScope" value="ONE"/>
<option name="userSubjectName" value="{user:uid}"/> <!-- Role search/assignment config settings --> <option name="useRoleSearch" value="true"/>
<option name="roleBaseDN" value="ou=groups,dc=example,dc=com"/>
<option name="roleAttrName" value="cn"/>
<option name="roleFilter" value="(uniqueMember=uid={user:uid},ou=people,dc=example,dc=com)"/>
<option name="roleScope" value="ONE"/> <option name="defaultRoles" value=""/>
</options>
</login-module-entry>

Example 14 - Cams AESO X.509 Certificate login module login-config.xml sample

The AESO X.509 Certificate LDAP login module options values are:

  • debug - Enables/disables debugging for the login module.
  • host - The LDAP server host name or IP address.
  • port - The LDAP server port number.
  • useSSL - (Optional) A flag that enables/disables use of SSL for connections. Use true to enable SSL, false to disable use of SSL. If not specified, false is the default.
    NOTE:
    You must also import a trusted certificate chain for your LDAP server into the Cams keystore at CAMS_HOME/conf/cams-keystore.jks. For complete instructions on how to do this, please see Using SSL when accessing LDAP user directories.
  • connectTimeout - (Optional) The number of milliseconds to wait to establish a LDAP server connection before timing out the request. This value provides a way to interrupt an attempted connection, which can take nearly 1 minute to fail in cases where the LDAP server host is unavailable due to a network outage (and may cause Cams web agents to timeout while waiting for an authentication request).
    NOTE: To prevent a Cams web agent authentication request timeout from occurring, make sure the connectTimeout value is less than the connection.authentication.timeout value found in a Cams web agent's cams-webagent.conf file.
  • bindUsername - (Required) The user name or DN for an account with permission to search the LDAP server for user and group information.
  • bindPassword - (Required) The password for the bindUsername account.
  • agentSecret - (Required) A unique value that should be generated for your site and configured both for this value and the agent_secret AESO callback value configured in Cams web agents. This value is checked to ensure that an authentication request was received by a trusted Cams web agent via AESO and not through another mechanism (like Cams form-based login).
    NOTE:
    You should use the Cams secret key generator script (CAMS_HOME/bin/camsKeyGen.bat or CAMS_HOME/bin/camsKeyGen.sh) to generate a unique value for your site.
  • cbValueNS - The namespace used to reference callback values in other configuration options. For example, if cbValueNS is "cb", then the value of a callback of name "email_addr" is referenced as: {cb:email_addr}
  • cbValuesRequired - A comma-separated list of callback values that must be present in the authentication request before login will be attempted. This list should name all callback values that are referenced by other configuration options, plus the agent_secret and the x509_client_cert callback values.
  • userResultsNS - The namespace used to reference attribute values returned from the user LDAP search in other configuration options. For example, the userResultsNS is "user" and the "uid" LDAP attribute is returned with the user LDAP search results, then the "uid" value can be referenced in another configuration option using: {user:uid}.
  • userBaseDN - The distinguished name at which to start a user search. This value should be the LDAP node closes to where user data is stored. For example: ou=people,dc=example,dc=com
  • userAttrNames - The LDAP attribute names to be returned on usersearches. If the user LDAP entry is found, the values of these attributesare made available for substitution in other configuration options, usually the "userSubjectName" and "roleFilter".
  • userCertAttr - The name of the LDAP attribute where the user's X.509 certificate is stored. The standard name is "userCertificate" and contains the DER-encoded (binary) certificate data.
  • userFilter - The LDAP filter used to search for the user LDAP entry and associated attributes. This filter will generally reference a callback value that was created at the web layer by an AESO-enabled web agent and obtained from the X.509 client certificate presented by the user. For example, a user filter value of (mail={cb:email_addr}) indicates that the user should be selected based on LDAP attribute "mail" with the value matching the callback value named "email_addr".
  • userScope - Specifies the LDAP search scope to use for user searches. Valid values are BASE (search is done only at the base DN specified by userBaseDN), ONE (search is done only at the first child tree node relative to userBaseDN), and SUB (search is done at userBaseDN and all child nodes).
  • useRoleSearch - (Optional) Used to enable true or disable false the LDAP search that assigns roles. If not specified, the default is true.
  • roleBaseDN - The base distinguished name to use for your LDAP schema role searches. For example: ou=groups,dc=example,dc=com
  • roleAttrName - The name of the attribute used to store the role names (usually only one name is supplied but this can be a comma-delimited list).
  • roleFilter - The filter to use for role searches. This value generally needs to reference one or more callback values or values returned from the user LDAP search. For example: (uniqueMember=uid={user:uid},ou=people,dc=example,dc=com) NOTE: Search filters often contain an ampersand character ("&"). To prevent a search filter ampersand from being interpreted by the Cams XML parser as tag, you must substitute the value "&amp;" for any ampersands in the filter.
  • roleScope - Specifies the LDAP search scope to use for role searches relative to roleBaseDN. Valid values are BASE (search is done only at the base dn tree node), ONE (search is done only at the first child tree node of the base dn) and SUB (search is done at the base dn node and all child nodes).
  • defaultRoles - (Optional) A comma-delimited list of roles to be assigned to each successfully authenticated user.
AESO XML Login Module

Example 15 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>

<!-- In security-domain.xml, register a cams-users.xml directory service -->
<service manager> ... <service id="cams-directory" enabled="true">
<service-type>com.cafesoft.cams.service.UserRepositoryService</service-type>
<service-class>com.cafesoft.security.engine.service.UserRepositoryServiceImpl</service-class>
<param-list>
<param name="repositoryFilePath"
value="${cams.security-domain.home}/cams-users.xml"/>
<param name="repositoryFactoryClass"
value="com.cafesoft.security.engine.auth.login.userrepository.XmlUserRepositoryFactory"/>
<param name="handlerClass"
value="com.cafesoft.security.engine.auth.login.userrepository.CamsXmlUserRepositoryHandler"/>
<param name="debug" value="false"/>
</param-list>
</service> ... </service-manager>

Example 15 - 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:

  • debug - Enables/disables debugging for the login module.
  • serviceId - The unique identifier of the Cams XML user repository service (configured in security-domain.xml) that you will use with the XML login module.
  • repositoryFilePath - The fully-qualified file path to the XML user repository (the default location is in the same security domain directory as the associated login-config.xml file).
  • repositoryFactoryClass - The fully-qualified Java class name of the class that implements the XML user repository (the default is com.cafesoft.security.engine.auth.login.userrepository.XmlUserRepositoryFactory).
  • defaultRoles - (Optional) A comma-delimited list of roles to be assigned to each successfully authenticated user.

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.

Callback Handlers

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

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:

  1. A Cams access control policy determines that a user must authenticate and returns the camsLoginUrl to the web agent.
  2. The web agent redirects the user's browser to the camsLoginUrl, which must be a URL where a Cams web agent handles Cams AESO login requests (e.g. ends with /cams/aeso).
  3. The web server is configured to require a native identity for access to the URL associated with Cams AESO login. The native identity may be established via Kerberos login, NTLM login, X.509 certificate login, HTTP Basic login, etc.
  4. On successful native login, the Cams web agent assembles the callback values needed to authenticate the user to Cams. The callback values are sent to a Cams policy server in an authentication request, which is processed by the requested security domain using one or more login modules configured in login-config.xml.
  5. On successful Cams login, a Cams session identifier is returned to the web agent. The web agent returns a Cams session cookie to the user's browser and redirects the browser to the URL the user originally requested (the one that triggered the entire login sequence).
  6. The user's browser requests the URL, this time providing a Cams session cookie to the web agent. The user is granted access to the requested resource based on his Cams identity, including whatever role constraints and other conditions are configured.
  7. The user receives the requested content if access is granted.

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 16 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 16 - 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.

Back | Next | Contents