Cams Web Agent Guide

Login Scripts

When Cams needs to prompt for users to supply login credentials, it displays a login page. This page is generally a script written in Java Server Pages (JSP), Active Server Pages (ASP) or Perl that includes dynamic required and optional values. Scripts are included with Cams web agents for the Cams Test Page and Login Page. These pages are found in the Cams web agent downloads as follows:

JSP - Java web servers
ASP - IIS web servers
Perl - Apache web servers

All scripts are examples, which you may customize for your site. This document provides instructions on how to do so. Please reference the example scripts in the Cams web agent downloads. Information on how to create a logout link to allow users to exit their current session is also provided.

NOTE: In order to ensure that the browser does not cache dynamic pages, you should use the following HTML Meta tags in the HEAD section of each page:

<meta http-equiv="Pragma"        content="no-cache">
<meta http-equiv="Cache-Control" content="no-cache">   		
<meta http-equiv="Expires"       content="-1">

Generally, this is a recommended security best practice for all dynamic and static pages protected by any web security system as it should (but does not always) prevent the browser from caching the pages.

Cams Test Page

The Cams web agent test page assists with web agent integration testing. The page is self-documented and provides an example of how to do pro-active authentication with Cams (meaning that you proactively authenticate before accessing protected resources).

For proactive authentication, the following values are usually statically populated in hidden fields within an HTML form. However, in the case of the Cams web agent test page, the user is allowed to see and change the values for testing convenience.

cams_security_domain - the security domain to use for authentication
cams_login_config - the name of security domain's <login-config-entry> to use
cams_original_url - The URL to redirect to after successful authorization

In addition, the form provides user name and password input fields:

cams_cb_username - the user name
cams_cb_password - the user password

The page must be posted to the URI specified by the cams.login.uri property in cams-webagent.conf. The Cams web agent intercepts the POST to the cams.login.uri and sends an authentication request to a Cams policy server. The request includes the security domain and a <login-config-entry> within the security domain to use to attempt authentication. Within the Cams policy server, these values are sent to the callback handler and login module(s) defined within a specified <login-config-entry>. If you successfully authenticate, the browser is redirected to the cams_orginal_url and a reevaluation of the original access request check is performed, for which you are granted or denied access.

Login Page

When you requested a protected resource and your identity is unknown, Cams prompt for authentication by requesting the Cams web agent to display a login page. The login page is specified by the camsLoginUrl parameter in a security domain's login-config.xml file. For example, the default system security domain's login page as configured in login-config.xml is:

<!-- Specify the default login page -->
<login-parameters>
  <login-parameter name="camsLoginUrl" value="/cams/login.jsp"/>
</login-parameters>

This is know as lazy authentication. With lazy authentication, following hidden values must be dynamically populated from HTTP query parameters by an HTML form in the login page.

cams_security_domain - the security domain to use for authentication
cams_login_config - the name of security domain's <login-config-entry> to use
cams_original_url - The URL to redirect to after successful authorization

In addition, the form must provide input fields for a user name and password:

cams_cb_username - the user name
cams_cb_password - the user password

NOTE: You can create a static login page to do proactive authentication by hard coding cams_security_domain, cams_login_config and cams_orginal_url hidden values. Set the Cams Test Page for an example.

The Cams login page may also display a login failed message. If authentication fails because either the user name or password are invalid, the browser is redirected to the login page with the following query parameter:

cams_login_failed_message (optional message generated within a login module)

The login page uses these values to detect an authentication failure and display any corresponding messages.

WARNING: You must correctly configure the login-parameters in the security domain's login-config.xml file or the login page will not be displayed. See the Cams Administrator's Guide - Login Configuration for more information on configuring login-parameters in login-config.xml.

Attack Prevention

Parameter validation is useful for detecting and thwarting cross site scripting, SQL injection and other attacks by invalidating parameters containing potentially dangerous character sequences. In particular, values that might ultimately be embedded into a dynamic HTML page should be validated to deny use of certain characters used to tag HTML elements. To prevent attacks, the Cams login pages include regular expressions that limit dynamic query parameters to characters that are normally used as shown in Table 1.

Parameter	Regular Expression
cams_security_domain	^[a-z0-9]{1,12}$ Allows lower case a to z, integers 0 to 9 and 1 to 12 characters in length (supports any valid Cams policy server security domain name). Alternative value: ^(system)$ for sites only using the default system security domain. Alternative value: ^(system\|mydomain)$ for sites using a small number of security domains.
cams_login_config	^[a-z0-9]{3,12}$ Allows lower case a to z, integers 0 to 9 and 3 to 12 characters in length (supports any valid Cams policy server <login-config-entry> name). Alternative value: ^(http)$ for sites only using the default http login config entry. Alternative value: ^(http\|http2)$ for sites using a small number of <login-config-entry>.
cams_original_url	(^/([a-zA-Z0-9=\\-\\.?,'\\/\\+\\&%\\$#_])?$\|^(http)(s?)://[0-9a-zA-Z]([-.\\w][0-9a-zA-Z])(:(0-9))(/?)([a-zA-Z0-9=\\-\\.?,'\\/\\+\\&%\\$#_]*)?$) Allows: An absolute path within the current web host context: absolute_path [[fragment] ? query ] A fully qualified http or https URL: scheme :// host [:port] [ absolute_path [[fragment] ? query ]] NOTE: Square brackets enclose optional entities. Where: absolute_path - starts with / followed by any case a to z, integers 0 to 9 or -./+_ fragment - starts with # followed by any case a to z, integers 0 to 0 or -.+_ query - preceded by ? and composed of name=value pairs separated by &. The value may contain hex encoded characters of the form %hh where h is a hexadecimal character in the range 0 to 9 and a to f any case. scheme - http or https followed by :// host - a non-fully qualified DNS host name (no periods), a fully qualified DNS host name (one or more periods) or an IP address. port - any number of integers in the range 0 to 9 preceded by : This regular expression is designed for efficiency and does not necessarily detect all invalid HTTP URLs, but it should detect those containing potentially malicious characters. A regular expression that completely validates an HTTP or HTTPS URL would be inefficient.
cams_login_failed_message	^[a-zA-Z0-9\\ \\.\\:\\?\\,\'\"\\/\\+%\\$#_]*\\)?$ Allows any case a to z, integers 0 to 9 and characters " .:?,'"/+%$#_"

Table 1 - Regular expressions used to validate dynamic values in a Cams login page

NOTE: All login parameters received by the Cams web agent from the login page must either have a validator regular expression defined or be declared valid-on-unknown using the cams.login.param.validator.valid-on-unknown configuration option in cams-webagent.conf. See Configuration Properties for more information.

Additional information on regular expressions can be found in the Cams Administrator's Guide - Regular Expressions. Also, a useful, free application named PCRE Workbench (Perl Compatible Regular Expression Workbench) is recommended for testing regular expressions.

Logout

Now that you know how to create a login page to login, what about logging out? There's no need to create a logout page, you simply supply a logout link from within any page.

The logout URL is specified in cams-webagent.conf. The Cams web agent knows to intercept the logout URL request and forward it to the Cams policy server with the user's session identity and the security domain name. Cams allows simultaneous login into multiple security domains, so you must inform the Cams server of the security domain from which you are requesting logout. For example, if the cams-webagent.conf logout property is:

cams.logout.uri=/cams/logout

and the security domain is system, then a properly formed relative logout URL might look like:

/cams/logout?cams_security_domain=system

After logout, your browser will be redirected to the URL configured in cams.webagent.conf by the cams.after.logout.url property. You can also override the cams.logout.uri by supply a query parameter:

/cams/logout?cams_security_domain=system&cams_after_logout_url=/customlogoutpage.html

NOTE: You can also make the logout action dynamic by using secure Cams HTTP request headers to populate the security domain parameter.

Back | Next | Contents