crm.fsf.org/20131203/files/sites/all/modules-old/cas/cas.api.php

   1 <?php
   2
   3 /**
   4  * @file
   5  * Documentation for CAS API.
   6  */
   7
   8 /**
   9  * Modify CAS user properties before the user is logged in.
  10  *
  11  * Allows modules to alter the CAS username and account creation permissions
  12  * after the CAS username is returned from phpCAS::getUser().
  13  *
  14  * Modules implementing this hook may wish to alter 'name' if the CAS server
  15  * returns user names which contain excess information or are not directly
  16  * machine readable. This field is not the Drupal name of the user. Instead,
  17  * this is used to load a Drupal user via the mapping in the {cas_user} table.
  18  *
  19  * The 'login' parameter controls whether the user is able to login. By
  20  * default this will be set to TRUE, but modules may set this flag to FALSE
  21  * to deny the user login access. For example, one might want to only allow
  22  * login access to members of a certain LDAP group. This verification is in
  23  * addition to the standard feature which lets you block users.
  24  *
  25  * The 'register' parameter controls whether an account should be created if
  26  * the user does not already have a Drupal account. Defaults to the value of
  27  * "Should Drupal user accounts be automatically created?" in the CAS module
  28  * settings. This setting is ignored if 'login' is set to FALSE.
  29  *
  30  * If multiple modules implement this hook, the values set by the last module
  31  * to execute this hook will be used. Therefore, it is good practice to only
  32  * set the 'login' and 'register' flags to FALSE, rather than the output of
  33  * a function. This prevents accidentally allowing a user to login when another
  34  * module had already denied access.
  35  *
  36  * @param $cas_user
  37  *   An associative array, with the following keys:
  38  *   - 'name': The CAS machine-readable user name.
  39  *   - 'login': If TRUE, the user will be allowed to login to an existing
  40  *     Drupal account.
  41  *   - 'register': If TRUE, the user will be allowed to register a Drupal
  42  *     account if one does not already exist. If 'login' is FALSE, this
  43  *     setting will be ignored.
  44  *   - 'attributes': If phpCAS is new enough to support getAttributes and the
  45  *     CAS server supports SAML attributes, this consists of an associative
  46  *     array of attribute names and values; otherwise it is an empty array.
  47  */
  48 function hook_cas_user_alter(&$cas_user) {
  49   // Alter the CAS username. The CAS server returned a compound name like
  50   //   it:johndoe:10.10.1.2:200805064255
  51   // and so we extract the actual user name of 'johndoe'.
  52   $parts = explode(':', $cas_user['name'], 3);
  53   $cas_user['name'] = $parts[1];
  54
  55   // Allow logins only for users in a certain LDAP group.
  56   if (!_ldap_is_member_group($cas_user['name'], 'admins')) {
  57     $cas_user['login'] = FALSE;
  58   }
  59
  60   // Allow registrations only for a certain class of users.
  61   if (!_ldap_user_has_home_directory($cas_user['name'])) {
  62     $cas_user['register'] = FALSE;
  63   }
  64 }
  65
  66 /**
  67  * A CAS user has authenticated and the login is about to be finalized.
  68  *
  69  * This allows modules to react to a CAS user logging in and alter their
  70  * account properties. For example, modules may want to synchronize Drupal
  71  * user roles or profile information with LDAP properties.
  72  *
  73  * If you would like to synchronize information only for new accounts, you may
  74  * examine the value of $account->login which will be 0 if the user has never
  75  * logged in before.
  76  *
  77  * The 'cas_user' key in $edit contains all information returned from
  78  * hook_cas_user_alter().
  79  *
  80  * The CAS module promises to call user_save() and user_login_finalize() with
  81  * this $edit data.
  82  *
  83  * @param $edit
  84  *   An array of values corresponding to the Drupal user to be created.
  85  * @param $account
  86  *   A Druapl user object.
  87  */
  88 function hook_cas_user_presave(&$edit, $account) {
  89   $cas_name = $edit['cas_user']['name'];
  90
  91   // Look up the user's real name using LDAP.
  92   $ldap_connection = ldap_connect('ldap.example.com', 389);
  93   $ldap_result = ldap_search($ldap_connection, 'ou=people', 'uid=' . $cas_name, array('cn'), 0, 1);
  94   $entries = ldap_get_entries($ldap_connection, $ldap_result);
  95   $attributes = $entries[0];
  96
  97   if (!empty($attributes['cn'])) {
  98     $edit['name'] = $attributes['cn'];
  99   }
 100 }
 101
 102 /**
 103  * Modify phpCAS authentication properties.
 104  *
 105  * This is called after phpCAS has been configured with the basic server
 106  * properties, but before phpCAS::forceAuthentication() is called.
 107  *
 108  * Users will generally not need to implement this hook, as most phpCAS
 109  * configuration options are already provided in the CAS module UI.
 110  *
 111  * There are no parameters, instead the module should directly call the
 112  * functions in the phpCAS namespace.
 113  */
 114 function hook_cas_phpcas_alter() {
 115   // Set a custom server login URL.
 116   phpCAS::setServerLoginURL('https://login.example.com/cas/login');
 117 }