| Back | Next | Contents | Cams Web Agent Guide |
When Cams needs user input or has a message for a user, it usually requires the display of the login, denied or error page. These pages include required and optional dynamic values for display and on input forms. Sample scripts are included with Cams web agents for each of the following pages:
These pages are available, with the Cams web agent downloads, in the following scripting languages:
All scripts are provided as examples, which you may customize as required. This document provides instructions on how to do so.
In addition, you may want to provide a logout hyperlink to allow users to exit their current session, which is also discussed on this page.
NOTE: In order to ensure that the browser does not cache these pages, it is important that you 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.
The Cams web agent test page assists with web agent integration testing. It is self-documented and also provides an example of how to do pro-active authentication with Cams (meaning that you proactively authenticate before accessing a protected resource).
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.
In addition, the form must provide input fields for a username and 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 to use to attempt authentication. If you successfully authenticate, the browser is redirected to the cams_orginal_url. Of course, a reevaluation of the original access request check is then performed, for which you'll be granted or denied access.
When Cams needs to prompt for authentication because you have requested a protected resource and your identity is unknown, the web agent displays a login page as specified by the camsLoginUrl parameters in a security domain's login-config.xml file. For example:
<!-- 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 within an HTML form within the login page.
In addition, the form must provide input fields for a user name and 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 parameters starting with cams_cb as part of an authentication request to a Cams policy server. The request includes the security domain and a login-config-entry to use to attempt authentication. Within the Cams policy server, these values will be sent to the callback handler and login module(s) defined within a specific login configuration entry. If authentication is successful, the browser is redirected to the cams_orginal_url. Of course, a reevaluation of the original access request check is then performed, for which you'll be 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_orginal_url hidden values.
The Cams login page may also display a login failed message. If authentication fails because either the username or password are invalid, the browser is redirected to the login page with the following query parameters:
The login pages 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.
If you are denied access to a resource by Cams, the page specified by the cams.denied.url property in cams-webagent.conf is displayed. The following dynamic HTTP query parameters are passed to this page (which you can optionally display):
If an exceptional condition occurs, the page specified by the cams.error.url property in cams-webagent.conf is displayed. The following dynamic HTTP query parameter is passed to this page (which you can optionally display):
This section provides example code in JSP and ASP scripts. Snippets are shown from the login and error page (the denied page is not shown but uses the same mechanism as the error page, but with a total of four potential HTTP query parameters). You are encouraged to reference the sample pages included with each Cams web agent for context and more complete examples.
<!-- Populate hidden fields from their request parameters -->
<input type="hidden" name="cams_security_domain"
value="<%= request.getParameter("securityDomain") %>">
<input type="hidden" name="cams_login_config"
value="<%= request.getParameter("loginConfig") %>">
<input type="hidden" name="cams_original_url"
value="<%= request.getParameter("originalUrl") %>">
|
Example 1 - Fetches required HTTP query values
in login.jsp
<!-- Display dynamic error messages -->
<%
String message = null;
message = request.getParameter("message");
if (message != null)
{
%>
<p class="error"><%= message %></p>
<% } %> |
Example 2 - Displays any dynamic error messages in error.jsp example
<!-- Populate hidden fields from their request parameters -->
<input type="hidden" name="cams_security_domain"
value="<%= Request.QueryString("cams_security_domain") %>">
<input type="hidden" name="cams_login_config"
value="<%= Request.QueryString("cams_login_config") %>">
|
Example 3 - Fetches required HTTP query values
in login.asp
<!-- Display any dynamic error messages -->
<%
var message = null;
message = Request.QueryString("message");
if (message != null)
{
%>
<p class="error"><%= message %></p>
<%
}
%>
|
Example 4 - Displays any dynamic error messages in error.asp example
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 hyperlink from within any page.
The logout URL, like the error and denied pages 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=/override.html
NOTE: You can also make the logout action dynamic by using secure Cams HTTP request headers to populate the security domain parameter.
© Copyright 1996-2005 Cafésoft LLC. All rights reserved.