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