diff --git a/website/source/api/secret/ad/index.html.md b/website/source/api/secret/ad/index.html.md new file mode 100644 index 0000000000..f6c44316c4 --- /dev/null +++ b/website/source/api/secret/ad/index.html.md @@ -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" +} +``` \ No newline at end of file diff --git a/website/source/docs/secrets/ad/index.html.md b/website/source/docs/secrets/ad/index.html.md new file mode 100644 index 0000000000..edff2c8d78 --- /dev/null +++ b/website/source/docs/secrets/ad/index.html.md @@ -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. \ No newline at end of file