Chris Hoffman b3fc3db6ec Adding LDAP API reference and misc docs formatting issues

2017-01-23 22:08:08 -05:00

22 KiB

Raw Blame History

layout	page_title	sidebar_current	description
docs	Auth Backend: LDAP	docs-auth-ldap	The "ldap" 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 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 backend 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

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

admins

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": [
      "admins"
    ],
    "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, it must first be configured with 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.

Configuration is written to auth/ldap/config.

Connection parameters

url (string, required) - The LDAP server to connect to. Examples: ldap://ldap.myorg.com, ldaps://ldap.myorg.com:636
starttls (bool, optional) - If true, issues a StartTLS 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.

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 method of specifying users supported by Active Directory. More information on UPN can be found here.

Binding - Authenticated Search

binddn (string, optional) - Distinguished name of object to bind when performing user search. Example: cn=vault,ou=Users,dc=example,dc=com
bindpass (string, optional) - Password to use along with binddn 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

Binding - Anonymous Search

discoverdn (bool, optional) - If true, use anonymous bind to discover the bind DN of a user
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
deny_null_bind (bool, optional) - This option prevents users from bypassing authentication when providing an empty password. The default is true.

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 as username@example.com.

Group Membership Resolution

Once a user has been authenticated, the LDAP auth backend 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 by groupfilter 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 is cn.

Use vault path-help for more details.

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, the member attribute will be checked for a match against the authenticated user.
Group names are identified using their cn attribute.

$ vault write auth/ldap/config \
    url="ldap://ldap.example.com" \
    groupdn="ou=Groups,dc=example,dc=com" \
    groupfilter="(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))" \
    groupattr="cn" \
    upndomain="example.com" \
    certificate=@ldap_ca_cert.pem \
    insecure_tls=false \
    starttls=true
...

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 password My$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 under ou=Users,dc=example,dc=com.

$ vault write auth/ldap/config url="ldap://ldap.example.com" \
    userattr=sAMAccountName \
    userdn="ou=Users,dc=example,dc=com" \
    groupdn="ou=Users,dc=example,dc=com" \
    groupfilter="(&(objectClass=person)(uid={{.Username}}))" \
    groupattr="memberOf" \
    binddn="cn=vault,ou=users,dc=example,dc=com" \
    bindpass='My$ecrt3tP4ss' \
    certificate=@ldap_ca_cert.pem \
    insecure_tls=false \
    starttls=true
...

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, or uniqueMember attributes. That search will begin under ou=Groups,dc=example,dc=com.
Group names are identified using the cn attribute.

$ vault write auth/ldap/config url="ldaps://ldap.example.com" \
    userattr="uid" \
    userdn="ou=Users,dc=example,dc=com" \
    discoverdn=true \
    groupdn="ou=Groups,dc=example,dc=com" \
    certificate=@ldap_ca_cert.pem \
    insecure_tls=false \
    starttls=true
...

LDAP Group -> Policy Mapping

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

$ vault write auth/ldap/groups/engineers policies=foobar
$ vault write auth/ldap/users/tesla groups=engineers policies=zoobar

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:

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

default, foobar, zoobar

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.

API

/auth/ldap/config

POST

Description

Configures the LDAP authentication backend.

Method

POST

URL

`/auth/ldap/config`

Parameters

rurl required The LDAP server to connect to. Examples: `ldap://ldap.myorg.com`, `ldaps://ldap.myorg.com:636`

starttls optional If true, issues a `StartTLS` command after establishing an unencrypted connection. Defaults to `false`.

tls_in_version optional Minimum TLS version to use. Accepted values are `tls10`, `tls11` or `tls12`. Defaults to `tls12`.

tls_max_version optional Maximum TLS version to use. Accepted values are `tls10`, `tls11` or `tls12`. Defaults to `tls12`.

insecure_tls optional If true, skips LDAP server SSL certificate verification - insecure, use with caution! Defaults to `false`.

certificate optional CA certificate to use when verifying LDAP server certificate, must be x509 PEM encoded.

binddn optional Distinguished name of object to bind when performing user search. Example: `cn=vault,ou=Users,dc=example,dc=com`

bindpass optional Password to use along with `binddn` when performing user search.

userdn optional Base DN under which to perform user search. Example: `ou=Users,dc=example,dc=com`

userattr optional Attribute on user attribute object matching the username passed when authenticating. Examples: `sAMAccountName`, `cn`, `uid`

discoverdn optional Use anonymous bind to discover the bind DN of a user. Defaults to `false`.

deny_null_bind optional This option prevents users from bypassing authentication when providing an empty password. Defaults to `true`.

upndomain 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 as `username@example.com`.

groupfilter 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 optional 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 optional LDAP attribute to follow on objects returned by `groupfilter` 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 is `cn`.

Returns

`204` response code.

/auth/ldap/config

GET

Description

Retrieves the LDAP configuration.

Method

GET

URL

`/auth/ldap/config`

Parameters

Returns

```javascript
{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "binddn": "cn=vault,ou=Users,dc=example,dc=com",
    "bindpass": "",
    "certificate": "",
    "deny_null_bind": true,
    "discoverdn": false,
    "groupattr": "cn",
    "groupdn": "ou=Groups,dc=example,dc=com",
    "groupfilter": "(\u0026(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))",
    "insecure_tls": false,
    "starttls": false,
    "tls_max_version": "tls12",
    "tls_min_version": "tls12",
    "upndomain": "",
    "url": "ldaps://ldap.myorg.com:636",
    "userattr": "samaccountname",
    "userdn": "ou=Users,dc=example,dc=com"
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

/auth/ldap/groups

LIST/GET

Description

Lists the existing groups in the backend

Method

LIST/GET

URL

`/auth/ldap/groups` (LIST) or `/auth/ldap/groups?list=true` (GET)

Parameters

None

Returns

```javascript
{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "keys": [
      "scientists",
      "engineers"
    ]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

/auth/ldap/groups/[group_name]

POST

Description

Creates and updates the LDAP group policy associations.

Method

GET

URL

`/auth/ldap/groups/[group_name]`

Parameters

policies required Comma-separated list of policies associated to the group.

Returns

`204` response code.

GET

Description

Reads the LDAP group policy mappings.

Method

GET

URL

`/auth/ldap/groups/[group_name]`

Returns

```javascript
{
  "data": {
    "policies": "admin,default"
  },
  "renewable": false,
  "lease_id": ""
  "lease_duration": 0,
  "warnings": null
}
```

DELETE

Description: Deletes an LDAP group.
Method: DELETE
URL: `/auth/ldap/groups/[group_name]`
Parameters: None.
Returns: `204` response code.

/auth/ldap/users

LIST/GET

Description

Lists the existing users in the backend.

Method

LIST/GET

URL

`/auth/ldap/users` (LIST) or `/auth/ldap/users?list=true` (GET)

Parameters

None

Returns

```javascript
{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "keys": [
      "tesla"
    ]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

/auth/ldap/users/[username]

POST

Description

Creates and updates the LDAP user group and policy mappings.

Method

GET

URL

`/auth/ldap/users/[username]`

Parameters

groups optional Comma-separated list of groups associated to the user.

policies optional Comma-separated list of policies associated to the user.

Returns

`204` response code.

GET

Description

Reads the LDAP user.

Method

GET

URL

`/auth/ldap/users/[username]`

Returns

```javascript
{
  "data": {
    "policies": "admins,default",
    "groups": ""
  },
  "renewable": false,
  "lease_id": ""
  "lease_duration": 0,
  "warnings": null
}
```

DELETE

Description: Deletes an LDAP user.
Method: DELETE
URL: `/auth/ldap/users/[username]`
Parameters: None.
Returns: `204` response code.

POST

Description

Creates and updates the LDAP user group and policy associations.

Method

GET

URL

`/auth/ldap/login/[username]`

Parameters

password required Password for the user.

Returns

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

22 KiB Raw Blame History

Auth Backend: LDAP

A Note on Escaping

Authentication

Via the CLI

Via the API

Configuration

Connection parameters

Binding parameters

Binding - Authenticated Search

Binding - Anonymous Search

Binding - User Principal Name (AD)

Group Membership Resolution

Examples:

Scenario 1

Scenario 2

Scenario 3

LDAP Group -> Policy Mapping

Note on policy mapping

API

/auth/ldap/config

POST

/auth/ldap/config

GET

/auth/ldap/groups

LIST/GET

/auth/ldap/groups/[group_name]

POST

GET

DELETE

/auth/ldap/users

LIST/GET

/auth/ldap/users/[username]

POST

GET

DELETE

/auth/ldap/login/[username]

POST

22 KiB

Raw Blame History