Perforce Public Knowledge Base - Authenticating with LDAP on Perforce 2014.1 and earlier
Downloads Blog Company Integrations Careers Contact Try Free
Menu Search
Reset Search



Authenticating with LDAP on Perforce 2014.1 and earlier

« Go Back


Performing LDAP or Active Directory with Perforce 2014.1 and earlier

External Authentication with Perforce 2014.1 and earlier

To implement external authentication, create an authentication trigger. The trigger connects to a remote password database and delivers the username and password for verification.

This article is for administrators who want to authenticate Perforce users against an external data source such as Active Directory or LDAP. Support for trigger types enabling external authentication was first made available in the 2005.2 release of the Perforce Server. A Perforce Server version 2005.2 or later is required use any of the following authentication triggers with Perforce.

To implement external authentication, an understanding of the following concepts is required:

The following articles may also be of use:
Debugging Triggers 
Authentication Triggers: Creating special users that bypass Active Directory
Authentication Triggers: Example Script Details
Authentication Triggers: Troubleshooting

Note: If the P4PASSWD environment variable is set (permitted on Perforce servers up to security level 2), it will no longer work to authenticate Perforce commands.

Note: After adding or removing an auth-check or auth-set trigger the Perforce server must be restarted for the change to take effect. Making changes to the parameters of these triggers, once they have been added, can be done without a server restart.

WARNING: Make sure to spell the trigger name correctly when adding an auth-check trigger with p4 triggers. A mistake here can result in all users being locked out of Perforce. Also, be sure to fully test the trigger and trigger table invocation prior to deployment in a production environment. If you should get locked out of your Perforce server due to a external authentication trigger problem, please use the p4d -xf 18362 flag or contact for assistance with restoring access to the Perforce server.

Auth-check and Auth-set

There are two types of authentication triggers that can be configured:

  • auth-check: this fires when a user runs the p4 login command, allowing authentication against a source external to the server. If successful, the user is issued with a ticket; if not, the login is rejected. 

  • auth-set: this fires when a user runs the p4 passwd command, allowing a password to be set in that external system. 

Important notes:

  • The auth-check trigger is also required to check old passwords before new external passwords can be set. As such, you cannot have an auth-set trigger without a working auth-check trigger.
  • The auth-set trigger is unlikely to be required since the users already have a way of setting their password external to the Perforce server. The auth-set trigger is run by the Perforce Server after the user issues the p4 passwd command.
  • When an auth-check trigger is in place, the Perforce security counter is ignored; Perforce no longer tries to enforce strong passwords or other such security measures, as this is now handled by the external authorization (such as LDAP).
  • One important difference between authentication triggers and other Perforce triggers is the way authentication triggers receive the passwords. Passwords are sent to the auth-check and auth-set triggers on the standard input (STDIN). The first thing the trigger must do is read the password from STDIN. As with all triggers, success is indicated by an execution exit status of 0.

Active Directory vs. LDAP server

Active Directory differs from most LDAP servers in that it supports secure authentication, but not secure communication.

Please note that the provided AD scripts work by using the cn for authentication. It expects the cn to be equal to tLDAP or Active Directoryhe sAMAccountID, the short name without spaces that users generally use to log into their machine. If cn fields on the AD server have been changed to include spaces, the scripts below will need to be modified to perform a lookup on the sAMAccountID and retrieve the cn before attempting the AD authentication component.

Installing an Active Directory Trigger

  1. Either:

Download ad-auth-check.ps1 (a PowerShell script) from the public depot. This simply requires the Active Directory username, and may be the easiest trigger to install and get working - but if it doesn't work for you then try the alternatives below. For detailed requirements, please see the comments in the script itself.

Download the active directory executable. Below is a small program that authenticates against an Active Directory server and compiles readily on Windows. Also included is a compiled copy that should work on all Windows platforms, and a Linux 24x86 binary. Before adding the script to the p4 triggers table, first run the script from a command line replacing %user% with an existing Active Directory username to make sure there are no errors and the script returns a zero exit code.

  1. To find the proper parameters to use, download the Port Query tool from Microsoft from here

    Microsoft also offers information on using this utility to query an Active Directory server.

Once the Port Query is obtained, find the serverName line

c:\PortQryV2>PortQry.exe -n localhost -p tcp -e 389
Querying target system called:
Attempting to resolve name to IP address...
Name resolved to
TCP port 389 (ldap service): LISTENING
Using ephemeral source port
Sending LDAP query to TCP port 389...
LDAP query response:
currentdate: 10/06/2011 17:16:29 (unadjusted GMT)
subschemaSubentry: CN=Aggregate,CN=Schema,CN=Configuration,DC=ad,DC=foo,DC=com
dsServiceName: CN=NTDS Settings,CN=GABRIEL,CN=Servers,CN=Default-First-Site-Name,CN=Sites,CN=Configuration,DC=ad,DC=foo,DC=com
namingContexts: DC=ad,DC=foo,DC=com
defaultNamingContext: DC=ad,DC=foo,DC=com
schemaNamingContext: CN=Schema,CN=Configuration,DC=ad,DC=foo,DC=com
configurationNamingContext: CN=Configuration,DC=ad,DC=foo,DC=com
rootDomainNamingContext: DC=ad,DC=foo,DC=com
supportedControl: 1.2.840.113556.1.4.319
supportedLDAPVersion: 3
supportedLDAPPolicies: MaxPoolThreads
highestCommittedUSN: 180235
supportedSASLMechanisms: GSSAPI
serverName: CN=GABRIEL,CN=Servers,CN=Default-First-Site-Name,CN=Sites,CN=Configuration,DC=ad,DC=foo,DC=com
supportedCapabilities: 1.2.840.113556.1.4.800
isSynchronized: TRUE
isGlobalCatalogReady: TRUE
domainFunctionality: 0
forestFunctionality: 0
domainControllerFunctionality: 2
======== End of LDAP query response ========


  1. Run the authentication command from the command line adding including the serverName and a typical Active Directory user name. In this example, the user is bruno and the password is mypassw0rd. Note that there will not be a prompt; after pressing enter, type in the password, then press enter again.

c:\PortQryV2>p4auth_ad.exe localhost 389 CN=GABRIEL,CN=Servers,CN=Default-First-Site-Name,CN=Sites,CN=Configuration,DC=ad,DC=foo,DC=com bruno
Success:  Password verified.

On some systems a Windows domain name must be appended to the user, such as:

ad auth-check auth "c:/p4auth_ad.exe localhost 389 CN=Users,DC=test,DC=perforce,DC=com foobar\%user%"

On other systems forward slashes are not allowed and backslashes must be used:

ad auth-check auth "c:\p4auth_ad.exe localhost 389 CN=Users,DC=test,DC=perforce,DC=com foobar\%user%"

If the above executables do not work, try the no_null executable alternative listed below. Sometimes a more simplified syntax works such as

./p4auth_ad 389 OU=LA,DC=p4test,DC=com

  1. Place the command into the triggers table. 

Run "p4 triggers" and add a line similar to below:

ad auth-check auth "c:/p4auth_ad.exe localhost 389 CN=Users,DC=test,DC=perforce,DC=com %user%"

where the path to the p4auth executable is specified, the parameters from Port Query determine the arguments, and %user% is substituted for the user name.

  1. Restart the Perforce server.

If authentication does not work after a restart and you need to log in, run p4d with the 18362 flag as shown below.

cd <Perforce root> p4d -r . -xf 18362 "echo 0"

No-null Executable Alternative

Users have reported that in some environments the above trigger does not properly handle users with null passwords. In such cases, the trigger below might allow the authentication to complete successfully. It operates in a similar fashion to the above trigger, but it does not allow users to login if they have not set an Active Directory password.

The above auth trigger is called slightly differently. It does not require the domain. Here is an example of how it should be called from a Perforce trigger where %user% might need to be replaced with %user%@<domainname>

ad auth-check auth "c:\p4auth_ad-no_null.exe localhost 389"

Two Factor Authentication

The above triggers do not perform two factor authentication. However, Perforce authentication triggers can be written to support two factor authentication. For more information, see the Perforce blog entry Two Factor Authentication with Perforce.

Password length and securing users passwords.

Password length limit for 2011.1+ releases is 1024 bytes. As to securing your en-route (P4 <-> P4D <-> built-in LDAP) passwords. P4 <-> P4d: we never send passwords in clear text, we hash them prior they hit the wire. P4D <-> built-in LDAP: if the Bind method is simple or search, the LDAP library sends the password as clear plain text. If the bind method is SASL, only a hash of the password is sent. In both of these cases, the communication with the LDAP server can be encrypted by setting the Encryption field to SSL or TLS. We recommend using tls with SASL wherever possible.

Perl Examples

For examples of authentication triggers (Perl/C), see the following code in the Public Depot. A detailed description of each script's function is explained in the comment sections of that script:

Custom Script

You can also write a custom script to perform authentication. The following is a small Perl script example of how the password is read from the standard input. This simple case just checks that the password is "secret".

The trigger table entry looks like this: 

test auth-check auth "/script/checkpass"

and the script itself is this: 
## Perforce requires messages on stdout
open(STDERR, ">&STDOUT") or die "Can't dup stdout";
## read the password from <stdin< and truncate the newline
chomp (my $password = <STDIN>);
$password =~ s/r$//;
## success
if($password eq "secret"){
   exit 0;
## failure
die "You got the password wrong!";

In the above example, when a p4 login request is issued with the correct password supplied the server displays the following output:

% p4 login
Password: secret
User joeb logged in.

By contrast, when the wrong password is entered, the following output is displayed:

% p4 login
Password: foobar
Password invalid.
'test' validation failed: You got the password wrong!

The only difference between an auth-set trigger and an auth-check trigger is that the auth-set trigger gets the old password followed by the new password on STDIN.

LDAP example

Below is an example auth-check trigger definition that authenticates against an LDAP server. Note that the LDAP distinguished name (DN) is being passed to the trigger as a trigger argument.

ldap auth-check auth "/script/checkpass uid=%user%,cn=users,dc=myco,dc=com
Related Links



Was this article helpful?



Please tell us how we can make this article more useful.

Characters Remaining: 255