From 20e201bdc3038ab740b7ad29ca959dcd17715d1b Mon Sep 17 00:00:00 2001 From: hc-github-team-secure-vault-core <82990506+hc-github-team-secure-vault-core@users.noreply.github.com> Date: Tue, 28 Feb 2023 13:55:57 -0500 Subject: [PATCH] backport of commit da31528fdc0d9b043a21b1676694eecfaef130db (#19405) Co-authored-by: Austin Gebauer <34121980+austingebauer@users.noreply.github.com> --- website/content/api-docs/secret/ad.mdx | 2 + website/content/docs/deprecation/faq.mdx | 2 +- website/content/docs/deprecation/index.mdx | 3 +- .../docs/secrets/{ad.mdx => ad/index.mdx} | 2 + .../docs/secrets/ad/migration-guide.mdx | 163 ++++++++++++++++++ .../docs/upgrading/upgrade-to-1.13.x.mdx | 8 + .../partials/ad-secrets-deprecation.mdx | 5 + website/data/docs-nav-data.json | 11 +- 8 files changed, 193 insertions(+), 3 deletions(-) rename website/content/docs/secrets/{ad.mdx => ad/index.mdx} (99%) create mode 100644 website/content/docs/secrets/ad/migration-guide.mdx create mode 100644 website/content/partials/ad-secrets-deprecation.mdx diff --git a/website/content/api-docs/secret/ad.mdx b/website/content/api-docs/secret/ad.mdx index fa2c1b5ba6f4..61c7b99bf282 100644 --- a/website/content/api-docs/secret/ad.mdx +++ b/website/content/api-docs/secret/ad.mdx @@ -6,6 +6,8 @@ description: This is the API documentation for the Vault Active Directory secret # Active Directory Secrets Engine (API) +@include 'ad-secrets-deprecation.mdx' + @include 'x509-sha1-deprecation.mdx' This is the API documentation for the Vault AD secrets engine. For general diff --git a/website/content/docs/deprecation/faq.mdx b/website/content/docs/deprecation/faq.mdx index 88fc18b175d9..c953ef5a576a 100644 --- a/website/content/docs/deprecation/faq.mdx +++ b/website/content/docs/deprecation/faq.mdx @@ -3,7 +3,7 @@ layout: docs page_title: Feature Deprecation FAQ sidebar_title: FAQ description: |- - An FAQ page to communicate frequently asked questions concering feature deprecations. + An FAQ page to communicate frequently asked questions concerning feature deprecations. --- # Feature Deprecation FAQ diff --git a/website/content/docs/deprecation/index.mdx b/website/content/docs/deprecation/index.mdx index 057783250d83..7dbe52d92958 100644 --- a/website/content/docs/deprecation/index.mdx +++ b/website/content/docs/deprecation/index.mdx @@ -20,9 +20,10 @@ This announcement page is maintained and updated periodically to communicate imp | Feature | Deprecation announcement | End of Support | Feature Removal | Migration Path/Impact | Resources | | ------------------------------------------------- | ------------------------ | -------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Active Directory Secrets Engine | 1.13 | v1.18 | v1.19 | Use the [LDAP Secrets Engine](/vault/docs/secrets/ldap) with the `ad` [schema](/vault/api-docs/secret/ldap#schema) | [Migration Guide](/vault/docs/secrets/ad/migration-guide) | | Vault Enterprise storage backend | N/A | v1.12 | N/A | Use [Integrated Storage](/vault/docs/configuration/storage/raft) or [Consul](/vault/docs/configuration/storage/consul) as your Vault's storage backend. Vault Enterprise will no longer start up if configured to use a storage backend other than Integrated Storage or Consul. | [Upgrade Guide](/vault/docs/upgrading/upgrade-to-1.12.x) | | Vault generation of Dynamic SSH Keys | v0.7.1 | N/A | v1.13 | Use the alternative [signed SSH certificates](/vault/docs/secrets/ssh/signed-ssh-certificates) feature which supports key pair generation as of Vault 1.12. SSH certificates do not require an external connection from Vault to provision the key/certificate and more secure than having Vault provision dynamic SSH keys. | [SSH Certificates](/vault/docs/secrets/ssh/signed-ssh-certificates) | -| [Duplicative Docker Images](https://hub.docker.com/_/vault) | v1.12 | 1.13 | v1.14 | Upon feature removal, the `vault` Docker image will no longer be updated. Only the [Verified Publisher](https://hub.docker.com/r/hashicorp/vault) `hashicorp/vault` image will be updated on DockerHub. Users of [Official Images](https://hub.docker.com/_/vault) will need to use `docker pull hashicorp/vault:` instead of `docker pull vault:version` to get newer versions of Vault in Docker images. Currently, HashiCorp publishes and updates identical Docker images of Vault as Verified Publisher and Official images separately. | [The Verified Publisher Program](https://docs.docker.com/docker-hub/publish/) +| [Duplicative Docker Images](https://hub.docker.com/_/vault) | v1.12 | 1.13 | v1.14 | Upon feature removal, the `vault` Docker image will no longer be updated. Only the [Verified Publisher](https://hub.docker.com/r/hashicorp/vault) `hashicorp/vault` image will be updated on DockerHub. Users of [Official Images](https://hub.docker.com/_/vault) will need to use `docker pull hashicorp/vault:` instead of `docker pull vault:version` to get newer versions of Vault in Docker images. Currently, HashiCorp publishes and updates identical Docker images of Vault as Verified Publisher and Official images separately. | [The Verified Publisher Program](https://docs.docker.com/docker-hub/publish/) | | Etcd V2 API (OSS) | v1.9 | N/A | v1.10 | The Etcd v2 has been deprecated with the release of Etcd v3.5, and will be decomissioned by Etcd v3.6. Etcd v2 API has been removed in Vaut 1.10. Users of Etcd storage backend must migrate Vault storage to an Etcd V3 cluster prior to upgrading to Vault 1.10. All storage migrations should be backed up prior to migration. | [Etcd Storage Backend](/vault/docs/configuration/storage/etcd) | | Licenses in storage (ENT) | v1.8 | v1.10 | v1.11 | Migrate to [Autoloading](/vault/docs/enterprise/license/autoloading) by v1.11. | [Vault License](/vault/docs/enterprise/license) [System Backend](/vault/api-docs/system/license) [FAQ](/vault/docs/enterprise/license/faq) | | Mount Filters (ENT) | v1.3 | v1.10 | v1.11 | Use the alternative feature: [Path Filters](/vault/api-docs/system/replication/replication-performance#create-paths-filter). | [API Deprecation Notice](/vault/api-docs/system/replication/replication-performance#create-mounts-filter-deprecated) [Filter Mount Replication Deprecation Notice](/vault/docs/upgrading/upgrade-to-1.3.0#filtered-mount-replication-deprecation) | diff --git a/website/content/docs/secrets/ad.mdx b/website/content/docs/secrets/ad/index.mdx similarity index 99% rename from website/content/docs/secrets/ad.mdx rename to website/content/docs/secrets/ad/index.mdx index a7bfcb07e877..8c94477f49bc 100644 --- a/website/content/docs/secrets/ad.mdx +++ b/website/content/docs/secrets/ad/index.mdx @@ -7,6 +7,8 @@ description: >- # Active Directory Secrets Engine +@include 'ad-secrets-deprecation.mdx' + @include 'x509-sha1-deprecation.mdx' The Active Directory (AD) secrets engine is a plugin residing [here](https://github.com/hashicorp/vault-plugin-secrets-active-directory). diff --git a/website/content/docs/secrets/ad/migration-guide.mdx b/website/content/docs/secrets/ad/migration-guide.mdx new file mode 100644 index 000000000000..5af91330f4b0 --- /dev/null +++ b/website/content/docs/secrets/ad/migration-guide.mdx @@ -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= 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 +``` diff --git a/website/content/docs/upgrading/upgrade-to-1.13.x.mdx b/website/content/docs/upgrading/upgrade-to-1.13.x.mdx index d0fd7fe22091..885e76c50838 100644 --- a/website/content/docs/upgrading/upgrade-to-1.13.x.mdx +++ b/website/content/docs/upgrading/upgrade-to-1.13.x.mdx @@ -18,6 +18,14 @@ for Vault 1.13.x compared to 1.12. Please read it carefully. @include 'consul-dataplane-upgrade-note.mdx' +### Active Directory Secrets Engine Deprecation + +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). + ### AliCloud Auth Role Parameter The AliCloud auth plugin will now require the `role` parameter on login. This diff --git a/website/content/partials/ad-secrets-deprecation.mdx b/website/content/partials/ad-secrets-deprecation.mdx new file mode 100644 index 000000000000..85732c38350e --- /dev/null +++ b/website/content/partials/ad-secrets-deprecation.mdx @@ -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). diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 1e4b4939f271..8b0f7f506e8f 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -993,7 +993,16 @@ }, { "title": "Active Directory", - "path": "secrets/ad" + "routes": [ + { + "title": "Overview", + "path": "secrets/ad" + }, + { + "title": "Migration Guide", + "path": "secrets/ad/migration-guide" + } + ] }, { "title": "AliCloud",