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:

$ 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.

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:

$ vault secrets disable ad

To disable at a custom path:

$ vault secrets disable <custom_path>