upstream/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2026-05-28 04:10:44 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Docs for the upcoming Active Directory secrets engine (#4612)

Browse source
This commit is contained in:
Becca Petrin 2018-05-29 08:49:09 -07:00 committed by GitHub
parent 2f67754951
commit f6b5cab7ba
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 323 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

175
website/source/api/secret/ad/index.html.md Normal file
View file

@ -0,0 +1,175 @@
---
layout: "api"
page_title: "Active Directory - Secrets Engines - HTTP API"
sidebar_current: "docs-http-secret-active-directory"
description: |-
This is the API documentation for the Vault Active Directory secrets engine.
---
# Active Directory Secrets Engine (API)
This is the API documentation for the Vault AD secrets engine. For general
information about the usage and operation of the AD secrets engine, please see
the [Vault Active Directory documentation](/docs/secrets/ad/index.html).
This documentation assumes the AD secrets engine is enabled at the `/ad` path
in Vault. Since it is possible to enable secrets engines at any location, please
update your API calls accordingly.
## Configuration
The `config` endpoint configures the LDAP connection and binding parameters, as well as the password rotation configuration.
### Password parameters
* `ttl` (string, optional) - The default password time-to-live in seconds. Once the ttl has passed, a password will be rotated the next time it's requested.
* `max_ttl` (string, optional) - The maximum password time-to-live in seconds. No role will be allowed to set a custom ttl greater than the `max_ttl`.
* `password_length` (string, optional) - The desired password length. Defaults to 64. Minimum is 14. Note: to meet complexity requirements, all passwords begin with "?@09AZ".
### Connection parameters
* `url` (string, required) - The LDAP server to connect to. Examples: `ldap://ldap.myorg.com`, `ldaps://ldap.myorg.com:636`. This can also be a comma-delineated list of URLs, e.g. `ldap://ldap.myorg.com,ldaps://ldap.myorg.com:636`, in which case the servers will be tried in-order if there are errors during the connection process.
* `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
* `binddn` (string, required) - Distinguished name of object to bind when performing user and group search. Example: `cn=vault,ou=Users,dc=example,dc=com`
* `bindpass` (string, required) - 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`
* `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`.
## Config management
At present, this endpoint does not confirm that the provided AD credentials are
valid AD credentials with proper permissions.
| Method | Path | Produces |
| :------- | :--------------------- | :--------------------- |
| `POST` | `/ad/config` | `204 (empty body)` |
| `GET` | `/ad/config` | `200 application/json` |
| `DELETE` | `/ad/config` | `204 (empty body)` |
### Sample Post Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ad/config
```
### Sample Post Payload
```json
{
"binddn": "domain-admin",
"bindpass": "pa$$w0rd",
"url": "ldap://127.0.0.11",
"userdn": "dc=example,dc=com"
}
```
### Sample Get Response Data
```json
{
"binddn": "domain-admin",
"certificate": "",
"insecure_tls": false,
"length": 64,
"max_ttl": 2764800,
"starttls": false,
"tls_max_version": "tls12",
"tls_min_version": "tls12",
"ttl": 2764800,
"upndomain": "",
"url": "ldap://127.0.0.11",
"userdn": "dc=example,dc=com"
}
```
## Role management
The `roles` endpoint configures how Vault will manage the passwords for individual service accounts.
### Parameters
* `service_account_name` (string, required) - The name of a pre-existing service account in Active Directory that maps to this role.
* `ttl` (string, optional) - The password time-to-live in seconds. Defaults to the configuration `ttl` if not provided.
When adding a role, Vault verifies its associated service account exists.
| Method | Path | Produces |
| :------- | :--------------------- | :--------------------- |
| `GET` | `/ad/roles` | `200 application/json` |
| `POST` | `/ad/roles/:role_name` | `204 (empty body)` |
| `GET` | `/ad/roles/:role_name` | `200 application/json` |
| `DELETE` | `/ad/roles/:role_name` | `204 (empty body)` |
### Sample Post Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/ad/roles/my-application
```
### Sample Post Payload
```json
{
"service_account_name": "my-application@example.com",
"ttl": 100
}
```
### Sample Get Role Response
```json
{
"last_vault_rotation": "2018-05-24T17:14:38.677370855Z",
"password_last_set": "2018-05-24T17:14:38.6038495Z",
"service_account_name": "my-application@example.com",
"ttl": 100
}
```
### Sample List Roles Response
Performing a `LIST` on the `/ad/roles` endpoint will list the names of all the roles Vault contains.
```json
[
"my-application"
]
```
## Retrieving passwords
The `creds` endpoint offers the credential information for a given role.
### Sample Get Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
--data @payload.json \
http://127.0.0.1:8200/v1/ad/creds/my-application
```
### Sample Get Response
```json
{
"current_password": "?@09AZnh4Q5N4O5zdLk/4F8aIMgsnpDM6tSQEZCge3Mz1wXcZEgZhOa6OR748F96",
"last_password": "?@09AZSen9TzUwK7ZhafS7B0GuWGraQjfWEna5SwnmF/tVaKFqjXhhGV/Z0v/pBJ",
"username": "my-application"
}
```

148
website/source/docs/secrets/ad/index.html.md Normal file
View file

@ -0,0 +1,148 @@
---
layout: "docs"
page_title: "Active Directory - Secrets Engines"
sidebar_current: "docs-secrets-active-directory"
description: |-
The Active Directory secrets engine for Vault generates passwords dynamically based on
roles.
---
# Active Directory Secrets Engine
The Active Directory (AD) secrets engine is a plugin residing [here](https://github.com/hashicorp/vault-plugin-secrets-active-directory).
The AD secrets engine rotates AD passwords dynamically,
and is designed for a high-load environment where many instances may be accessing
a shared password simultaneously. With a simple set up and a simple creds API,
it doesn't require instances to be manually registered in advance to gain access.
As long as access has been granted to the creds path via a method like
[AppRole](https://www.vaultproject.io/api/auth/approle/index.html), they're available.
Passwords are lazily rotated based on preset TTLs and can have a length configured to meet
your needs.
## A Note on Lazy Rotation
To drive home the point that passwords are rotated "lazily", consider this scenario:
- A password is configured with a TTL of 1 hour.
- All instances of a service using this password are off for 12 hours.
- Then they wake up and again request the password.
In this scenario, although the password TTL was set to 1 hour, the password wouldn't be rotated for 12 hours when it
was next requested. "Lazy" rotation means passwords are rotated when all of the following conditions are true:
- They are over their TTL
- They are requested
Therefore, the AD TTL can be considered a soft contract. It's fulfilled when the given password is next requested.
To ensure your passwords are rotated as expected, we'd recommend you configure services to request each password at least
twice as often as its TTL.
## 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 method 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](https://www.ietf.org/rfc/rfc4514.txt) and this
[TechNet post on characters to escape in Active
Directory](http://social.technet.microsoft.com/wiki/contents/articles/5312.active-directory-characters-to-escape.aspx).
## Quick Setup
Most secrets engines must be configured in advance before they can perform their
functions. These steps are usually completed by an operator or configuration
management tool.
1. Enable the Active Directory secrets engine:
```text
$ vault secrets enable ad
Success! Enabled the ad secrets engine at: ad/
```
By default, the secrets engine will mount at the name of the engine. To
enable the secrets engine at a different path, use the `-path` argument.
2. Configure the credentials that Vault uses to communicate with Active Directory
to generate passwords:
```text
$ vault write ad/config \
binddn=$USERNAME \
bindpass=$PASSWORD \
url=ldap://138.91.247.105 \
userdn='dc=example,dc=com'
```
The `$USERNAME` and `$PASSWORD` given must be of a high enough access level that
they can be used for modifying passwords. Typically, this will be a domain admin.
If you'd like to do a quick, insecure evaluation, also set `insecure_tls` to true. However, this is NOT RECOMMENDED
in a production environment. In production, we recommend `insecure_tls` is false (its default) and is used with a valid
`certificate`.
3. Configure a role that maps a name in Vault to an account in Active Directory.
When applications request passwords, password rotation settings will be managed by
this role.
```text
$ vault write ad/roles/my-application \
service_account_name="my-application@example.com"
```
4. Grant "my-application" access to its creds at `ad/creds/my-application` using an
auth method like [AppRole](https://www.vaultproject.io/api/auth/approle/index.html).
## FAQ
### What if someone directly rotates an Active Directory password that Vault is managing?
If an administrator at your company rotates a password that Vault is managing, the next time an application asks _Vault_
for that password, Vault won't know it.
To maintain that application's up-time, Vault will need to return to a state of knowing the password. Vault will generate
a new password, update it, and return it to the application(s) asking for it. This all occurs automatically, without human
intervention.
Thus, we wouldn't recommend that administrators directly rotate the passwords for accounts that Vault is managing. This
may lead to behavior the administrator wouldn't expect, like finding very quickly afterwards that their new password
has already been changed.
The password `ttl` on a role can be updated at any time to ensure that the responsibility of updating passwords can be
left to Vault, rather than requiring manual administrator updates.
### How does this feature work with Managed Service Accounts?
Managed Service Accounts are a feature where, in some situations, Active Directory can be set up to rotate passwords for you.
Vault can be used alongside Managed Service Accounts, but on separate accounts.
If Vault were set up to rotate a Managed Service Account's password, there would effectively be _two_ entities rotating
passwords for that account. This would create a strange situation where the password might be rotated by Active Directory,
and then Vault would also be forced to rotate the password in order to know and return it again.
We're not aware of any use case for this setup and would advise against it. Please use one _or_ the other as best fits
your needs.
### How does this feature work with Group Managed Service Accounts?
Group Managed Service Accounts are a successor to Managed Service Accounts. Please see their discussion above.
### Why does Vault return the last password in addition to the current one?
Active Directory promises _eventual consistency_, which means that new passwords may not be propagated to all instances
immediately. To deal with this, Vault returns the current password with the last password if it's known. That way, if a new
password isn't fully operational, the last password can also be used.