459 lines
12 KiB
Markdown
459 lines
12 KiB
Markdown
---
|
||
layout: "api"
|
||
page_title: "LDAP Auth Backend - HTTP API"
|
||
sidebar_current: "docs-http-auth-ldap"
|
||
description: |-
|
||
This is the API documentation for the Vault LDAP authentication backend.
|
||
---
|
||
|
||
# LDAP Auth Backend HTTP API
|
||
|
||
This is the API documentation for the Vault LDAP authentication backend. For
|
||
general information about the usage and operation of the LDAP backend, please
|
||
see the [Vault LDAP backend documentation](/docs/auth/ldap.html).
|
||
|
||
This documentation assumes the LDAP backend is mounted at the `/auth/ldap`
|
||
path in Vault. Since it is possible to mount auth backends at any location,
|
||
please update your API calls accordingly.
|
||
|
||
## Configure LDAP Backend
|
||
|
||
This endpoint configures the LDAP authentication backend.
|
||
|
||
| Method | Path | Produces |
|
||
| :------- | :--------------------------- | :--------------------- |
|
||
| `POST` | `/auth/ldap/config` | `204 (empty body)` |
|
||
|
||
### Parameters
|
||
|
||
- `url` `(string: <required>)` – The LDAP server to connect to. Examples:
|
||
`ldap://ldap.myorg.com`, `ldaps://ldap.myorg.com:636`
|
||
- `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` or `tls12`.
|
||
- `tls_max_version` `(string: tls12)` – Maximum TLS version to use. Accepted
|
||
values are `tls10`, `tls11` or `tls12`.
|
||
- `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.
|
||
- `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: "")` – 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`.
|
||
- `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`.
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://vault.rocks/v1/auth/ldap/config
|
||
```
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"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",
|
||
"userattr": "samaccountname",
|
||
"userdn": "ou=Users,dc=example,dc=com"
|
||
}
|
||
```
|
||
|
||
## Read LDAP Configuration
|
||
|
||
This endpoint retrieves the LDAP configuration for the authentication backend.
|
||
|
||
| Method | Path | Produces |
|
||
| :------- | :--------------------------- | :--------------------- |
|
||
| `GET` | `/auth/ldap/config` | `200 application/json` |
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
https://vault.rocks/v1/auth/ldap/config
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"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": ""
|
||
}
|
||
```
|
||
|
||
## List LDAP Groups
|
||
|
||
This endpoint returns a list of existing groups in the backend.
|
||
|
||
| Method | Path | Produces |
|
||
| :------- | :--------------------------- | :--------------------- |
|
||
| `LIST` | `/auth/ldap/groups` | `200 application/json` |
|
||
| `GET` | `/auth/ldap/groups?list=true` | `200 application/json` |
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request LIST \
|
||
https://vault.rocks/v1/auth/ldap/groups
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"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 | Produces |
|
||
| :------- | :--------------------------- | :--------------------- |
|
||
| `GET` | `/auth/ldap/groups/:name` | `200 application/json` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – The name of the LDAP group
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
https://vault.rocks/v1/auth/ldap/groups/admins
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"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 | Produces |
|
||
| :------- | :--------------------------- | :--------------------- |
|
||
| `POST` | `/auth/ldap/groups/:name` | `204 (empty body)` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – The name of the LDAP group
|
||
- `policies` `(string: "")` – Comma-separated list of policies associated to the
|
||
group.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"policies": "admin,default"
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://vault.rocks/v1/auth/ldap/groups/admins
|
||
```
|
||
|
||
## Delete LDAP Group
|
||
|
||
This endpoint deletes the LDAP group and policy association.
|
||
|
||
| Method | Path | Produces |
|
||
| :------- | :--------------------------- | :--------------------- |
|
||
| `DELETE` | `/auth/ldap/groups/:name` | `204 (empty body)` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – The name of the LDAP group
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request DELETE \
|
||
https://vault.rocks/v1/auth/ldap/groups/admins
|
||
```
|
||
|
||
## List LDAP Users
|
||
|
||
This endpoint returns a list of existing users in the backend.
|
||
|
||
| Method | Path | Produces |
|
||
| :------- | :--------------------------- | :--------------------- |
|
||
| `LIST` | `/auth/ldap/users` | `200 application/json` |
|
||
| `GET` | `/auth/ldap/users?list=true` | `200 application/json` |
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request LIST \
|
||
https://vault.rocks/v1/auth/ldap/users
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"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 | Produces |
|
||
| :------- | :--------------------------- | :--------------------- |
|
||
| `GET` | `/auth/ldap/users/:username` | `200 application/json` |
|
||
|
||
### Parameters
|
||
|
||
- `username` `(string: <required>)` – The username of the LDAP user
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
https://vault.rocks/v1/auth/ldap/users/mitchellh
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"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 | Produces |
|
||
| :------- | :--------------------------- | :--------------------- |
|
||
| `POST` | `/auth/ldap/users/:username` | `204 (empty body)` |
|
||
|
||
### 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
|
||
|
||
```json
|
||
{
|
||
"policies": "admin,default"
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://vault.rocks/v1/auth/ldap/users/mitchellh
|
||
```
|
||
|
||
## Delete LDAP User
|
||
|
||
This endpoint deletes the LDAP user and policy association.
|
||
|
||
| Method | Path | Produces |
|
||
| :------- | :--------------------------- | :--------------------- |
|
||
| `DELETE` | `/auth/ldap/users/:username` | `204 (empty body)` |
|
||
|
||
### Parameters
|
||
|
||
- `username` `(string: <required>)` – The username of the LDAP user
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request DELETE \
|
||
https://vault.rocks/v1/auth/ldap/users/mitchellh
|
||
```
|
||
|
||
## Login with LDAP User
|
||
|
||
This endpoint allows you to log in with LDAP credentials
|
||
|
||
| Method | Path | Produces |
|
||
| :------- | :--------------------------- | :--------------------- |
|
||
| `POST` | `/auth/ldap/login/:username` | `200 application/json` |
|
||
|
||
### Parameters
|
||
|
||
- `username` `(string: <required>)` – The username of the LDAP user
|
||
- `password` `(string: <required>)` – The password for the LDAP user
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"password": "MyPassword1"
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://vault.rocks/v1/auth/ldap/login/mitchellh
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"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
|
||
}
|
||
}
|
||
```
|
||
|