From 36cae3ae1e2ab08346becb589a0a619bf0fa084f Mon Sep 17 00:00:00 2001
From: Jacek Kowalski <jkowalsk@student.agh.edu.pl>
Date: Sat, 05 Sep 2015 21:37:35 +0000
Subject: [PATCH] Add README

---
 README.md |  169 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 169 insertions(+), 0 deletions(-)

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a7b413a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,169 @@
+# uphpCAS
+
+Simple PHP library for CAS authentication
+
+## Introduction
+
+This library intends to be a replacement for overly complex
+[phpCAS](https://wiki.jasig.org/display/casc/phpcas) library.
+
+It only supports basic [CAS protocol](http://jasig.github.io/cas/4.0.x/protocol/CAS-Protocol.html),
+without proxying capabilities, which is enough for website authentication.
+
+## Usage
+
+### Composer
+
+1. Add jacekkow/uphpcas dependency:
+	
+	```bash
+	composer require jacekkow/uphpcas
+	```
+
+1. Include autoloader in your application:
+	
+	```php
+	<?php
+	require_once(__DIR__ . '/vendor/autoload.php');
+	```
+
+1. See the usage examples below
+
+### Raw usage
+
+1. Download [uphpCAS.php](https://raw.githubusercontent.com/jacekkow/uphpCAS/master/uphpCAS.php)
+1. Include it in your application:
+	
+	```php
+	<?php
+	require_once(__DIR__ . '/uphpCAS.php');
+	```
+
+1. See the usage examples below
+
+## Examples
+
+### Require authentication
+
+To require authentication to access the page:
+
+```php
+<?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
+<?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>';
+}
+```
+
+login.php:
+
+```php
+<?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
+<?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:
+
+```php
+$cas = new uphpCAS('https://cas.server.local/cas');
+$cas->setServiceUrl('https://service.local/subpage');
+```
+
+or second argument of the constructor:
+
+```php
+$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():
+
+```php
+$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:
+
+```php
+$cas = new uphpCAS('https://cas.server.local/cas');
+$cas->setCaFile('./localStore.pem');
+```

--
Gitblit v1.9.1