1
|
Introduction
|
2
|
============
|
3
|
|
4
|
Central Authentication Services (CAS) is a commonly used Single Sign-On
|
5
|
protocol used by many universities and large organizations. For a brief
|
6
|
introduction, please see the CAS website: https://www.apereo.org/projects/cas
|
7
|
|
8
|
The Drupal CAS project has two modules:
|
9
|
|
10
|
* CAS:
|
11
|
Drupal acts as a CAS client, allowing users to authenticate with a
|
12
|
separate single sign-on CAS server.
|
13
|
|
14
|
* CAS Server:
|
15
|
Drupal acts as a CAS server.
|
16
|
|
17
|
Do NOT enable both modules at the same time, as it may lead to unpredictable
|
18
|
results.
|
19
|
|
20
|
The following README.txt covers the CAS module only. If you are interested in
|
21
|
the CAS Server module, please see README_SERVER.txt
|
22
|
|
23
|
Requirements
|
24
|
============
|
25
|
PHP 5 with the following extensions:
|
26
|
curl, openssl, dom, zlib, and xml
|
27
|
phpCAS version 1.0.0 or later.
|
28
|
|
29
|
Installation
|
30
|
============
|
31
|
|
32
|
* Place the cas folder in your Drupal modules directory.
|
33
|
|
34
|
* Download phpCAS from https://wiki.jasig.org/display/CASC/phpCAS. You will
|
35
|
need version 1.3.2 or later (1.3.3 for CAS 3.0 support). The most recent
|
36
|
release is available at https://developer.jasig.org/cas-clients/php/current.tgz
|
37
|
|
38
|
* There are several locations you can install the phpCAS library.
|
39
|
|
40
|
1. Module directory installation. This means installing the library folder
|
41
|
under the modules directory, so that the file
|
42
|
sites/<site>/modules/cas/CAS/CAS.php exists.
|
43
|
|
44
|
2. System wide installation. See the phpCAS installation guide, currently at
|
45
|
https://wiki.jasig.org/display/CASC/phpCAS+installation+guide
|
46
|
|
47
|
3. Libraries API installation. Install and enable the Libraries API module,
|
48
|
available at http://drupal.org/project/libraries. Then extract phpCAS so
|
49
|
that sites/<site>/libraries/CAS/CAS.php exists. For example:
|
50
|
$ cd sites/all/libraries
|
51
|
$ curl https://developer.jasig.org/cas-clients/php/current.tgz | tar xz
|
52
|
$ mv CAS-* CAS
|
53
|
|
54
|
* Go to Administer > Modules and enable this module.
|
55
|
|
56
|
* Go to Administer > Configuration > People > CAS to configure the CAS module.
|
57
|
Depending on where and how you installed the phpCAS library, you may need
|
58
|
to configure the path to CAS.php. The current library version will be
|
59
|
displayed if the library is found.
|
60
|
|
61
|
Configuration & Workflow
|
62
|
========================
|
63
|
|
64
|
For the purposes of this example, assume the following configuration:
|
65
|
* https://auth.example.com/cas - Your organization's CAS server
|
66
|
* http://site.example.com/ - This Drupal site using the CAS module
|
67
|
|
68
|
Configure the CAS module:
|
69
|
* Log in to the Drupal site and navigate to Admin > Configuration > People >
|
70
|
Central Authentication Services.
|
71
|
* Point the CAS module at the CAS server:
|
72
|
- Hostname: auth.example.com
|
73
|
- Port: 443
|
74
|
- URI: /cas
|
75
|
* Configure user accounts:
|
76
|
- Decide if you want to automatically create Drupal user accounts for each
|
77
|
CAS-authenticated user. If you leave this option deselected, you will
|
78
|
have to manually add a paired Drupal account for every one of your users
|
79
|
in advance.
|
80
|
- Hide the Drupal password field if your users will never know (or need to
|
81
|
know) their Drupal password.
|
82
|
* Configure the login form(s):
|
83
|
- There are four ways that a user can start the CAS authentication
|
84
|
process:
|
85
|
1. Visit http://site.example.com/cas
|
86
|
This option is always available and is good for embedding a text
|
87
|
"Login" link in your theme. (See the note to themers below).
|
88
|
|
89
|
2. Click on a CAS Login menu link.
|
90
|
The menu item is disabled by default, but may be enabled in
|
91
|
Admin > Structure > Menus. You should find the link in the
|
92
|
"Navigation" menu.
|
93
|
|
94
|
3. Select the CAS login option on the Drupal login form.
|
95
|
The CAS login option needs to be added to the login form in the
|
96
|
CAS settings.
|
97
|
|
98
|
4. Use the CAS login block.
|
99
|
The CAS login block may be enabled in Admin > Structure > Blocks.
|
100
|
|
101
|
Note to Themers
|
102
|
===============
|
103
|
|
104
|
You may want to include a text CAS "Login" link in your theme. If you simply
|
105
|
link to "/cas", you will find that your users are redirected to the site
|
106
|
frontpage after they are authenticated. To redirect your users to the page
|
107
|
they were previously on, instead use:
|
108
|
|
109
|
<?php
|
110
|
print l(t('Login'), 'cas', array('query' => drupal_get_destination()));
|
111
|
?>
|
112
|
|
113
|
Upgrading from 6.x-2.x / Associating CAS usernames with Drupal users
|
114
|
=====================================================================
|
115
|
|
116
|
The following options have been depreciated:
|
117
|
* "Is Drupal also the CAS user repository?"
|
118
|
* "If Drupal is not the user repository, should CAS hijack users with the same name?"
|
119
|
|
120
|
The CAS module uses a lookup table (cas_user) to associate CAS usernames with
|
121
|
their corresponding Drupal user ids. The depreciated options bypassed this
|
122
|
lookup table and let users log in if their CAS username matched their Drupal
|
123
|
name. The update.php script has automatically inserted entries into the lookup
|
124
|
table so that your users will continue to be able to log in as before.
|
125
|
|
126
|
You can see the results of the update script and manage CAS usernames on the
|
127
|
"Administration >> People" (admin/people) page. A new column displays CAS
|
128
|
usernames, and the bulk operations drop-down includes options for rapidly
|
129
|
creating and removing CAS usernames. The "Create CAS username" option will
|
130
|
assign a CAS username to each selected account that matches their Drupal name.
|
131
|
The "Remove CAS usernames" option will remove all CAS usernames from the
|
132
|
selected accounts. (Note: This will not appear if the Admin_Views module is used,
|
133
|
as it replaces the built-in People administration screen with a View)
|
134
|
|
135
|
API Changes Since 6.x-2.x
|
136
|
=========================
|
137
|
The hooks hook_auth_name() and hook_auth_filter() were combined and renamed
|
138
|
to hook_cas_user_alter(). See cas.api.php.
|
139
|
|
140
|
Testing
|
141
|
=======
|
142
|
The CAS module comes with built-in test routines. To enable testing on a
|
143
|
development site, enable the 'Testing' module. Then navigate to Admin >
|
144
|
Configuration > Development > Testing. The CAS test routines are available
|
145
|
under "Central Authentication Service".
|
146
|
|
147
|
Note, the CAS test routines will automatically download phpCAS from the JASIG
|
148
|
website, to ensure a version compatible with the test routines, and so that
|
149
|
the tests may run successfully on qa.drupal.org.
|