view release on metacpan or  search on metacpan

lib/Apache2/AuthCAS.pm  view on Meta::CPAN

1;
__END__

=head1 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.

=head1 SYNOPSIS

C<perl -MCPAN -e 'install Apache2::AuthCAS'>

=head1 DESCRIPTION

=head2 General

The I<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.

=head2 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)

=head2 Proxiable Credentials

This module can be optionally configured to use proxy credentials.  This is
enabled by setting the I<CASService> and I<CASProxyService> configuration
parameters.

=head2 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"

=head2 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