NAME
Apache2::AuthCAS - A configurable Apache authentication module that enables you to protect content on an Apache server using an existing JA-SIG CAS authentication server.
SYNOPSIS
perl -MCPAN -e 'install Apache2::AuthCAS'
DESCRIPTION
General
The Apache2::AuthCAS module allows a user to protect arbitrary content on an Apache server with JA-SIG CAS.
Add the following lines to your Apache configuration file to load the custom configuration tags for CAS and allow for CAS authentication:
PerlLoadModule APR::Table
PerlLoadModule Apache2::AuthCAS::Configuration
PerlLoadModule Apache2::AuthCAS
At this point, the configuration directives may be used. All directives can be nested in Location, Directory, or VirtualHost sections.
Add the following lines to an Apache configuration file or .htaccess file:
AuthType Apache2::AuthCAS
AuthName "CAS"
PerlAuthenHandler Apache2::AuthCAS->authenticate
require valid-user
*note* - this simple config assumes that the rest of the settings have
been set in your Apache configuration file. If not, they
will need to be set here (if allowed by your configuration).
Any options that are not set in the Apache configuration will default to the values preconfigured in the Apache2::AuthCAS module. Either explicitly override those options that do not match your environment or set them in the module itself.
Requirements
Apache 2.x with mod_perl2
Perl modules: Net::SSLeay MIME::Base64 URI::Escape XML::Simple DBI DBD::<module name> (i.e. DBD::Pg)
Proxiable Credentials
This module can be optionally configured to use proxy credentials. This is enabled by setting the CASService and CASProxyService configuration parameters.
Examples
Example configuration without proxiable credentials:
AuthType Apache2::AuthCAS
AuthName "CAS"
PerlAuthenHandler Apache2::AuthCAS->authenticate
require valid-user
CASHost "auth.yourdomain.com"
CASErrorURL "https://yourdomain.com/cas/error/"
CASDbDataSource "dbname=cas;host=dbhost.yourdomain.com;port=5432"
Example configuration without proxiable credentials, using custom database parameters:
AuthType Apache2::AuthCAS
AuthName "CAS"
PerlAuthenHandler Apache2::AuthCAS->authenticate
require valid-user
CASHost "auth.yourdomain.com"
CASErrorURL "https://yourdomain.com/cas/error/"
CASDbDriver "Oracle
CASDbDataSource "sid=yourdb;host=dbhost.yourdomain.com;port=1521"
CASDbUser "cas_user"
CASDbPass "cas_pass"
CASDbSessionTable "cas_sessions_service1"
Example configuration with proxiable credentials:
AuthType Apache2::AuthCAS
AuthName "CAS"
PerlAuthenHandler Apache2::AuthCAS->authenticate
require valid-user
CASService "https://yourdomain.com/email/"
CASProxyService "mail.yourdomain.com"
Example configuration with proxiable credentials, using custom database parameters:
AuthType Apache2::AuthCAS
AuthName "CAS"
PerlAuthenHandler Apache2::AuthCAS->authenticate
require valid-user
CASService "https://yourdomain.com/email/"
CASProxyService "mail.yourdomain.com"
CASDbDriver "Oracle
CASDbDataSource "sid=yourdb;host=dbhost.yourdomain.com;port=1521"
CASDbUser "cas_user"
CASDbPass "cas_pass"
CASDbSessionTable "cas_sessions_service1"
Configuration Options
These are the Apache configuration options, defaults, and descriptions for Apache2::AuthCAS.
# The CAS server parameters. These should be self explanatory.
CASHost "localhost"
CASPort "443"
CASLoginUri "/cas/login"
CASLogoutUri "/cas/logout"
CASProxyUri "/cas/proxy"
CASProxyValidateUri "/cas/proxyValidate"
CASServiceValidateUri "/cas/serviceValidate"
# The level of logging, ERROR(0) - EMERG(4)
CASLogLevel 0
# Should we set the 'Basic' authentication header?
CASPretendBasicAuth 0
# Where do we redirect if there is an error?
CASErrorUrl "http://localhost/cas/error/"
# Session cleanup threshold (1 in N requests)
# Session cleanup will occur for each Apache thread or process -
# i.e. for 10 processes, it may take as many as 100 requests before
# session cleanup is performed with a threshold of 10)
CASSessionCleanupThreshold 10
# Session cookie configuration for this service
CASSessionCookieDomain ""
CASSessionCookieName "APACHECAS"
CASSessionTimeout 1800
# Should the ticket parameter be removed from the URL?
CASRemoveTicket 0
# Optional override for this service name
CASService ""
# If you are proxying for a backend service you will need to specify
# these parameters. The service is the name of the backend service
# you are proxying for, the receptor is the URL you will listen at
# for pgtiou/pgt mappings from the CAS server, and the final parameter
# specifies how many proxy tickets should be requested for the backend
# service.
CASProxyService ""
CASNumProxyTickets 0
# Database parameters for session and ticket management
CASDbDriver "Pg"
CASDbDataSource "dbname=apache_cas;host=localhost;port=5432"
CASDbSessionTable "cas_sessions"
CASDbUser "cas"
CASDbPass "cas"
NOTES
Configuration
Any options that are not set in the Apache configuration will default to the
values preconfigured in the Apache2::AuthCAS module. You should explicitly
override those options that do not match your environment.
Database
If you installed this module via CPAN shell, cpan2rpm, or some other automated installer, don't forget to create the session table!
The SQL-92 format of the table is:
CREATE TABLE cas_sessions (
id varchar(32) not null primary key,
last_accessed int8 not null,
user_id varchar(32) not null,
pgtiou varchar(256),
pgt varchar(256)
service_ticket varchar(256)
);
Add indexes and adjust as appropriate for your database and usage.
SSL
Be careful not to use the CASSessionCookieSecure flag with an HTTP resource.
If this flag is set and the protocol is HTTP, then no cookie will get sent
to Apache and Apache2::AuthCAS may act very strange.
Be sure to set CASSessionCookieSecure only on HTTPS resources!
COMPATIBILITY
This module will only work with mod_perl2. mod_perl1 is not supported.
SEE ALSO
Official JA-SIG CAS Website
http://www.ja-sig.org/products/cas/
mod_perl Documentation
http://perl.apache.org/
AUTHORS
Jason Hitt <jhitt@illumasys.com>
COPYRIGHT
Copyright (C) 2007 Jason Hitt <jhitt@illumasys.com>
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA