/ 
LibCAS-0.02a
River stage zero No dependents
/ LibCAS::Client

NAME

LibCAS::Client - A perl module for authenticating and validating against Jasig's CAS server

VERSION

Version 0.01

SYNOPSIS

LibCAS::Client provides an OO interface for generating URLs and validating tickets for Jasig's Central Authentication Service (CAS).

Using the module should hopefully be straight forward, something similar to:

my $cas = LibCAS::Client->new(cas_url => 'https://my-cas-server/cas');
my $login_url = $cas->login_url(service => 'my_service_name');

# Do a HTTP redirect to $login_url to have CAS prompt for credentials
# or to have the CAS server issue a service ticket.

my $r = $cas->service_validate(service => 'my_service_name', ticket => 'ticket_from_login');

if ($r->is_success()) {
	# Do things for successful authentication
} elsif ($r->is_failure()) {
	# Do things for failed authentication
} else {
	# Anything that makes it here is an error
}

METHODS

new

Create a new instance of the LibCAS::Client object. Valid parameters are:

cas_url - The base URL to the CAS server, defaults to https://localhost/cas
cas_login_path - The path to the CAS login service, defaults to /login
cas_logout_path - The path to the CAS logout service, defaults to /logout
cas_validate_path - The path to the CAS v1.0 validation service, defaults to /validate
cas_proxy_path - The path to the CAS proxy service, defaults to /proxy
cas_serviceValidate_path - The path to the CAS v2.0 service validation service, defaults to /serviceValidate
cas_proxyValidate_path - The path to the CAS v2.0 proxy validation service, defaults to /proxyValidate

login_url

Generate the login url needed for the CAS server, depending on the cas_url and cas_login_path parameters passed during object construction.

Valid parameters to the login_url method are:

service [optional] - The name of the service to authenticate for.
renew [optional] - Bypass any existing single sign-on session, and require the client to represent their credentials.
gateway [optional] - Do not require the client to present credentials if a single sign-on has not been established.

logout_url

Generate the logout url needed for the CAS server, depending on the cas_url and cas_logout_path parameters passed during object construction.

NOTE: Calling this method will destroy the single sign-on session, which may affect the client's ability to access other applications protected by this CAS server.

Valid parameters to the logout_url method are:

url [optional] - A URL to be displayed on the logout page.

validate_url

Generate the URL that performs CAS protocol version 1.0 service ticket validation.

Valid parameters to the validate_url method are:

service [required] - The name of the service which the ticket was issued for.
ticket [required] - The service ticket issued by the CAS server.
renew [optional] - If set, this option will only allow validation to pass if the ticket was issued immediatly after the client presents their credentials. It will fail if the service ticket that is presented was issued from a single sign-on session.

service_validate_url

Generate the URL that performs CAS protocol version 2.0 service ticket validation, and generate proxy- granting tickets, if requested.

Valid parameters to the service_validate_url method are:

service [required] - The name of the service which the ticket was issued for.
ticket [required] - The service ticket issued by the CAS server.
renew [optional] - If set, this option will only allow validation to pass if the ticket was issued immediatly after the client presents their credentials. It will fail if the service ticket that is presented was issued from a single sign-on session.
pgtUrl [optional] - The URL of the proxy callback.

proxy_url

Generate the URL to the CAS server for generating proxy tickets.

Valid parameters to the proxy_url method are:

pgt [required] - The proxy granting ticket.
targetService [required] - The service identifier for the back-end service.

proxy_validate_url

This method performs the same functions as the service_validate_url method, with the added benefit of being able to validate proxy tickets as well.

Valid parameters for proxy_validate_url are the same as they are for service_validate_url

validate

Validate a service ticket using CAS protocol version 1.0. Supported arguments for this method are the same as they are for the validate_url method.

Returns an LibCAS::Client::Response object to denote whether or not the validation was successful. Success, failure, or error conditions can be checked by calling the is_success(), is_failure(), or is_error() methods on the returned object.

service_validate

Validate a service ticket using CAS protocol version 2.0. Supported arguments for this method are the same as they are for the service_validate_url method.

Returns an LibCAS::Client::Response object to denote whether or not the validation was successful. Success, failure, or error conditions can be checked by calling the is_success(), is_failure(), or is_error() methods on the returned object.

proxy

Obtain a proxy ticket to services that have a proxy granting ticket, and will be using proxy authentication to a back-end service. Supported arguments for this method are the same as they are for the service_validate_url method.

Returns an LibCAS::Client::Response object to denote whether or not the validation was successful. Success, failure, or error conditions can be checked by calling the is_success(), is_failure(), or is_error() methods on the returned object.

proxy_validate

Validate a service ticket, or a proxy ticket, using CAS protocol version 2.0. Supported arguments for this method are the same as they are for the proxy_validate_url method.

Returns an LibCAS::Client::Response object to denote whether or not the validation was successful. Success, failure, or error conditions can be checked by calling the is_success(), is_failure(), or is_error() methods on the returned object.

AUTHOR

"Mike Morris", <"michael.m.morris at gmail.com">

BUGS

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc LibCAS::Client

You can also look for information at:

ACKNOWLEDGEMENTS

This code is derived from Authen::CAS::Client and AuthCAS, with the added ability to customize the paths for the services on the CAS server, and use URI and XML parsing libs.

Documentation for the CAS protocol can be found at http://www.jasig.org/cas/protocol

LICENSE AND COPYRIGHT

Copyright 2012 "Michael Morris".

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.