mod_auth_cas

Owned by Phil Ames
Last updated: Jun 18, 2012 by Marvin AddisonVersion comment
5 min read

mod_auth_cas is an Apache 2.0/2.2 compliant module that supports the CASv1 and CASv2 protocols.  You can download the current version of mod_auth_cas by visiting JA-SIG's Subversion repository at https://github.com/Jasig/mod_auth_cas/tags.

Matt Smith's 11 January 2008 note about mod_auth_cas compared with mod_cas

mod_auth_cas was written to specifically target Apache 2.2 and the CAS v2 protocol, although it will also work with Apache 2.0 and the CAS v1 protocol. Much of mod_auth_cas' design was based upon the original mod_cas. I can't speak for mod_cas, but mod_auth_cas is being actively maintained.

I may be a bit biased, but I would recommend mod_auth_cas.

-Matt
(See original post in context on cas@)

 You may find the most up-to-date documentation in https://github.com/Jasig/mod_auth_cas/blob/master/README 

SOFTWARE DEPENDENCIES
The module was built and tested on the following libraries/versions:

OpenSSL - 0.9.8c
Apache Portable Runtime - 1.2.8
Apache Portable Runtime Utilities - 1.2.7
Apache Web Server - 2.2.3

Compatibility with other versions will depend on those other libraries.

INSTALLATION INSTRUCTIONS
Ensure that the follow files are in the working directory:
mod_auth_cas.c
mod_auth_cas.h

COMPILE INSTRUCTIONS
Use the APache eXtenSion tool (APXS) to compile and install this
object as a dynamically shared object (DSO):

apxs2 -i -c mod_auth_cas.c

If you want to install this for an Apache 2.0 server, please edit
mod_auth_cas.h and modify the line that says:
#undef APACHE2_0

to

#define APACHE2_0

CONFIGURING THE SOFTWARE
First, you must tell Apache to load the module. In your httpd.conf,
add:

LoadModule auth_cas_module /path/to/mod_auth_cas.so

The following are valid configuration options and their default:

Valid Server/VirtualHost Directives
Directive: CASVersion
Default: 2
Description: The version of the CAS protocol to adhere to (1 or 2).
This affects whether Gateway mode is available and how
the CAS validation response is parsed.

Directive: CASDebug
Default: Off
Description: Enable or disable debugging mode for troubleshooting.

Directive: CASValidateServer
Default: On
Description: If set to 'On', mod_auth_cas will validate that the certificate
presented by the server specified in CASLoginURL is both
signed by the Certificate Authority specified in CASCertificatePath
and that the hostname matches the Common Name of the certificate.

Directive: CASValidateDepth
Default: 9
Description: This directive will set the maximum depth for chained certificate
validation. The default (according to OpenSSL documentation) is 9.

Directive: CASAllowWildcardCert
Default: Off
Description: This directive determines whether a wildcard certificate can be trusted
to verify the CAS server. For instance, if the CAS server presents a
certificate for *.example.com and the hostname portion of the CASValidateURL
is 'cas.login.example.com', this directive (if enabled) will accept that
certificate.

Directive: CASCertificatePath
Default: /etc/ssl/certs/
Description: The path to the X509 certificate of the Certificate Authority for
the server in CASLoginURL and CASValidateURL. This may be either
a file, or a directory containing the certificate files linked to
by their hashed names.

Directive: CASLoginURL
Default:https://login.uconn.edu/cas/login
Description: The URL to redirect users to when they attempt to access a CAS
protected resource and do not have an existing session. The
'service', 'renew', and 'gateway' parameters will be appended to
this by mod_auth_cas if necessary.

Directive: CASValidateURL
Default:https://login.uconn.edu/cas/serviceValidate
Description: The URL to use when validating a ticket presented by a client in
the HTTP query string (ticket=...).

Directive: CASProxyValidateURL
Default:https://login.uconn.edu/cas/proxyValidate
Description: The URL to use when performing a proxy validation. This is currently
an unimplemented feature, so setting this will have no effect.

Directive: CASCookiePath
Default: /tmp/cas/
Description: When users first authenticate to mod_auth_cas with a valid service ticket,
a local session is established. Information about this session (the
username, time of creation, last activity time, the resource initially
requested, and whether or not the credentials were renewed) is stored
in this file. This location should be writable by the web server.

Directive: CASCookieEntropy
Default: 32
Description: When creating a local session, this many random bytes are used to
create a unique session identifier. Using large values for this
field may result in delays when generating session IDs if not
enough entropy is available.

Directive: CASTimeout
Default: 7200 (2 hours)
Description: This is the hard limit, in seconds, for a mod_auth_cas session (whether
it is idle or not). When a session has reached this age and a new
request is made, the user is redirected to the CASLoginURL to
obtain a new service ticket. When this new ticket is validated,
they will be assigned a new mod_auth_cas session.

Directive: CASIdleTimeout
Default: 3600 (1 hour)
Description: This is a limit, in seconds, of how long a mod_auth_cas session can be idle.
When a request comes in, if it has been inactive for CASIdleTimeout
seconds, the user is redirected to the CASLoginURL to obtain a new
service ticket.

Directive: CASCacheCleanInterval
Default: 1800 (30 minutes)
Description: This is the minimum amount of time that must pass inbetween cache
cleanings. When a new ticket is issued, or when an expired session
is presented, the time of the last cache clean is compared against
this value. If CASCacheCleanInterval seconds have passed since the
last cleaning, then all files in CASCookiePath are examined and if
they have expired, they are removed. This is merely to prevent the
file system from becoming excessively cluttered.

Valid Directory/.htaccess Directives
Directive: CASScope
Default: Off
Description: Use this directive with an argument as a relative path (e.g. /application/)
to specify the scope for which a mod_auth_cas cookie is valid. This is beneficial to prevent
additional round trips to the CAS server. Assume someone authenticates to /application/subdir/
and then browses to /application/ - without CASScope set, each request would result in a round
trip to the CAS server and a new cookie being created (one for each directory). CASScope would
set one cookie, which will be presented on access to both directories. Note that if someone
accessed /application/ and then /application/subdir/ this would not be an issue, but that order
of access can not be guaranteed. To disable this feature, the special argument 'Off' will
return to per-directory cookie paths for this directory and subdirectories.

Directive: CASRenew
Default: Off
Description: Use this directive with an argument as a relative path (e.g. /application/secure/
for http://www.example.com/application/secure/*) to force a user to renew their credentials when
accessing that directory. The argument MUST be a relative path. To disable this requirement,
the special argument 'Off' will disable this requirement for this directory and subdirectories.

Directive: CASGateway
Default: Off
Description: Use this directive with an argument as a relative path (e.g. /application/insecure/
for http://www.example.com/application/insecure/*) to allow anonymous access to that directory.
The argument MUST be a relative path. To disable this feature, the special argument 'Off' will
reinstate the requirement for authentication.

Directive: CASCookie
Default: MOD_AUTH_CAS
Description: The name of the cookie used to store the session ID over HTTP connections.
It should be changed if it will interfere with the application protected
by mod_auth_cas.

Directive: CASSecureCookie
Default: MOD_AUTH_CAS_S
Description: The name of the cookie used to store the session ID over HTTPS connections.
It should be changed if it will interfere with the application protected
by mod_auth_cas.

Directive: CASGatewayCookie
Default: MOD_AUTH_CAS_G
Description: The name of the cookie used to store whether or not the user has attempted
to access this resource before. It should be changed if it will interfere
with the application protected by mod_auth_cas.

 Directive: CASAuthNHeader
Default: None
Description: If enabled, this will store the user returned by CAS in an HTTP header
 accessible to your web applications (should they require something else than REMOTE_USER).

Using it to protect access to resources

Protecting access to web apps / CGIs

Once you'll have setup the Apache auth / permissions on access to an application,  the application's CGIs or scripts will be called with environment containing the user login in the REMOTE_USER variable.

Additionally, should your application need another HTTP, header  you may  use the CASAuthNHeader directive to provide another environment variable.