forked from hashicorp/vault
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs/ad: adds deprecation announcements and migration guide (hashicor…
…p#19388) * docs/ad: adds deprecation announcements and migration guide * fix table ending * remove fully-qualified links * Minor format fixes - migrationguide * Update website/content/docs/secrets/ad/migration-guide.mdx Co-authored-by: vinay-gopalan <86625824+vinay-gopalan@users.noreply.github.com> * Update website/content/docs/secrets/ad/migration-guide.mdx Co-authored-by: vinay-gopalan <86625824+vinay-gopalan@users.noreply.github.com> --------- Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com> Co-authored-by: vinay-gopalan <86625824+vinay-gopalan@users.noreply.github.com>
- Loading branch information
3 people
authored
Feb 28, 2023
1 parent
bcc1d5d
commit da31528
Showing
8 changed files
with
193 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,163 @@ | ||
| --- | ||
| 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> | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| ~> **Note**: The Active Directory (AD) secrets engine has been deprecated as of the Vault | ||
| 1.13 release. We will continue to support the AD secrets engine in maintenance mode for | ||
| six major Vault releases. Maintenance mode means that we will fix bugs and security issues | ||
| but will not add new features. For additional information, see the [deprecation table](/vault/docs/deprecation) | ||
| and [migration guide](/vault/docs/secrets/ad/migration-guide). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters