p4 ldap

Synopsis

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

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

Syntax

p4 [gopts] ldap configname
p4 [gopts] ldap -i
p4 [gopts] ldap -o configname
p4 [gopts] ldap -d configname
p4 [gopts] ldap -t username configname

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.

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 Perforce server can 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 Perforce 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 Perforce 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 certificate validation.

For more information, see “Configurables”.

Note

LDAP configurations are stored in the new db.ldap table. This table is journaled, so LDAP configurations are now 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”.

Here is a sample LDAP configuration:

Name:     sleepy
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

You can use a command like the following to test an LDAP configuration:

$ p4 ldap -t userX myConfig

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

c:\temp> p4 -p 1666 ldap -t userX sleepy
Enter password:
Authentication as cn=userX,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

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 in order to search the directory.

Relevant to bind method: search

SearchPasswd:

Writable

The password for the BindDN record. You may quote this field; this allows special characters, like # to be used in the password.

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.

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 myLdap

Create the myLdap configuration.

p4 ldap -o myLdap

Write the myLdap configuration to standard output.

p4 ldap -t Joanna myLdap

Authenticate the user Joanna against the server specified by the myLdap configuration.

p4 ldap -d myLdap

Delete the myLdap configuration.

Related Commands

To view a list of all LDAP configurations.

p4 ldaps

To define LDAP-related configurables.

p4 configure