SSO_Cutover.command_summary.txt #6

USAGE for SSO_Cutover.sh v1.1.4:

SSO_Cutover.sh -g <GroupOfUsersExemptFromSSO> [-i <SDPInstance>] [-nc] [-ne] [-nt] [-nu] [-f] [-y] [-d|-D] [-L <Log>]

or

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


DESCRIPTION:
	This script supports the production cutover to enable Single Sign-On (SSO)
	using the Perforce Authentication Service (P4AS). The P4AS service is a
	bridge to your Identity Provider (IdP) system, e.g. Google OneLogin, Microsoft
	Entra, Okta, Perforce IdP, Ping Federate, etc.

	In a typical phased rollout of SSO, SSO is first deployed in a pilot phase
	in "opt-in" mode, where a few users are manually configured to use SSO.

	Then, after testing, the production rollout is done -- that's where this
	script comes in.  This script supports the production rollout process by
	changing a set of users to be ready for SSO rollout.  For the production
	rollout, this set of users is typically all human users.

	Digression: The P4 Server itself is not aware of "human" vs. "non-human"
	users.  The user spec does have a 'Type:' field, the value of which can have
	values of 'standard', 'service', or 'operator'. The distinction of 'standard'
	vs. 'service/operator' users is known to the P4 Server. However, 'service'
	and 'operator' users are extremely limited functionally, so much so that
	automated accounts are almost always of type 'standard' as far as the P4
	Server is concerned.

	To call this script, the name of a P4 group containing a list of exempt
	users must be provided.  This group must contain the user 'perforce' and
	must also contain a list any others users that should not be configured
	for SSO. This typically is all non-human accounts such as CI/CD/DevOps
	automation, AI agents, etc. It may also contain any users that are not
	intended to use SSO for whatever reason (e.g. contractors who are not
	defined in your organization's IdP).

	The list of users to be processed is starts with the list of users
	reported by the 'p4 users' command without the '-a' option (thus naturally
	excluding users with a 'Type:' value of 'service' or 'operator', which
	cannot use SSO). Then the users in the exempt group are removed. The set
	of remaining users are configured for SSO.

	This script operates in these phases:

	Phase 0: Pre-flight checks.

	This phase evaluates readiness of the environment for the SSO cutover, and
	performs various checks. If any tests fail, further processing is aborted.
	Among the checks are:
	  - Verifies P4 super user access.
	  - Checks case-sensitivity of P4 Server.
	  - Ensures group of exempt users exists.
	  - Ensures group of exempt users contains SDP P4USER 'perforce'.

	Phase 1: Process Configurables

	Check SSO configurables; set if needed:
	  - Set auth.sso.allow.passwd=1
	  - Set auth.sso.nonldap=1
	  - Set auth.default.method=perforce

   Phase 1 can be skipped with the '-nc' option.

	Phase 2: Process P4AS Extension

	Check the P4AS extension, add updated if needed:
	  - Ensure "opt-in" users/groups are NOT defined.
	  - Ensure "opt-out" group references exclusion group specified with '-g'.
	  - Ensure "opt-out" user is the P4USER 'perforce'.

   Phase 2 can be skipped with the '-ne' option.

	Phase 3: Process Triggers

	Check triggers, add SSO_default.sh trigger if needed.
	  - Ensure SSO_default.sh trigger script is installed.
	  - Ensure SSO_default trigger is in the Triggers table.

	Phase 3 can be skipped with the '-nt' option.

	Phase 4: Processing Users

	For all non-exempt uesrs:
	  - Check AuthMethod, change to 'perforce' if needed.
	  - Set UUID password.

	Phase 4 can be skipped with the '-nu' option.

	By default, the password is set only once per user, even if this script is
	run multiple times.  Use '-f' to always set the password. A warning is
	displayed if the password reset is skipped becuase it had been set
	previously.  Keys named of the form 'SSO_Cutover.<NoOp>.<User>'
	are set when the password is set successfuly.  The '<NoOp>' value is '1'
	for a Dry Run and '0' for a Live Run, so that passwords set in Dry Run
	mode (which do NOT involve an actually password change) do not affect
	passwords set for the Live Run.

	Ideally, this script should be run exactly once in Live Run mode.  It is
	expected that a series of iterative Dry Runs may be needed to refine the
	set of users in the group of users excempt from SSO.

	Phase 5: P4 Code Review Update
	  - If P4.Swarm.URL is set, advise considering config.php update.

	There is no option to skip Phase 5 becuase it only displays optional
	advice; it takes no action.

SAFETY FEATURES:
	By default, this script operates in Dry Run (preview) mode, showing
	what it would do but not making any changes that affect data.  Run
	with '-y' to operate for real.

REQUIRED PARAMETERS:
 -g <GroupOfUsersExemptFromSSO>
	Specify the name of a group containing a list of users that are not to be
	configured for to SSO.  This group must exist and must contain at least the
	the 'perforce' user.

	This parameter is required.

OPTIONS:
 -i <SDPInstance>
	Specify the SDP instance. If not specified, the $SDP_INSTANCE variable from
	the shell environment is used.

 -nc	Specify '-nc' to skip SSO Configurables processing.

 -ne	Specify '-ne' to skip SSO Extension processing.

 -nt	Specify '-nt' to skip SSO Trigger processing.

 -nu	Specify '-nu' to skip SSO User processing.

 -f	Specify that passwords for users that have already been set to a UUID password
	are to be reset anyway.

 -y	Live operation mode.  By default, any commands that affect data, such as
	setting configurables, are displayed, but not executed.  With the '-y' option,
	commands affecting data may be executed.

HELP OPTIONS:
 -h	Display short help message.
 -man	Display man-style help message.
 -V	Display script name and version.

LOGGING AND DEBUGGING OPTIONS:
 -L <log>
	Specify the path to a log file, or the special value 'off' to disable
	logging.  By default, all output (stdout and stderr) goes to a log file
	pointed to by a symlink:

	$LOGS/SSO_Cutover.log

	The symlink is for convenience. It refers to the log from the most recent
	run if where '-L' was not used.

	Each time this script is run, a new timestamped log is started, and
	the symlink updated to reference the new/latest log during startup.

	NOTE: This script is self-logging.  That is, output displayed on the screen
	is simultaneously captured in the log file. Using redirection operators like
	'> log' or '2>&1' are unnecessary, as is using 'tee' (though using 'tee'
	or additional redirects will not interfere with the script).

 -d	Display debug messages.
 
 -D     Set extreme debugging verbosity using bash 'set -x' mode. Implies -d.

EXAMPLES:
	Example 1: Dry Run with debug-level verbosity.

	SSO_Cutover.sh -g Non-SSO -d

	Example 2: Production Cutover

	SSO_Cutover.sh -g Non-SSO -y