JCas - First CAS server

JCas User Guide

        Introduction
        Setup
        First CAS server
        Access Control
        JDBC Database Authorization
        JAAS User Authorization
        SSL Setup
        JSP Taglib
        JCas Client
        JLL - JAAS Login Library

Reference

        Release Notes
        JCas Configuration
        FAQ
        Help Forum

JCas Developers

API Javadocs
CAS Specification

The information presented is divided into the following sections:

Introduction - Briefly describes the information covered here, with links and references to other sources of information.
Installation - Covers acquiring and installing the required software components to use JCas
Basic Configuration - Discusses basic, necessary steps to configure JCas.
JDBC Example - Explains a simple CAS JDBC setup and configuration.
JAAS Example - A simple JAAS setup and configuration.
Testing a CAS server - explains how to test a specific CAS server with methods delivered with JCas.

Introduction

This manual is a primer covering the basic steps of using JCas to set up a distributed authorization environment, organize your resources, and then test your JCas server. It does not discuss architectures for distributed applications, or provide in depth instructions on operating the tools that are discussed. References to sources of additional information are included in the following subsections.

The discussion in this manual is aimed at administrators who will be setup a CAS server. As such, the recommendations are fairly generic -- but you should easily be able to apply them in either a Windows-based or Unix-based environment.

The following links provide access to selected sources of online information, documentation, and software that is useful in setting up a CAS server.

CAS/1.0 Specification - Describes the protocol that must be applied for CAS based, distributed authorization. Specific information on requests, responses and error codes is helpful.
J2SE Documentation - Documents all tools related to the Java 2 Platform, Standard Edition.
Sun BluePrints (tm) Design Guidelines for J2EE - Comprehensive advice and examples on application design for the Java2 Enterprise Edition (J2EE) platform, which includes JAAS pages. The chapters on JAAS design are useful even when your application does not require other J2EE platform components.

Installation

In order to use JCas for distributed authorization, you must first install it (and the software it depends on). The required steps are outlined in the following subsections.

J2SE

JCas will operate under any Java Runtime Environment (JRE) environment that provides a JRE 1.4 (also known as Java2 Standard Edition, or J2SE) or later platform. JCas has been extensively tested with JDK 1.4.2, which is recommended.

Compatible JREs for many platforms (or links to where they can be found) are available at http://java.sun.com/j2se/.

JDBC drivers

JCas will need appropriate JDBC drivers to access backend databases. Some of the most important JDBC drivers are listed below:

MySQL JDBC driver is developed as part of the MMMySQL project at Sourceforge.net.
Oracle JDBC drivers can be found at http://www.oracle.com/.
DB2 UDB JDBC drivers are delivered with the software package. If someone finds a specific page for DB2 JDBC downloads, please tell us!
Informix JDBC drivers can be found at http://www.ibm.com/. You need to search for "Informix JDBC" at the download section.

You need to include the appropriate JDBC driver for your specific database engine into CLASSPATH variable, so JCas is able to load it.

JAAS drivers

Sun delivers a few JAAS modules along with its J2SE, such as:

Unix Login Module - enables authorization against the Unix /etc/users file.
NT Login Module - enables authorization against Windows NT authorization system, works on Win2k, WinXP and WinNT.
JNDI Login Module - enables authorization against a JNDI source, e.g. LDAP directory.
Kerberos 5 Login Module - enables authorization against Kerberos 5 systems.

Some application servers, such as IBM WebSphere and BEA WebLogic, deliver their own JAAS Login Module. Please refer to their documentation if you need to make use of the products.

Additionally, some other, free JAAS modules are available:

Hibernate Login Module - for use in conjunction with Hibernate. The page merley describes how to write the module than to provide it as a download.
Slide Login Module - for use in Slide, an Apache.org Content Management System.

Basic Configuration

This section will discuss briefly how to setup the minimum configuration elements in the XML configuration file. Additional information can be found at:

SSL - SSL setup for JCas.
Access Control - Discusses mechanism to control access to JCas.
JDBC Authorization - Discusses JDBC related configuration elements.
JAAS Authorization - Discusses JAAS related configuration elements.
Reference - Complete reference manual of all configuration elements.

The configuration file consists of basically four parts: server configuration, Cookie configuration, JDBC instances configuration and scheme definitions:

<?xml version="1.0"?>
<CAS>
    <Server>
    ...
    </Server>

    <Cookies>
    ...
    </Cookies>

    <Instances>
    ...
    </Instances>

    <Scheme>
    ...
    </Scheme>

</CAS>

Not all of these parts must be present in a configuration file, e.g. Cookies are not required if you don't plan to make use of them (although they incredibly speed up the authorization process).

The following sections will shortly introduce the major configuration issues that may arise when you start using JCas. They will cover the first part of the configuration: server configuration. Then, a few examples of typical JDBC and JAAS authorizations are given.

Network Configuration

The network configuration defines, how JCas will bind its socket listener to your network. This includes a specific host adapter as well as TCP/IP ports and whether the socket will encrypt all data with SSL. Usually, you do not need to alter the default network configuration unless you have serious reasons to do so, e.g. security considerations force you to accept connections only from the Intranet side host adapter.

Host Adapter. - By default, JCas will bind its listener socket to all host adapters (symbolized by a star). The <Address> element gives you control over this behaviour.
Port. - JCas will listen on a specific TCP/IP port for requests from clients. The default port is 4466, but any port can be configured if the default cannot be applied onto your machine. Use the <Port> element to specify the port.
SSL Encryption. - CAS specification recommends using SSL as network encryption method. JCas enables SSL by default but <SSL> element can switch off encryption.

Here is an example:

...
<Bind>
    <!-- Bind to localhost only. This will accept connections on 127.0.0.1 only! -->
    <Address>localhost</Address>

    <!-- Bind to port 4466. This will accept connections on port 4466. 
        This is the default and, hence, can be missing! -->
    <Port>4466</Port>

    <!-- Since only local connections are allowed, SSL will be turned off to
        increase performance.  -->
    <SSL>false</SSL>
</Bind>
...

SSL Configuration

If SSL encryption is being used, you will need a valid server certificate (.crt file) and the corresponding DER encoded private key.

Both information is given in the <SSLKeyFile>> and <SSLCertificateFile> elements. <SSLKeyPassword> element gives instructions hot to retrieve the password of the keyfile:

Prefix pass: gives the password directly (plain text) after the colon in the XML configuration file, e.g.
Prefix file: instructs JCas to read the password from a file on local disk, e.g.
Prefix exec: instructs JCas to execute a program. The program will give the correct password on STDOUT, e.g.

Thread Configuration

JCas will assign client connections to specific threads that handle all the work related to it. Apache HTTP Daemon uses the same approach to enable multiple connections at the same time (although Apache uses child processes instead of threads). Four elements control how JCas will manage threads:

<ThreadStart> - tells the number of threads JCas will spawn at startup. Default value is 5.
<ThreadSpareMin> - defines minimum number of idle threads. JCas will create idle threads in advance to allow faster assignment of new connections coming in. Default value is 5.
<ThreadSpareMax> - defines maximum number of threads that are idle. JCas will destroy additional idle threads to free unnecessary resources. Default value is 5.
<ThreadRequestMax> - Each thread will exist throughout the lifetime of the server (except other configuration elements require desctruction of it) serving an unlimited number of requests. This element defines a upper limit for a specific thread. Once the limit is reached, JCas will close the associated connection and destroy the thread. Default value is 0 (unlimited).

Access Restriction Configuration

For finer control over what clients are allowed to connect to the server (apart from <Address> element, see above), JCas can be defined to restrict the network and/or client's agents it responds to.

The <AllowFrom> element that is used for this kind of restriction can be applied to all connections, administration commands and schemes. General restrictions overrule sub-restrictions.

An <Address> element restricts the permitted IP addresses of clients. Placeholders, such as stars can be used, e.g.:
A <Subnet> element restricts the permitted IP subnets a client may come from. Placeholders, such as stars can be used, e.g.:
An <Agent> element restricts the permitted client products that may request an authorization. By using this, you can further eliminate unwanted requests. Placeholders, such as stars can be used, e.g.:

Address and subnet restrictions are alternatives, only one restriction must be fulfilled, whereas agent restrictions apply additionally. In other words, a client that comes from a valid IP address but uses a wrong agent, will be rejected. This behaviour applies to a single <AllowFrom> element. But multiple, alternative <AllowFrom> elements can be given.

JDBC Example

Here is an example of a simple JDBC authorization against a Oracle database.

 1 <?xml version="1.0"?>
 2 <CAS>
 3     <Server>
 4        <Bind>
 5            <Address>localhost</Address>
 6            <SSL>false</SSL>
 7        </Bind>
 8
 9        <AllowFrom>
10            <Agent>mod_cas/*</Agent>
11        </AllowFrom>
12
13        <Logfile>/var/log/jcas.log</Logfile>
14   </Server>
15
16    <Instances>
17        <Instance>
18            <Name>ORA1</Name>
19            <Driver>oracle.jdbc.driver.OracleDriver</Driver>
20            <Path>jdbc:oracle:thin:$uid$/$pwd$@localhost:1521:ralph</Path>
21            <RoleSelect>select role from session_roles</RoleSelect>
22            <AdminRole>DBA</AdminRole>
23            <DummyTable>DUAL</DummyTable>
24        </Instance>
25    </Instances>
26
27    <Scheme>
28         <Name>ORA1_SCHEME</Name>
29         <Instance>ORA1</Instance>
30         <Logfile>/var/log/jcas.ORA1.log</Logfile>
31         <SystemAuthorization>
32            <RequireRole>APPLICATION_ROLE</RequireRole>
33         </SystemAuthorization>
34         <UseCookies>true</UseCookies>
35     </Scheme>
36 
37 </CAS>

Lines 3-14 tell JCas how to connect to the network and which agents are allowed to connect to the server. JCas will bind to localhost only (line 5) and disable SSL (line 6). Only mod_cas agents are permitted to send requests (line 10).

This example defines a single (Oracle) JDBC database instance named ORA1 (lines 17-24). The driver and driver's path (lines 19-20) are necessary to enable JCas to contact the database. Please note the placeholders $uid and $pwd. JCas will replace these variables with the actual values from a client's request. Additional information is given about how to find out about roles and administrators on the specific database instance (lines 21-23). These information vary for each database vendor.

Lines 27-35 define the scheme ORA1_SCHEME. Here, assignment of the database instance is made (line 29) and System Authorization method is defined (lines 31-33). Each user must have user role APPLICATION_ROLE to be authorized successfully in that scheme.

JAAS Example

Here is an example of a simple JAAS authorization against the UNIX system:

 1 <?xml version="1.0"?>
 2 <CAS>
 3     <Server>
 4        <Bind>
 5            <Address>localhost</Address>
 6            <SSL>false</SSL>
 7        </Bind>
 8
 9        <AllowFrom>
10            <Agent>mod_cas/*</Agent>
11        </AllowFrom>
12
13        <Logfile>/var/log/jcas.log</Logfile>
14   </Server>
15
16    <Scheme>
17         <Name>SYSTEM_SCHEME</Name>
18         <Jaas>UnixLogin</Jaas>
19         <Logfile>/var/log/jcas.SYSTEM.log</Logfile>
20         <UseCookies>true</UseCookies>
21     </Scheme>
22 
23 </CAS>

This example defines a single JAAS resource to be used. The scheme SYSTEM_SCHEME (lines 16-21) is assigned to the JAAS resource in line 18.

The corresponding JAAS module configuration is defined as:

 1 UnixLogin {
 2     com.sun.security.auth.module.UnixLoginModule required;
 3 };

Here, the JAAS resource UnixLogin is attached to the Unix Login Module delivered by Sun's J2SE.

Testing a CAS server

JCas delivers a Java CAS command line client that will return if the user can be authorized against a server. Thus, you can use it to test your configuration.

Usage is:

java -cp /usr/local/jcas/jcas.jar cas.JCasClient <host> <port> <scheme> <user> <password> -ssl|-nossl

For the JAAS example above, you would issue the following command:

java -cp /usr/local/jcas/jcas.jar cas.JCasClient localhost 4466 SYSTEM_SCHEME root password -nossl

This will check the root/password combination on scheme SYSTEM_SCHEME at the local JCas server. No SSL encryption will be used.