README

CASpian is an authentication library for Central Authentication Service (CAS) 3.0 protocol.

CASpian is inspired by the original apereo/phpCAS, but designed to be more flexible and easier to use for our needs.

Installation

composer require aurora/caspian

Usage

For the most part, CASpian is a drop-in replacement for phpCAS, with only slight differences in the method names and parameters.

The first step is to decide on a storage backend for the CASpian client. The storage backend is used to store the CAS session information.

Storage Backends

CASpian comes with two storage backends out of the box: CASPian\Storage\SessionStorageProvider and CASPian\Storage\RedisStorageProvider which use PHP's $_SESSION and Redis respectively.

You can use the CASPian\Storage\SessionStorageProvider by calling the CASPian\Caspian::sessionProvider() method.

$storage = CASPian\Caspian::sessionProvider();

You can use the CASPian\Storage\RedisStorageProvider by calling the CASPian\Caspian::redisProvider() method.

// For redis servers with no authentication
$storage = CASPian\Caspian::redisProvider('localhost', 6379);

// For redis servers with password authentication
$storage = CASPian\Caspian::redisProvider('localhost', 6379, 'password');

You can also implement your own storage backend by implementing the CASPian\CaspianStorageProvider interface.

Client Setup

Once you have a storage backend, you can set up the CASpian client by calling the CASPian\Caspian::client() method.

// By default, the client will be created with no logging
\CASpian\Caspian::client('https://cas.example.edu', 'https://www.service.com', $storage);

// You may pass a PSR-3 logger to the client to enable logging
// Here we use Monolog to log to stdout at the DEBUG level
$logger = new Monolog\Logger('caspian');
$logger->pushHandler(new Monolog\Handler\StreamHandler('php://stdout', Monolog\Logger::DEBUG));
\CASpian\Caspian::client('https://cas.example.edu', 'https://www.service.com', $storage, $logger);

There are also some configuration options that you can set on the client.

\CASpian\Caspian::disableRemoveTicketRedirect(); // Disables removing the ticket from the URL after a successful login

Using the Client

Once the client is set up, here are some of the methods you can use to authenticate users.

The isAuthenticated() method checks if the user is authenticated.

if (\CASpian\Caspian::isAuthenticated()) {
    // User is authenticated
    echo 'Hello, ' . \CASpian\Caspian::getUser();
}

The forceAuthentication() method ensures that any code that follows it will only be executed if the user is authenticated. If the user is not authenticated, the user will be redirected to the CAS server to log in.

\CASpian\Caspian::forceAuthentication();

// Code that should only be executed if the user is authenticated
echo 'Hello, ' . \CASpian\Caspian::getUser();

The logout() method logs the user out and redirects them to the CAS server to log out. You can also pass a URL to redirect the user to after logging out. If you want to log the user out and stay on the same page, you can pass the current URL as the redirect URL. After the logout() method is called, code execution will stop.

if (isset($_GET['logout'])) {
    \CASpian\Caspian::logout();
}

// Optionally, you can pass a URL to redirect the user to after logging out
if (isset($_GET['logout'])) {
    \CASpian\Caspian::logout('https://www.example.com');
}

The getUser() method returns the username of the authenticated user. If the user is not authenticated, it will return null. Note: you must call isAuthenticated() or forceAuthentication() at some point before calling getUser() otherwise the existing session may not be loaded into the client.

\CASpian\Caspian::forceAuthentication();

echo 'Hello, ' . \CASpian\Caspian::getUser();

The getAttributes() method returns an array of attributes for the authenticated user if configured by the CAS server. If the user is not authenticated, it will return an empty array. Note: you must call isAuthenticated() or forceAuthentication() at some point before calling getAttributes() otherwise the existing session may not be loaded into the client.

\CASpian\Caspian::forceAuthentication();

$attributes = \CASpian\Caspian::getAttributes();
echo 'Hello, ' . $attributes['givenName'];

// You can also get a specific attribute
echo 'Hello, ' . \CASpian\Caspian::getAttribute('givenName');