Helix Core Server Administrator Guide: Fundamentals (2019.2)

Single sign-on and auth-check-sso triggers

Client script and server script

Triggers of type auth-check-sso fire when standard users run the p4 login command. Two scripts are run: a client-side script is run on the user’s workstation, and its output is passed (in plaintext) to the Helix Core server, where the server-side script runs.

Client-side script Server-side script

On the user’s client workstation, a script (whose location is specified by the P4LOGINSSO environment variable) is run to obtain the user’s credentials or other information verifiable by the Helix server. P4LOGINSSO contains:

  • the name of the client-side script
  • zero or more of the following trigger variables, passed as parameters to the script:
    • %user%
    • %serverAddress%
    • %P4PORT%

For example,

 $ export P4LOGINSSO="/path/to/sso-client.sh %user% %serverAddress% %P4PORT%"

Where %user% is the Helix server client user, %serverAddress% is the address of the target Helix server, and %P4PORT% is an intermediary between the client and the server.

On the server, the output of the client-side script is passed to the server-side script as standard input. The server-side script specified in the trigger table runs, and the server returns an exit status of 0 if successful.

With a distributed configuration in which a proxy or broker acts as an intermediary between the client and the server:

  • the %serverAddress% variable holds the address/port of the server
  • the %P4PORT% variable holds the port of the intermediary.

The script decides what to do with this information.

See also: Helix SAML .

p4 login behavior with auth-check-sso trigger

The table below describes the behavior of p4 login when a trigger of type auth-check-sso is in place.

Depending on the configuration and environment:

  • The P4LOGINSSO client-side script is executed, performing customizable SSO operations, potentially without user interaction.
  • The user is prompted to authenticate by password. This is a fallback if no client-side P4LOGINSSO script is configured.
  • The user's login attempt is rejected until a valid P4LOGINSSO script is configured in the user's environment.

Version 2018.2 introduced two configurables that change the default behavior:

  • auth.sso.allow.passwd allows a user whose password is stored in the database (db.user) to fall back to password authentication if P4LOGINSSO is not configured.
  • auth.sso.nonldap allows a user whose AuthMethod is set to perforce on an LDAP-enabled server to make use of P4LOGINSSO

If P4LOGINSSO is set:

    Not LDAP-Enabled LDAP-Enabled
auth.sso.allow.passwd auth.sso.nonldap db.user only auth-check trigger 'perforce' + LDAP enabled 'ldap' + LDAP enabled
0 0 P4LOGINSSO fires Password requested P4LOGINSSO fires
1 P4LOGINSSO fires
1 0 Password requested
1 P4LOGINSSO fires

If P4LOGINSSO is not set:

    Not LDAP-Enabled LDAP-Enabled
auth.sso.allow.passwd auth.sso.nonldap db.user only auth-check trigger 'perforce' + LDAP enabled 'ldap' + LDAP enabled
0 0 Login rejected Password requested Password requested Password requested
1 Login rejected
1 0 Password requested Password requested Password requested Password requested
1

Example   Interaction between client-side and server-side scripts

Note

What follows is a trivial example. For a substantial example and a step by step walk-through for both Linux and Windows, see the Knowledge Base article, "Setting up Single Sign-On (P4LOGINSSO)".

An auth-check-sso trigger fires whenever users run p4 login. The system administrator might add the following line to the trigger table to specify the script that should run on the server side:

sample13  auth-check-sso  auth  "serverside.sh %user%"

and each end user sets the following environment variable on the client side:

export P4LOGINSSO=/usr/local/bin/clientside.sh %serverAddress%

When the user attempts to log on, the P4LOGINSSO script runs on the user’s workstation:

##!/bin/bash
# clientside.sh - a client-side authentication script
#
# if we use %serverAddress% in the command-line like this:
#    p4 -E P4LOGINSSO=clientside.sh %serverAddress%
# then this script receives the serverAddress as $1, and the user
# can use it for multiple connections to different Helix Servers.
#
# In this example, we simulate a client-side authentication process
# based on whether the user is connecting to the same Helix Server
# as is already configured in his or her environment.
# (We also output debugging information to a local file.)

input_saddr=$1

env_saddr=`p4 info | grep "Server address" | awk '{printf "%s", $3}'`

if test "$input_saddr" == "$env_saddr"
  then
    # User is connected to the server specified by P4PORT - pass
    echo "sso pass"; echo pass "$input_saddr" >> debug.txt; exit 0
  else
    # User is attempting to connect to another server - fail
    echo "no pass"; echo fail "$input_saddr" >> debug.txt; exit 1
fi

If the user is connected to the same Helix Core server as specified by P4PORT (that is, if the server address passed from the Server to this script matches the server that appears in the output of a plain p4 info command), client-side authentication succeeds. If the user is connected to another Helix Core server (for example, by running p4 -p host:port login against a different Helix Core server), client-side authentication fails.

The server-side script is as follows:

#!/bin/bash
#
# serverside.sh - a server-side authentication script
#

if test $# -eq 0
  then
    echo "No user name passed in.";
    exit 1;
fi

read msg </dev/stdin

if test "$msg" == ""
  then
    echo "1, no stdin"
    exit 1
fi

if test "$msg" == "sso pass"
  then
    exit 0
  else
    exit 1
fi

In a more realistic example, the end user’s P4LOGINSSO script points to a clientside.sh script that contacts an authentication service to obtain a token of some sort. The client-side script then passes this token to Helix Core server’s trigger script, and serverside.sh uses the single-signon service to validate the token.

In this example, clientside.sh merely checks whether the user is using the same connection as specified by P4PORT, and the output of clientside.sh is trivially checked for the string "sso pass"; if the string is present, the user is permitted to log on.

Optional auth-invalidate trigger

The optional auth-invalidate trigger type is fired when a user's ticket is explicitly invalidated by p4 logout. This trigger can propagate the logout to an authentication systems that is external to Helix Core. For example, the trigger can be used between the SAML SSO agent and the identity provider (IdP ).

For an auth-invalidate trigger:

%user% -- the user's username

%fullname% -- the user's fullname

%email% -- the user's email address

%host% -- the host IP address of the ticket being invalidated or all-hosts for p4 logout -a

%2fa% -- true if the multi factor authentication status was reset, false if the user doesn't use multi factor authentication and only2fa for p4 logout -2