Back | Next | Contents Cams Web Agent Guide

Scripts

Cams web agents include example scripts that enable users to interact with the Cams policy server. These scripts provide a starting point for look and feel and other customizations you might make. This document provides instructions on how to configure the scripts, which include:

The example scripts are written in Java Server Pages (JSP), ASP.Net or Perl and provided with Cams web agent downloads depending upon the target web server:

  • JSP - Java web servers
  • ASP.NET - IIS web servers
  • Perl - Apache web servers

NOTE: To ensure that the browser does not cache dynamic pages, scripts 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 security best practice for all dynamic and static pages as it should (but may not always) prevent browsers from caching the page.

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_original_url and a reevaluation of the original access request check is performed, for which you are granted or denied access.

Cams Login Page

When Cams needs to prompt for users to supply login credentials, it displays a 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

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_original_url and a reevaluation of the original access request check is performed, for which you are granted or denied access.

NOTE: You can create a static login page to do proactive authentication by hard coding cams_security_domain, cams_login_config and cams_original_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.

Login 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

^(https?:(//([a-zA-Z0-9\\-._~%]+)(:[0-9]+)?(/[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+)*/?|(/?[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+(/[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+)*/?)?)|([a-zA-Z0-9\\-._~%!$&'()*+,;=@]+(/[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+)*/?|(/[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+)+/?))(\\?[a-zA-Z0-9\\-._~%!$&'()*+,;=:@/?]*)?(#[a-zA-Z0-9\\-._~%!$&'()*+,;=:@/?]*)?$

Enforces RFC 3986 URLs with:

  1. An absolute path within the current web host context:
    absolute_path [[fragment] ? query ]
  2. A fully qualified http or https URL:

    scheme :// host [:port] [ absolute_path [[fragment] ? query ]]

    NOTE: Square brackets enclose optional entities.
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.

Cams Standard Logout Snippet

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

Logout 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, Cams web agents use regular expressions to validate the query parameters sent with requests to the configured logout URI. The default regular expressions used to validate logout parameters are shown in Table 2.

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_after_logout_url

^(https?:(//([a-zA-Z0-9\\-._~%]+)(:[0-9]+)?(/[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+)*/?|(/?[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+(/[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+)*/?)?)|([a-zA-Z0-9\\-._~%!$&'()*+,;=@]+(/[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+)*/?|(/[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+)+/?))(\\?[a-zA-Z0-9\\-._~%!$&'()*+,;=:@/?]*)?(#[a-zA-Z0-9\\-._~%!$&'()*+,;=:@/?]*)?$

Enforces RFC 3986 URLs with:

  1. An absolute path within the current web host context:
    absolute_path [[fragment] ? query ]
  2. A fully qualified http or https URL:

    scheme :// host [:port] [ absolute_path [[fragment] ? query ]]

    NOTE: Square brackets enclose optional entities.

Table 2- Regular expressions used to validate dynamic values in a Cams logout request

NOTE: All logout parameters received by the Cams web agent from the HTTP client must either have a validator regular expression defined or be declared valid-on-unknown using the cams.logout.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.

Cams Cross DNS Domain Single Logout Page

Starting with Cams version 3.2, web agents include a single logout (SLO) script to logout users and delete session cookies for multiple cookie domains. SLO is useful when you have configured Cams Cross DNS Domain Web Single Sign-On (CDSSO), which creates Cams session cookies in more than one IdP and one or more SP cookie domains.

Cams SLO works in conjunction with a script, which you may customize as desired. These scripts use a combination of Cams, HTML, and Javascript to logout the user and delete all Cams session cookies. Scripts include:

  • slo.jsp - included with Java-based web agents
  • slo.aspx - included with IIS web agents
  • cams-slo.pl - included with Apache web agents

When a browser loads the HTML from an Cams SLO script, it finds a list of image <img> tags and attempts to load them simultaneously. There is one tag for each possible cookie domain configured in your CDSSO environment. The URL referenced by each <img> tag is a link for Cams Standard Logout (e.g. /cams/logout) with query parameters referencing the cams_security_domain and a cams_after_logout_url to an image file.

As Cams web agents receive the logout requests, the first request received closes the user's Cams policy server session and deletes the session cookie for its cookie domain. The user's browser then redirects to the image referenced by cams_after_logout_url. Subsequent requests find the referenced Cams policy server session already closed and just delete the session cookie for its cookie domain, then redirect to the SLO image.

After a delay of 5 seconds, the SLO scripts use Javascript to redirect the user from the SLO script to the target URL originally passed into the script using the cams_after_logout_url query parameter. You may adjust the timeout value in the SLO script or jump directly to the cams_after_logout_url by changing the contents of Javascript function sloSuccess(), which is invoked after the page body is loaded.

NOTE: The list of <img> requests should include all IdP and SP cookie domains configured at your site, even though a user may not  create session cookies for each on a particular visit.

To implement cross DNS domain single logout:

1. Create a logout hyperlink or button reference to the SLO script from a page on your web site. The associated URL needs to include two query parameters: cams_security_domain and cams_after_logout_url. For example:

<a href="http://www.mydomain.com/cams/slo.jsp?cams_security_domain=system&cams_after_logout_url=http://www.mydomain.com/">Logout</a>

2. Edit the SLO script and create one image <img> tag for each cookie domain configured in your environment. The image src attribute must reference the fully-qualified /cams/logout URL for a specific cookie domain along with cams_security_domain and cams_after_logout_url query parameters. For example, if your environment provides SSO between www.mydomain.com and www.example.com (different cookie domains), then the SLO script should contain the following two <img> tags:

<img src="http://www.mydomain.com/cams/logout?cams_security_domain=system&cams_after_logout_url=/cams/slo.jpg" alt="Logging out from www.mydomain.com"/>

<img src="http://www.example.com/cams/logout?cams_security_domain=system&cams_after_logout_url=/cams/slo.jpg" alt="Logging out from www.example.com"/>

Cams web agents use a default image slo.gif, which looks like this:

You can reference any image including one pixel transparent images if you don't want the image to be visible. You may also remove the image alt attribute to prevent display of alternative text as the image loads.

Back | Next | Contents