LDAP auth method
Note: This engine can use external X.509 certificates as part of TLS or signature validation. Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer usable without a workaround starting in Vault 1.12. See the deprecation FAQ for more information.
The ldap
auth method allows authentication using an existing LDAP
server and user/password credentials. This allows Vault to be integrated
into environments using LDAP without duplicating the user/pass configuration
in multiple places.
The mapping of groups and users in LDAP to Vault policies is managed by using
the users/
and groups/
paths.
A note on escaping
It is up to the administrator to provide properly escaped DNs. This includes the user DN, bind DN for search, and so on.
The only DN escaping performed by this method is on usernames given at login time when they are inserted into the final bind DN, and uses escaping rules defined in RFC 4514.
Additionally, Active Directory has escaping rules that differ slightly from the RFC; in particular it requires escaping of '#' regardless of position in the DN (the RFC only requires it to be escaped when it is the first character), and '=', which the RFC indicates can be escaped with a backslash, but does not contain in its set of required escapes. If you are using Active Directory and these appear in your usernames, please ensure that they are escaped, in addition to being properly escaped in your configured DNs.
For reference, see RFC 4514 and this TechNet post on characters to escape in Active Directory.
Authentication
Via the CLI
Via the API
The response will be in JSON. For example:
Configuration
Auth methods must be configured in advance before users or machines can authenticate. These steps are usually completed by an operator or configuration management tool.
Enable the ldap auth method:
Configure connection details for your LDAP server, information on how to authenticate users, and instructions on how to query for group membership. The configuration options are categorized and detailed below.
Connection parameters
url
(string, required) - The LDAP server to connect to. Examples:ldap://ldap.myorg.com
,ldaps://ldap.myorg.com:636
. This can also be a comma-delineated list of URLs, e.g.ldap://ldap.myorg.com,ldaps://ldap.myorg.com:636
, in which case the servers will be tried in-order if there are errors during the connection process.starttls
(bool, optional) - If true, issues aStartTLS
command after establishing an unencrypted connection.insecure_tls
- (bool, optional) - If true, skips LDAP server SSL certificate verification - insecure, use with caution!certificate
- (string, optional) - CA certificate to use when verifying LDAP server certificate, must be x509 PEM encoded.client_tls_cert
- (string, optional) - Client certificate to provide to the LDAP server, must be x509 PEM encoded.client_tls_key
- (string, optional) - Client certificate key to provide to the LDAP server, must be x509 PEM encoded.
Binding parameters
There are two alternate methods of resolving the user object used to authenticate the end user: Search or User Principal Name. When using Search, the bind can be either anonymous or authenticated. User Principal Name is a method of specifying users supported by Active Directory. More information on UPN can be found here.
userfilter
works with both authenticated and anonymous Search.
In order for userfilter
to apply for authenticated searches, binddn
and bindpass
must be set.
For anonymous search, discoverdn
must be set to true
, and deny_null_bind
must be set to false.
Binding - authenticated search
binddn
(string, optional) - Distinguished name of object to bind when performing user and group search. Example:cn=vault,ou=Users,dc=example,dc=com
bindpass
(string, optional) - Password to use along withbinddn
when performing user search.userdn
(string, optional) - Base DN under which to perform user search. Example:ou=Users,dc=example,dc=com
userattr
(string, optional) - Attribute on user attribute object matching the username passed when authenticating. Examples:sAMAccountName
,cn
,uid
userfilter
(string, optional) - Go template used to construct a ldap user search filter. The template can access the following context variables: [UserAttr
,Username
]. The default userfilter is({{.UserAttr}}={{.Username}})
or(userPrincipalName={{.Username}}@UPNDomain)
if theupndomain
parameter is set. The user search filter can be used to restrict what user can attempt to log in. For example, to limit login to users that are not contractors, you could write(&(objectClass=user)({{.UserAttr}}={{.Username}})(!(employeeType=Contractor)))
.
When specifying a userfilter
, either the templated value {{.UserAttr}}
or
the literal value that matches userattr
should be present in the filter to
ensure that the search returns a unique result that takes userattr
into
consideration for entity alias mapping purposes and avoid possible collisions on login.
Binding - anonymous search
discoverdn
(bool, optional) - If true, use anonymous bind to discover the bind DN of a useruserdn
(string, optional) - Base DN under which to perform user search. Example:ou=Users,dc=example,dc=com
userattr
(string, optional) - Attribute on user attribute object matching the username passed when authenticating. Examples:sAMAccountName
,cn
,uid
userfilter
(string, optional) - Go template used to construct a ldap user search filter. The template can access the following context variables: [UserAttr
,Username
]. The default userfilter is({{.UserAttr}}={{.Username}})
or(userPrincipalName={{.Username}}@UPNDomain)
if theupndomain
parameter is set. The user search filter can be used to restrict what user can attempt to log in. For example, to limit login to users that are not contractors, you could write(&(objectClass=user)({{.UserAttr}}={{.Username}})(!(employeeType=Contractor)))
.deny_null_bind
(bool, optional) - This option prevents users from bypassing authentication when providing an empty password. The default istrue
.anonymous_group_search
(bool, optional) - Use anonymous binds when performing LDAP group searches. Defaults tofalse
.
When specifying a userfilter
, either the templated value {{.UserAttr}}
or
the literal value that matches userattr
should be present in the filter to
ensure that the search returns a unique result that takes userattr
into
consideration for entity alias mapping purposes and avoid possible collisions on login.
Alias dereferencing
dereference_aliases
(string, optional) - Control how aliases are dereferenced when performing the search. Possible values are:never
,finding
,searching
, andalways
.finding
will only dereference aliases during name resolution of the base.searching
will dereference aliases after name resolution.
Binding - user principal name (AD)
upndomain
(string, optional) - userPrincipalDomain used to construct the UPN string for the authenticating user. The constructed UPN will appear as[username]@UPNDomain
. Example:example.com
, which will cause vault to bind asusername@example.com
.
Group membership resolution
Once a user has been authenticated, the LDAP auth method must know how to resolve which groups the user is a member of. The configuration for this can vary depending on your LDAP server and your directory schema. There are two main strategies when resolving group membership - the first is searching for the authenticated user object and following an attribute to groups it is a member of. The second is to search for group objects of which the authenticated user is a member of. Both methods are supported.
groupfilter
(string, optional) - Go template used when constructing the group membership query. The template can access the following context variables: [UserDN
,Username
]. The default is(|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}}))
, which is compatible with several common directory schemas. To support nested group resolution for Active Directory, instead use the following query:(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))
.groupdn
(string, required) - LDAP search base to use for group membership search. This can be the root containing either groups or users. Example:ou=Groups,dc=example,dc=com
groupattr
(string, optional) - LDAP attribute to follow on objects returned bygroupfilter
in order to enumerate user group membership. Examples: for groupfilter queries returning group objects, use:cn
. For queries returning user objects, use:memberOf
. The default iscn
.
Note: When using Authenticated Search for binding parameters (see above) the distinguished name defined for binddn
is used for the group search. Otherwise, the authenticating user is used to perform the group search.
Use vault path-help
for more details.
Other
username_as_alias
(bool, optional) - If set to true, forces the auth method to use the username passed by the user as the alias name.max_page_size
(int, optional) - If set to a value greater than 0, the LDAP backend will use the LDAP server's paged search control to request pages of up to the given size. This can be used to avoid hitting the LDAP server's maximum result size limit. Otherwise, the LDAP backend will not use the paged search control.
Examples:
Scenario 1
- LDAP server running on
ldap.example.com
, port 389. - Server supports
STARTTLS
command to initiate encryption on the standard port. - CA Certificate stored in file named
ldap_ca_cert.pem
- Server is Active Directory supporting the userPrincipalName attribute. Users are identified as
username@example.com
. - Groups are nested, we will use
LDAP_MATCHING_RULE_IN_CHAIN
to walk the ancestry graph. - Group search will start under
ou=Groups,dc=example,dc=com
. For all group objects under that path, themember
attribute will be checked for a match against the authenticated user. - Group names are identified using their
cn
attribute.
Scenario 2
- LDAP server running on
ldap.example.com
, port 389. - Server supports
STARTTLS
command to initiate encryption on the standard port. - CA Certificate stored in file named
ldap_ca_cert.pem
- Server does not allow anonymous binds for performing user search.
- Bind account used for searching is
cn=vault,ou=users,dc=example,dc=com
with passwordMy$ecrt3tP4ss
. - User objects are under the
ou=Users,dc=example,dc=com
organizational unit. - Username passed to vault when authenticating maps to the
sAMAccountName
attribute. - Group membership will be resolved via the
memberOf
attribute of user objects. That search will begin underou=Users,dc=example,dc=com
.
Scenario 3
- LDAP server running on
ldap.example.com
, port 636 (LDAPS) - CA Certificate stored in file named
ldap_ca_cert.pem
- User objects are under the
ou=Users,dc=example,dc=com
organizational unit. - Username passed to vault when authenticating maps to the
uid
attribute. - User bind DN will be auto-discovered using anonymous binding.
- Group membership will be resolved via any one of
memberUid
,member
, oruniqueMember
attributes. That search will begin underou=Groups,dc=example,dc=com
. - Group names are identified using the
cn
attribute.
LDAP group -> policy mapping
Next we want to create a mapping from an LDAP group to a Vault policy:
This maps the LDAP group "scientists" to the "foo" and "bar" Vault policies. We can also add specific LDAP users to additional (potentially non-LDAP) groups. Note that policies can also be specified on LDAP users as well.
This adds the LDAP user "tesla" to the "engineers" group, which maps to the "foobar" Vault policy. User "tesla" itself is associated with "zoobar" policy.
Finally, we can test this by authenticating:
Note on policy mapping
It should be noted that user -> policy mapping happens at token creation time. And changes in group membership on the LDAP server will not affect tokens that have already been provisioned. To see these changes, old tokens should be revoked and the user should be asked to reauthenticate.
User lockout
If a user provides bad credentials several times in quick succession, Vault will stop trying to validate their credentials for a while, instead returning immediately with a permission denied error. We call this behavior "user lockout". The time for which a user will be locked out is called “lockout duration”. The user will be able to login after the lockout duration has passed. The number of failed login attempts after which the user is locked out is called “lockout threshold”. The lockout threshold counter is reset to zero after a few minutes without login attempts, or upon a successful login attempt. The duration after which the counter will be reset to zero after no login attempts is called "lockout counter reset". This can defeat both automated and targeted requests i.e, user-based password guessing attacks as well as automated attacks.
The user lockout feature is enabled by default. The default values for "lockout threshold" is 5 attempts, "lockout duration" is 15 minutes, "lockout counter reset" is 15 minutes.
The user lockout feature can be disabled as follows:
- It can be disabled globally using environment variable
VAULT_DISABLE_USER_LOCKOUT
. - It can be disabled for all supported auth methods (ldap, userpass and approle) or a specific supported auth method using the
disable_lockout
parameter withinuser_lockout
stanza in configuration file. Please see user lockout configuration for more details. - It can be disabled for a specific auth mount using "auth tune". Please see auth tune command or auth tune api for more details.
NOTE: This feature is available from Vault version 1.13 and is only supported by the userpass, ldap, and approle auth methods.
API
The LDAP auth method has a full HTTP API. Please see the LDAP auth method API for more details.