LDAP auth method (API)

This is the API documentation for the Vault LDAP auth method. For general information about the usage and operation of the LDAP method, please see the Vault LDAP method documentation.

This documentation assumes the LDAP method is mounted at the /auth/ldap path in Vault. Since it is possible to enable auth methods at any location, please update your API calls accordingly.

Configure LDAP

This endpoint configures the LDAP auth method.

Method Path

Method	Path
`POST`	`/auth/ldap/config`

POST

/auth/ldap/config

Parameters

url (string: ldap://127.0.0.1) – The LDAP server to connect to. Examples: ldap://ldap.myorg.com, ldaps://ldap.myorg.com:636. Multiple URLs can be specified with commas, e.g. ldap://ldap.myorg.com,ldap://ldap2.myorg.com; these will be tried in-order.
case_sensitive_names (bool: false) – If set, user and group names assigned to policies within the backend will be case sensitive. Otherwise, names will be normalized to lower case. Case will still be preserved when sending the username to the LDAP server at login time; this is only for matching local user/group definitions.
connection_timeout (integer: 30 or string: "30s") - Timeout, in seconds, when attempting to connect to the LDAP server before trying the next URL in the configuration.
request_timeout (integer: 90 or string: "90s") - Timeout, in seconds, for the connection when making requests against the server before returning back an error.
starttls (bool: false) – If true, issues a StartTLS command after establishing an unencrypted connection.
tls_min_version (string: tls12) – Minimum TLS version to use. Accepted values are tls10, tls11, tls12 or tls13.
tls_max_version (string: tls12) – Maximum TLS version to use. Accepted values are tls10, tls11, tls12 or tls13.
insecure_tls (bool: false) – If true, skips LDAP server SSL certificate verification - insecure, use with caution!
certificate (string: "") – CA certificate to use when verifying LDAP server certificate, must be x509 PEM encoded.
client_tls_cert (string "") - Client certificate to provide to the LDAP server, must be x509 PEM encoded (optional).
client_tls_key (string "") - Client certificate key to provide to the LDAP server, must be x509 PEM encoded (optional).
binddn (string: "") – Distinguished name of object to bind when performing user search. Example: cn=vault,ou=Users,dc=example,dc=com
bindpass (string: "") – Password to use along with binddn when performing user search.
userdn (string: "") – Base DN under which to perform user search. Example: ou=Users,dc=example,dc=com
userattr (string: "cn") – Attribute on user attribute object matching the username passed when authenticating. Examples: sAMAccountName, cn, uid
discoverdn (bool: false) – Use anonymous bind to discover the bind DN of a user.
deny_null_bind (bool: true) – This option prevents users from bypassing authentication when providing an empty password.
upndomain (string: "") – The 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.
userfilter (string: "") – An optional LDAP user search filter. The template can access the following context variables: UserAttr, Username. The default is ({{.UserAttr}}={{.Username}}), or ({{.UserAttr}}={{.Username@.upndomain}}) if upndomain is set. In order for the userfilter to be applied, both binddn and bindpass must be set, or discoverdn must be set to true.
anonymous_group_search (bool: false) - Use anonymous binds when performing LDAP group searches (note: even when true, the initial credentials will still be used for the initial connection test).
groupfilter (string: "") – 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: "") – 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: "") – 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.
username_as_alias (bool: false) - If set to true, forces the auth method to use the username passed by the user as the alias name.
dereference_aliases (string: never) - When aliases should be dereferenced on search operations. Accepted values are 'never', 'finding', 'searching', 'always'. Defaults to 'never'.
max_page_size (int: 0) - 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.

@include 'tokenfields.mdx'

@include 'ldap-auth-userfilter-warning.mdx'

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/ldap/config

Sample payload

{
  "binddn": "cn=vault,ou=Users,dc=example,dc=com",
  "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",
  "url": "ldaps://ldap.myorg.com:636",
  "username_as_alias": false,
  "userattr": "samaccountname",
  "userdn": "ou=Users,dc=example,dc=com",
  "max_page_size": 1000
}

Read LDAP configuration

This endpoint retrieves the LDAP configuration for the auth method.

Method Path

Method	Path
`GET`	`/auth/ldap/config`

GET

/auth/ldap/config

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/auth/ldap/config

Sample response

{
  "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",
    "username_as_alias": false,
    "userattr": "samaccountname",
    "userdn": "ou=Users,dc=example,dc=com"
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

List LDAP groups

This endpoint returns a list of existing groups in the method.

Method Path

Method	Path
`LIST`	`/auth/ldap/groups`

LIST

/auth/ldap/groups

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/auth/ldap/groups

Sample response

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

Read LDAP group

This endpoint returns the policies associated with a LDAP group.

Method Path

Method	Path
`GET`	`/auth/ldap/groups/:name`

GET

/auth/ldap/groups/:name

Parameters

name (string: <required>) – The name of the LDAP group

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/auth/ldap/groups/admins

Sample response

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

Create/Update LDAP group

This endpoint creates or updates LDAP group policies.

Method Path

Method	Path
`POST`	`/auth/ldap/groups/:name`

POST

/auth/ldap/groups/:name

Parameters

name (string: <required>) – The name of the LDAP group
policies (string: "") – Comma-separated list of policies associated to the group.

Sample payload

{
  "policies": "admin,default"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/ldap/groups/admins

Delete LDAP group

This endpoint deletes the LDAP group and policy association.

Method Path

Method	Path
`DELETE`	`/auth/ldap/groups/:name`

DELETE

/auth/ldap/groups/:name

Parameters

name (string: <required>) – The name of the LDAP group

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/auth/ldap/groups/admins

List LDAP users

This endpoint returns a list of existing users in the method.

Method Path

Method	Path
`LIST`	`/auth/ldap/users`

LIST

/auth/ldap/users

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/auth/ldap/users

Sample response

{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "keys": ["mitchellh", "armon"]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

Read LDAP user

This endpoint returns the policies associated with a LDAP user.

Method Path

Method	Path
`GET`	`/auth/ldap/users/:username`

GET

/auth/ldap/users/:username

Parameters

username (string: <required>) – The username of the LDAP user

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/auth/ldap/users/mitchellh

Sample response

{
  "data": {
    "policies": [
      "admin",
      "default"
    ],
    "groups": ""
  },
  "renewable": false,
  "lease_id": ""
  "lease_duration": 0,
  "warnings": null
}

Create/Update LDAP user

This endpoint creates or updates LDAP users policies and group associations.

Method Path

Method	Path
`POST`	`/auth/ldap/users/:username`

POST

/auth/ldap/users/:username

Parameters

username (string: <required>) – The username of the LDAP user
policies (string: "") – Comma-separated list of policies associated to the user.
groups (string: "") – Comma-separated list of groups associated to the user.

Sample payload

{
  "policies": "admin,default"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/ldap/users/mitchellh

Delete LDAP user

This endpoint deletes the LDAP user and policy association.

Method Path

Method	Path
`DELETE`	`/auth/ldap/users/:username`

DELETE

/auth/ldap/users/:username

Parameters

username (string: <required>) – The username of the LDAP user

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/auth/ldap/users/mitchellh

This endpoint allows you to log in with LDAP credentials

Method Path

Method	Path
`POST`	`/auth/ldap/login/:username`

POST

/auth/ldap/login/:username

Parameters

username (string: <required>) – The username of the LDAP user
password (string: <required>) – The password for the LDAP user. When authenticating with the Vault CLI, i.e. vault login -method=ldap username=mitchellh the password can alternatively be supplied via the VAULT_LDAP_PASSWORD environment variable.

Sample payload

{
  "password": "MyPassword1"
}

Sample request

$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/ldap/login/mitchellh

Sample response

{
  "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
  }
}

PreviousKubernetes auth method (API)NextOCI auth method (API)

Last updated 1 year ago

Configure LDAP

Parameters

Sample request

Sample payload

Read LDAP configuration

Sample request

Sample response

List LDAP groups

Sample request

Sample response

Read LDAP group

Parameters

Sample request

Sample response

Create/Update LDAP group

Parameters

Sample payload

Sample request

Delete LDAP group

Parameters

Sample request

List LDAP users

Sample request

Sample response

Read LDAP user

Parameters

Sample request

Sample response

Create/Update LDAP user

Parameters

Sample payload

Sample request

Delete LDAP user

Parameters

Sample request

Login with LDAP user

Parameters

Sample payload

Sample request

Sample response