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.

  1. Set up SSL if needed.
  2. Set up a firewall if needed.
  3. Set up protections for users and user groups.
  4. Review available authentication options and server security levels.
  5. Set the security level for the server.
  6. Define the authentication to be used for existing users and new users.
  7. Create authentication triggers if you are planning to use a non-standard LDAP server.
  8. 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

http://kbportal.perforce.com/article/2484

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.

Note

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 tcp:host:port for plaintext, or ssl:host:port for encrypted connections.

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 file).

Key and certificate management

When configured to accept SSL connections, all server processes (p4d, p4p, 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:

  • P4SSLDIR must be set to a valid directory.
  • The P4SSLDIR directory must be owned by the same userid as the one running the Perforce server, proxy, or broker process. The P4SSLDIR directory must not be readable by any other user. On UNIX, for example, the directory’s permissions must be set to 0700 (drwx------) or 0500 (dr-x------).

  • Two files, named privatekey.txt and certificate.txt, must exist in P4SSLDIR.

    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 (-r--------).

    You can supply your own private key and certificate, or you can use p4d -Gc to generate a self-signed key and certificate pair.

  • To generate a fingerprint from your server’s private key and certificate, run p4d -Gf . (P4SSLDIR must 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 trust to add the fingerprint to their P4TRUST files.

Key and certificate generation

To generate a certificate and private key for your server:

  1. Set P4SSLDIR to a valid directory in a secure location. The directory specified by P4SSLDIR must be secure: owned by the same userid as the one generating the key pair, and it must not be readable by any other user.

  2. Optionally, create a file named config.txt in your P4SSLDIR directory 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 =

  3. Generate the certificate and key pair with the following command:

    p4d -Gc

    If P4SSLDIR (and optionally, config.txt) has been correctly configured, and if no existing private key or certificate is found, two files, named privatekey.txt and certificate.txt, are created in P4SSLDIR.

    If a config.txt file 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=the-DNS-name-of-your-server
EX=730
UNITS=days

  4. Generate a fingerprint for your server’s key and certificate pair.

    p4d -Gf

    This command displays the fingerprint of the server’s public key, and then exits. 

    Fingerprint: CA:BE:5B:77:14:1B:2E:97:F0:5F:31:6E:33:6F:0E:1A:E9:DA:EF:E2

    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.

Note

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 user-supplied credentials.

If you are supplying your own key, your privatekey.txt and 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 with p4d -Gc, it is imperative that these files are stored in a secure location that is readable only by the p4d binary.

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 1.

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 listen on tcp:old-server:1666, and redirect all requests to a target of ssl:new-server:1667. Users of new Perforce applications could use SSL to connect directly to the upgraded Perforce Server (by setting P4PORT to ssl:new-server:1667), while users of older Perforce applications could continue to use plaintext when connecting to a Perforce Broker (by setting P4PORT to old-server:1666). After migration is complete, the broker at old-server:1666 could 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 -Gc and -Gf 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.

Using firewalls

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:

http://answers.perforce.com/articles/KB/2433

Authentication options

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.

Overview

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, db.user.

    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 login or p4 passwd commands 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 security configurable, issue the command: 

$ p4 configure set security=seclevel

where seclevel is 0, 1, 2, 3, or 4.

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 system.

The following table explains the effect of each security level:

Security level Server behavior

0 (or unset)

The default security level 0 does not require passwords and does not enforce password strength.

Users with passwords can use either their P4PASSWD setting or the p4 login command for ticket-based authentication.

1

Ensures that all users have passwords. (Users of old Perforce applications can still enter weak passwords.)

Users with passwords can use either their P4PASSWD setting or the p4 login command for ticket-based authentication.

2

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.

3

Requires that all users have strong passwords, and requires the use of ticket-based (p4 login) authentication.

If you have scripts that rely on passwords, use p4 login to create a ticket valid for the user running the script, or use p4 login -p to display the value of a ticket that can be passed to Perforce commands as though it were a password (that is, either from the command line, or by setting P4PASSWD to the value of the valid ticket).

Setting passwords with the p4 user form or the p4 passwd -O oldpass -P newpass command is prohibited.

4

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:

  • The request must come from a replica with a valid serverid.
  • The serverid must identify a valid server spec.
  • If the server spec has a user field, the request must come from that service user.
  • If the server spec has filters, these are used in preference to whatever filters might have been specified by the replica.

Note

Use the dm.password.minlength configurable to enforce a minimum password length at levels 1 - 3.

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.

The AuthMethod field of the user specification, created with the p4 user command, specifies the authentication method to be used for that user.

  • ldap indicates 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.

  • perforce indicates 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.

The auth.default.method configurable defines the default value for the AuthMethod on new users. Possible values are perforce or ldap.

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 dm.user.noautocreate 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 perforce. 

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 about the auth.default.method configurable, see the description of the p4 configure command and the "Configurables" appendix in the P4 Command Reference.

Note

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).

Warning

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.

Password-based authentication

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 0, 1, and 2.

The default minimum password length is eight characters. Minimum password length is configurable by setting the dm.password.minlength 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 PasswordTimeout: value for that group. For users in multiple groups, the largest defined PasswordTimeout (including unlimited, but ignoring unset) value applies.

The 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 are enabled.)

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 a1b2c3d4, A1B2C3D4, aBcDeFgH are considered strong in an environment in which dm.password.minlength is 8, and security is configurable to at least 2.

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 can run: 

$ 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 username

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 username

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

Running 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

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 Timeout: 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 Timeout: field to unlimited.

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 3 and 4.

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 p4 login command.

    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 using the 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 p4 login after multiple failed login attempts. To alter this behavior, set dm.user.loginattempts to the maximum allowable failed login attempts before the service imposes a 10-second delay on subsequent login attempts.

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.

Note

The auth.csv log is used to log the results of p4 login 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:

  1. The user logs in, specifying a name and password.

  2. 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.user table; it then issues a ticket if validation succeeds.

  3. The server checks the user record to see which authentication method to use: ldap or perforce.

    • If 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.
    • If perforce, the server validates the user against the db.user table 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, and 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 p4 logout command to invalidate a user’s ticket. The following command invalidates Joe’s ticket. 

$ p4 logout -a joe

LDAP Authentication

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.

Note

Create at least one account with super access that uses perforce authentication. This will allow you to login if by some chance you lose AD/LDAP connectivity.

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 ldap command 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 AuthMethod field 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.

Note

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 auth.ldap.order.N configurable.
  • You disable LDAP authentication by removing or disabling all existing LDAP configurations. You remove an LDAP configuration by using the -d option to the p4 ldap command. You disable all LDAP configurations by having no auth.ldap.order.N configurables set.
  • LDAP implies at least security level 3.

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 the 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: 

    BindMethod: sasl

    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 SaslRealm field 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. 

    uid=jsmith,ou=users,dc=example,dc=com

    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 SearchBaseDN, SearchFilter, and SearchScope fields 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 SearchBindDN and SearchPasswd fields 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 downcase option to specify that user names should be downcased from the directory on an LDAP sync.
  • Set the getattrs option to specify that the Fullname and Email fields should be populated for autocreated users; the information is taken from the LDAP server.
  • Set the realminusername option 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 auth.ldap.order.N 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 server.

Defining LDAP-related configurables

To use LDAP authentication, you must set a number of authentication-related configurables:

  • auth.ldap.order.N - 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.noautocreate is implied at 2 for auth.default.method=ldap

  • auth.ldap.userautocreate - specifies whether new users should be automatically created on login when using LDAP authentication. This requires auth.default.method=ldap.

    You can set the getattrs Options field of the LDAP configuration to have the FullName and Email fields populated from the directory.

  • 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 perforce: 

$ 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 this: 

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. For example: 

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 account with 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.

  1. Test the configuration using the -t flag on the p4 ldap command; 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.

  2. Define the auth.ldap.order.N 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.

  3. Check active configurations by running the following command:

    $ p4 ldaps -A

  4. Restart the server:

    $ p4 admin restart

  5. Check that the server is running in LDAP authentication mode by running the following command: 

    $ p4 -ztag info

    Then check to see that ldapAuth is enabled.

  6. 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.
  7. Migrate users to LDAP authentication by setting the authMethod to ldap for 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 the 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:

  • The p4 ldap -o command displays information about a single server.
  • The p4 ldaps command lists all defined servers or, using the -A option, 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.

Authorizing access

Perforce provides a protection scheme to prevent unauthorized or inadvertent access to files in the depot. The protections determine which Perforce commands can be run, on which files, by whom, and from which host. You configure protections with the p4 protect command.

Note

Protections apply to files in the depot only. They do not apply to forms: changelists, workspace views, and so on.

When should protections be set?

Run p4 protect immediately after installing Perforce for the first time. Before the first call to p4 protect, every Perforce user is a superuser and thus can access and change anything in the depot. The first time a user runs p4 protect, a protections table is created that gives superuser access to the user from all IP addresses, and lowers all other users' access level to write permission on all files from all IP addresses.

The Perforce protections table is stored in the db.protect file in the server root directory; if p4 protect is first run by an unauthorized user, the depot can be brought back to its unprotected state by removing this file.

Setting protections with p4 protect

The p4 protect form contains a single form field called Protections: that consists of multiple lines. Each line in Protections: contains subfields, and the table looks like this:

Example 4. A sample protections table

Protections:
    read     user     emily   *                    //depot/elm_proj/...
    write    group    devgrp  *                    //...
    write    user     *       192.168.41.0/24     -//...
    write    user     *       [2001:db8:1:2::]/64 -//...
    write    user     joe     *                   -//...
    write    user     lisag   *                   -//depot/...
    write    user     lisag   *                    //depot/doc/...
    super    user     edk     *                    //...

(The five fields might not line up vertically on your screen; they are aligned here for readability.)

Note

If your site makes use of the Perforce Proxy or broker, prepend proxy- to the addresses in the host field to make the lines apply to users of the proxy or broker. For detailed information, see the material on "P4P and protections" in Helix Versioning Engine Administrator Guide: Multi-site Deployment.

The permission lines' five fields

Each line specifies a particular permission level and/or access right, as defined by five fields:

Field Meaning

Access Level

Which access level (list, read, open, write, review, owner, admin, or super) or specific right (=read, =open, =write, or =branch) is being granted or denied.

  • Each permission level includes all the permissions above it (except for review).
  • Each permission right (denoted by an =) only includes the specific right and not all of the lesser rights.

In general, one typically grants an access level to a user or group, after which, if finer-grained control is required, one or more specific rights may then be denied.

User/Group

Does this protection apply to a user or a group?

Name

The user or group whose protection level is being defined. This field can contain the * wildcard. A * by itself grants this protection to everyone, *e grants this protection to every user (or group) whose username ends with an e.

Host

The TCP/IP address of the host being granted access. This must be provided as the numeric address of either one specific host (for instance, 192.168.41.2 or [2001:db8:195:1:2::1234]) or a subnet expressed in CIDR notation.

The host field can also contain the * wildcard. A * by itself means that this protection is being granted for all hosts. The wildcard can be used as in any string, so 192.168.41.* is equivalent to 192.168.41.0/24.

You cannot combine the * wildcard with CIDR notation, except at the start of a line when controlling proxy matching. If you are using IPv6 with the * wildcard, you must enclose the address with square brackets. [2001:db8:1:2:*] is equivalent to [2001:db8:1:2::]/64. Best practice is to use CIDR notation, surround IPv6 addresses with brackets, and to avoid the * wildcard.

For more about controlling access to a Perforce server via the Perforce Proxy, see the relevant chapter of Helix Versioning Engine Administrator Guide: Multi-site Deployment.

Files

A file specification representing the files in the depot on which permissions are being granted. Perforce wildcards can be used in the specification.

"//..." means all files in all depots.

If a depot is excluded, the user denied access will no longer see the depot in the output of p4 depots. Nor will the depot show up, for this user, in the default branch, client, and label views.

Access levels

The access level is described by the first value on each line. The permission levels and access rights are described in the following table:

Level Meaning

list

Permission is granted to run Perforce commands that display file metadata, such as p4 filelog. No permission is granted to view or change the contents of the files.

read

The user can run those Perforce commands that are needed to read files, such as p4 client and p4 sync. The read permission includes list access.

=read

If this right is denied, users cannot use p4 print, p4 diff, or p4 sync on files.

open

Grants permission to read files from the depot into the client workspace, and gives permission to open and edit those files. This permission does not permit the user to write the files back to the depot. The open level is similar to write, except that with open permission, users are not permitted to run p4 submit or p4 lock.

The open permission includes read and list access.

=open

If this right is denied, users cannot open files with p4 add, p4 edit, p4 delete, or p4 integrate.

write

Permission is granted to run those commands that edit, delete, or add files. The write permission includes read, list, and open access.

This permission allows use of all Perforce commands except protect, depot, obliterate, and verify.

=write

If this right is denied, users cannot submit open files.

=branch

If this right is denied, users may not use files as a source for p4 integrate.

review

Provides list and read access, plus use of the p4 review command. This is a special permission granted to review scripts.

owner

Allows access to the p4 protect command to the specified user or group, for the specified path. See Delegate management of parts of the protections table for details.

admin

For Perforce administrators; grants permission to run Perforce commands that affect metadata, but not server operation. Provides write and review access plus the added ability to override other users' branch mappings, client specifications, jobs, labels, and change descriptions, as well as to update the typemap table, verify and obliterate files, and customize job specifications.

super

For Perforce superusers; grants permission to run all Perforce commands. Provides write, review, and admin access plus the added ability to create depots and triggers, edit protections and user groups, delete users, reset passwords, and shut down the server.

Each Perforce command is associated with a particular minimum access level. For example, to run p4 sync or p4 print on a particular file, the user must have been granted at least read access on that file. For a full list of the minimum access levels required to run each Perforce command, see How protections are implemented.

The specific rights of =read, =open, =write, and =branch can be used to override the automatic inclusion of lower access levels. This makes it possible to deny individual rights without having to then re-grant lesser rights.

For example, if you want administrators to have the ability to run administrative commands, but to deny them the ability to make changes in certain parts of the depot, you could set up a permissions table as follows: 

admin      user      joe       *             //...
=write     user      joe       *             -//depot/build/...
=open      user      joe       *             -//depot/build/...

In this example, user joe can perform administrative functions, and this permission applies to all depots in the system. Because the admin permission level also implies the granting of all lower access levels, joe can also write, open, read and list files anywhere in the system, including //depot/build/. To protect the build area, the =write and =open exclusionary lines are added to the table. User joe is prevented from opening any files for edit in the build area. He is also prevented from submitting any changes in this area he may already have open. He can continue to create and modify files, but only if those files are outside of the protected //depot/build/... area.

Default protections

Before p4 protect is invoked, every user has superuser privileges. When p4 protect is first run, two permissions are set by default. The default protections table looks like this: 

write        user        *        *        //...
super        user        edk      *        //...

This indicates that write access is granted to all users, on all hosts, to all files. Additionally, the user who first invoked p4 protect (in this case, edk) is granted superuser privileges.

Which users should receive which permissions?

The simplest method of granting permissions is to give write permission to all users who don’t need to manage the Perforce system and super access to those who do, but there are times when this simple solution isn’t sufficient.

Read access to particular files should be granted to users who never need to edit those files. For example, an engineer might have write permission for source files, but have only read access to the documentation, and managers not working with code might be granted read access to all files.

Because open access enables local editing of files, but does not permit these files to be written to the depot, open access is granted only in unusual circumstances. You might choose open access over write access when users are testing their changes locally but when these changes should not be seen by other users. For instance, bug testers might need to change code in order to test theories as to why particular bugs occur, but these changes are not to be written to the depot. Perhaps a codeline has been frozen, and local changes are to be submitted to the depot only after careful review by the development team. In these cases, open access is granted until the code changes have been approved, after which time the protection level is upgraded to write and the changes submitted. open access is also useful with shelves. Using open is enough to shelve changes but not submit them and can be useful for code reviews.

Interpreting multiple permission lines

The access rights granted to any user are defined by the union of mappings in the protection lines that match her user name and client IP address. (This behavior is slightly different when exclusionary protections are provided and is described in the next section.)

Example 5. Multiple permission lines

Lisa, whose Perforce username is lisag, is using a workstation with the IP address 195.42.39.17. The protections file reads as follows: 

read      user    *        195.42.39.17     //...
write     user    lisag    195.42.39.17     //depot/elm_proj/doc/...
read      user    lisag    *                //...
super     user    edk      *                //...

The union of the first three permissions applies to Lisa. Her username is lisag, and she’s currently using a client workspace on the host specified in lines 1 and 2. Thus, she can write files located in the depot’s elm_proj/doc subdirectory but can only read other files. Lisa tries the following:

She types p4 edit depot/elm_proj/doc/elm-help.1, and is successful.

She types p4 edit //depot/elm_proj/READ.ME, and is told that she doesn’t have the proper permission. She is trying to write to a file to which has only read access. She types p4 sync depot/elm_proj/READ.ME, and this command succeeds, because only read access is needed, and this is granted to her on line 1.

Lisa later switches to another machine with IP address 195.42.39.13. She types p4 edit //depot/elm_proj/doc/elm-help.1, and the command fails; when she’s using this host, only the third permission applies to her, and she only has read privileges.

Delegate management of parts of the protections table

It is possible to delegate management of parts of the protections table to non-super users or groups, by creating an entry with the mode owner. These entries must have a unique path, without wildcards except for a trailing ellipsis (…​).

Users with super or that have been granted owner for a path may run the p4 protect command specifying the granted path as an argument, accessing the sub-protections table for that path.

The server appends any entries in this table to the effective protections table directly below the 'owner' entry; if an 'owner' entry is removed, so are any entries in the sub-protections table for that path. Neither 'owner' nor 'super' entries may be added to a sub-protections table, and any other entries' paths must be within the scope of the sub-protections table’s path.

If a path argument is specified, and an 'owner' entry with the same path exists, then the sub-protections table for that path will be accessed instead of the main protections table.

Suppose super user Bruno issues the following commands:

# Create a user called Sally
$ p4 user -f sally

# Create a depot called stats
$ p4 depot stats

# Edit the protections table
$ p4 protect

The last command opens the protections table in an editor. Let’s suppose the protections table contains the following lines: 

Protections:
    write user * * //...
    super user bruno * //...

Suppose Bruno wants to delegate control of the sub-protections table for the path //stats/dev/…​ to Sally. He edits the protections table to append the necessary line to the protections table, which now looks like this: 

Protections:
    write user * * //...
    super user bruno * //...
    owner user sally * //stats/dev/...

Exclusionary protections

A user can be denied access to particular files by prefacing the fifth field in a permission line with a minus sign (-). This is useful for giving most users access to a particular set of files, while denying access to the same files to only a few users.

To use exclusionary mappings properly, it is necessary to understand some of their peculiarities:

  • When an exclusionary protection is included in the protections table, the order of the protections is relevant: the exclusionary protection is used to remove any matching protections above it in the table.
  • No matter what access level is provided in an exclusionary protection, all access levels for the matching files and IP addresses are denied. The access levels provided in exclusionary protections are irrelevant. See How protections are implemented for a more detailed explanation.
  • Without exclusionary mappings, the order of items in the protections table is not important.

Example 6. Exclusionary protections

An administrator has used p4 protect to set up protections as follows: 

write       user       *           *       //...
read        user       emily       *       //depot/elm_proj/...
super       user       joe         *       -//...
list        user       lisag       *       -//...
write       user       lisag       *       //depot/elm_proj/doc/...

The first permission looks like it grants write access to all users to all files in all depots, but this is overruled by later exclusionary protections for certain users.

The third permission denies Joe permission to access any file from any host. No subsequent lines grant Joe any further permissions; thus, Joe has been effectively denied any file access.

The fourth permission denies Lisa all access to all files on all hosts, but the fifth permission gives her back write access on all files within a specific directory. If the fourth and fifth lines were switched, Lisa would be unable to run any Perforce command.

Displaying protections for a user, group, or path.

Use the p4 protects command to display the lines from the protections table that apply to a user, group, or set of files.

With no options, p4 protects displays the lines in the protections table that apply to the current user. If a file argument is provided, only those lines in the protection table that apply to the named files are displayed. Using the -m flag displays a one-word summary of the maximum applicable access level, ignoring exclusionary mappings.

Perforce superusers can use p4 protects -a to see all lines for all users, or p4 protects -u user, -g group, or -h host flags to see lines for a specific user, group, or host IP address.

Use the -s option to display protection information from a protect table referenced by the file revision specified with the spec argument. For example, the following command returns information about the user sam in the third revision of the protections table: 

C:\> p4 -u super protects -s //spec/protect.p4s#3 -u sam
write user* * //...

This is useful when users lose access privileges at a given point in time and you want to check what changes were made to the protection table just before that date.

Note

To use this option, you must define a spec depot for protect forms; this automatically saves revisions to the protect specification every time you edit the protection table. See the description of the p4 depot command in the P4 Command Reference for information on how to create a spec depot.

Granting access to groups of users

Perforce groups simplify maintenance of the protections table. The names of users with identical access requirements can be stored in a single group; the group name can then be entered in the table, and all the users in that group receive the specified permissions.

Groups are maintained with p4 group, and their protections are assigned with p4 protect. Only Perforce superusers can use these commands. (Perforce administrators can use p4 group -A to administer a group, but only if the group does not already exist.)

For information about groups and LDAP, see Synchronizing Perforce groups with LDAP groups.

Creating and editing groups

If p4 group groupname is called with a nonexistent groupname, a new group named groupname is created. Calling p4 group with an existing groupname allows editing of the user list for this group.

To add users to a group, add user names in the Users: field of the form generated by the p4 group groupname command. User names are entered under the Users: field header; each user name must be typed on its own line, indented. A single user can be listed in any number of groups. Group owners are not necessarily members of a group; if a group owner is to be a member of the group, the userid must also be added to the Users: field.

Groups can contain other groups as well as individual users. To add all users in a previously defined group to the group you’re working with, include the group name in the Subgroups: field of the p4 group form. User and group names occupy separate namespaces, so groups and users can have the same names.

Adding nonexistent users to group definitions does not actually create the users, nor does it consume licenses; use the p4 user command to create users.

Groups and protections

To use a group with the p4 protect form, specify a group name instead of a user name in any line in the protections table and set the value of the second field on the line to group instead of user. All the users in that group are granted the specified access.

Example 7. Granting access to Perforce groups

This protections table grants list access to all members of the group devgrp, and super access to user edk: 

list        group        devgrp      *        //...
super       user         edk         *        //...

According to the following three permission lines, group ac1 will have write access to //ac1/... while giving the group read-only access to //ac1/ac1_dev/.... 

write        group        ac1      *        //ac1/...
list         group        ac1      *        -//ac1/ac1_dev/...
read         group        ac1      *        //ac1/ac1_dev/...

If a user belongs to multiple groups, one permission can override another. For instance, if you use exclusionary mappings to deny access to an area of the depot to members of group1, but grant access to the same area of the depot to members of group2, a user who is a member of both group1 and group2 is either granted or denied access based on whichever line appears last in the protections table. The actual permissions granted to a specific user can be determined by replacing the names of all groups to which a particular user belongs with the user’s name within the protections table and applying the rules described earlier in this chapter.

Synchronizing Perforce groups with LDAP groups

You can configure Perforce to automatically synchronize the contents of a given Perforce user group with that of an LDAP group. Protections are still assigned based on the identity of the Perforce group (using the p4 protect command), but which users are included in the Perforce group is determined by the membership of the LDAP group.

Synchronization can happen once or at specified intervals. See the description of the p4 ldapsync command in the P4 Command Reference for additional information.

Before you configure group synchronization, you need to define an LDAP configuration.

Note

If the LDAP server requires login for read-only queries, the LDAP configuration must contain valid bind credentials in the LDAP spec’s SearchBindDN and SearchPasswd fields.

To configure group synchronization, you must do the following:

  1. Define the following fields in the Perforce group spec:

    • LdapConfig: The name of an LDAP configuration created using the p4 ldap command.

      The LDAP configuration provides the hostname, port, and encryption for the LDAP connection; it also specifies how authentication is to be done using the SearchBindDN, SearchPasswd, and GroupSearchBaseDN fields.

    • LdapSearchQuery: The search query to identify the group member records.
    • LdapUserAttribute: The attribute that contains the group member’s user id. This user name is added to the Perforce group.
  2. Define a group owner for the Perforce group. The owner does not have to be a member of the corresponding LDAP group.

  3. Use the p4 ldapsync command, specifying which Perforce group(s) should be synchronized, to test the anticipated results using a command like the following. 

    $ p4 ldapsync -g -n my-perforce-group1 my-perforce-group2

    p4 ldapsync uses the context provided by the LDAP configuration to execute the search query and collect all the defined attributes from the results that are returned. The resultant list becomes the members list of the group.

  4. If you are satisfied with the preview results, run p4 ldapsync again (without -n) to synchronize the groups.

    To schedule synchronization to occur at regular intervals, you must make the p4 ldapsync command run at startup time and specify the value of the interval. For details see the description of the p4 ldapsync command in P4 Command Reference.

The following examples, included in Synchronizing with Active Directory and Synchronizing with OpenLDAP, demonstrate two ways in which you can define group synchronization. These examples illustrate how configurations depend on how references to users and groups are stored on different servers:

  • OpenLDAP stores a list of memberUid’s in its group records; these can often be used directly as Perforce user names.
  • Active Directory stores a list of member’s full DN’s in its group records, and the full DN of each group a user belongs to in its user records; in this case, you need to look for the user records that contain the back reference to the group instead of finding the group record directly.

Note the difference in the GroupBaseDn in the LDAP spec. In Active Directory, we’re looking for users who are in the group; in OpenLDAP, we’re looking for groups that contain users. This affects the path we’re searching under.

In the following examples, both servers have user under the DN ou=users,dc=example,dc=com. We will be creating a Perforce group called development that is populated from the LDAP group cn=development,ou=groups,dc=example,dc=com.

Synchronizing with Active Directory

We begin with a sample LDAP configuration named my-ad-example defined as follows: 

Name:              my-ad-example
Host:              ad.example.com
Port:              389
Encryption:        tls
BindMethod:        search
SearchBaseDN:      ou=users,dc=example,dc=com
SearchFilter:      (&(objectClass=user)(sAMAccountName=%user%))
SearchBindDN:      cn=read-only,ou=users,dc=example,dc=com
SearchPasswd:      password
SearchScope:       subtree
GroupBaseDN:       ou=users,dc=example,dc=com
GroupSearchScope:  subtree

The group spec created by the command p4 group development, would then look like this: 

Group:             development
LdapConfig:        my-ad-example
LdapSearchQuery:   (&(objectClass=user)(memberOf=cn=development,ou=groups,
                                                       dc=example,dc=com))
LdapUserAttribute: sAMAccountName
Owners:            super
Synchronizing with OpenLDAP

We begin with a sample LDAP configuration named my-openldap-example defined as follows: 

Name:              my-openldap-example
Host:              openldap.example.com
Port:              389
Encryption:        tls
BindMethod:        search
SearchBaseDN:      ou=users,dc=example,dc=com
SearchFilter:      (&(objectClass=inetOrgPerson)(uid=%user%))
SearchBindDN:      cn=read-only,ou=users,dc=example,dc=com
SearchPasswd:      password
SearchScope:       subtree
GroupBaseDN:       ou=groups,dc=example,dc=com
GroupSearchScope:  subtree

The group spec created by the command p4 group development, would then look like this: 

Group:             development
LdapConfig:        my-openldap-example
LdapSearchQuery:   (&(objectClass=posixGroup)(cn=development))
LdapUserAttribute: memberUid
Owners:            super

Deleting groups

To delete a group, invoke

$ p4 group -d groupname

Alternately, invoke p4 group groupname and delete all users, subgroups, and owners from the group in the resulting editor form. The group will be deleted when the form is closed.

Comments in protection tables

Protection tables can be difficult to interpret and debug. Including comments can make this work much easier.

  • You can append comments at the end of a line using the ## symbols: 

    write user *   10.1.1.1   //depot/test/...  ## robinson crusoe

  • Or you can write a comment line by prefixing the line with the ## symbols: 

    ## robinson crusoe
write user *   10.1.1.1   //depot/test/...

Warning

Comments you have created using the P4Admin tool are not compatible with comments created using the 2016.1 version of p4 protect. You can use the following command to convert a file containing comments created with P4Admin into a file containing p4 protect type comments: 

$ p4 protect --convert-p4admin-comments -o

Then save the resulting file.

Once you have converted the comments, you must continue to define and manage protections using p4 protect and can no longer use P4Admin to do so because this tool is unable to parse p4 protect comments.

How protections are implemented

This section describes the algorithm that Perforce follows to implement its protection scheme. Protections can be used properly without reading this section; the material here is provided to explain the logic behind the behavior described above.

Users' access to files is determined by the following steps:

  1. The command is looked up in the command access level table shown in Access Levels Required by Perforce Commands to determine the minimum access level needed to run that command. In our example, p4 print is the command, and the minimum access level required to run that command is read.

  2. Perforce makes the first of two passes through the protections table. Both passes move up the protections table, bottom to top, looking for the first relevant line.

    The first pass determines whether the user is permitted to know if the file exists. This search simply looks for the first line encountered that matches the user name, host IP address, and file argument. If the first matching line found is an inclusionary protection, the user has permission to at least list the file, and Perforce proceeds to the second pass. Otherwise, if the first matching protection found is an exclusionary mapping, or if the top of the protections table is reached without a matching protection being found, the user has no permission to even list the file, and will receive a message such as File not on client.

    Example 8. Interpreting the order of mappings in the protections table

    Suppose the protections table is as follows:

    write       user        *        *      //...
read        user        edk      *      -//...
read        user        edk      *      //depot/elm_proj/...

    If Ed runs p4 print //depot/file.c, Perforce examines the protections table bottom to top, and first encounters the last line. The files specified there don’t match the file that Ed wants to print, so this line is irrelevant. The second-to-last line is examined next; this line matches Ed’s user name, his IP address, and the file he wants to print; since this line is an exclusionary mapping, Ed isn’t allowed to list the file.

  3. If the first pass is successful, Perforce makes a second pass at the protections table; this pass is the same as the first, except that access level is now taken into account.

    If an inclusionary protection line is the first line encountered that matches the user name, IP address, and file argument, and has an access level greater than or equal to the access level required by the given command, the user is given permission to run the command.

    If an exclusionary mapping is the first line encountered that matches according to the above criteria, or if the top of the protections table is reached without finding a matching protection, the user has no permission to run the command, and receives a message such as: 

    You don't have permission for this operation

Access Levels Required by Perforce Commands

The following table lists the minimum access level required to run each command. For example, because p4 add requires at least open access, you can run p4 add if you have open, write, admin, or super access

Command Access Level Notes

add

open

  

admin

super

  

annotate

read

  

archive

admin

  

attribute

write

The -f flag to set the attributes of submitted files requires admin access.

branch

open

The -f flag to override existing metadata or other users' data requires admin access.

branches

list

  

cachepurge

super

  

change

open

The -o flag (display a change on standard output) requires only list access. The -f flag to override existing metadata or other users' data requires admin access.

changes

list

This command doesn’t operate on specific files. Permission is granted to run the command if the user has the specified access to at least one file in any depot.

clean

read

  

client

list

The -f flag to override existing metadata or other users' data requires admin access.

clients

list

  

clone

read

On the remote server.

configure

super

  

copy

list

list access to the source files; open access to the destination files.

counter

review

list access to at least one file in any depot is required to view an existing counter’s value; review access is required to change a counter’s value or create a new counter.

counters

list

  

cstat

list

  

dbschema

super

  

dbstat

super

  

dbverify

super

  

delete

open

  

depot

super

The -o flag to this command, which allows the form to be read but not edited, requires only list access.

depots

list

This command doesn’t operate on specific files. Permission is granted to run the command if the user has the specified access to at least one file in any depot.

describe

read

The -s flag to this command, which does not display file content, requires only list access.

diff

read

  

diff2

read

  

dirs

list

  

diskspace

super

  

edit

open

  

export

super

  

fetch

admin

  

filelog

list

  

files

list

  

fix

open

  

fixes

list

This command doesn’t operate on specific files. Permission is granted to run the command if the user has the specified access to at least one file in any depot.

flush

list

  

fstat

list

  

grep

read

  

group

super

The -o flag to this command, which allows the form to be read but not edited, requires only list access.

The -a flag to this command requires only list access, provided that the user is also listed as a group owner.

The -A flag requires admin access.

groups

list

This command doesn’t operate on specific files. Permission is granted to run the command if the user has the specified access to at least one file in any depot.

have

list

  

help

none

  

ignores

N/A

  

info

none

  

init

N/A

  

integrate

open

The user must have open access on the target files and read access on the source files.

integrated

list

  

interchanges

list

  

istat

list

  

job

open

The -o flag to this command, which allows the form to be read but not edited, requires only list access.

The -f flag to override existing metadata or other users' data requires admin access.

jobs

list

This command doesn’t operate on specific files. Permission is granted to run the command if the user has the specified access to at least one file in any depot.

jobspec

admin

The -o flag to this command, which allows the form to be read but not edited, requires only list access.

journalcopy

super

  

journaldbchecksums

super

  

journals

super or operator

  

key

review

list access to at least one file in any depot is required to view an existing key’s value; review access is required to change a key’s value or create a new key.

key

list

admin access is required if the dm.keys.hide configurable is set to 2.

keys

list

admin access is required if the dm.keys.hide configurable is set to 1 or 2.

label

open

This command doesn’t operate on specific files. Permission is granted to run the command if the user has the specified access to at least one file in any depot.

The -f flag to override existing metadata or other users' data requires admin access.

labels

list

This command doesn’t operate on specific files. Permission is granted to run the command if the user has the specified access to at least one file in any depot.

labelsync

open

  

ldap

super

  

ldaps

super

  

ldapsync

super

  

license

super

The -u flag, which displays license usage, requires only admin access.

list

open

  

lock

write

  

lockstat

super

  

logappend

list

  

logger

review

  

login

list

  

logout

list

  

logparse

super

  

logrotate

super

  

logschema

super

  

logstat

super

  

logtail

super

  

merge

open

  

monitor

list

super access is required to terminate or clear processes, or to view arguments.

move

open

  

obliterate

admin

  

opened

list

  

passwd

list

  

ping

admin

  

populate

open

  

print

read

  

property

list, admin

list to read, admin to add/delete new properties, or show a property setting and sequence number for all users and groups.

protect

super

  

protects

list

super access is required to use the -a, -g, and -u flags.

proxy

none

Must be connected to a Perforce Proxy.

prune

write

For stream owner.

pull

super

  

push

read or write

read on the local server or write on the remote server.

reconcile

open

  

reload

open

admin access is required to use p4 reload -f to reload other users' workspaces and labels.

remote

open or list or admin

open or list to use the -o option or admin to use the -f option.

remotes

list

  

rename

read or write

read for fromFile or write for toFile.

renameuser

super

  

reopen

open

  

replicate

super

  

resolve

open

  

resolved

open

  

restore

admin

  

resubmit

write or admin

write or admin for -i option.

revert

list

  

review

review

This command doesn’t operate on specific files. Permission is granted to run the command if the user has the specified access to at least one file in any depot.

reviews

list

This command doesn’t operate on specific files. Permission is granted to run the command if the user has the specified access to at least one file in any depot.

server

super

  

serverid

list

super access is required to set the server ID.

servers

list

  

set

none

  

shelve

open

admin access is required to forcibly delete shelved files with p4 shelve -f -d

sizes

list

  

status

open

  

stream

open

  

streams

list

  

submit

write

  

switch

open or list or write

open to use the -c or -r options, or list to use the -L, or write for default switching.

sync

read

  

tag

list

  

tickets

none

  

triggers

super

  

trust

none

  

typemap

admin

The -o flag to this command, which allows the form to be read but not edited, requires only list access.

unload

open

admin access is required to use p4 unload -f to unload other users' workspaces and labels.

unlock

open

The -f flag to override existing metadata or other users' data requires admin access.

unshelve

open

  

unsubmit

admin

  

unzip

admin

  

update

list

  

user

list

This command doesn’t operate on specific files. Permission is granted to run the command if the user has the specified access to at least one file in any depot.

The -f flag (which is used to create or edit users) requires super access.

users

list

This command doesn’t operate on specific files. Permission is granted to run the command if the user has the specified access to at least one file in any depot.

If the run.users.authorize configurable is set to 1, you must also authenticate yourself to the server before you can run p4 users.

verify

admin

  

where

list

This command doesn’t operate on specific files. Permission is granted to run the command if the user has the specified access to at least one file in any depot.

workspace

list

  

workspaces

list

  

zip

super

  

Commands that list files, such as p4 describe, list only those files to which the user has at least list access.

Some commands (for example, p4 change, when you edit a previously submitted changelist) take a -f flag that can only be used by Perforce superusers. See Forcing operations with the -f flag for details.