Triggering to use external authentication

To configure Helix Server to work with an external authentication manager (such as LDAP or Active Directory), use authentication triggers (auth-check, auth-check-sso, service-check, and auth-set). These triggers fire on the p4 login and p4 passwd commands.

Note

You might prefer to enable LDAP authentication by using an LDAP specification. This option is recommended: it is easier to use, no external scripts are required, it provides greater flexibility in defining bind methods, it allows users who are not in the LDAP directory to be authenticated against Helix Server’s internal user database, and it is more secure. For more information, see Authentication options.

That being said, you also have the option of using auth-check-sso triggers when LDAP authentication is enabled. In this case, users authenticated by LDAP can define a client-side SSO script instead of being prompted for a password. If the trigger succeeds, the active LDAP configurations are used to confirm that the user exists in at least one LDAP server. The user must also pass the group authorization check if it is configured. Triggers of type auth-check-sso will not be called for users who do not authenticate against LDAP.

Authentication triggers differ from changelist and form triggers in that passwords typed by the user as part of the authentication process are supplied to authentication scripts as standard input; never on the command line. (The only arguments passed on the command line are those common to all trigger types, such as %user%, %clientip%, and so on.)

Warning

Be sure to spell the trigger name correctly when you add the trigger to the trigger table because a misspelling can result in all users being locked out of Helix Server.

Be sure to fully test your trigger and trigger table invocation prior to deployment in a production environment.

Contact Perforce Technical Support if you need assistance with restoring access to your server.

The examples in this book are for illustrative purposes only. For a more detailed discussion, including links to sample code for an LDAP environment, see the Support Knowledgebase article, "Authenticating with LDAP".

You must restart the Helix Core Server after adding an auth-check (or service-check) trigger in order for it to take effect. You can, however, change an existing auth-check trigger table entry (or trigger script) without restarting the server.

After an auth-check trigger is in place and the server restarted, the Helix Server security configurable is ignored. Because authentication is now under the control of the trigger script, the server’s default mechanism for password strength requirements is redundant.

The following table describes the fields of an authentication trigger definition.

Field	Meaning
`name`	The name of the trigger.
`type`	auth-check: Execute an authentication check trigger to verify a user’s password against an external password manager during login, or when setting a new password. If an `auth-check` trigger is present, the Perforce`security` configurable (and any associated password strength requirement) is ignored, as authentication is now controlled by the trigger script. You must restart the Helix Core Server after adding an `auth-check` trigger. auth-check-sso: Facilitate a single sign-on user authentication. auth-set: Execute an authentication set trigger to send a new password to an external password manager. service-check: Execute a trigger to verify the password of a service user, rather than a standard user. Service check triggers work in the same way that `auth-check` triggers do. Do not use this type of trigger for an operator user; use the `auth-check` type trigger instead. You must restart the Helix Core Server after adding a `service-check` trigger. See also the Optional auth-invalidate trigger.
`path`	Use `auth` as the path value.
`command`	The trigger for the Helix Core Server to run. See the following sections about specific authentication trigger types for more information on when the trigger is fired. In most cases, it is when the `p4 login` command executes. Specify the command in a way that allows the Helix Core Server account to locate and run the command. The `command` (typically a call to a script) must be quoted, and can take as arguments any argument that your `command` is capable of parsing, including any applicable Helix Server trigger variables. When your trigger script is stored in the depot, its path must be specified in depot syntax, delimited by percent characters. For example, if your script is stored in the depot as `//depot/scripts/myScript.pl`, the corresponding value for the command field might be `"/usr/bin/perl %//depot/scripts/myScript.pl%"`. See Storing triggers in the depot for more information. For `auth-check` and `service-check` triggers (fired by `p4 login` from standard/operator users and service users respectively), the user’s typed password is supplied to the trigger command as standard input. If the trigger executes successfully, the Helix Server ticket is issued. The user name is available as `%user%` to be passed on the command line. For `auth-check-sso` triggers, (fired by `p4 login` for all users) the output of the client-side script (specified by `P4LOGINSSO`) is sent to the server-side script in cleartext. For `auth-set` triggers, (fired by `p4 passwd`, but only after also passing an `auth-check` trigger check) the user’s old password and new password are passed to the trigger as standard input. The user name is available as `%user%` to be passed on the command line.