README

Simple PHP library for CAS authentication

Introduction

This library intends to be a replacement for overly complex phpCAS library.

It only supports basic CAS protocol, without proxying capabilities, which is enough for website authentication.

Usage

Composer

Add jacekkow/uphpcas dependency:
```
composer require jacekkow/uphpcas
```

Include autoloader in your application:

<?php
require_once(__DIR__ . '/vendor/autoload.php');

See the usage examples below

Raw usage

Download uphpCAS.php

Include it in your application:

<?php
require_once(__DIR__ . '/uphpCAS.php');

See the usage examples below

Examples

Require authentication

To require authentication to access the page:

<?php
require_once('uphpCAS.php');

try {
    $cas = new uphpCAS('https://cas.server.local/cas');
    $user = $cas->authenticate();
    
    echo 'Authenticated as '.$user->user;
} catch(Exception $e) {
    echo 'Jasig authentication failed: '.$e->getMessage();
    die();
}

Login and logout pages

index.php:

<?php
require_once('uphpCAS.php');

$cas = new uphpCAS();
if($cas->isAuthenticated()) {
    $user = $cas->authenticate();
    echo 'Authenticated as '.$user->user;
} else {
    echo 'Not authenticated. <a href="login.php">Log in</a>';
}

<?php
require_once('uphpCAS.php');

try {
    $cas = new uphpCAS('https://cas.server.local/cas');
    $user = $cas->authenticate();
    
    header('Location: index.php');
} catch(Exception $e) {
    echo 'Jasig authentication failed: '.$e->getMessage();
    die();
}

logout.php:

<?php
require_once('uphpCAS.php');

try {
    $cas = new uphpCAS('https://cas.server.local/cas');
    $user = $cas->logout();
} catch(Exception $e) {
    echo 'Jasig authentication failed: '.$e->getMessage();
    die();
}

Common issues

Invalid redirection from CAS server

By default uphpCAS tries to guess correct URL to pass to CAS server as a "service" parameter using values from $_SERVER superglobal (see getCurrentUrl() method). This URL is used by CAS server to redirect user back to the application after successful CAS login.

If this guess is incorrect, eg. when the server is behind proxy, you can override it using setServiceUrl() method:

$cas = new uphpCAS('https://cas.server.local/cas');
$cas->setServiceUrl('https://service.local/subpage');

or second argument of the constructor:

$cas = new uphpCAS('https://cas.server.local/cas',
	'https://service.local/subpage');

HTTP POST issues

The standard method of passing "ticket" from CAS server to application is by HTTP GET method. To avoid having additional "ticket" parameter in the URL on single-page apps, which can expire and cause uphpCAS to throw exception, this library uses POST method by default.

You can change the method back to HTTP GET with setMethod():

$cas = new uphpCAS('https://cas.server.local/cas');
$cas->setMethod('GET');

CAS over HTTPS

This library enforces CAS certificate validation. The hostname of the CAS server must match the one in provided SSL certificate. Also the certificate must be signed by CA included in CA store (or self-signed - then the certificate itself must be included). By default it looks for CA store at:

/etc/ssl/certs/ca-certificates.crt
/etc/ssl/certs/ca-bundle.crt
/etc/pki/tls/certs/ca-bundle.crt

You can change path to CA store file using setCaFile() method:

$cas = new uphpCAS('https://cas.server.local/cas');
$cas->setCaFile('./localStore.pem');

jacekkow / uphpcas

Maintainers

Details