CAS Apache moduleget help

mod_auth_cas introduction

mod_auth_cas is an Apache module that uses CAS to protect static and dynamic web content.


An older module, called mod_cas, was available for Apache 2.0, and should continue to work. However the URLs of CAS have changed, so that module would require recompiling after modifying the cas.h file to point to the new URLs. The new mod_auth_cas module will work with both Apache2.x and Apache 2.2.

All applications that use SFU CAS must be registered as a service.  Fill out the CAS Service Application form to get started.

Building

Obtain a copy of the SFU mod_auth_cas module


Follow the instructions in the README file to install the module in Apache.

Installation

To use the CAS module (mod_auth_cas), mod_auth_cas.so should be installed in an appropriate path and loaded with the following in httpd.conf:


LoadModule auth_cas_module modules/mod_auth_cas.so

 <IfModule mod_auth_cas.c>
      CASVersion 2
      CASValidateServer On
      CASCertificatePath /etc/ssl/certs/ThawtePremiumServerBundleCA.pem
      CASAllowWildcardCert Off
      CASLoginURL https://cas.sfu.ca/cas/login
      CASValidateURL https://cas.sfu.ca/cas/serviceValidate
      CASTicketsURL https://cas.sfu.ca/cas/rest/v1/tickets
      CASCookiePath /usr/local/apache2/cas/
 </IfModule>

To allow mod_auth_cas to validate the SSL connection to CAS, you need a copy of ThawtePremiumServerBundleCA.pem. Place this file in a convenient location on your server (e.g. /etc/ssl/certs) and use The CASCertificatePath directive to point to it.

For the CAS module to be triggered, the AuthType must be set to "CAS" or "Basic" with a line like


     AuthType CAS


in the server configuration (httpd.conf) file or a local .htaccess file.


Because the SFU version of mod_cas does basic authentication as well as authentication of SFU accounts, Basic is allowed as well as CAS. To avoid conflict with the built in Basic authentication module, make sure the following LoadModule lines are commented out in the httpd.conf file:


#LoadModule authn_default_module modules/mod_authn_default.so
#LoadModule authz_user_module modules/mod_authz_user.so
#LoadModule auth_basic_module modules/mod_auth_basic.so


Various Require directives are supported, and are described in detail in the document on using .htaccess files with CAS.

Configuration

For mod_auth_cas, the following parameters are additionally supported in the central configuration file but are not allowed in.htaccess; they are intended to be set only by the server administrator and, with the exception of CASLocalCacheInsecure and CASRootProxiedAs, only once per server:


CASDebug Off
Enable or disable debugging mode for troubleshooting.


CASValidateServer On
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.


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


CASAllowWildcardCert Off
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. Note that at SFU, this should be off.


CASCertificatePath /etc/ssl/certs/
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.


CASLoginURL (no default, so must be set)
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. Include 'http[s]://...'


At SFU this should be set to https://cas.sfu.ca/cas/login


CASValidateURL (no default, so must be set)
The URL to use when validating a ticket presented by a client in the HTTP query string (ticket=...). Must include 'https://' and must be an HTTPS URL.


At SFU this should be set to https://cas.sfu.ca/cas/serviceValidate


CASTicketsURL (no default, so must be set)
The REST interface URL to use when validating ID/passwords presented by an application/browser when using Basic authentication. Basic authentication can be used only if this is specified (see CASAuthType). Must include 'https://' and must be an HTTPS URL.


At SFU this should be set to https://cas.sfu.ca/cas/rest/v1/tickets


CASCookiePath (no default, so must be set)
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 directory. This location should be writable by the web server ONLY. Any user that can write to this location can falsify authentication information by creating a fake data file.


NOTE : Some distributions purge the contents of /tmp/ on a reboot, including user created directories. This will prevent mod_auth_cas from storing cookie information until that directory is created. To avoid this, try using a different location, such as /var/cache/apache2/mod_auth_cas/


CASCookieEntropy 32
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.


CASTimeout 7200 (2 hours)
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.


CASIdleTimeout 3600 (1 hour)
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.


CASCacheCleanInterval 1800 (30 minutes)
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.


CASCookieHttpOnly Off
Set the optional 'HttpOnly' flag for cookies issues by mod_auth_cas. This parameter may break RFC compliance since HttpOnly is not defined in RFC 2109. See http://msdn2.microsoft.com/en-us/library/ms533046.aspx for more information. Please note this feature is not honored by all browsers.


CASRootProxiedAs
This URL represents the URL that end users may see in the event that access to this Apache server is proxied. This will override the automatic generation of service URLs and construct them using this prefix. As an example: If the site being protected is http://example.com/ and the Apache instance of this server is http://internal.example.com:8080, setting CASRootProxiedAs to http://example.com would result in proper service parameter generation.