Cams Programmer's Guide

Webapp Programming

You can use information provided by Cams to make fine-grained access control decisions in your webapps. In other words, users with distinct identities, roles, account information, logon locations, logon times, etc. may be presented with different webapp user interfaces and application functionality. The difference can range from dynamically changing a button or image based on user values to completely denying access to a resource.

Cams is integrated more tightly with some environments. For example, all webapp programming environments (JSP/servlet, ASP, PHP, PERL, etc.) will have access to Cams secure request headers. But only J2EE containers with Cams web agents will have access to the J2EE servlet security APIs.

Who Should Read this Document

This document provides a brief tutorial on the Cams security services and resources available to webapp programmers. You should have an understanding webapp programming as well as a basic knowledge of the HTTP protocol. A knowledge of Java is required if you need to use the Cams APIs to extend the Cams server.

Accessing Cams HTTP Request Headers

HTTP request headers provide a convenient, programming language neutral method for obtaining information about a user request. Each HTTP browser request contains header variables that you can use to implement fine-grained access control and make programmatic decisions.

By default, Cams adds secure HTTP request headers to each request. Cams HTTP request headers are secure because they are inserted by the Cams web agent before the request is handed to the webapp. Any HTTP request headers sent by the client that start with CAMS_HTTP_ are treated as malicious and result in an error. By default, the following Cams HTTP request headers are inserted into each request:

CAMS_HTTP_SESSION_ID - the authenticated user's session id
CAMS_HTTP_SESSION_CREATED - the date/time when the user's session was created
CAMS_HTTP_SECURITY_DOMAIN - the security domain to which the authenticated user session belongs
CAMS_HTTP_USER - the authenticated user name
CAMS_HTTP_ROLE - the role(s) assigned to the authenticated user. One instance of this header is added for each role (some environments may permit multiple instances of this request header)
CAMS_HTTP_ROLES - a comma-delimited list of roles assigned to the authenticated user

NOTE: Web server cgi-bin interfaces make HTTP request headers available as environment variables. Request header CAMS_HTTP_ROLE may have multiple instances for each role in some environments like a J2EE servlet container. For cgi-bin, however, only one instance of an environment variable is accessible, which makes use of the CAMS_HTTP_ROLES request headers more appropriate.

You can use these intrinsic Cams HTTP request headers to customize your web applications. For example, your web applications might give different privileges to users with the Admin, Manager, and Everyone roles. You can define the program logic and presentation based on these roles and then use Cams HTTP request headers at run-time to dynamically change the presentation based on the authenticated user.

Using Java

To fetch a Cams HTTP request header value with Java, use the HttpServletRequest API calls:

request.getHeader(String name) - returns the value of the specified header as a String
request.getHeaders(String name) - returns all the values of the specified header as an enumeration of String objects
request.getHeaderNames() - returns an Enumeration of all the header names
request.getIntHeader(String name) - returns the value of the specified header as an int

NOTE: Multiple HTTP headers can have the same name. For example, a Cams user may have multiple CAMS_HTTP_ROLE values. To fetch all the values for a header name with multiple values, you must use the getHeaders(name) method and iterate over the enumeration.

Example 1 shows the use of request.getHeaderNames() and request.getHeaders() in a JSP page to obtain, find, and display the names and values of all intrinsic Cams HTTP request headers.

<%@ page language="java" %>
<%@ page import="java.util.Enumeration" %>

...

<h2>Cams HTTP Request Headers</h2>
 <table border="0" cellspacing="1" cellpadding="2">
  <tr> 
   <th>Name</th>
   <th>Value</th>
  </tr>

<%
 // Get all Cams HTTP request headers names/values 
 if (request.getHeader("CAMS_HTTP_SESSION_ID") != null)
 {
  Enumeration e1 = request.getHeaderNames();
  while (e1.hasMoreElements())
  {
   boolean doLoop = true;
   String name = ((String)e1.nextElement()).toUpperCase();
   if (name.startsWith("CAMS_HTTP_"))
   {
    Enumeration e2 = request.getHeaders(name);
    while (e2.hasMoreElements())
    { 
     String value = (String)e2.nextElement();
%>

 <tr> 
  <td class=gray><%= name %></td>
  <td class=gray><%= value %></td>
 </tr>

<%
    }
   }
  }
 }
%>

Example 1 - JSP code snippet that displays the intrinsic Cams HTTP request headers

As you will see later in this document, you can use the J2EE servlet security API isUserInRole() and getUserPrincipal() methods in J2EE servers with Cams web agents to make programmatic role based decisions. If the servlet security API is not available you can also use Cams HTTP request header to accomplish the same role based decisions as shown in Example 2.

<%@ page language="java" %>
<%@ page import="java.util.ArrayList" %>
<%@ page import="java.util.Enumeration" %>

...

<%
 // Determine role and get corresponding list
 ArrayList list = null;
 Enumeration e = request.getHeaders("CAMS_HTTP_ROLE");
 while (e.hasMoreElements())
 { 
  if ("Manager".equals((String)e.nextElement()))
  {
   // Managers see a list of all employees
   list = EmployeeList.getAllEmployees();
   break;
  }
 }

 // Employees see a list with their own identity 
 if (list == null)
 {
  list = EmployeeList.getEmployee(request.getRemoteUser());
 }
%>

Example 2 - JSP code snippet that uses Cams HTTP request headers to make role based programmatic decisions

This JSP code snippet that shows the use of the Cams HTTP request headers to determine if an employee account information list should contain all employees or only the currently authenticated user. If the authenticated user has the role of Manager, then he will see a list with all employees. Otherwise, he only sees a list with his own account information.

Using ASP Scripts

Example 2 shows the use of Microsoft Jscript to obtain, find, and display the names and values of all the Cams HTTP request headers.

<%@ language = JScript %>

...

<h2>Cams HTTP Request Headers</h2>
 <table border="0" cellspacing="1" cellpadding="2">
  <tr> 
   <th>Name</th>
   <th>Value</th>
  </tr>

<%
 // Get all Cams HTTP request headers names/values 
 var e = new Enumerator(Request.ServerVariables);
 if (e != false)
 {
  while(!e.atEnd()) 
  {
   var re = new RegExp("^HTTP_CAMS_HTTP_.*");
   if (!e.item().search(re))
   {
    Response.Write("<tr><td align=\"right\" class=\"gray\">"
          + e.item() + "</td><td class=\"gray\">"  				
          + Request.ServerVariables(e.item()).item + "</td></tr>");
   }
   e.moveNext();
  }
 }
%>

Example 2 - ASP code snippet that displays the intrinsic Cams HTTP request headers

NOTE: As with cgi-bin, HTTP_ is prepended to each Cams HTTP request header in the ASP environment.

Using PERL

Example 3 shows the use of PERL to display the cgi-bin environment variables, which includes the Cams HTTP request headers.


#!/usr/bin/perl

#
# Displays the cgi environment variables in a table.
#

print "Content-type:text/html\n\n";
print "<html>\n";
print " <head>\n";
print " <title>View CGI Environment Variables</title>\n";
print " </head>\n";
print " <body bgcolor=white>\n";
print " <h2><font face=helv color=cc9900>CGI Environment Variables</font></h2>\n";
print " <table cellpadding=3 cellspacing=0 border=1>\n";

foreach $key (sort(keys %ENV))
{
  print " <tr><td align=right>$key:</td><td>&nbsp;$ENV{$key}</td></tr>\n";
}

print " </table>\n";
print " </body>\n";
print "</html>\n";

exit(0);

Example 3 - Using Perl to display CGI environment variables including the intrinsic Cams HTTP headers

NOTE: As you'll see when you execute this example, cgi-bin preprends HTTP_ to all Cams HTTP request headers.

Custom Cams HTTP Request Headers

In addition to the intrinsic Cams HTTP request headers shown in this section, you can also create custom request headers using the Cams Session API. For example, you might want to make certain user profile information securely available to all of your web applications without requiring each web application to do a query to obtain the information. With Cams, you can query this information once when the user authenticates and his session is created. Then, you can pass the information to your web applications using Cams HTTP request headers. Using this method allows you to easily make any user data you require available to web applications in almost any programming environment. Furthermore, you improve performance and security by centralizing and reducing the number of queries to what may be sensitive information.

J2EE Servlet Security APIs

Most permissions for resources secured by Cams are managed at the resource request level (URLs in the HTTP space). However, you may want finer-grained control over webapps that run in J2EE web containers such as Tomcat. You do this using J2EE programmatic security, which is enabled by Cams agents on supported containers.

When you design a J2EE webapp or component, you should always think about the kinds of users who will access it. For example, an order fulfillment webapp might be accessed by customers, shipping clerks, sales representatives, and managers. Each of these user categories is called a security role, an abstract logical grouping of users that is defined by the person who deploys or manages the application. When a webapp is deployed, the deployer will map the roles to security identities in the operational environment.

J2EE programmatic security for webapps consists of the following methods of the HttpServletRequest interface:

request.getRemoteUser() - determine the user name with which the client authenticated
request.isUserInRole(String name) - determine if a user is in a specific security role
request.getUserPrincipal() - returns a java.security.Principal object

These APIs allow servlets to make business logic decisions based on the logical role of the remote user. They also allow the servlet to determine the principal name of the current user. Example 4 is a JSP code snippet that shows the use of the isUserInRole() method to determine if an employee account information list should contain all employees or only the currently authenticated user. If the authenticated user has the role of Manager, then he will see a list with all employees. Otherwise, he only sees a list with his own account information.

// Managers see a list of all employees
if (request.isUserInRole("Manager"))
{
  list = EmployeeList.getAllEmployees();
}
// Employees see a list with their own identity
else
{
  list = EmployeeList.getEmployee(request.getUserPrincipal().getName());
}

Example 1 - Using J2EE web programmatic security

You can use these J2EE servlet security API methods to flexibly apply fine-grained access control to images, links, buttons, or any other web page component.

NOTE: If you desire to use the J2EE servlet security API methods when using Tomcat as a JSP/servlet engine for the Apache or IIS web servers, you can with Cams. You simply need to configure the Cams web agents for both the web server and Tomcat.

Back | Next | Contents