NAME

AuthCASpbh - CAS SSO integration for Apache/mod_perl

SYNOPSIS

Load the module in your Apache mod_perl configuration:

        PerlLoadModule Apache2::AuthCASpbh
        AuthCAS_ServerURL https://my.cas.server/cas

and include additional configuration from the ancillary modules as necessary:

Apache2::AuthCASpbh::Authn

Apache2::AuthCASpbh::Authz

Apache2::AuthCASpbh::ProxyCB

Apache2::AuthCASpbh::UserAgent

DESCRIPTION

AuthCASpbh is a framework for integrating CAS SSO support into the Apache web server using mod_perl. It can authenticate Apache resources via CAS, perform authorization via CAS attributes, acquire proxy granting tickets, and provides a client allowing transparent access to other CAS applications via proxy authentication. It automatically manages sessions using Apache::Session (currently via sqlite, but other mechanisms could be used) and provides mod_perl based applications access to session state and attributes.

Configuration options

AuthCAS_DebugLevel

Use a different logging level for debugging messages generated by AuthCASpbh rather than the default "debug", allowing visibility into internal operation without being overwhelmed by debugging output from unrelated components. Messages can be logged at any supported Apache level, for example:

        AuthCAS_DebugLevel warn
AuthCAS_LoginPath

The URL component added after the AuthCAS_ServerURL value to access the CAS login service; by default "/login".

AuthCAS_PGTCallback

The location of the callback used by the configured CAS server when the request of a proxy granting ticket is enabled. By default, it is the relative URL "/cas_pgt" on the server running AuthCASpbh; however, it could also be a fully qualified URL to point it to an arbitrary location:

        AuthCAS_PGTCallback https://some.other.server/cas_pgt

The URL must be served by Apache2::AuthCASpbh::ProxyCB or a compatible mechanism that will store the proxy ticket information into the global AuthCASpbh session.

AuthCAS_PGTIOU_TTL

The amount of time in seconds that a proxy granting ticket IOU to proxy granting ticket value mapping will be maintained in the AuthCASpbh global session. By default it is 10 seconds, and it is unlikely that value would need to be overridden in normal circumstances.

AuthCAS_ProxyAllow

A list of proxy servers to allow access to the AuthCASpbh protected application if proxied authentication is desired. Proxied authentication is only enabled if at least one of AuthCAS_ProxyAllow or AuthCAS_ProxyAllowRE is configured for the location being accessed. For example:

        AuthCAS_ProxyAllow https://my.frontend.server/cas
AuthCAS_ProxyAllowRE

A list of regular expressions to be compared to connecting proxy server to determine whether or not to allow access to the AuthCASpbh protected application. Proxied authentication is only enabled if at least one of AuthCAS_ProxyAllow or AuthCAS_ProxyAllowRE is configured for the location being accessed. For example:

        AuthCAS_ProxyAllow ^https://[^/]+\.my\.domain/
AuthCAS_ProxyPath

The URL component added after the AuthCAS_ServerURL value to access the CAS proxy ticket issuing service; by default "/proxy".

AuthCAS_ProxyRequire

If proxied authentication is enabled, only allow access via proxy credentials, not direct access by a user; by default disabled.

AuthCAS_ProxyValidatePath

The URL component added after the AuthCAS_ServerURL value to access the CAS proxy ticket validation service; by default "/proxyValidate". =item AuthCAS_RemoveServiceTicket

Whether or not to remove the ticket parameter from the request arguments (eg, query string) after it is processed; by default disabled. Note that the value is only removed from the Apache args variable, not from the unparsed URI; if an application directly accesses the unparsed URI it will still see the value.

AuthCAS_RequestPGT

Whether or not to request a proxy granting ticket when a client service ticket is validated; by default disabled.

AuthCAS_ServerURL

The URL value to access the CAS authentication server; by default "http://localhost/cas". For example:

        AuthCAS_ServerURL https://idp.my.domain/idp/profile/cas
AuthCAS_ServiceOverride

A URL with which to override the computed service URL used when redirecting to the CAS login page or validating a supplied service ticket. For example:

        AuthCAS_ServiceOverride https://my.service/cas-login
AuthCAS_ServiceValidatePath

The URL component added after the AuthCAS_ServerURL value to access the CAS ticket validation service; by default "/serviceValidate".

AuthCAS_SessionCleanupInterval

How frequently (in seconds) to remove expired authentication sessions and examine the global session to remove orphaned expired proxy ticket mappings; by default 3600 seconds.

AuthCAS_SessionCookieName

The name of the cookie sent to the client to store the AuthCASpbh session identifier; by default "AuthCAS_Session".

AuthCAS_SessionCookiePath

An optional path to include in the session cookie.

AuthCAS_SessionCookieSecure

Whether or not to set the secure flag on the session cookie; by default enabled.

AuthCAS_SessionDBName

The filename of the sqlite database used to store session information; by default "authcas_sessions.db". Prior to use of AuthCASpbh, the database must be created and the schema created using the following command within sqlite:

        CREATE TABLE sessions (
                id char(32) not null primary key,
                a_session text
        );

In addition, the global state session must be created. If using the default SessionStateName value of "ABC123" this can be accomplished by:

        insert into sessions (id, a_session) values ('ABC123', '{"_session_id":"ABC123"}');

Finally, the service account used by the Apache web server must be granted access to this file by whatever mechanism is appropriate for your deployment.

AuthCAS_SessionDBPath

The path to the sqlite database used to store session information; by default "/tmp".

AuthCAS_SessionStateName

The name of the session used to maintain AuthCASpbh global state; by default "ABC123".

AuthCAS_SessionTTL

How long in seconds an AuthCASpbh authentication session should be valid; by default 3600 seconds. Note that if you are utilizing client proxy authentication with the session that this value should not exceed the lifetime of the proxy granting ticket provided by your CAS server or failures to acquire proxy tickets might occur.

AVAILABILITY

AuthCASpbh is available via CPAN as well as on GitHub at

https://github.com/pbhenson/Apache2-AuthCASpbh

AUTHOR

Copyright (c) 2018, Paul B. Henson <henson@acm.org>

This file is part of AuthCASpbh.

AuthCASpbh 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 3 of the License, or (at your option) any later version.

AuthCASpbh 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 AuthCASpbh. If not, see <http://www.gnu.org/licenses/>.

SEE ALSO

Apache2::AuthCASpbh::Authn - Authentication functionality

Apache2::AuthCASpbh::Authz - Authorization functionality

Apache2::AuthCASpbh::ProxyCB - Proxy granting ticket callback module

Apache2::AuthCASpbh::UserAgent - Proxy authentication client