164 lines
8.7 KiB
Plaintext
164 lines
8.7 KiB
Plaintext
|
---
|
||
|
|
layout: docs
|
||
|
|
page_title: Migration Guide - Active Directory - Secrets Engines
|
||
|
|
description: >-
|
||
|
|
The guide for migrating from the Active Directory secrets engine to the LDAP secrets engine.
|
||
|
|
---
|
||
|
|
|
||
|
|
# Migration Guide - Active Directory Secrets Engine
|
||
|
|
|
||
|
|
The Vault [Active Directory secrets engine](/vault/docs/secrets/ad) 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](/vault/docs/secrets/ldap) 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](/vault/docs/deprecation/faq#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](/vault/docs/deprecation/faq#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:
|
||
|
|
|
||
|
|
```shell-session
|
||
|
|
$ vault secrets enable ldap
|
||
|
|
```
|
||
|
|
|
||
|
|
To enable at a custom path:
|
||
|
|
|
||
|
|
```shell-session
|
||
|
|
$ 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](/vault/api-docs/secret/ad#configuration)
|
||
|
|
will need to be migrated to an LDAP secrets engine [configuration](/vault/api-docs/secret/ldap#configuration-management).
|
||
|
|
The API paths and parameters will need to be considered during the migration.
|
||
|
|
|
||
|
|
#### API Path
|
||
|
|
|
||
|
|
| AD Secrets Engine | LDAP Secrets Engine |
|
||
|
|
| ----------------- |-------------------- |
|
||
|
|
| [/ad/config](/vault/api-docs/secret/ad#configuration) | [/ldap/config](/vault/api-docs/secret/ad#configuration) |
|
||
|
|
|
||
|
|
#### 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](/vault/api-docs/secret/ldap#schema) | Must be set to the `ad` option on the LDAP secrets engine configuration. |
|
||
|
|
| [userdn](/vault/api-docs/secret/ad#userdn) | [userdn](/vault/api-docs/secret/ad#userdn) | Required to be set if using the [library sets](#4-migrate-library-sets) check-out feature. It can be optionally set if using the [static roles](#3-migrate-roles) feature without providing a distinguished name ([dn](/vault/api-docs/secret/ldap#dn)). |
|
||
|
|
| [ttl](/vault/api-docs/secret/ad#ttl) | N/A | Replaced by static role [rotation_period](/vault/api-docs/secret/ldap#rotation_period). |
|
||
|
|
| [max_ttl](/vault/api-docs/secret/ad#max_ttl) | N/A | Not supported for [static roles](#3-migrate-roles). Can be set using [max_ttl](/vault/api-docs/secret/ldap#max_ttl-1) for library sets. |
|
||
|
|
| [last_rotation_tolerance](/vault/api-docs/secret/ad#last_rotation_tolerance) | N/A | Not supported by the LDAP secrets engine. Passwords will be rotated based on the static role [rotation_period](/vault/api-docs/secret/ldap#rotation_period). |
|
||
|
|
|
||
|
|
### 3. Migrate Roles
|
||
|
|
|
||
|
|
AD secrets engine [roles](/vault/api-docs/secret/ad#role-management) will need to be migrated
|
||
|
|
to LDAP secrets engine [static roles](/vault/api-docs/secret/ldap#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](/vault/api-docs/secret/ad#role-management) | [/ldap/static-role/:role_name](/vault/api-docs/secret/ldap#static-roles) |
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
|
||
|
|
The following parameters must be migrated.
|
||
|
|
|
||
|
|
| AD Secrets Engine | LDAP Secrets Engine | Details |
|
||
|
|
| ----------------- | ------------------- | ------- |
|
||
|
|
| [ttl](/vault/api-docs/secret/ad#ttl-1) | [rotation_period](/vault/api-docs/secret/ldap#rotation_period) | N/A |
|
||
|
|
| [service_account_name](/vault/api-docs/secret/ad#service_account_name) | [username](/vault/api-docs/secret/ldap#username) | If `username` is set without setting the [dn](/vault/api-docs/secret/ldap#dn) value, then the configuration [userdn](/vault/api-docs/secret/ldap#userdn) must also be set. |
|
||
|
|
|
||
|
|
#### Rotation Periods
|
||
|
|
|
||
|
|
Rotations that occur from AD secrets engine [roles](/vault/api-docs/secret/ad#role-management)
|
||
|
|
may conflict with rotations performed by LDAP secrets engine [static roles](/vault/api-docs/secret/ldap#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](/vault/api-docs/secret/ldap#rotation_period) that provides
|
||
|
|
a large enough window to complete [application migrations](#5-migrate-applications) to minimize
|
||
|
|
the chance of this happening. Additionally, tuning the AD secrets engine [last_rotation_tolerance](/vault/api-docs/secret/ad#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.
|
||
|
|
|
||
|
|
### 4. Migrate Library Sets
|
||
|
|
|
||
|
|
AD secrets engine [library sets](/vault/api-docs/secret/ad#library-management) will need to
|
||
|
|
be migrated to LDAP secrets engine [library sets](/vault/api-docs/secret/ldap#library-set-management).
|
||
|
|
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](/vault/api-docs/secret/ad#library-management) | [/ldap/library/:set_name](/vault/api-docs/secret/ldap#library-set-management) |
|
||
|
|
|
||
|
|
#### 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](/vault/docs/concepts/tokens)
|
||
|
|
with an ACL [policy](/vault/docs/concepts/policies) 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](/vault/api-docs/secret/ad#retrieving-passwords) | [/ldap/static-cred/:role_name](/vault/api-docs/secret/ldap#static-role-passwords) | Response formats differ. Namely, `current_password` is now `password`. See [AD response](/vault/api-docs/secret/ad#sample-get-response) and [LDAP response](/vault/api-docs/secret/ldap#sample-get-response-1) for the difference. |
|
||
|
|
| [/ad/library/:set_name/check-out](/vault/api-docs/secret/ad#check-a-credential-out) | [/ldap/library/:set_name/check-out](/vault/api-docs/secret/ldap#check-out-management) | Response formats do not differ. |
|
||
|
|
| [/ad/library/:set_name/check-in](/vault/api-docs/secret/ad#check-a-credential-in) | [/ldap/library/:set_name/check-in](/vault/api-docs/secret/ldap#check-in-management) | 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:
|
||
|
|
|
||
|
|
```shell-session
|
||
|
|
$ vault secrets disable ad
|
||
|
|
```
|
||
|
|
|
||
|
|
To disable at a custom path:
|
||
|
|
|
||
|
|
```shell-session
|
||
|
|
$ vault secrets disable <custom_path>
|
||
|
|
```
|