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). 14It has two main features. 15 16The first feature (password rotation) is where the AD secrets engine rotates AD passwords dynamically. 17This is designed for a high-load environment where many instances may be accessing 18a shared password simultaneously. With a simple set up and a simple creds API, 19it doesn't require instances to be manually registered in advance to gain access. 20As long as access has been granted to the creds path via a method like 21[AppRole](https://www.vaultproject.io/api/auth/approle/index.html), they're available. Passwords are 22lazily rotated based on preset TTLs and can have a length configured to meet your needs. 23 24The second feature (service account check-out) is where a library of service accounts can 25be checked out by a person or by machines. Vault will automatically rotate the password 26each time a service account is checked in. Service accounts can be voluntarily checked in, or Vault 27will check them in when their lending period (or, "ttl", in Vault's language) ends. 28 29## Password Rotation 30 31### A Note on Lazy Rotation 32 33To drive home the point that passwords are rotated "lazily", consider this scenario: 34 35- A password is configured with a TTL of 1 hour. 36- All instances of a service using this password are off for 12 hours. 37- Then they wake up and again request the password. 38 39In this scenario, although the password TTL was set to 1 hour, the password wouldn't be rotated for 12 hours when it 40was next requested. "Lazy" rotation means passwords are rotated when all of the following conditions are true: 41 42- They are over their TTL 43- They are requested 44 45Therefore, the AD TTL can be considered a soft contract. It's fulfilled when the given password is next requested. 46 47To ensure your passwords are rotated as expected, we'd recommend you configure services to request each password at least 48twice as often as its TTL. 49 50### A Note on Escaping 51 52**It is up to the administrator** to provide properly escaped DNs. This 53includes the user DN, bind DN for search, and so on. 54 55The only DN escaping performed by this method is on usernames given at login 56time when they are inserted into the final bind DN, and uses escaping rules 57defined in RFC 4514. 58 59Additionally, Active Directory has escaping rules that differ slightly from the 60RFC; in particular it requires escaping of '#' regardless of position in the DN 61(the RFC only requires it to be escaped when it is the first character), and 62'=', which the RFC indicates can be escaped with a backslash, but does not 63contain in its set of required escapes. If you are using Active Directory and 64these appear in your usernames, please ensure that they are escaped, in 65addition to being properly escaped in your configured DNs. 66 67For reference, see [RFC 4514](https://www.ietf.org/rfc/rfc4514.txt) and this 68[TechNet post on characters to escape in Active 69Directory](http://social.technet.microsoft.com/wiki/contents/articles/5312.active-directory-characters-to-escape.aspx). 70 71### Quick Setup 72 73Most secrets engines must be configured in advance before they can perform their 74functions. These steps are usually completed by an operator or configuration 75management tool. 76 771. Enable the Active Directory secrets engine: 78 79 ```text 80 $ vault secrets enable ad 81 Success! Enabled the ad secrets engine at: ad/ 82 ``` 83 84 By default, the secrets engine will mount at the name of the engine. To 85 enable the secrets engine at a different path, use the `-path` argument. 86 872. Configure the credentials that Vault uses to communicate with Active Directory 88to generate passwords: 89 90 ```text 91 $ vault write ad/config \ 92 binddn=$USERNAME \ 93 bindpass=$PASSWORD \ 94 url=ldaps://138.91.247.105 \ 95 userdn='dc=example,dc=com' 96 ``` 97 98 The `$USERNAME` and `$PASSWORD` given must have access to modify passwords 99 for the given account. It is possible to delegate access to change 100 passwords for these accounts to the one Vault is in control of, and this is 101 usually the highest-security solution. 102 103 If you'd like to do a quick, insecure evaluation, also set `insecure_tls` to true. However, this is NOT RECOMMENDED 104 in a production environment. In production, we recommend `insecure_tls` is false (its default) and is used with a valid 105 `certificate`. 106 1073. Configure a role that maps a name in Vault to an account in Active Directory. 108When applications request passwords, password rotation settings will be managed by 109this role. 110 111 ```text 112 $ vault write ad/roles/my-application \ 113 service_account_name="my-application@example.com" 114 ``` 115 1164. Grant "my-application" access to its creds at `ad/creds/my-application` using an 117auth method like [AppRole](https://www.vaultproject.io/api/auth/approle/index.html). 118 119### FAQ 120 121#### What if someone directly rotates an Active Directory password that Vault is managing? 122 123If an administrator at your company rotates a password that Vault is managing, 124the next time an application asks _Vault_ for that password, Vault won't know 125it. 126 127To maintain that application's up-time, Vault will need to return to a state of 128knowing the password. Vault will generate a new password, update it, and return 129it to the application(s) asking for it. This all occurs automatically, without 130human intervention. 131 132Thus, we wouldn't recommend that administrators directly rotate the passwords 133for accounts that Vault is managing. This may lead to behavior the 134administrator wouldn't expect, like finding very quickly afterwards that their 135new password has already been changed. 136 137The password `ttl` on a role can be updated at any time to ensure that the 138responsibility of updating passwords can be left to Vault, rather than 139requiring manual administrator updates. 140 141#### Why does Vault return the last password in addition to the current one? 142 143Active Directory promises _eventual consistency_, which means that new 144passwords may not be propagated to all instances immediately. To deal with 145this, Vault returns the current password with the last password if it's known. 146That way, if a new password isn't fully operational, the last password can also 147be used. 148 149## Service Account Check-Out 150 151Vault offers the ability to check service accounts in and out. This is a separate, 152different set of functionality from the password rotation feature above. Let's walk 153through how to use it, with explanation at each step. 154 155First we'll need to enable the AD secrets engine and tell it how to talk to our AD 156server just as we did above. 157 158```text 159$ vault secrets enable ad 160Success! Enabled the ad secrets engine at: ad/ 161 162$ vault write ad/config \ 163 binddn=$USERNAME \ 164 bindpass=$PASSWORD \ 165 url=ldaps://138.91.247.105 \ 166 userdn='dc=example,dc=com' 167``` 168 169Our next step is to designate a set of service accounts for check-out. 170 171```text 172$ vault write ad/library/accounting-team \ 173 service_account_names=fizz@example.com,buzz@example.com \ 174 ttl=10h \ 175 max_ttl=20h \ 176 disable_check_in_enforcement=false 177``` 178 179In this example, the service account names of `fizz@example.com` and `buzz@example.com` have 180already been created on the remote AD server. They've been set aside solely for Vault to handle. 181The `ttl` is how long each check-out will last before Vault checks in a service account, 182rotating its password during check-in. The `max_ttl` is the maximum amount of time it can live 183if it's renewed. These default to `24h`. Also by default, a service account must be checked in 184by the same Vault entity or client token that checked it out. However, if this behavior causes 185problems, set `disable_check_in_enforcement=true`. 186 187When a library of service accounts has been created, view their status at any time to see if they're 188available or checked out. 189 190```text 191$ vault read ad/library/accounting-team/status 192Key Value 193--- ----- 194buzz@example.com map[available:true] 195fizz@example.com map[available:true] 196``` 197 198To check out any service account that's available, simply execute: 199 200```text 201$ vault write -f ad/library/accounting-team/check-out 202Key Value 203--- ----- 204lease_id ad/library/accounting-team/check-out/EpuS8cX7uEsDzOwW9kkKOyGW 205lease_duration 10h 206lease_renewable true 207password ?@09AZKh03hBORZPJcTDgLfntlHqxLy29tcQjPVThzuwWAx/Twx4a2ZcRQRqrZ1w 208service_account_name fizz@example.com 209``` 210 211If the default `ttl` for the check-out is higher than needed, set the check-out to last 212for a shorter time by using: 213 214```text 215$ vault write ad/library/accounting-team/check-out ttl=30m 216Key Value 217--- ----- 218lease_id ad/library/accounting-team/check-out/gMonJ2jB6kYs6d3Vw37WFDCY 219lease_duration 30m 220lease_renewable true 221password ?@09AZerLLuJfEMbRqP+3yfQYDSq6laP48TCJRBJaJu/kDKLsq9WxL9szVAvL/E1 222service_account_name buzz@example.com 223``` 224 225This can be a nice way to say, "Although I _can_ have a check-out for 24 hours, if I 226haven't checked it in after 30 minutes, I forgot or I'm a dead instance, so you can just 227check it back in." 228 229If no service accounts are available for check-out, Vault will return a 400 Bad Request. 230 231```text 232$ vault write -f ad/library/accounting-team/check-out 233Error writing data to ad/library/accounting-team/check-out: Error making API request. 234 235URL: PUT http://localhost:8200/v1/ad/library/accounting-team/check-out 236Code: 400. Errors: 237 238* No service accounts available for check-out. 239``` 240 241To extend a check-out, renew its lease. 242 243```text 244$ vault lease renew ad/library/accounting-team/check-out/0C2wmeaDmsToVFc0zDiX9cMq 245Key Value 246--- ----- 247lease_id ad/library/accounting-team/check-out/0C2wmeaDmsToVFc0zDiX9cMq 248lease_duration 10h 249lease_renewable true 250``` 251 252Renewing a check-out means its current password will live longer, since passwords are rotated 253anytime a password is _checked in_ either by a caller, or by Vault because the check-out `ttl` 254ends. 255 256To check a service account back in for others to use, call: 257 258```text 259$ vault write -f ad/library/accounting-team/check-in 260Key Value 261--- ----- 262check_ins [fizz@example.com] 263``` 264 265Most of the time this will just work, but if multiple service accounts checked out by the same 266caller, Vault will need to know which one(s) to check in. 267 268```text 269$ vault write ad/library/accounting-team/check-in service_account_names=fizz@example.com 270Key Value 271--- ----- 272check_ins [fizz@example.com] 273``` 274 275To perform a check-in, Vault verifies that the caller _should_ be able to check in a given service account. 276To do this, Vault looks for either the same [entity ID](https://learn.hashicorp.com/vault/identity-access-management/iam-identity) 277used to check out the service account, or the same client token. 278 279If a caller is unable to check in a service account, or simply doesn't try, 280Vault will check it back in automatically when the `ttl` expires. However, if that is too long, 281service accounts can be forcibly checked in by a highly privileged user through: 282 283```text 284$ vault write -f ad/library/manage/accounting-team/check-in 285Key Value 286--- ----- 287check_ins [fizz@example.com] 288``` 289 290Or, alternatively, revoking the secret's lease has the same effect. 291 292```text 293$ vault lease revoke ad/library/accounting-team/check-out/PvBVG0m7pEg2940Cb3Jw3KpJ 294All revocation operations queued successfully! 295``` 296 297### Troubleshooting 298 299#### Old passwords are still valid for a period of time. 300 301During testing, we found that by default, many versions of Active Directory 302perpetuate old passwords for a short while. After we discovered this behavior, 303we found articles discussing it by searching for "AD password caching" and "OldPasswordAllowedPeriod". We 304also found [an article from Microsoft](https://support.microsoft.com/en-us/help/906305/new-setting-modifies-ntlm-network-authentication-behavior) 305discussing how to configure this behavior. This behavior appears to vary by AD 306version. We recommend you test the behavior of your particular AD server, 307and edit its settings to gain the desired behavior. 308 309#### I get a lot of 400 Bad Request's when trying to check out service accounts. 310 311This will occur when there aren't enough service accounts for those requesting them. Let's 312suppose our "accounting-team" service accounts are the ones being requested. When Vault 313receives a check-out call but none are available, Vault will log at debug level: 314"'accounting-team' had no check-outs available". Vault will also increment a metric 315containing the strings "active directory", "check-out", "unavailable", and "accounting-team". 316 317Once it's known _which_ library needs more service accounts for checkout, fix this issue 318by merely creating a new service account for it to use in Active Directory, then adding it to 319Vault like so: 320 321```text 322$ vault write ad/library/accounting-team \ 323 service_account_names=fizz@example.com,buzz@example.com,new@example.com 324``` 325 326In this example, fizz and buzz were pre-existing but were still included in the call 327because we'd like them to exist in the resulting set. The new account was appended to 328the end. 329 330#### Sometimes Vault gives me a password but then AD says it's not valid. 331 332Active Directory is eventually consistent, meaning that it can take some time for word 333of a new password to travel across all AD instances in a cluster. In larger clusters, we 334have observed the password taking over 10 seconds to propagate fully. The simplest way to 335handle this is to simply wait and retry using the new password. 336 337## API 338 339The Active Directory secrets engine has a full HTTP API. Please see the 340[Active Directory secrets engine API](/api/secret/ad/index.html) for more 341details. 342