Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 CLI Reference | 2025.1

# p4 ldap

Create, display, edit, or delete an LDAP configuration specification, or test an existing LDAP configuration.

## Syntax

    p4 [g-opts] ldap configname
    p4 [g-opts] ldap -i
    p4 [g-opts] ldap -o configname
    p4 [g-opts] ldap -d configname
    p4 [g-opts] ldap -t username configname

Syntax conventions

## Description

The `p4 ldap` command includes five syntax variants:

- The first variant allows you to create or edit an LDAP configuration.
- The `p4 ldap -i` command allows you to read an LDAP configuration from standard input.
- The `p4 ldap -o` command allows you to display the specified LDAP configuration.
- The `p4 ldap -d` command allows you to delete the specified LDAP configuration.
- The `p4 ldap -t` command allows you to test an existing LDAP configuration.

LDAP queries for a user are performed as that user. Therefore, a user must be a member of a group before that user can see that group. (See Authorization using LDAP groups in the P4 Server Administration Documentation.)

This command cannot be run from a read-only or build replica.

### Creating an LDAP Configuration

The LDAP configuration you create with the `p4 ldap` command defines an Active Directory or other LDAP server against which the P4 Servercan authenticate users.

To create an LDAP configuration specification, you provide values that specify the host and port of the AD/LDAP server, bind method information, and security parameters. Bind methods can be one of the following:

- Simple: Uses a template based on the user’s name to produce a distinguished name that the P4 Server attempts to bind against, validating the user’s password. For example:

      uid=%user%,ou=users,dc=example,doc=org

- Search: Uses an LDAP search query to locate the user record. 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 required 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 is a sample search query:

      BaseDN: ou=users,dc=example,dc=org
      LDAP query: (uid=%user%)

- SASL: If the AD/LDAP server supports `SASL DIGEST-MD5`, this method defers the user search to the AD/LDAP server and does not require a distinguished name to be discovered before the bind is attempted. The user provides a user name, a password, and an optional realm.

In addition to creating the LDAP configuration, you must use the following configurables to enable the configuration and to further define the authentication process:

- auth.ldap.order.N - enables an AD/LDAP server and specifies the order in which it should be searched.
- auth.default.method - specifies whether new users should be authenticated by P4 Server or using LDAP.
- auth.ldap.userautocreate - specifies whether new users should be automatically created on login when using LDAP authentication.
- auth.ldap.timeout - time to wait before giving up on a connection.
- auth.ldap.cafile - the path to a file used for certification when the AD/LDAP server uses SSL or TLS.
- auth.ldap.ssllevel - level of SSL/TLS certificate validation.

LDAP configurations are stored in the `db.ldap` table. This table is journaled, so LDAP configurations are included in checkpoints and are replicated.

Authentication is user-based.

The LDAP authentication method is selected for each existing user with the `AuthMethod` field of the user specification. For more information, see the `p4 user` command.

The authentication method applied to auto-created users (LDAP or Perforce) is determined by the `auth.userautocreate` configurable. For more information, see Configurables.

A sample LDAP configuration:

    Name:     myLDAPconfig
    Host:     openldap.example.com
    Port:     389
    Encryption:    tls
    BindMethod:    search
    Options: nodowncase nogetattrs norealminusername
    SimplePattern: someuserid
    SearchBaseDN:  ou=employees,dc=example,dc=com
    SearchFilter:  (cn=%user%)
    SearchScope:    subtree
    GroupSearchScope:  subtree

### Testing an LDAP Configuration

Use a command like the following to test an LDAP configuration:

    p4 ldap -t Maria myLDAPconfig

The command prompts you for a password and returns successfully if user `Maria` can be found. If the AD/LDAP server specified by `myLDAPconfig` is down, if the user can’t be found, or if the password you supply is incorrect, the command returns an error message. For example:

    c:\temp> p4 -p 1666 ldap -t Maria myLDAPconfig

    Enter password:
    Authentication as cn=Maria,ou=employees,dc=example,dc=com
    failed. Reason: Invalid Credentials

### Form Fields

Field Name | Type | Description
--- | --- | ---
`Name:` | Read only | The name of the LDAP configuration. Relevant to bind method: all
`Host:` | Writable | Fully qualified domain name of AD/LDAP server. The default is `localhost`. Relevant to bind method: all
`Port:` | Writable | The port to connect on. The default is `389`. Relevant to bind method: all Port 389 has historically been used for unencrypted connections into an LDAP server. Port 636 is used for legacy SSL/TLS connections. Port 389 is used for TLS connections; TLS establishes a non encrypted connection on port 389 that it 'upgrades' to an encrypted TLS connection as the initial connection proceeds. This allows unencrypted and encrypted connections to be setup and handled by this one port. The Perforce LDAP specification must therefore have the specified 'Port:' field corresponding to the relevant encryption method in the 'Encryption:' ('none', 'ssl' or 'tls') field.
`Encryption:` | Writable | One of `none`, `ssl`, and `tls`. The default is `tls`. Relevant to bind method: all
`BindMethod:` | Writable | One of `simple`, `search`, and `sasl`. See Creating an LDAP Configuration above for more details. Relevant to bind method: all
`Options` | Writable | Modifies the behavior of the LDAP integration that is specific to this configuration. Choose from the following: [no]downcase specifies whether `p4 ldapsync -g` should downcase user names from the directory. For example, if user names in LDAP are ABrown, and SMITH, they are added to the group as `abrown` and `smith`. [no]getattrs specifies whether the `Fullname` and `Email` fields for users auto created with `p4 login` should be populated from the directory. This requires that you set the `AttributeName` and/or `AttributeEmail` fields in the ldap spec. See below. [no]realminusername specifies whether the realm should be taken from the SASL username if it is in UNC or UPN format. That is, if your user names look like this: `user@realm` or `realm\user`, the user and realm are separated and passed separately. By default, these options are not set.
`SimplePattern:` | Writable | The distinguished name used to bind against to validate the user’s credentials. The `%user%` placeholder is replaced with the user’s `userId`. Relevant to bind method: simple
`SearchBaseDN:` | Writable | The distinguished name from which to start the search for the user object. Relevant to bind method: search
`SearchFilter:` | Writable | The LDAP query filter that identifies the user object to bind against. The `%user%` placeholder is replaced with the user’s `userId`. Relevant to bind method: search
`SearchScope:` | Writable | One of the following: baseonly - search just the `BaseDN` object. children - search the `BaseDN` object and its direct children. subtree - search the `BaseDN` object and all objects below it. Relevant to bind method: search
`SearchBindDN:` | Writable | The distinguished name to bind against to search the directory. For example, CN=bruno, DC=foo, DC=com Relevant to bind method: search
`SearchPasswd:` | Writable | The password for the `BindDN` record. If the password contains special characters, such as `#`, enclose the password in quotation marks. Relevant to bind method: search
`SaslRealm:` | Writable | The optional realm to use when authenticating the user using SASL. Relevant to bind method: sasl
`GroupSearchFilter:` | Writable | The filter to use for the group search. Relevant to bind method: all
`GroupBaseDN:` | Writable | The search base for performing a group search. The default is the value of `SearchBaseDN`. Relevant to bind method: all
`GroupSearchScope` | Writable | One of the following, to be used when performing a group search. baseonly - search just the `BaseDN` object. children - search the `BaseDN` object and its direct children. subtree - search the `BaseDN` object and all objects below it. Relevant to bind method: all
`AttributeUid` | Writable | The name of the attribute in the user object that contains the user’s UID.
`AttributeName` | Writable | The name(s) of the attribute(s) in the user object that contains the user’s full name. If multiple attributes are required to form the full name, specify each one surrounded by % symbols, so that expanding these forms the user’s full name. The `getattrs` option must be enabled for this field to be populated using the value specified in the LDAP `AttributeName` field.
`AttributeEmail` | Writable | The name of the attribute in the directory’s user object that contains the users' email addresses. The `getattrs` option must be enabled for this field to be populated using the value in the LDAP `AttributeEmail` field.

## Options

`-d config` | Deletes the specified LDAP configuration.
`-i` | Read the LDAP specification from standard input.
`-o config` | Writes the specified LDAP configuration to standard output.
`-t username config` | Specifies a username to authenticate against the specified LDAP configuration. It is provided for testing purposes. The command returns a success message or a detailed error message. You do not have to enable the configuration to run this test.
`g-opts` | See Global options.

## Usage notes

Can File Arguments Use Revision Specifier? | Can File Arguments Use Revision Range? | Minimal Access Level Required
--- | --- | ---
N/A | N/A | `super`

## Examples

`p4 ldap myLDAPconfig` | Create the `myLDAPconfig` configuration.
`p4 ldap -o myLDAPconfig` | Write the `myLDAPconfig` configuration to standard output.
`p4 ldap -t Maria myLDAPconfig` | Authenticate user `Maria` against the server specified by the `myLDAPconfig` configuration.
`p4 ldap -d myLDAPconfig` | Delete the `myLDAPconfig` configuration.

## Related commands

To view a list of all LDAP configurations. | `p4 ldaps`
To define LDAP-related configurables. | `p4 configure`

Your search for returned results