Introduction
============

Central Authentication Services (CAS) is a commonly used Single Sign-On
protocol used by many universities and large organizations. For a brief
introduction, please see the Jasig website: http://www.jasig.org/cas/about

The Drupal CAS project has two modules:

 * CAS:
     Drupal acts as a CAS client, allowing users to authenticate with a
     separate single sign-on CAS server.

 * CAS Server:
     Drupal acts as a CAS server.

Do NOT enable both modules at the same time, as it may lead to unpredictable
results.

The following README.txt covers the CAS module only. If you are interested in
the CAS Server module, please see README_SERVER.txt

Requirements
============
PHP 5 with the following modules:
  curl, openssl, dom, zlib, and xml
phpCAS version 1.0.0 or later.

Installation
============

* Place the cas folder in your Drupal modules directory.

* Download phpCAS from https://wiki.jasig.org/display/CASC/phpCAS. You will
  need version 1.0.0 or later. The most recent release is available at
  http://downloads.jasig.org/cas-clients/php/current.tgz

* There are several locations you can install the phpCAS library.

  1. Module directory installation. This means installing the library folder
     under the moduels directory, so that the file
     sites/<site>/modules/cas/CAS/CAS.php exists.

  2. System wide installation. See the phpCAS installation guide, currently at
     https://wiki.jasig.org/display/CASC/phpCAS+installation+guide

  3. Libraries API installation. Install and enable the Libraries API module,
     available at http://drupal.org/project/libraries. Then extract phpCAS so
     that sites/<site>/libraries/CAS/CAS.php exists. For example:
       $ cd sites/all/libraries
       $ curl http://downloads.jasig.org/cas-clients/php/current.tgz | tar xz
       $ mv CAS-* CAS

* Go to Administer > Modules and enable this module.

* Go to Administer > Configuration > People > CAS to configure the CAS module.
  Depending on where and how you installed the phpCAS library, you may need
  to configure the path to CAS.php. The current library version will be
  displayed if the library is found.

Configuration & Workflow
========================

For the purposes of this example, assume the following configuration:
 * https://auth.example.com/cas - Your organization's CAS server
 * http://site.example.com/ - This Drupal site using the CAS module

Configure the CAS module:
 * Log in to the Drupal site and navigate to Admin > Configuration > People >
   Central Authentication Services.
 * Point the CAS module at the CAS server:
     - Hostname: auth.example.com
     - Port: 443
     - URI: /cas
 * Configure user accounts:
     - Decide if you want to automatically create Drupal user accounts for each
       CAS-authenticated user. If you leave this option deselected, you will
       have to manually add a paired Drupal account for every one of your users
       in advance.
     - Hide the Drupal password field if your users will never know (or need to
       know) their Drupal password.
 * Configure the login form(s):
     - There are four ways that a user can start the CAS authentication
       process:
         1. Visit http://site.example.com/cas
              This option is always available and is good for embedding a text
              "Login" link in your theme. (See the note to themers below).

         2. Click on a CAS Login menu link.
              The menu item is disabled by default, but may be enabled in
              Admin > Structure > Menus. You should find the link in the
              "Navigation" menu.

         3. Select the CAS login option on the Drupal login form.
              The CAS login option needs to be added to the login form in the
              CAS settings.

         4. Use the CAS login block.
              The CAS login block may be enabled in Admin > Structure > Blocks.

Note to Themers
===============

You may want to include a text CAS "Login" link in your theme. If you simply
link to "/cas", you will find that your users are redirected to the site
frontpage after they are authenticated. To redirect your users to the page
they were previously on, instead use:

  <?php
    print l(t('Login'), 'cas', array('query' => drupal_get_destination()));
  ?>

Upgrading from 6.x-2.x / Associating CAS usernames with Drupal users
=====================================================================

The following options have been depreciated:
* "Is Drupal also the CAS user repository?"
* "If Drupal is not the user repository, should CAS hijack users with the same name?"

The CAS module uses a lookup table (cas_user) to associate CAS usernames with
their corresponding Drupal user ids. The depreciated options bypassed this
lookup table and let users log in if their CAS username matched their Drupal
name. The update.php script has automatically inserted entries into the lookup
table so that your users will continue to be able to log in as before.

You can see the results of the update script and manage CAS usernames on the
"Administration >> People" (admin/people) page. A new column displays CAS
usernames, and the bulk operations drop-down includes options for rapidly
creating and removing CAS usernames. The "Create CAS username" option will
assign a CAS username to each selected account that matches their Drupal name.
The "Remove CAS usernames" option will remove all CAS usernames from the
selected accounts.

API Changes Since 6.x-2.x
=========================
The hooks hook_auth_name() and hook_auth_filter() were combined and renamed
to hook_cas_user_alter(). See cas.api.php.

Testing
=======
The CAS module comes with built-in test routines. To enable testing on a
development site, enable the 'Testing' module. Then navigate to Admin >
Configuration > Development > Testing. The CAS test routines are available
under "Central Authentication Service".

Note, the CAS test routines will automatically download phpCAS from the JASIG
website, to ensure a version compatible with the test routines, and so that
the tests may run successfully on qa.drupal.org.