layout | page_title | description |
---|---|---|
api |
LDAP - Auth Methods - HTTP API |
This is the API documentation for the Vault LDAP auth method. |
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.
This endpoint configures the LDAP auth method.
Method | Path |
---|---|
POST |
/auth/ldap/config |
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.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 aStartTLS
command after establishing an unencrypted connection.tls_min_version
(string: tls12)
– Minimum TLS version to use. Accepted values aretls10
,tls11
,tls12
ortls13
.tls_max_version
(string: tls12)
– Maximum TLS version to use. Accepted values aretls10
,tls11
,tls12
ortls13
.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 withbinddn
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 asusername@example.com
.anonymous_group_search
(bool: false)
- Use anonymous binds when performing LDAP group searches (note: even whentrue
, 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 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
.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.
@include 'tokenfields.mdx'
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/ldap/config
{
"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"
}
This endpoint retrieves the LDAP configuration for the auth method.
Method | Path |
---|---|
GET |
/auth/ldap/config |
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/ldap/config
{
"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": ""
}
This endpoint returns a list of existing groups in the method.
Method | Path |
---|---|
LIST |
/auth/ldap/groups |
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/ldap/groups
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": ["scientists", "engineers"]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
This endpoint returns the policies associated with a LDAP group.
Method | Path |
---|---|
GET |
/auth/ldap/groups/:name |
name
(string: <required>)
– The name of the LDAP group
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/ldap/groups/admins
{
"data": {
"policies": [
"admin",
"default"
]
},
"renewable": false,
"lease_id": ""
"lease_duration": 0,
"warnings": null
}
This endpoint creates or updates LDAP group policies.
Method | Path |
---|---|
POST |
/auth/ldap/groups/:name |
name
(string: <required>)
– The name of the LDAP grouppolicies
(string: "")
– Comma-separated list of policies associated to the group.
{
"policies": "admin,default"
}
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/ldap/groups/admins
This endpoint deletes the LDAP group and policy association.
Method | Path |
---|---|
DELETE |
/auth/ldap/groups/:name |
name
(string: <required>)
– The name of the LDAP group
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/ldap/groups/admins
This endpoint returns a list of existing users in the method.
Method | Path |
---|---|
LIST |
/auth/ldap/users |
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/ldap/users
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": ["mitchellh", "armon"]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
This endpoint returns the policies associated with a LDAP user.
Method | Path |
---|---|
GET |
/auth/ldap/users/:username |
username
(string: <required>)
– The username of the LDAP user
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/ldap/users/mitchellh
{
"data": {
"policies": [
"admin",
"default"
],
"groups": ""
},
"renewable": false,
"lease_id": ""
"lease_duration": 0,
"warnings": null
}
This endpoint creates or updates LDAP users policies and group associations.
Method | Path |
---|---|
POST |
/auth/ldap/users/:username |
username
(string: <required>)
– The username of the LDAP userpolicies
(string: "")
– Comma-separated list of policies associated to the user.groups
(string: "")
– Comma-separated list of groups associated to the user.
{
"policies": "admin,default"
}
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/ldap/users/mitchellh
This endpoint deletes the LDAP user and policy association.
Method | Path |
---|---|
DELETE |
/auth/ldap/users/:username |
username
(string: <required>)
– The username of the LDAP user
$ 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 |
---|---|
POST |
/auth/ldap/login/:username |
username
(string: <required>)
– The username of the LDAP userpassword
(string: <required>)
– The password for the LDAP user
{
"password": "MyPassword1"
}
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/ldap/login/mitchellh
{
"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
}
}