| layout | page_title | description |
|---|---|---|
docs |
Migration Guide - Active Directory - Secrets Engines |
The guide for migrating from the Active Directory secrets engine to the LDAP 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.
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.
The following sections detail how to migrate the AD secrets engine configuration and applications consuming secrets to the new 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:
$ vault secrets enable ldap
To enable at a custom path:
$ vault secrets enable -path=<custom_path> ldap
If enabled at a custom path, the /ldap/ path segment in API paths must be replaced with
the custom path value.
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.
| AD Secrets Engine | LDAP Secrets Engine |
|---|---|
| /ad/config | /ldap/config |
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. |
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.
| AD Secrets Engine | LDAP Secrets Engine |
|---|---|
| /ad/roles/:role_name | /ldap/static-role/:role_name |
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. |
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.
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.
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.
| AD Secrets Engine | LDAP Secrets Engine |
|---|---|
| /ad/library/:set_name | /ldap/library/:set_name |
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.
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.
| 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. |
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:
$ vault secrets disable ad
To disable at a custom path:
$ vault secrets disable <custom_path>