Creating an LDAP configuration

An LDAP configuration specifies an Active Directory or other LDAP server against which the Helix 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:              UK_LDAP
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 Helix 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 Helix 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:  CN=bruno, DC=foo, DC=com
SearchPasswd:  ******
```
```
BindMethod:    search
SearchBaseDN:  ou=users,dc=example,dc=com
SearchFilter:  (&(objectClass=user) (sAMAccountName=%user%))
SearchScope:   subtree
SearchBindDN:  CN=bruno, DC=foo, DC=com
SearchPasswd:  ******
```

See the Helix Core Command-Line (P4) Reference for information about the p4 ldap command and the LDAP specification. The LDAP spec also allows you to control the behavior of LDAP integration:

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. This 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=UK_LDAP

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

If you are using multiple directory servers for Failover or user management, you might need to create multiple LDAP configurations. In this case,

create an LDAP configuration for each LDAP server
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 cannot have two LDAP configurations using the same order number for the same Helix Server.