Securing the Server
You can set up secure communication between clients and servers as well as between servers.
Communication between clients and servers can be secured using the SSL protocol, which you specify when connecting to the server. See Using SSL to encrypt connections to a Perforce server for information on how you secure client-server communication.
Communication between clients and servers can also be secured using a firewall. For more information, see Using firewalls.
- User authentication can be done using passwords or tickets, and the strength of the password can be defined by an administrator. Users can be authenticated against an Active Directory or LDAP server, or against an internal Helix user database. See Authentication options for information about how you can authenticate users.
- Access is defined using a protections that determine which Perforce commands can be run, on which files, by whom, and from which host. See Authorizing access to find out how you define protections.
- Communication between servers in a distributed environment can be secured using a trust file and by setting permissions for the service users that own the different servers in the environment. For more information, see Helix Versioning Engine Administrator Guide: Multi-site Deployment.
Before you can configure access and authentication, you must create users as described in Managing users.
Securing the server: workflow
The following workflow summarizes the steps required to secure the server and authenticate users. The suggested order might vary, depending on the authentication method used and on whether users are automatically created.
- Set up SSL if needed.
- Set up a firewall if needed.
- Set up protections for users and user groups.
- Review available authentication options and server security levels.
- Set the security level for the server.
- Define the authentication to be used for existing users and new users.
- Create authentication triggers if you are planning to use a non-standard LDAP server.
- Enable and configure LDAP authentication if you are planning to authenticate users against an LDAP or Active Directory server.
For information about basic security considerations when setting up a Perforce server, see
Using SSL to encrypt connections to a Perforce server
The following sections explain how you set up encrypted communications between a client and a Perforce server.
For any given Perforce server, proxy, or broker, SSL encryption is an all-or-nothing option: If a Perforce server is configured to use SSL (presumably for security reasons), all Perforce applications must be configured to use SSL. Conversely, if a Perforce server is configured to accept plaintext connections (either for performance reasons or for backwards compatibility), all client applications must connect in plaintext. It is possible however, if you have an intermediary (such as a proxy or a broker) between the client and the Perforce server, that one leg of the communication is encrypted and the following is not. For more information, see Using SSL in a mixed environment.
TLSv1.1 is currently supported; SSL 3.0 is not.
Server and client setup
By default, a
P4PORT setting that does not specify a protocol is
assumed to be in plaintext. It is good practice to configure Perforce
applications to explicitly specify the protocol, either
for encrypted connections.
port for plaintext, or
The first time a user connects to an SSL-enabled server, their Perforce applications will inform them of the fingerprint of the server’s key.
If the user can independently verify that the fingerprint is accurate,
they should add the server to their
P4TRUST file (either by using the
p4 trust command, by following the prompts in P4V or other
Perforce applications, or by manually adding the fingerprint to the
Key and certificate management
When configured to accept SSL connections, all server processes
p4broker), require a valid
certificate and key pair on startup. These files are stored in the
directory specified by the
P4SSLDIR environment variable. In order for
an SSL-enabled server process to start, the following additional
conditions must be met:
P4SSLDIRmust be set to a valid directory.
P4SSLDIRdirectory must be owned by the same userid as the one running the Perforce server, proxy, or broker process. The
P4SSLDIRdirectory must not be readable by any other user. On UNIX, for example, the directory’s permissions must be set to 0700 (
drwx------) or 0500 (
Two files, named
certificate.txt, must exist in
These files correspond to the PEM-encoded private key and certificate used for the SSL connection. They must be owned by the userid that runs the Perforce server, proxy, and broker process, and must also have their permissions set such as to make them unreadable by other users. On UNIX, for example, the files' permissions must be set to 0600 (
-rw-------) or 0400 (
You can supply your own private key and certificate, or you can use
p4d -Gcto generate a self-signed key and certificate pair.
To generate a fingerprint from your server’s private key and certificate, run
p4d -Gf. (
P4SSLDIRmust be configured with the correct file names and permissions, and the current date must be valid for the certificate.)
After you have communicated this fingerprint to your end users, your end users can then compare the fingerprint the server offers with the fingerprint you have provided. If the two fingerprints match, users can use
p4 trustto add the fingerprint to their
Key and certificate generation
To generate a certificate and private key for your server:
P4SSLDIRto a valid directory in a secure location. The directory specified by
P4SSLDIRmust be secure: owned by the same userid as the one generating the key pair, and it must not be readable by any other user.
Optionally, create a file named
P4SSLDIRdirectory before running
p4d -Gc, and format the file as follows:
# C: Country Name - 2 letter code (default: US) C = # ST: State or Province Name - full name (default: CA) ST = # L: Locality or City Name (default: Alameda) L = # O: Organization or Company Name (default: Perforce Autogen Cert) O = # OU = Organization Unit - division or unit OU = # CN: Common Name (usually the DNS name of the server) # (default: the current server's DNS name) CN = # EX: number of days from today for certificate expiration # (default: 730, e.g. 2 years) EX = # UNITS: unit multiplier for expiration (defaults to "days") # Valid values: "secs", "mins", "hours" UNITS =
Generate the certificate and key pair with the following command:
config.txt) has been correctly configured, and if no existing private key or certificate is found, two files, named
certificate.txt, are created in
config.txtfile is not present, the following default values are assumed, and a certificate is created that expires in 730 days (two years, excluding leap years).
C=US ST=CA L=Alameda O=Perforce Autogen Cert OU= CN=
Generate a fingerprint for your server’s key and certificate pair.
This command displays the fingerprint of the server’s public key, and then exits.
Record your server’s fingerprint for your own records and communicate it to your users via an out-of-band communications channel.
If a Perforce application reports a different fingerprint (and you have not recently installed a new certificate and key pair), your users should consider such changes as evidence of a potential man-in-the-middle threat.
Because Perforce Servers can use self-signed certificates, you may also
use third-party tools such as OpenSSL or PuTTY to generate the key
pairs, or supply your own key pair. The
p4d -Gf command accepts
If you are supplying your own key, your
certificate.txt files in
P4SSLDIR must be PEM-encoded, with the
private key file stripped of passphrase protection.
Whether you supply your own key and certificate pair or generate one
p4d -Gc, it is imperative that these files are stored in
a secure location that is readable only by the
Secondary cipher suite
By default, Perforce’s SSL support is based on the AES256-SHA cipher
suite. To use CAMELLIA256-SHA, set the
ssl.secondary.suite tunable to
Using SSL in a mixed environment
In a mixed environment, each link between Perforce servers, proxies, or brokers may be configured to be in either plaintext or SSL, independent of the encryption choice for any other link. Consider the following examples:
- During a migration from cleartext to SSL, a Perforce Broker may be configured to accept plaintext connections from older Perforce applications, and to forward those requests (encrypted by SSL) to a Perforce Server that requires SSL connections.
- A Perforce Broker could be configured to
tcp:old-server:1666, and redirect all requests to a
ssl:new-server:1667. Users of new Perforce applications could use SSL to connect directly to the upgraded Perforce Server (by setting
ssl:new-server:1667), while users of older Perforce applications could continue to use plaintext when connecting to a Perforce Broker (by setting
old-server:1666). After migration is complete, the broker at
old-server:1666could be deactivated (or reconfigured to require SSL connections), and any remaining legacy processes or scripts still attempting to connect via plaintext could be upgraded manually.
The Perforce Proxy and the Perforce Broker support the
flags, and use the
P4SSLDIR environment variable. You generate
certificate and key pairs for these processes (and confirm fingerprints)
as you would with a single Perforce Server. In order for two servers to
communicate over SSL, the administrator of the downstream server
(typically a replica server, Proxy, or Broker process) must also use the
p4 trust command to generate a
P4TRUST file for the service
user associated with the downstream server.
When migrating from a non-SSL environment to an SSL-based environment, it is your responsibility to securely communicate the new server’s fingerprint to your users.
If available, remote clients can use a Virtual Private Network (VPN) or a Secure Shell (SSH) tunnel to access services on the inside trusted network.
For additional information about using an SSH tunnel to connect to a Perforce server, see the following Knowledge Base article:
This section introduces the options you have in authenticating users who log in to Perforce. It focuses on authenticating against Active Directory and LDAP servers without using authentication triggers.
User authentication can take place using one of three options:
Against an Active Directory or LDAP server that is accessed according to an LDAP specification. Enabling this option disables trigger-based authentication.
This section focuses on this option. It notes the advantages of using this option, it explains how you create an LDAP configuration, it gives instructions on how you activate and test this configuration, and it provides reference information on the commands and configurables you use to implement this option.
Against Perforce’s internal user database,
This option allows plain-text password-based authentication. It is described in Authenticating using passwords and tickets.
Against an authentication server, using an authentication trigger.
These types of triggers are useful if you need to authenticate users against a non-standard authentication server. Authentication triggers fire when the
p4 passwdcommands execute. This option is described in the section Triggering to use external authentication.
The authentication server you choose is used for user definitions, user authentication (passwords), group definitions, license details, and ticket generation.
Authentication is configured on a per-user basis (except for trigger-based authentication): for each user, you can specify what method should be used for authentication. Some options are mutually exclusive: enabling configuration-based LDAP authentication turns off trigger-based authentication. However, you can have some users authenticate using LDAP, while others authenticate against Perforce’s internal user database. For more information, see Defining authentication for users.
When logging in using either authentication method, Perforce encrypts the password before passing it to the specified authentication agent.
Server security levels
The authentication option you choose is partly determined by the
security level set for the server. Perforce superusers can configure
server-wide password usage requirements, password strength enforcement,
and supported methods of user/server authentication by setting the
security configurable. To set or change the
issue the command:
$ p4 configure set security=
Security level settings do not apply if you are using an external
authentication manager such as LDAP or Active Directory. In this case,
the server either behaves as though
security=3 (or greater) was set, or
is placed completely under the control of the external authentication
The following table explains the effect of each security level:
|Security level||Server behavior|
The default security level
Users with passwords can use either their
Ensures that all users have passwords. (Users of old Perforce applications can still enter weak passwords.)
Users with passwords can use either their
Ensures that all users have strong passwords.
Very old Perforce applications continue to work, but users must change their password to a strong password and upgrade to 2003.2 or later.
Requires that all users have strong passwords,
and requires the use of ticket-based (
If you have scripts that rely on passwords, use
Setting passwords with the
In multi-server and replicated environments this level ensures that only authenticated service users (subject to all of the restrictions of level 3) can connect to this server.
The following checks are also made:
dm.password.minlength configurable to enforce a minimum
password length at levels
Defining authentication for users
Authentication is defined by the setting of the
AuthMethod field of
the user spec and also by configurables that affect user authentication.
AuthMethod field of the user specification, created with the
p4 user command, specifies the authentication method to be used
for that user.
ldapindicates that the user is to be authenticated against the LDAP directory defined by an active LDAP configuration. User access can be further restricted to those users who belong to a particular LDAP group.
All authentication triggers are disabled when LDAP authentication is enabled.
perforceindicates that the user is to be authenticated by an authentication trigger script if such a script exists, or against Perforce’s internal user database. This is the default setting.
A superuser must edit the user spec with the
p4 user -f command
to change the default value to
ldap if desired.
auth.default.method configurable defines the default value for the
AuthMethod on new users. Possible values are
By default, Perforce creates a new user record in its database whenever
a previously unknown user invokes any command that can update the
repository or its metadata. For greatest security, it is recommended
that you turn this feature off using the
configurable with the
p4 configure command.
If you select the
ldap configurable, only superusers are allowed to
create new users (using the
p4 user command). To have new users
automatically created upon login, you must set
auth.ldap.userautocreate to 1.
If you need more control over which LDAP users are allowed access to
Perforce, you can use the group-related fields of the LDAP configuration
to implement a basic authorization step that filters out non-Perforce
users. For example, specifying a filter like the following limits access
to LDAP users who belong to the LDAP group with the common name
Base DN: ou=groups,dc=example,dc=org LDAP query: (&(cn=perforce)(memberUid=%user%))
In this case, only users who provide the proper credentials and who are
members of the specified group are authenticated. For more information
auth.default.method configurable, see the description of the
p4 configure command and the "Configurables" appendix in the
P4 Command Reference.
If a user is set to use LDAP-configuration based authentication, the
user may not update their password with the
p4 passwd command.
Authenticating using passwords and tickets
Perforce supports two methods of authentication: password-based and ticket-based. Although it might be more accurate to say that you can use password-only authentication or authentication that uses passwords and associated tickets.
- Password-only authentication is based on plain-text passwords that do not expire and that are passed around when the user executes a command.
- Ticket-based authentication is based on tickets that are issued for a given amount of time and are generated after the user has logged in with a valid password. After log in, the ticket is used to authenticate the user (rather than the password being passed around).
Although ticket-based authentication is more secure than password-based authentication, it does not encrypt network traffic between client workstations and the Perforce server.
To encrypt network traffic between client workstations and the Perforce server, configure your installation to use SSL. See Using SSL to encrypt connections to a Perforce server.
Plain-text password-based authentication is stateless; after a password
is correctly set, access is granted for indefinite time periods.
Passwords may be up to 1024 characters in length. To enforce password
strength and existence requirements, set the server security level. See
Server security levels for details. Plain-text password based authentication is
supported only at security levels
The default minimum password length is eight characters. Minimum
password length is configurable by setting the
configurable. For example, to require passwords to be at least 16
characters in length, a superuser can run:
$ p4 configure set dm.password.minlength=16
To require users to change their passwords after a specified interval,
assign your users to at least one group and set the
value for that group. For users in multiple groups, the largest defined
unlimited, but ignoring
p4 admin resetpassword command forces specified users with
existing passwords to change their passwords before they can run another
command. (This command works only for users whose
authMethod is set to
perforce. However, you can use it in a mixed environment, that is an
environment in which both Perforce-based and LDAP-based authentication
Password strength requirements
Certain combinations of server security level and Perforce applications
require users to set "strong" passwords. A password is considered strong
if it is at least
dm.password.minlength characters long (by default,
eight characters), and at least two of the following are true:
- The password contains uppercase letters.
- The password contains lowercase letters.
- The password contains non-alphabetic characters.
For example, the passwords
considered strong in an environment in which
security is configurable to at least
You can configure a minimum password length requirement on a site-wide
basis by setting the
dm.password.minlength configurable. For example,
to require passwords to be at least 16 characters in length, a superuser
$ p4 configure set dm.password.minlength=16
Passwords may be up to 1,024 characters in length. The default minimum password length is eight characters.
Managing and resetting user passwords
Perforce superusers can manually set a Perforce user’s password with:
$ p4 passwd
When prompted, enter a new password for the user.
To force a user with an existing password to reset his or her own password the next time they use Perforce, use the following command:
$ p4 admin resetpassword -u
You can force all users with passwords (including the superuser that invokes this command) to reset their passwords by using the command:
$ p4 admin resetpassword -a
p4 admin resetpassword -a resets only the passwords of
users who already exist (and who have passwords). If you create new user
accounts with default passwords, you can further configure your
installation to require that all newly-created users reset their
passwords before issuing their first command. To do this, set the
dm.user.resetpassword configurable as follows:
$ p4 configure set dm.user.resetpassword=1
Ticket-based authentication is based on time-limited tickets that enable
users to connect to Perforce servers. Perforce creates a ticket for a
user when they log in to Perforce using the
p4 login -a command.
Perforce applications store tickets in the file specified by the
P4TICKETS environment variable. If this variable is not set, tickets
are stored in
%USERPROFILE%\p4tickets.txt on Windows, and in
$HOME/.p4tickets on UNIX and other operating systems.
By default, tickets have a finite lifespan, after which they cease to be
valid. By default, tickets are valid for 12 hours (43200 seconds). To
set different ticket lifespans for groups of users, edit the
field in the
p4 group form for each group. The timeout value for
a user in multiple groups is the largest timeout value (including
unlimited, but ignoring
unset) for all groups of which a user is a
member. To create a ticket that does not expire, set the
Although tickets are not passwords, Perforce servers accept valid
tickets wherever users can specify Perforce passwords (except when
logging in with the
p4 login command). This behavior provides
the security advantages of ticket-based authentication with the ease of
scripting afforded by password authentication. Ticket-based
authentication is supported at all server security levels, and is
required at security level
If password aging is in effect, tickets expire when their passwords expire.
Login process for the user
Users are authenticated in one of two ways:
The user logs in explicitly using the
The user enters a p4 command, and the command requires that the user be authenticated. If the user is not already authenticated, the command will prompt for login. If the login is successful, the original command continues.
To log in to Perforce, the user obtains a ticket from the server by
p4 login command:
$ p4 login
The user is prompted for a password, and a ticket is created for the
user in the file specified by
P4TICKETS. The user can extend the
ticket’s lifespan by calling
p4 login while already logged in;
this extends the ticket’s lifespan by 1/3 of its initial timeout
setting, subject to a maximum of the user’s initial timeout setting.
The Perforce service rate-limits the user’s ability to run
login after multiple failed login attempts. To alter this behavior,
dm.user.loginattempts to the maximum allowable failed login
attempts before the service imposes a 10-second delay on subsequent
By default, Perforce tickets are valid for the user’s IP address only.
If the user has a shared home directory that is used on more than one
machine, the user can log in to Perforce from both machines by using
p4 login -a to create a ticket in the home directory that is
valid from all IP addresses.
Tickets can be used by multiple clients on the same machine so long as they use the same user and port.
auth.csv log is used to log the results of
attempts. If the login failed, the reason for this is included in the
log. Additional information provided by the authentication method is
included in the log entries.
Login process for the server
The server uses the following process to login a user:
- The user logs in, specifying a name and password.
The server checks to see if LDAP integration has been enabled for the server.
- If LDAP integration has been enabled, the server checks the user record as described in Step 3.
- If LDAP integration has not been enabled, the server passes the user’s
credentials to an authentication script if one exists, or it
validates credentials using the
db.usertable; it then issues a ticket if validation succeeds.
The server checks the user record to see which authentication method to use:
ldap, the server cycles through available LDAP configurations to find the user. If the user is found and the password is valid, a ticket is issued for the user.
perforce, the server validates the user against the
db.usertable and issues a ticket if the user exists and credentials are valid.
Logging out of Perforce
To log out of Perforce from one machine by removing your ticket, use the command:
$ p4 logout
The entry in your ticket file is removed. If you have valid tickets for the same Perforce server, but those tickets exist on other machines, those tickets remain present (and you remain logged in) on those other machines.
If you are logged in to Perforce from more than one machine, you can log out of Perforce from all machines from which you were logged in by using the command:
$ p4 logout -a
All of your Perforce tickets are invalidated and you are logged out.
Determining ticket status
To see if your current ticket (that is, for your IP address, user name,
P4PORT setting) is still valid, use the command:
$ p4 login -s
If your ticket is valid, the length of time for which it will remain valid is displayed.
To display all tickets you currently have, use the command:
$ p4 tickets
The contents of your ticket file are displayed.
Invalidating a user’s ticket
As a super user, you can use the
-a flag of the
command to invalidate a user’s ticket. The following command invalidates
$ p4 logout -a joe
The following sections explain how you can authenticate against Active Directory and LDAP servers. It describes how you do the following:
- Create an LDAP configuration
- Set LDAP-related configurables
- Authorize access using LDAP groups
- Test and enable LDAP configurations
- Get information about LDAP servers
- Use LDAP with SSO triggers
Authenticating against Active Directory and LDAP servers
LDAP, Lightweight Directory Access Protocol, is supported by many directory services; chief among these is Active Directory and OpenLDAP. Perforce offers two ways of authenticating against Active Directory or LDAP servers: using an authentication trigger or using an LDAP specification. The latter method offers a number of advantages: it is easier to use, no external scripts are required, it allows users who are not in the LDAP directory to be authenticated against Perforce’s internal user database, and it is more secure.
Create at least one account with
super access that uses perforce
authentication. This will allow you to login if by some chance you lose
SASL authentication is supported; SAML is not.
The steps required to set up configuration-based LDAP authentication are described in the following sections. Throughout this section, information relating to LDAP authentication applies equally to using Active Directory. In broad strokes, the configuration process include the following steps:
- Use the
p4 ldapcommand to create an LDAP configuration specification for each LDAP or Active Directory server that you want to use for authentication.
- Define authentication-related configurables to enable authentication, to specify the order in which multiple LDAP servers are to be searched, and to provide additional information about how LDAP authentication is to be implemented.
- Set the
AuthMethodfield of the user specification for existing users to specify how they are to be authenticated.
- Test the LDAP configurations you have defined to make sure searches are conducted as you expect.
- If this is the first time you have enabled LDAP authentication, restart the server.
You must restart the Perforce server whenever you enable or disable LDAP authentication:
- You enable LDAP authentication the first time you enable an LDAP
configuration by setting the
- You disable LDAP authentication by removing or disabling all
existing LDAP configurations. You remove an LDAP configuration
by using the
-doption to the
p4 ldapcommand. You disable all LDAP configurations by having no
- LDAP implies at least security level
Creating an LDAP configuration
An LDAP configuration specifies an Active Directory or other LDAP
server against which the Perforce server can authenticate users. You use
p4 ldap command to create configurations.
To define an LDAP configuration specification, you provide values that specify the host and port of the Active Directory or LDAP service, bind method information, and security parameters. Here is a sample LDAP configuration using the search bind method:
Name: sleepy Host: openLdap.example.com Port: 389 Options: getattrs Encryption: tls BindMethod: search SearchBaseDN: ou=employees,dc=example,dc=com SearchFilter: (cn=%user%) SearchScope: subtree GroupSearchScope: subtree
You can choose among the following bind methods: SASL, simple, and search.
SASL: One complication of the non-SASL bind methods is that the administrator needs to know about the structure of the directory. Most LDAP and Active Directory servers have the option of binding using SASL, which only requires a username and password to authenticate a user.
If the LDAP server supports SASL DIGEST-MD5 (Active Directory does), this method defers the user search to the LDAP server and does not require a distinguished name to be discovered before the bind is attempted. This method is recommended for Active Directory. Look how simple this is:
If your LDAP server has multiple realms (or domains in Active Directory), you might need to specify which one the LDAP configuration should be using. In this case, you’ll need to set the
SaslRealmfield too; for example:
BindMethod: sasl SaslRealm: example
Active Directory supports SASL out of the box, and most LDAP servers support SASL.
Simple: This method is suitable for simple directory layouts. It uses a pattern and the user’s username to produce a distinguished name that the Perforce server attempts to bind against, validating the user’s password. The name given is set on the Simple Pattern field. For example:
BindMethod: simple SimplePattern: uid=%user%,ou=users,dc=example,dc=com
This pattern is expanded when a user is logging in. For example, if the user is
jsmith, the Perforce server would attempt to bind against the DN shown below, using the password the user provided.
This bind method only works in environments where the user’s username is part of their DN and all of the users you want to authenticate are in the same organizational unit (OU).
Search: This method performs a search for the user’s record in the directory, overcoming the restrictions of the simple bind method Instead of a DN pattern, an LDAP search query is provided to identify the user’s record. The
%user%placeholder is also used with this method. A starting point and scope for the search are provided, allowing control over how much of the directory is searched. The search relies on a known base DN and an LDAP search query; you provide these using the
SearchScopefields of the LDAP configuration specification. This method might also require the full distinguished name and password of a known read-only entity in the directory. You supply these using the
SearchPasswdfields of the LDAP configuration. Here are two sample search queries:
BindMethod: search SearchBaseDN: ou=users,dc=example,dc=com SearchFilter: (&(objectClass=inetOrgPerson) (uid=%user%)) SearchScope: subtree SearchBindDN: uid=read-only, dc=example, dc=com SearchPasswd: ******
BindMethod: search SearchBaseDN: ou=users,dc=example,dc=com SearchFilter: (&(objectClass=user) (sAMAccountName=%user%)) SearchScope: subtree SearchBindDN: uid=read-only, dc=example, dc=com SearchPasswd: ******
See the P4 Command Reference for information about the
p4 ldap command
and the LDAP specification. The LDAP spec also allows you to fine tune
the behavior of LDAP integration. In particular, three options allows
you to control the following behavior:
- Set the
downcaseoption to specify that user names should be downcased from the directory on an LDAP sync.
- Set the
getattrsoption to specify that the Fullname and Email fields should be populated for autocreated users; the information is taken from the LDAP server.
- Set the
realminusernameoption to specify that the realm should be taken for the SASL user name if it is in UNC or UPN format
Test your LDAP configuration using a command like the following:
$ p4 ldap -t myuser myldapconfig
After you create the configuration, you must enable it using the
auth.ldap.order.N configurable. For example:
$ p4 configure set auth.ldap.order.1=sleepy
(You must restart the server to enable LDAP.)
The configuration is now active and can be used for authentication. You might also have to define additional configurables to define the authentication process. These are described in Defining LDAP-related configurables.
You might need to create multiple LDAP configurations if you are using
multiple directory servers for failover or user management. In this
case, you will need to create an LDAP configuration for each LDAP
server; you must also use the
configurable to specify the order in which they should be searched.
Configurables are keyed on their name, therefore you may not have two
LDAP configurations using the same order number for the same Perforce
Defining LDAP-related configurables
To use LDAP authentication, you must set a number of authentication-related configurables:
auth.ldap.order.- enables an LDAP server and specifies the order in which it should be searched.
auth.default.method- specifies whether new users should be authenticated by Perforce or using LDAP.
dm.user.noautocreateis implied at 2 for
auth.ldap.userautocreate- specifies whether new users should be automatically created on login when using LDAP authentication. This requires
You can set the
getattrsOptions field of the LDAP configuration to have the
dm.user.noautocreate- further controls the behavior of user autocreation.
auth.ldap.timeout- time to wait before giving up on a connection attempt.
auth.ldap.cafile- the path to a file used for certification when the LDAP server uses SSL or TLS.
auth.ldap.ssllevel- level of SSL certificate validation.
auth.ldap.ssllevel- helps you manage LDAP searches with paged results by setting limits to page size.
For example, the following commands define the define the search order
for active directories and the default authentication method for new
users to be
$ p4 configure set auth.ldap.order.1=sleepy $ p4 configure set auth.ldap.order.2=dopey $ p4 configure set auth.ldap.order.5=sneezy $ p4 configure set auth.default.method=perforce
For additional information about authentication-related configurables, see the "Configurables" appendix in the P4 Command Reference.
Authorization using LDAP groups
You use bind methods to configure user authentication, but you don’t want to give everyone in your organization the ability to log in to your Perforce server, especially if everyone is in the same directory. Rather, you should create a group object in the directory that contains only authorized users. The new LDAP integration provides support for checking group membership.
LDAP groups work just like the search bind method, where an LDAP search
query determines whether a user is a member of an allowed group and
whether a search base and scope are also provided. For example, if there
is a group in the LDAP directory named
perforce, whose users are
allowed to access Perforce servers, you might have a configuration like
GroupBaseDN: ou=groups, dc=example, dc=com GroupSearchFilter: (&(objectClass=posixGroup) (cn=perforce) (memberUid=%user%)) GroupSearchScope: subtree
Group objects in Active Directory are slightly different from those in
OpenLDAP: rather than containing a list of member’s user names, they
contain a list of the member’s full DNs. These are not typically easy to
match; however, back references are added to the member’s User objects,
which can be matched. Therefore, when using group authorization against
Active Directory, you will probably need to search for the user’s User
object and check that it contains a
memberOf reference to the group.
GroupBaseDN: ou=users, dc=example, dc=com SearchFilter: (&(objectClass=user) (sAMAccountName=%user%) (memberOf=cn=perforce,ou=groups,dc=example,dc=com)) SearchScope: subtree
Testing and enabling LDAP configurations
Before you enable LDAP configurations, you should create at least one
super access that uses
perforce authentication. This
will allow you to login if by some chance you lose AD/LDAP connectivity.
Having created an LDAP configuration, you must test and enable the configuration. The ability to test your LDAP configurations allows you to make sure everything is working properly without impacting existing users, even if they are already using an authentication trigger to authenticate against LDAP. Once the LDAP configuration proves successful, you can switch users to the new mechanism without having to recreate them. The following steps illustrate the process of testing and activating a configuration.
Test the configuration using the
-tflag on the
p4 ldapcommand; for example:
$ p4 ldap -t Cleopatra sleepy
You will be prompted for the user’s password. If the password is correct, the command completes successfully.
The amount of information returned by testing depends on the bind method used:
- A simple bind returns only pass/fail feedback.
- A search-based bind returns information about whether the user’s credentials are bad and whether the user could be found.
- SASL binds usually provide more diagnostics than simple binds, but results can vary.
auth.ldap.order.to tell Perforce to in what order to use this configuration; for example:
$ p4 configure set auth.ldap.order.1=sleepy
You must set this configurable even if you are only using one configuration.
Check active configurations by running the following command:
$ p4 ldaps -A
Restart the server:
$ p4 admin restart
Check that the server is running in LDAP authentication mode by running the following command:
$ p4 -ztag info
Then check to see that
- Create additional LDAP servers if needed, and repeat steps 1, 2, 3 for each. Of course, if you add more configurations, you will need to assign a different priority to each.
- Migrate users to LDAP authentication by setting the
ldapfor each user to be authenticated by LDAP.
In addition to testing authentication against a single LDAP server, you
can test against multiple servers using the
p4 ldaps -t command.
For more information, see the description of the see the description of
p4 ldaps -t command in the P4 Command Reference.
Getting information about LDAP servers
You can use two commands to get information about LDAP servers:
p4 ldap -ocommand displays information about a single server.
p4 ldapscommand lists all defined servers or, using the
-Aoption, lists only enabled servers in order of priority.
For more information, see the description of the two commands in P4 Command Reference.
Using LDAP with single sign-on triggers
You have the option of using
auth-check-sso type 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.
For information about SSO triggers, see Triggering to use external authentication. For information about group authorization, see the next section.