manage_users_from_ldap.txt #9

USAGE for manage_users_from_ldap.sh v1.4.5:
 
manage_users_from_ldap.sh -i <instance> -lc <LDAPConfig> -ga <LDAPP4AdminUsersGroup> -gr <LDAPP4ReadUsersGroup> -gw <LDAPP4WriteUsersGroup> [-gA] [-c] [-d] [-L <log>] [-si] [-v<n>] [-n] [-D]

or

manage_users_from_ldap.sh [-h|-man|-V]


DESCRIPTION:
	This script provides a workflow based on various calls to the
	'p4 ldapsync' command, which support a methodolgy for
	establishing an LDAP server as the 'source of truth' for who
	should have access to a Helix Core server.

	This script can be called easily via cron.  In addition to
	using 'p4 ldapsync' to udpate groups from Perforce, this
	script adds a more comprehensive workflow for automatically
	adding and deleting users based on changes in LDAP. (Automatic
	deletion is strong discouraged, see EXAMPLES below).

	This scripts promtes a workflow with email notification for
	Helix Core admins, notifying about users to be added or removed,

	In some cases where 'p4 ldapsync -u -U' with '-u' does not work as
	expected, this script provides a workaround by creating missing
	users directly with 'p4 user' command.  This can happen if certain
	data elements in LDAP contain characters incompatible with Helix
	Core (e.g. '#' chars).

	This script wraps the 'p4 ldapsync' command, working with '-g'
	(group management) and '-u' user update modes.  It aborts the
	'p4 ldapsync' queries fails.

	The basic idea for this script is that all Helix Core users must be
	in one or more of these groups to have an account:
	* LDAPP4AdminUsersGroup
	* LDAPP4ReadUsersGroup
	* LDAPP4WriteUsersGroup
	* Non-LDAP-Users

	Having Admin, Read, and Write group enables basic access controls
	if a Protections table is crafted to reference the different groups.
	If less granularity is required, the Admin, Read, and Write groups
	can be the same group name.  The actual granting of access occurs
	in the Protections table; this scripts responsibility is to update
	the Perforce groups based ln LDAP group membership.

	It is CRITICAL that all Helix Core users that are not in LDAP
	per local policy) be added to the group Non-LDAP-Users.
	This typically includes automation users.  As an exception, user
	accounts that are only listed with the '-a' flag to 'p4 users',
	including accounts with a 'Type' value in the user spec of 'service'
	or 'operator', need not be listed. This script is, by design, unaware
	of such accounts, and will never attempt to delete them.  Such users
	always have a 'AuthMethod' value of 'perforce', and so are not going
	to be listed in LDAP.

	This script does the following:
	* Calls 'p4 ldapsync -g' to update the Perforce group Unset
	from the LDAP group of the same name.

	* Calls 'p4 ldapsync -g' to update the Perforce group Unset
	from the LDAP group of the same name.

	* Calls 'p4 ldapsync -g' to update the Perforce group Unset
	from the LDAP group of the same name.

	* Detects users missing from Perforce, i.e. if an account is listed in
	any of the groups noted above, but does not have a Perforce account.
	Missing users will be reported, and optionally added with '-c'.

	* Detects extra users in Perforce, i.e. if any exist in Perforce but are
	not listed in any of the groups noted above.  Extra users will be
	reported.  If '-d' is specified, extra users will be deleted, along
	with all of their workspaces (according to the 'Owner' field of the
	client spec).  Workspace removal is done using a command like:

	p4 client -df -Fs <workspace_name>

	These flags will blast checkouts and deleted sheled files associated
	with the workspace.  To preserve shelved files, they must be unshelved
	by another user in another workspace prior to running this script.

	Workspace removal can fail in some edge cases, such as if the user has
	files checked out to a workspace for which they are not the listed
	Owner.  Manual corrective action is necessary in these cases.  If
	workspace removal fails, user removal will fail.

WORING AROUND A SPECIFIC LDAP INCOMPATIBILITY:
	This custom script is needed in scenarios where the command
	'p4 ldapsync' does not work in '-u' (update) mode.  This can
	happen if certain data elements in LDAP contain characters
	incompatible with Perforce (e.g. '#' chars).

OPTIONS:
 -i <instance>
	Specify the SDP instance name.  If the '-i' flag is omitted, the value
	is derived from the $SDP_INSTANCE environment variable.

	If $SDP_INSTANCE is not defined, then '-i <instance>' is required.

 -lc	Specify the LDAP config.  This is required.

 -gA	Indicate that all Perforce groups with LDAP config settings are to
	be updated.  This can be useful if the Protections table is crafted
	to reference multiple Helix Core groups connected to LDAP groups.

	Only groups groups specified with required -ga, -gr, and -gw determine
	which accounts are created/deleted, or suggested for creation/removal,
	depending on usage of '-c' and '-d' flags.

 -ga	Specify the LDAP group for admin users. Required.

 -gr	Specify the LDAP group for read-only users. Required.

 -gw	Specify the LDAP group for write  users. Required.

 -c	Create users that exist in either of the two user groups mentioned
	above but which do not exist in Perforce.

	Users will be added with an Email field value of <userid>@<domain>,
	where domain is determined from the MAILFROM setting, which evaluates
	to @p4demo.com.  The FullName field is set to the same value as
	the userid, and can be adjusted by the user manually.  The AuthMethod
	will be set to whatever the default is (per the auth.default.method
	configurable).

	By default, without '-c', users to be added are reported, but no
	action is taken.

	As a safety feature, a maximum of 5 missing users will
	be added on any one invocation of this script.  To add more users,
	call this script as many times as needed.

 -d	Delete extra uses and any client specs (workspaces) for which they
	are the listed Owner.  By default, without '-d', users to be added
	are reported, but no action is taken.

	As a safety feature, a maximum of 5 extra users will
	be deleted on any one invocation of this script.  To delete more users,
	call this script as many times as needed.

 -v<n>	Set verbosity 1-5 (-v1 = quiet, -v5 = highest).

	NOTE: This script is self-logging.  That is, output displayed on the
	screen is simultaneously captured in the log file.  Do not run this
	script with redirection operators like '> log' or '2>&1', and do not
	use 'tee'.

-si	Operate silently.  All output (stdout and stderr) is redirected to the
	log only; no output appears on the terminal.
	
 -n	No-Op.  Prints certain commands instead of running them.  Some
	commands, such as the 'p4 ldapsync -g' command that does not affect
	data, are executd regardless of whether '-n' is used.  Using '-n'
	will prevent creation and removal of users even if '-c' and/or '-d'
	are used.

 -D     Set extreme debugging verbosity.

HELP OPTIONS:
 -h	Display short help message
 -man	Display man-style help message
 -V	Dispay version info for this script and its libraries.

EXAMPLES:
	The following is a sample call from 'cron', typically once per
	day:

	manage_users_from_ldap.sh -i 1 -gA -ga P4Admins -gw P4Write -gr P4Read -c
	In this example, the P4Admins, P4Write, and P4Read groups would be
	Perforce groups with 'LdapConfig' and other AD connection settings
	defined.

	This sample illustrates the preferred policy:  Use '-c' to
	automatically create users from AD, but DO NOT use '-d' to
	automatically delete users.

	Using '-c' is recommended as there is only benefit to having Perforce
	user accounts created automtically once they have been added to
	appropriate groups in LDAP indicating they are authorized to have
	Perforce Helix Core access.

	Using '-d' is STRONGLY DISCOURAGED, as it risks data loss of work-in-
	progress data from recently departed staff.  Instead, human admins
	should review the list of users suggested for removal, and delete
	them with manual processes, perhaps with coordination with managers
	or colleagues of departed staff to ensure no useful data is lost.
	For example, staff may want to review lists of workspaces and checked
	out files to see if anything valuable is left.  This sort of analysis
	is most needed in cases of sudden and/or unplanned staff departure.

	Risks of using -d include, but are not limited to:
	* Sometimes workspaces are shared by multiple users.  This script
	deletes all workspaces for which the to-be-deleted user is listed as
	the Owner based on the client spec.  Manual reivew of workspaces to
	be deleted (which this script provides when '-d' is not provided)
	gives a trail to follow to look for potential scenarios like this.
	If the departed user was helpful and helped other users create
	workspaces or created build workspaces, changing the Owner field
	is required to prevent their removal.
	* Checked out files of departed users will be forgotten about.
	While the actual contents of such files on client machines is not
	affected, the server's knowedge of those being checked out is lost
	when the user workspace is deleted on the server.
	* Shelved files will be deleted.  If they are of value, they should
	first be transferred to another user.
	* If admins make mistakes in putting users in the correct LDAP groups,
	it could cause accidental removal of active human or robot accounts
	(which might not be on LDAP).

	All this said, there are scenarios for which the '-d' flag is useful,
	and so it exists.

LDAP CONFIG:
	This script replies on the LDAP configuration working properly. This
	implies that an LDAP 'reader' account is configured in an LDAP spec,
	and that the required LDAP credentials are codified (encrypted) in
	the 'p4 ldap' spec.

	See:
	* https://www.perforce.com/manuals/p4sag/Content/P4SAG/security.ldap.auth.html
	* p4 help ldap, for ldap specs
	* p4 help group, for per-group LDAP configuration

	Comments: When crafting your LDAP configs and LDAP group configs,
	it is wise to put effort into optimizing granular seach queries,
	to optimize performance and reduce load on the LDAP server. This
	can also prevent obscure timeout failures and other scale-related
	errors.