Skip to content

Commit 20e201b

Browse files
hc-github-team-secure-vault-coreaustingebauer
hc-github-team-secure-vault-core
and
austingebauer
authored
backport of commit da31528 (#19405)
Co-authored-by: Austin Gebauer <[email protected]>
1 parent 7383b52 commit 20e201b

File tree

8 files changed

+193
-3
lines changed

8 files changed

+193
-3
lines changed

‎website/content/api-docs/secret/ad.mdx

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ description: This is the API documentation for the Vault Active Directory secret
66

77
# Active Directory Secrets Engine (API)
88

9+
@include 'ad-secrets-deprecation.mdx'
10+
911
@include 'x509-sha1-deprecation.mdx'
1012

1113
This is the API documentation for the Vault AD secrets engine. For general

‎website/content/docs/deprecation/faq.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ layout: docs
33
page_title: Feature Deprecation FAQ
44
sidebar_title: FAQ
55
description: |-
6-
An FAQ page to communicate frequently asked questions concering feature deprecations.
6+
An FAQ page to communicate frequently asked questions concerning feature deprecations.
77
---
88

99
# Feature Deprecation FAQ

‎website/content/docs/deprecation/index.mdx

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,10 @@ This announcement page is maintained and updated periodically to communicate imp
2020

2121
| Feature | Deprecation announcement | End of Support | Feature Removal | Migration Path/Impact | Resources |
2222
| ------------------------------------------------- | ------------------------ | -------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
23+
| 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) |
2324
| 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) |
2425
| 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) |
25-
| [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:<version>` 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/)
26+
| [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:<version>` 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/) |
2627
| 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) |
2728
| 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) |
2829
| 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) |

‎website/content/docs/secrets/ad.mdx renamed to ‎website/content/docs/secrets/ad/index.mdx

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ description: >-
77

88
# Active Directory Secrets Engine
99

10+
@include 'ad-secrets-deprecation.mdx'
11+
1012
@include 'x509-sha1-deprecation.mdx'
1113

1214
The Active Directory (AD) secrets engine is a plugin residing [here](https://github.com/hashicorp/vault-plugin-secrets-active-directory).

‎website/content/docs/secrets/ad/migration-guide.mdx

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
layout: docs
3+
page_title: Migration Guide - Active Directory - Secrets Engines
4+
description: >-
5+
The guide for migrating from the Active Directory secrets engine to the LDAP secrets engine.
6+
---
7+
8+
# Migration Guide - Active Directory Secrets Engine
9+
10+
The Vault [Active Directory secrets engine](/vault/docs/secrets/ad) has been deprecated as
11+
of the Vault 1.13 release. This document provides guidance for migrating from the Active
12+
Directory secrets engine to the [LDAP secrets engine](/vault/docs/secrets/ldap) that was
13+
introduced in Vault 1.12.
14+
15+
## Deprecation Timeline
16+
17+
Beginning from the Vault 1.13 release, we will continue to support the Active Directory (AD)
18+
secrets engine in maintenance mode for six major Vault releases. Maintenance mode means that
19+
we will fix bugs and security issues, but no new features will be added. All new feature
20+
development efforts will go towards the unified LDAP secrets engine. At Vault 1.18, we will
21+
mark the AD secrets engine as [pending removal](/vault/docs/deprecation/faq#pending-removal).
22+
At this time, Vault will begin to strongly signal operators that they need to migrate off of
23+
the AD secrets engine. At Vault 1.19, we will mark the AD secrets engine as
24+
[removed](/vault/docs/deprecation/faq#removed). At this time, the AD secrets engine will be
25+
removed from Vault. Vault will not start up with the AD secrets engine mounts enabled.
26+
27+
## Migration Steps
28+
29+
The following sections detail how to migrate the AD secrets engine configuration and
30+
applications consuming secrets to the new LDAP secrets engine.
31+
32+
### 1. Enable LDAP Secrets Engine
33+
34+
The LDAP secrets engine needs to be enabled in order to have a target for migration of
35+
existing AD secrets engine mounts. AD secrets engine mounts should be mapped 1-to-1 with
36+
new LDAP secrets engine mounts.
37+
38+
To enable the LDAP secrets engine:
39+
40+
```shell-session
41+
$ vault secrets enable ldap
42+
```
43+
44+
To enable at a custom path:
45+
46+
```shell-session
47+
$ vault secrets enable -path=<custom_path> ldap
48+
```
49+
50+
If enabled at a custom path, the `/ldap/` path segment in API paths must be replaced with
51+
the custom path value.
52+
53+
### 2. Migrate Configuration
54+
55+
The AD secrets engine [configuration](/vault/api-docs/secret/ad#configuration)
56+
will need to be migrated to an LDAP secrets engine [configuration](/vault/api-docs/secret/ldap#configuration-management).
57+
The API paths and parameters will need to be considered during the migration.
58+
59+
#### API Path
60+
61+
| AD Secrets Engine | LDAP Secrets Engine |
62+
| ----------------- |-------------------- |
63+
| [/ad/config](/vault/api-docs/secret/ad#configuration) | [/ldap/config](/vault/api-docs/secret/ad#configuration) |
64+
65+
#### Parameters
66+
67+
The parameters from existing AD secrets engine configurations can generally be mapped 1-to-1
68+
to LDAP secrets engine configuration. The following LDAP secrets engine parameters are the
69+
exception and must be considered during the migration.
70+
71+
| AD Secrets Engine | LDAP Secrets Engine | Details |
72+
| ----------------- | ------------------- | ------- |
73+
| N/A | [schema](/vault/api-docs/secret/ldap#schema) | Must be set to the `ad` option on the LDAP secrets engine configuration. |
74+
| [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)). |
75+
| [ttl](/vault/api-docs/secret/ad#ttl) | N/A | Replaced by static role [rotation_period](/vault/api-docs/secret/ldap#rotation_period). |
76+
| [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. |
77+
| [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). |
78+
79+
### 3. Migrate Roles
80+
81+
AD secrets engine [roles](/vault/api-docs/secret/ad#role-management) will need to be migrated
82+
to LDAP secrets engine [static roles](/vault/api-docs/secret/ldap#static-roles). The API paths,
83+
parameters, and rotation periods will need to be considered during the migration.
84+
85+
#### API Path
86+
87+
| AD Secrets Engine | LDAP Secrets Engine |
88+
| ----------------- | ------------------- |
89+
| [/ad/roles/:role_name](/vault/api-docs/secret/ad#role-management) | [/ldap/static-role/:role_name](/vault/api-docs/secret/ldap#static-roles) |
90+
91+
#### Parameters
92+
93+
The following parameters must be migrated.
94+
95+
| AD Secrets Engine | LDAP Secrets Engine | Details |
96+
| ----------------- | ------------------- | ------- |
97+
| [ttl](/vault/api-docs/secret/ad#ttl-1) | [rotation_period](/vault/api-docs/secret/ldap#rotation_period) | N/A |
98+
| [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. |
99+
100+
#### Rotation Periods
101+
102+
Rotations that occur from AD secrets engine [roles](/vault/api-docs/secret/ad#role-management)
103+
may conflict with rotations performed by LDAP secrets engine [static roles](/vault/api-docs/secret/ldap#static-roles)
104+
during the migration process. This could cause applications consuming passwords to read a
105+
password that gets invalidated by a rotation shortly after. To mitigate this, it's recommended
106+
to set an initial [rotation_period](/vault/api-docs/secret/ldap#rotation_period) that provides
107+
a large enough window to complete [application migrations](#5-migrate-applications) to minimize
108+
the chance of this happening. Additionally, tuning the AD secrets engine [last_rotation_tolerance](/vault/api-docs/secret/ad#last_rotation_tolerance)
109+
parameter could help mitigate applications reading stale passwords, since the parameter allows
110+
rotation of the password if it's been rotated out-of-band within a given duration.
111+
112+
### 4. Migrate Library Sets
113+
114+
AD secrets engine [library sets](/vault/api-docs/secret/ad#library-management) will need to
115+
be migrated to LDAP secrets engine [library sets](/vault/api-docs/secret/ldap#library-set-management).
116+
The API paths and parameters will need to be considered during the migration.
117+
118+
#### API Path
119+
120+
| AD Secrets Engine | LDAP Secrets Engine |
121+
| ----------------- | ------------------- |
122+
| [/ad/library/:set_name](/vault/api-docs/secret/ad#library-management) | [/ldap/library/:set_name](/vault/api-docs/secret/ldap#library-set-management) |
123+
124+
#### Parameters
125+
126+
The parameters from existing AD secrets engine library sets can be exactly mapped 1-to-1
127+
to LDAP secrets engine library sets. There are no exceptions to consider.
128+
129+
### 5. Migrate Applications
130+
131+
The AD secrets engine provides APIs to obtain credentials for AD users and service accounts.
132+
Applications, or Vault clients, are typically the consumer of these credentials. For applications
133+
to successfully migrate, they must begin using new API paths and response formats provided
134+
by the LDAP secrets engine. Additionally, they must obtain a Vault [token](/vault/docs/concepts/tokens)
135+
with an ACL [policy](/vault/docs/concepts/policies) that authorizes access to the new APIs.
136+
The following section details credential-providing APIs and how their response formats differ
137+
between the AD secrets engine and LDAP secrets engine.
138+
139+
#### API Paths
140+
141+
| AD Secrets Engine | LDAP Secrets Engine | Details |
142+
| ----------------- | ------------------- | ------- |
143+
| [/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. |
144+
| [/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. |
145+
| [/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. |
146+
147+
### 6. Disable AD Secrets Engines
148+
149+
AD secrets engine mounts can be disabled after successful migration of configuration and
150+
applications to the LDAP secrets engine. Note that disabling the secrets engine will erase
151+
its configuration from storage. This cannot be reversed.
152+
153+
To disable the AD secrets engine:
154+
155+
```shell-session
156+
$ vault secrets disable ad
157+
```
158+
159+
To disable at a custom path:
160+
161+
```shell-session
162+
$ vault secrets disable <custom_path>
163+
```

‎website/content/docs/upgrading/upgrade-to-1.13.x.mdx

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,14 @@ for Vault 1.13.x compared to 1.12. Please read it carefully.
1818

1919
@include 'consul-dataplane-upgrade-note.mdx'
2020

21+
### Active Directory Secrets Engine Deprecation
22+
23+
The Active Directory (AD) secrets engine has been deprecated as of the Vault 1.13 release.
24+
We will continue to support the AD secrets engine in maintenance mode for six major Vault
25+
releases. Maintenance mode means that we will fix bugs and security issues but will not add
26+
new features. For additional information, see the [deprecation table](/vault/docs/deprecation)
27+
and [migration guide](/vault/docs/secrets/ad/migration-guide).
28+
2129
### AliCloud Auth Role Parameter
2230

2331
The AliCloud auth plugin will now require the `role` parameter on login. This

‎website/content/partials/ad-secrets-deprecation.mdx

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
~> **Note**: The Active Directory (AD) secrets engine has been deprecated as of the Vault
2+
1.13 release. We will continue to support the AD secrets engine in maintenance mode for
3+
six major Vault releases. Maintenance mode means that we will fix bugs and security issues
4+
but will not add new features. For additional information, see the [deprecation table](/vault/docs/deprecation)
5+
and [migration guide](/vault/docs/secrets/ad/migration-guide).

‎website/data/docs-nav-data.json

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -993,7 +993,16 @@
993993
},
994994
{
995995
"title": "Active Directory",
996-
"path": "secrets/ad"
996+
"routes": [
997+
{
998+
"title": "Overview",
999+
"path": "secrets/ad"
1000+
},
1001+
{
1002+
"title": "Migration Guide",
1003+
"path": "secrets/ad/migration-guide"
1004+
}
1005+
]
9971006
},
9981007
{
9991008
"title": "AliCloud",

0 commit comments

Comments
 (0)