Project

General

Profile

Paste
Download (4.72 KB) Statistics
| Branch: | Revision:

root / drupal7 / sites / all / modules / cas / cas.api.php @ 38c269d5

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 name is used to lookup existing local Drupal
17
 * CAS accounts via the {cas_user} mapping table. If the user does not exist
18
 * locally, and automatic registration is enabled, this name will be also 
19
 * be as the local Drupal user account name that's created.
20
 *
21
 * The 'login' parameter controls whether the user is able to login. By
22
 * default this will be set to TRUE, but modules may set this flag to FALSE
23
 * to deny the user login access. For example, one might want to only allow
24
 * login access to members of a certain LDAP group. This verification is in
25
 * addition to the standard feature which lets you block users.
26
 *
27
 * The 'register' parameter controls whether an account should be created if
28
 * the user does not already have a Drupal account. Defaults to the value of
29
 * "Should Drupal user accounts be automatically created?" in the CAS module
30
 * settings. This setting is ignored if 'login' is set to FALSE.
31
 *
32
 * If multiple modules implement this hook, the values set by the last module
33
 * to execute this hook will be used. Therefore, it is good practice to only
34
 * set the 'login' and 'register' flags to FALSE, rather than the output of
35
 * a function. This prevents accidentally allowing a user to login when another
36
 * module had already denied access.
37
 *
38
 * @param $cas_user
39
 *   An associative array, with the following keys:
40
 *   - 'name': The CAS machine-readable user name.
41
 *   - 'login': If TRUE, the user will be allowed to login to an existing
42
 *     Drupal account.
43
 *   - 'register': If TRUE, the user will be allowed to register a Drupal
44
 *     account if one does not already exist. If 'login' is FALSE, this
45
 *     setting will be ignored.
46
 *   - 'attributes': If phpCAS is new enough to support getAttributes and the
47
 *     CAS server supports SAML attributes, this consists of an associative
48
 *     array of attribute names and values; otherwise it is an empty array.
49
 */
50
function hook_cas_user_alter(&$cas_user) {
51
  // Alter the CAS username. The CAS server returned a compound name like
52
  //   it:johndoe:10.10.1.2:200805064255
53
  // and so we extract the actual user name of 'johndoe'.
54
  $parts = explode(':', $cas_user['name'], 3);
55
  $cas_user['name'] = $parts[1];
56

    
57
  // Allow logins only for users in a certain LDAP group.
58
  if (!_ldap_is_member_group($cas_user['name'], 'admins')) {
59
    $cas_user['login'] = FALSE;
60
  }
61

    
62
  // Allow registrations only for a certain class of users.
63
  if (!_ldap_user_has_home_directory($cas_user['name'])) {
64
    $cas_user['register'] = FALSE;
65
  }
66
}
67

    
68
/**
69
 * A CAS user has authenticated and the login is about to be finalized.
70
 *
71
 * This allows modules to react to a CAS user logging in and alter their
72
 * account properties. For example, modules may want to synchronize Drupal
73
 * user roles or profile information with LDAP properties.
74
 *
75
 * If you would like to synchronize information only for new accounts, you may
76
 * examine the value of $account->login which will be 0 if the user has never
77
 * logged in before.
78
 *
79
 * The 'cas_user' key in $edit contains all information returned from
80
 * hook_cas_user_alter().
81
 *
82
 * The CAS module promises to call user_save() and user_login_finalize() with
83
 * this $edit data.
84
 *
85
 * @param $edit
86
 *   An array of values corresponding to the Drupal user to be created.
87
 * @param $account
88
 *   A Druapl user object.
89
 */
90
function hook_cas_user_presave(&$edit, $account) {
91
  $cas_name = $edit['cas_user']['name'];
92

    
93
  // Look up the user's real name using LDAP.
94
  $ldap_connection = ldap_connect('ldap.example.com', 389);
95
  $ldap_result = ldap_search($ldap_connection, 'ou=people', 'uid=' . $cas_name, array('cn'), 0, 1);
96
  $entries = ldap_get_entries($ldap_connection, $ldap_result);
97
  $attributes = $entries[0];
98

    
99
  if (!empty($attributes['cn'])) {
100
    $edit['name'] = $attributes['cn'];
101
  }
102
}
103

    
104
/**
105
 * Modify phpCAS authentication properties.
106
 *
107
 * This is called after phpCAS has been configured with the basic server
108
 * properties, but before phpCAS::forceAuthentication() is called.
109
 *
110
 * Users will generally not need to implement this hook, as most phpCAS
111
 * configuration options are already provided in the CAS module UI.
112
 *
113
 * There are no parameters, instead the module should directly call the
114
 * functions in the phpCAS namespace.
115
 */
116
function hook_cas_phpcas_alter() {
117
  // Set a custom server login URL.
118
  phpCAS::setServerLoginURL('https://login.example.com/cas/login');
119
}