modules/userprotect/README.txt

$Id: README.txt,v 1.7 2009/10/31 21:27:25 thehunmonkgroup Exp $

****************************************************
User Protect Module -- README

written by Chad Phillips: thehunmonkgroup at yahoo dot com
****************************************************

This module provides various editing protection for users. The protections can
be specific to a user, or applied to all users in a role. The following protections
are supported:

  -- username
  -- e-mail address
  -- password
  -- status changes
  -- roles
  -- cancellation
  -- OpenID identities (both adding and deleting) 
  -- all edits (any accessed via user/X/edit)

When a protection is enabled for a specified user (or the protection is enabled
because the user belongs to a role that has the protection), it prevents the
editing operation in question that anyone might try to perform on the
user -- unless an administrator who is permitted to bypass the protection is
editing the specified user. The module will protect fields by disabling them at
user/X/edit.

User administrators may be configured to bypass specified protections, on
either a global or per-administrator basis.

These protections are valid both when trying to edit the user directly from
their user/X/edit page, or using the mass user editing operations.

The module also provides protection at the paths user/X/edit and user/X/cancel,
should anyone try to visit those paths directly.

Note: this module is compatible with the RoleAssign module.

SETTINGS:
At Administer -> Configuration and modules -> People and permissions -> User
Protect, you'll find the settings for the module. When the module is initially
enabled, the default settings are such:

  -- User administrators bypass all protections.
  -- The root user specifically bypasses all protections.
  -- The anonymous user (uid 0) and root user (uid 1) are protected from all
     edits, cancellation, and OpenID operations.
  -- All role protections are disabled.
  -- The 'change own e-mail', 'change own password', and 'change own openid'
     permissions are enabled for authenticated users in the User Protect section
     at Administer -> Configuration and modules -> People and permissions -> 
     Permissions.

This effectively amounts to no protections. It is suggested that you turn off
as many default administrator bypass settings as possible, and set bypass
settings for specific user administrators--this allows you to take advantage
of the status, roles, cancellation, openid and edit protections in a meaningful
way. Because of the per-user bypass/protection settings for the anonymous and
root user, this will also begin protecting those users, without compromising
the root user's access to the entire site.

Important note: In order to protect a user from cancellation (by visiting
user/X/cancel directly) and/or OpenID edits (by visiting user/X/openid
directly), you must enable the 'cancel' and/or 'openid' protection specifically.
Enabling 'all account edits' does not enable these protections!

Also note that this module only provides protection against actions via the
website interface--operations that a module takes directly are not protected!
This module should play well with other contributed modules, but there is no
guarantee that all protections will remain intact if you install modules outside
of the drupal core installation.

ADDING PROTECTIONS FOR A SINGLE USER:
This is done at Administer -> Configuration and modules -> People and
permissions -> User Protect -> Protected users.  Any time a user is added for
protection, they will initially receive the default protections enabled at
Administer -> Configuration and modules -> People and permissions -> User
Protect -> Protection defaults.

ADDING PROTECTIONS FOR ROLES:
This is done at Administer -> Configuration and modules -> People and
permissions -> User Protect -> Protected roles.  Be cautious about adding
protections by role, or you can lock out users from things unintentionally!

In particular, note the if you enable role protections for a specific role, and
you have no bypasses enabled, you've effectively locked out any role editing
for that role by anybody, unless you come back to the settings page and disable
the role protection!

ADDING ADMINISTRATOR BYPASS RULES:
One of the more powerful features of the module are the administrator bypass
settings. Any user that has been granted the 'administer users' permission can
be configured to bypass any protection, either via the default administrator
bypass settings at 
Administer -> Configuration and modules -> People and permissions -> User
Protect -> Protection defaults, or via a per-administrator setting at
Administer -> Configuration and modules -> People and permissions -> User
Protect -> Administrator bypass. If a bypass is enabled for a user
administrator, they will be given editing rights on that protection regardless
if it is enabled for a single user or an entire role.

Note that the per-administrator bypass settings override the default bypass
settings.

DEFAULT PROTECTION SETTINGS:
Set the default protections for newly protected users at Administer ->
Configuration and modules -> People and permissions -> User Protect ->
Protection defaults. In addition, you can enable the auto-protect feature,
which will automatically add the default protections to any newly created user
accounts, and set default bypass options for all user administrators.

HOW THE MODULE DETERMINES A PROTECTION:
In order to properly use User Protect, it's important to understand how the
module determines if a specified field is to be protected. Here is the basic
logic:

  -- If the current user is a user administrator, check if they have
     per-administrator bypass settings. If so, then check to see if they are
     allowed to bypass the protection. If so, then stop the checks and allow
     editing of the field.

  -- If not, then if the current user is a user administrator, check if the
     default administrator bypass is enabled for the protection in question. If
     so, then stop the checks and allow editing of the field.

  -- If not, check if the user is editing their own account. If so, determine
     the protections for e-mail, password, and openid by examining the User
     Protect permissions for 'change own e-mail', 'change own password' and
     'change own openid', then'continue with the rest of the checks below.

  -- If not, check if the protection is set for the individual user being
     edited. If so, then stop the checks here, and prevent editing of the field
     (this effectively means that individual protections override role
     protections).

  -- If not, then examine all the roles for the user being edited. If any of
     those roles have the protection enabled, then prevent editing of the
     field.

  -  If not, then allow the field to be edited.

Note: If a user is editing their own account, they are never protected from
editing their own username, e-mail, password or OpenID. Administrators can
still limit the ability of users to change their username via the role-based
permission at Administer -> Configuration and modules -> People and
permissions -> Permissions.

1	$Id: README.txt,v 1.7 2009/10/31 21:27:25 thehunmonkgroup Exp $
2
3	****************************************************
4	User Protect Module -- README
5
6	written by Chad Phillips: thehunmonkgroup at yahoo dot com
7	****************************************************
8
9	This module provides various editing protection for users. The protections can
10	be specific to a user, or applied to all users in a role. The following protections
11	are supported:
12
13	-- username
14	-- e-mail address
15	-- password
16	-- status changes
17	-- roles
18	-- cancellation
19	-- OpenID identities (both adding and deleting)
20	-- all edits (any accessed via user/X/edit)
21
22	When a protection is enabled for a specified user (or the protection is enabled
23	because the user belongs to a role that has the protection), it prevents the
24	editing operation in question that anyone might try to perform on the
25	user -- unless an administrator who is permitted to bypass the protection is
26	editing the specified user. The module will protect fields by disabling them at
27	user/X/edit.
28
29	User administrators may be configured to bypass specified protections, on
30	either a global or per-administrator basis.
31
32	These protections are valid both when trying to edit the user directly from
33	their user/X/edit page, or using the mass user editing operations.
34
35	The module also provides protection at the paths user/X/edit and user/X/cancel,
36	should anyone try to visit those paths directly.
37
38	Note: this module is compatible with the RoleAssign module.
39
40	SETTINGS:
41	At Administer -> Configuration and modules -> People and permissions -> User
42	Protect, you'll find the settings for the module. When the module is initially
43	enabled, the default settings are such:
44
45	-- User administrators bypass all protections.
46	-- The root user specifically bypasses all protections.
47	-- The anonymous user (uid 0) and root user (uid 1) are protected from all
48	edits, cancellation, and OpenID operations.
49	-- All role protections are disabled.
50	-- The 'change own e-mail', 'change own password', and 'change own openid'
51	permissions are enabled for authenticated users in the User Protect section
52	at Administer -> Configuration and modules -> People and permissions ->
53	Permissions.
54
55	This effectively amounts to no protections. It is suggested that you turn off
56	as many default administrator bypass settings as possible, and set bypass
57	settings for specific user administrators--this allows you to take advantage
58	of the status, roles, cancellation, openid and edit protections in a meaningful
59	way. Because of the per-user bypass/protection settings for the anonymous and
60	root user, this will also begin protecting those users, without compromising
61	the root user's access to the entire site.
62
63	Important note: In order to protect a user from cancellation (by visiting
64	user/X/cancel directly) and/or OpenID edits (by visiting user/X/openid
65	directly), you must enable the 'cancel' and/or 'openid' protection specifically.
66	Enabling 'all account edits' does not enable these protections!
67
68	Also note that this module only provides protection against actions via the
69	website interface--operations that a module takes directly are not protected!
70	This module should play well with other contributed modules, but there is no
71	guarantee that all protections will remain intact if you install modules outside
72	of the drupal core installation.
73
74	ADDING PROTECTIONS FOR A SINGLE USER:
75	This is done at Administer -> Configuration and modules -> People and
76	permissions -> User Protect -> Protected users. Any time a user is added for
77	protection, they will initially receive the default protections enabled at
78	Administer -> Configuration and modules -> People and permissions -> User
79	Protect -> Protection defaults.
80
81	ADDING PROTECTIONS FOR ROLES:
82	This is done at Administer -> Configuration and modules -> People and
83	permissions -> User Protect -> Protected roles. Be cautious about adding
84	protections by role, or you can lock out users from things unintentionally!
85
86	In particular, note the if you enable role protections for a specific role, and
87	you have no bypasses enabled, you've effectively locked out any role editing
88	for that role by anybody, unless you come back to the settings page and disable
89	the role protection!
90
91	ADDING ADMINISTRATOR BYPASS RULES:
92	One of the more powerful features of the module are the administrator bypass
93	settings. Any user that has been granted the 'administer users' permission can
94	be configured to bypass any protection, either via the default administrator
95	bypass settings at
96	Administer -> Configuration and modules -> People and permissions -> User
97	Protect -> Protection defaults, or via a per-administrator setting at
98	Administer -> Configuration and modules -> People and permissions -> User
99	Protect -> Administrator bypass. If a bypass is enabled for a user
100	administrator, they will be given editing rights on that protection regardless
101	if it is enabled for a single user or an entire role.
102
103	Note that the per-administrator bypass settings override the default bypass
104	settings.
105
106	DEFAULT PROTECTION SETTINGS:
107	Set the default protections for newly protected users at Administer ->
108	Configuration and modules -> People and permissions -> User Protect ->
109	Protection defaults. In addition, you can enable the auto-protect feature,
110	which will automatically add the default protections to any newly created user
111	accounts, and set default bypass options for all user administrators.
112
113	HOW THE MODULE DETERMINES A PROTECTION:
114	In order to properly use User Protect, it's important to understand how the
115	module determines if a specified field is to be protected. Here is the basic
116	logic:
117
118	-- If the current user is a user administrator, check if they have
119	per-administrator bypass settings. If so, then check to see if they are
120	allowed to bypass the protection. If so, then stop the checks and allow
121	editing of the field.
122
123	-- If not, then if the current user is a user administrator, check if the
124	default administrator bypass is enabled for the protection in question. If
125	so, then stop the checks and allow editing of the field.
126
127	-- If not, check if the user is editing their own account. If so, determine
128	the protections for e-mail, password, and openid by examining the User
129	Protect permissions for 'change own e-mail', 'change own password' and
130	'change own openid', then'continue with the rest of the checks below.
131
132	-- If not, check if the protection is set for the individual user being
133	edited. If so, then stop the checks here, and prevent editing of the field
134	(this effectively means that individual protections override role
135	protections).
136
137	-- If not, then examine all the roles for the user being edited. If any of
138	those roles have the protection enabled, then prevent editing of the
139	field.
140
141	- If not, then allow the field to be edited.
142
143	Note: If a user is editing their own account, they are never protected from
144	editing their own username, e-mail, password or OpenID. Administrators can
145	still limit the ability of users to change their username via the role-based
146	permission at Administer -> Configuration and modules -> People and
147	permissions -> Permissions.
148