The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Apache2-AuthCAS-0.4
River stage zero No dependents
++
/ Apache2::AuthCAS

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