mirror of https://github.com/jacekkow/uphpCAS
view | history | commit | commitdiff
Jacek Kowalski
2015-09-06 7ee2b268d4ca2e672b1c1e6599c8829321f21b91
commit | author | age
36cae3 1 # uphpCAS
JK 2
3 Simple PHP library for CAS authentication
4
7ee2b2 5 [![Build Status](https://travis-ci.org/jacekkow/uphpCAS.svg?branch=master)](https://travis-ci.org/jacekkow/uphpCAS)
JK 6
36cae3 7 ## Introduction
JK 8
9 This library intends to be a replacement for overly complex
10 [phpCAS](https://wiki.jasig.org/display/casc/phpcas) library.
11
12 It only supports basic [CAS protocol](http://jasig.github.io/cas/4.0.x/protocol/CAS-Protocol.html),
13 without proxying capabilities, which is enough for website authentication.
14
15 ## Usage
16
17 ### Composer
18
19 1. Add jacekkow/uphpcas dependency:
20     
21     ```bash
22     composer require jacekkow/uphpcas
23     ```
24
25 1. Include autoloader in your application:
26     
27     ```php
28     <?php
29     require_once(__DIR__ . '/vendor/autoload.php');
30     ```
31
32 1. See the usage examples below
33
34 ### Raw usage
35
36 1. Download [uphpCAS.php](https://raw.githubusercontent.com/jacekkow/uphpCAS/master/uphpCAS.php)
37 1. Include it in your application:
38     
39     ```php
40     <?php
41     require_once(__DIR__ . '/uphpCAS.php');
42     ```
43
44 1. See the usage examples below
45
46 ## Examples
47
48 ### Require authentication
49
50 To require authentication to access the page:
51
52 ```php
53 <?php
54 require_once('uphpCAS.php');
55
56 try {
57     $cas = new uphpCAS('https://cas.server.local/cas');
58     $user = $cas->authenticate();
59     
60     echo 'Authenticated as '.$user->user;
61 } catch(Exception $e) {
62     echo 'Jasig authentication failed: '.$e->getMessage();
63     die();
64 }
65 ```
66
67 ### Login and logout pages
68
69 index.php:
70
71 ```php
72 <?php
73 require_once('uphpCAS.php');
74
75 $cas = new uphpCAS();
76 if($cas->isAuthenticated()) {
77     $user = $cas->authenticate();
78     echo 'Authenticated as '.$user->user;
79 } else {
80     echo 'Not authenticated. <a href="login.php">Log in</a>';
81 }
82 ```
83
84 login.php:
85
86 ```php
87 <?php
88 require_once('uphpCAS.php');
89
90 try {
91     $cas = new uphpCAS('https://cas.server.local/cas');
92     $user = $cas->authenticate();
93     
94     header('Location: index.php');
95 } catch(Exception $e) {
96     echo 'Jasig authentication failed: '.$e->getMessage();
97     die();
98 }
99 ```
100
101 logout.php:
102
103 ```php
104 <?php
105 require_once('uphpCAS.php');
106
107 try {
108     $cas = new uphpCAS('https://cas.server.local/cas');
109     $user = $cas->logout();
110 } catch(Exception $e) {
111     echo 'Jasig authentication failed: '.$e->getMessage();
112     die();
113 }
114 ```
115
116 ## Common issues
117
118 ### Invalid redirection from CAS server
119
120 By default uphpCAS tries to guess correct URL to pass to CAS server
121 as a "service" parameter using values from $_SERVER superglobal
122 (see getCurrentUrl() method). This URL is used by CAS server
123 to redirect user back to the application after successful CAS login.
124
125 If this guess is incorrect, eg. when the server is behind proxy,
126 you can override it using setServiceUrl() method:
127
128 ```php
129 $cas = new uphpCAS('https://cas.server.local/cas');
130 $cas->setServiceUrl('https://service.local/subpage');
131 ```
132
133 or second argument of the constructor:
134
135 ```php
136 $cas = new uphpCAS('https://cas.server.local/cas'),
137     'https://service.local/subpage');
138 ```
139
140 ### HTTP POST issues
141
142 The standard method of passing "ticket" from CAS server to application
143 is by HTTP GET method. To avoid having additional "ticket" parameter
144 in the URL on single-page apps, which can expire and cause uphpCAS
145 to throw exception, this library uses POST method by default.
146
147 You can change the method back to HTTP GET with setMethod():
148
149 ```php
150 $cas = new uphpCAS('https://cas.server.local/cas');
151 $cas->setMethod('GET');
152 ```
153
154 ### CAS over HTTPS
155
156 This library enforces CAS certificate validation. The hostname
157 of the CAS server must match the one in provided SSL certificate.
158 Also the certificate must be signed by CA included in CA store
159 (or self-signed - then the certificate itself must be included).
160 By default it looks for CA store at:
161
162 - /etc/ssl/certs/ca-certificates.crt
163 - /etc/ssl/certs/ca-bundle.crt
164 - /etc/pki/tls/certs/ca-bundle.crt
165
166 You can change path to CA store file using setCaFile() method:
167
168 ```php
169 $cas = new uphpCAS('https://cas.server.local/cas');
170 $cas->setCaFile('./localStore.pem');
171 ```