1--- 2layout: "docs" 3page_title: "Active Directory - Secrets Engines" 4sidebar_title: "Active Directory" 5sidebar_current: "docs-secrets-active-directory" 6description: |- 7 The Active Directory secrets engine for Vault generates passwords dynamically based on 8 roles. 9--- 10 11# Active Directory Secrets Engine 12 13The Active Directory (AD) secrets engine is a plugin residing [here](https://github.com/hashicorp/vault-plugin-secrets-active-directory). 14 15The AD secrets engine rotates AD passwords dynamically, 16and is designed for a high-load environment where many instances may be accessing 17a shared password simultaneously. With a simple set up and a simple creds API, 18it doesn't require instances to be manually registered in advance to gain access. 19As long as access has been granted to the creds path via a method like 20[AppRole](https://www.vaultproject.io/api/auth/approle/index.html), they're available. 21 22Passwords are lazily rotated based on preset TTLs and can have a length configured to meet 23your needs. 24 25## A Note on Lazy Rotation 26 27To drive home the point that passwords are rotated "lazily", consider this scenario: 28 29- A password is configured with a TTL of 1 hour. 30- All instances of a service using this password are off for 12 hours. 31- Then they wake up and again request the password. 32 33In this scenario, although the password TTL was set to 1 hour, the password wouldn't be rotated for 12 hours when it 34was next requested. "Lazy" rotation means passwords are rotated when all of the following conditions are true: 35 36- They are over their TTL 37- They are requested 38 39Therefore, the AD TTL can be considered a soft contract. It's fulfilled when the given password is next requested. 40 41To ensure your passwords are rotated as expected, we'd recommend you configure services to request each password at least 42twice as often as its TTL. 43 44## A Note on Escaping 45 46**It is up to the administrator** to provide properly escaped DNs. This 47includes the user DN, bind DN for search, and so on. 48 49The only DN escaping performed by this method is on usernames given at login 50time when they are inserted into the final bind DN, and uses escaping rules 51defined in RFC 4514. 52 53Additionally, Active Directory has escaping rules that differ slightly from the 54RFC; in particular it requires escaping of '#' regardless of position in the DN 55(the RFC only requires it to be escaped when it is the first character), and 56'=', which the RFC indicates can be escaped with a backslash, but does not 57contain in its set of required escapes. If you are using Active Directory and 58these appear in your usernames, please ensure that they are escaped, in 59addition to being properly escaped in your configured DNs. 60 61For reference, see [RFC 4514](https://www.ietf.org/rfc/rfc4514.txt) and this 62[TechNet post on characters to escape in Active 63Directory](http://social.technet.microsoft.com/wiki/contents/articles/5312.active-directory-characters-to-escape.aspx). 64 65## Quick Setup 66 67Most secrets engines must be configured in advance before they can perform their 68functions. These steps are usually completed by an operator or configuration 69management tool. 70 711. Enable the Active Directory secrets engine: 72 73 ```text 74 $ vault secrets enable ad 75 Success! Enabled the ad secrets engine at: ad/ 76 ``` 77 78 By default, the secrets engine will mount at the name of the engine. To 79 enable the secrets engine at a different path, use the `-path` argument. 80 812. Configure the credentials that Vault uses to communicate with Active Directory 82to generate passwords: 83 84 ```text 85 $ vault write ad/config \ 86 binddn=$USERNAME \ 87 bindpass=$PASSWORD \ 88 url=ldaps://138.91.247.105 \ 89 userdn='dc=example,dc=com' 90 ``` 91 92 The `$USERNAME` and `$PASSWORD` given must have access to modify passwords 93 for the given account. It is possible to delegate access to change 94 passwords for these accounts to the one Vault is in control of, and this is 95 usually the highest-security solution. 96 97 If you'd like to do a quick, insecure evaluation, also set `insecure_tls` to true. However, this is NOT RECOMMENDED 98 in a production environment. In production, we recommend `insecure_tls` is false (its default) and is used with a valid 99 `certificate`. 100 1013. Configure a role that maps a name in Vault to an account in Active Directory. 102When applications request passwords, password rotation settings will be managed by 103this role. 104 105 ```text 106 $ vault write ad/roles/my-application \ 107 service_account_name="my-application@example.com" 108 ``` 109 1104. Grant "my-application" access to its creds at `ad/creds/my-application` using an 111auth method like [AppRole](https://www.vaultproject.io/api/auth/approle/index.html). 112 113## FAQ 114 115### What if someone directly rotates an Active Directory password that Vault is managing? 116 117If an administrator at your company rotates a password that Vault is managing, 118the next time an application asks _Vault_ for that password, Vault won't know 119it. 120 121To maintain that application's up-time, Vault will need to return to a state of 122knowing the password. Vault will generate a new password, update it, and return 123it to the application(s) asking for it. This all occurs automatically, without 124human intervention. 125 126Thus, we wouldn't recommend that administrators directly rotate the passwords 127for accounts that Vault is managing. This may lead to behavior the 128administrator wouldn't expect, like finding very quickly afterwards that their 129new password has already been changed. 130 131The password `ttl` on a role can be updated at any time to ensure that the 132responsibility of updating passwords can be left to Vault, rather than 133requiring manual administrator updates. 134 135### Why does Vault return the last password in addition to the current one? 136 137Active Directory promises _eventual consistency_, which means that new 138passwords may not be propagated to all instances immediately. To deal with 139this, Vault returns the current password with the last password if it's known. 140That way, if a new password isn't fully operational, the last password can also 141be used. 142 143## API 144 145The Active Directory secrets engine has a full HTTP API. Please see the 146[Active Directory secrets engine API](/api/secret/ad/index.html) for more 147details. 148