NAME

Catalyst::Authentication::Credential::CAS - Catalyst support for JA-SIG's Central Authentication Service.

SYNOPSIS

  # in MyApp.pm
  __PACKAGE__->config->{'Plugin::Authentication'} = {
    default_realm => 'default',
    default => {
      credential => {
        class          => 'CAS',
        uri            => 'https://cas.example.com/cas',
        username_field => 'username', # optional
        version        => '2.0',      # optional
      },
      store => {
        ...
      },
    },
  };

  # in a controller
  sub auto :Private {
    unless( $c->user_exists || $c->authenticate ) {
      $c->res->status( 401 );
      $c->res->body( 'Access Denied' );
      return 0;
    }
  }

DESCRIPTION

This module allows you to CAS-ify your Catalyst applications. It integrates Authen::CAS::Client into Catalyst's authentication framework.

CONFIGURATION

The following properties may be configured:

uri

This specifies the base URI for the CAS instance and is passed to the new() method of the CAS client. See the documentation for Authen::CAS::Client for more information.

username_field

This specifies the name of the key in the $authinfo hash that is passed to $realm->find_user() for mapping the user name returned from the CAS upon successful authentication and ticket validation. Its value will depend on what the configured user store expects. It defaults to 'username' if not specified in the application's configuration.

version

This specifies the verion of the CAS protocol to use. Currently only '1.0' and '2.0' are supported. If not specified in the application's configuration, the default of '2.0' is used. Its value will depend on if you can use the current version of the CAS protocol or if you need to fall back to the older version for compatibility.

METHODS

authenticate( $authinfo, $realm, $c )

This is called during the normal Catalyst authentication process and should never be called directly.

Since CAS is a service that verifies credentials outside of your application, the login process for your application will have two phases. In the first phase, an unauthenticated user will attempt to access your application and be redirected to the CAS for credential verification. A service URI must be provided to the CAS so that once the user has been identified, they can be redirected from the CAS back to your application for the second phase of authentication. During this second phase the (supposedly) authenticated user will be given a ticket that your application must validate with the CAS. If the ticket is valid, the user is considered authenticated. The authenticate() method handles both phases of authentication.

Unless specified otherwise, this method will do its best to guess the appropriate behavior for the service URI and ticket handling. The service URI will be derived as the URI for the currently executing action unless specified in the 'service' key of the $authinfo hash. The ticket returned from the CAS will be retrieved from the request parameters unless specifed in the 'ticket' key of the $authinfo hash. If no ticket is defined (phase one authentication) the response will be set to redirect to the CAS and the current action will be detached.

You may also pass other parameters in the $authinfo hash that will affect the way the CAS verifies credentials. See the documentation for Authen::CAS::Client for more on the 'renew', 'gateway' and 'pgtUrl' parameters.

BUGS

None are known at this time, but if you find one, please feel free to submit a report to the author.

SEE ALSO

Authen::CAS::Client

Catalyst::Plugin::Authentication

AUTHOR

jason hord <pravus@cpan.org>

with contributions from:

Kevin L. Kane <kkane@cpan.org>

COPYRIGHT

Copyright (c) 2010, jason hord

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.