Migration guide - active directory secrets engine
The Vault Active Directory secrets engine has been deprecated as of the Vault 1.13 release. This document provides guidance for migrating from the Active Directory secrets engine to the LDAP secrets engine that was introduced in Vault 1.12.
Deprecation timeline
Beginning from the Vault 1.13 release, we will continue to support the Active Directory (AD) secrets engine in maintenance mode for six major Vault releases. Maintenance mode means that we will fix bugs and security issues, but no new features will be added. All new feature development efforts will go towards the unified LDAP secrets engine. At Vault 1.18, we will mark the AD secrets engine as pending removal. At this time, Vault will begin to strongly signal operators that they need to migrate off of the AD secrets engine. At Vault 1.19, we will mark the AD secrets engine as removed. At this time, the AD secrets engine will be removed from Vault. Vault will not start up with the AD secrets engine mounts enabled.
Migration steps
The following sections detail how to migrate the AD secrets engine configuration and applications consuming secrets to the new LDAP secrets engine.
1. enable LDAP secrets engine
The LDAP secrets engine needs to be enabled in order to have a target for migration of existing AD secrets engine mounts. AD secrets engine mounts should be mapped 1-to-1 with new LDAP secrets engine mounts.
To enable the LDAP secrets engine:
To enable at a custom path:
If enabled at a custom path, the /ldap/ path segment in API paths must be replaced with
the custom path value.
2. migrate configuration
The AD secrets engine configuration will need to be migrated to an LDAP secrets engine configuration. The API paths and parameters will need to be considered during the migration.
API path
| AD Secrets Engine | LDAP Secrets Engine |
|---|---|
| /ad/config | /ldap/config |
Parameters
The parameters from existing AD secrets engine configurations can generally be mapped 1-to-1 to LDAP secrets engine configuration. The following LDAP secrets engine parameters are the exception and must be considered during the migration.
| AD Secrets Engine | LDAP Secrets Engine | Details |
|---|---|---|
| N/A | schema | Must be set to the ad option on the LDAP secrets engine configuration. |
| userdn | userdn | Required to be set if using the library sets check-out feature. It can be optionally set if using the static roles feature without providing a distinguished name (dn). |
| ttl | N/A | Replaced by static role rotation_period. |
| max_ttl | N/A | Not supported for static roles. Can be set using max_ttl for library sets. |
| last_rotation_tolerance | N/A | Not supported by the LDAP secrets engine. Passwords will be rotated based on the static role rotation_period. |
3. migrate roles
AD secrets engine roles will need to be migrated to LDAP secrets engine static roles. The API paths, parameters, and rotation periods will need to be considered during the migration.
API path
| AD Secrets Engine | LDAP Secrets Engine |
|---|---|
| /ad/roles/:role_name | /ldap/static-role/:role_name |
Parameters
The following parameters must be migrated.
| AD Secrets Engine | LDAP Secrets Engine | Details |
|---|---|---|
| ttl | rotation_period | N/A |
| service_account_name | username | If username is set without setting the dn value, then the configuration userdn must also be set. |
Rotation periods
Rotations that occur from AD secrets engine roles may conflict with rotations performed by LDAP secrets engine static roles during the migration process. This could cause applications consuming passwords to read a password that gets invalidated by a rotation shortly after. To mitigate this, it's recommended to set an initial rotation_period that provides a large enough window to complete application migrations to minimize the chance of this happening. Additionally, tuning the AD secrets engine last_rotation_tolerance parameter could help mitigate applications reading stale passwords, since the parameter allows rotation of the password if it's been rotated out-of-band within a given duration.
Lazy rotation vs automatic rotation
The AD secrets engine uses lazy rotation for passwords. With lazy rotation, passwords rotate whenever the engine receives a request for a role whose rotation period has elapsed.
The LDAP secret engine uses automatic rotation for passwords. With automatic rotation, passwords are rotated as soon as the rotation period elapses, without waiting for a client request.
When migrating to the LDAP secret engine, you may need to account for the rotation changes in your clients. For example, if your client assumes the password does not change until its next request to Vault and uses the password to verify against other services.
4. migrate library sets
AD secrets engine library sets will need to be migrated to LDAP secrets engine library sets. The API paths and parameters will need to be considered during the migration.
API path
| AD Secrets Engine | LDAP Secrets Engine |
|---|---|
| /ad/library/:set_name | /ldap/library/:set_name |
Parameters
The parameters from existing AD secrets engine library sets can be exactly mapped 1-to-1 to LDAP secrets engine library sets. There are no exceptions to consider.
5. migrate applications
The AD secrets engine provides APIs to obtain credentials for AD users and service accounts. Applications, or Vault clients, are typically the consumer of these credentials. For applications to successfully migrate, they must begin using new API paths and response formats provided by the LDAP secrets engine. Additionally, they must obtain a Vault token with an ACL policy that authorizes access to the new APIs. The following section details credential-providing APIs and how their response formats differ between the AD secrets engine and LDAP secrets engine.
API paths
| AD Secrets Engine | LDAP Secrets Engine | Details |
|---|---|---|
| /ad/creds/:role_name | /ldap/static-cred/:role_name | Response formats differ. Namely, current_password is now password. See AD response and LDAP response for the difference. |
| /ad/library/:set_name/check-out | /ldap/library/:set_name/check-out | Response formats do not differ. |
| /ad/library/:set_name/check-in | /ldap/library/:set_name/check-in | Response formats do not differ. |
6. disable AD secrets engines
AD secrets engine mounts can be disabled after successful migration of configuration and applications to the LDAP secrets engine. Note that disabling the secrets engine will erase its configuration from storage. This cannot be reversed.
To disable the AD secrets engine:
To disable at a custom path: