crm.fsf.org/20131203/files/sites/all/modules-new/cas/README.txt

   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 Jasig website: http://www.jasig.org/cas/about
   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 http://downloads.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 http://downloads.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.
 133
 134 API Changes Since 6.x-2.x
 135 =========================
 136 The hooks hook_auth_name() and hook_auth_filter() were combined and renamed
 137 to hook_cas_user_alter(). See cas.api.php.
 138
 139 Testing
 140 =======
 141 The CAS module comes with built-in test routines. To enable testing on a
 142 development site, enable the 'Testing' module. Then navigate to Admin >
 143 Configuration > Development > Testing. The CAS test routines are available
 144 under "Central Authentication Service".
 145
 146 Note, the CAS test routines will automatically download phpCAS from the JASIG
 147 website, to ensure a version compatible with the test routines, and so that
 148 the tests may run successfully on qa.drupal.org.