open-vault/website/source/docs/auth/ldap.html.md

layout	page_title	sidebar_current	description
docs	Auth Backend: LDAP	docs-auth-ldap	The "kdap" auth backend allows users to authenticate with Vault using LDAP credentials.

Auth Backend: LDAP

Name: ldap

The "ldap" auth backend 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 in LDAP to Vault policies is managed by using the groups/ path.

Authentication

Via the CLI

$ vault auth -method=ldap username=mitchellh
Password (will be hidden):
Successfully authenticated! The policies that are associated
with this token are listed below:

root

Via the API

The endpoint for the login is auth/ldap/login/<username>.

The password should be sent in the POST body encoded as JSON.

$ curl $VAULT_ADDR/v1/auth/ldap/login/mitchellh \
    -d "password=foo"

The response will be in JSON. For example:

{
  "lease_id":"",
  "renewable":false,
  "lease_duration":0,
  "data":null,
  "auth":{
    "client_token":"c4f280f6-fdb2-18eb-89d3-589e2e834cdb",
    "policies":[
      "root"
    ],
    "metadata":{
      "username":"mitchellh"
    },
    "lease_duration":0,
    "renewable":false
  }
}

Configuration

First, you must enable the ldap auth backend:

$ vault auth-enable ldap
Successfully enabled 'ldap' at 'ldap'!

Now when you run vault auth -methods, the ldap backend is available:

Path       Type      Description
ldap/      ldap
token/     token     token based credentials

To use the "ldap" auth backend, an operator must configure it with the address of the LDAP server that is to be used. An example is shown below. Use vault help for more details.

$ vault write auth/ldap/config url="ldap://ldap.forumsys.com" \
		userattr=uid \
        userdn="dc=example,dc=com" \
        groupdn="dc=example,dc=com" \
...

The above configures the target LDAP server, along with the parameters specifying how users and groups should be queried from the LDAP server.

Next we want to create a mapping from an LDAP group to a Vault policy:

$ vault write auth/ldap/groups/scientists policies=foo,bar

This maps the LDAP group "scientists" to the "foo" and "bar" Vault policies.

Finally, we can test this by authenticating:

$ vault auth -method=ldap username=tesla
Password (will be hidden):
Successfully authenticated! The policies that are associated
with this token are listed below:

bar, foo