USAGE for manage_users_from_ldap.sh v1.4.4: manage_users_from_ldap.sh -i -lc -ga -gr -gw [-gA] [-c] [-d] [-L ] [-si] [-v] [-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 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 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 ' 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 @, 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 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.