diff --git a/website/content/docs/concepts/identity.mdx b/website/content/docs/concepts/identity.mdx index 3a7daee57c3f..53507f7b067f 100644 --- a/website/content/docs/concepts/identity.mdx +++ b/website/content/docs/concepts/identity.mdx @@ -20,11 +20,13 @@ Each user may have multiple accounts with various identity providers, and Vault supports many of those providers to authenticate with Vault. Vault Identity can tie authentications from various auth methods to a single representation. This representation of a consolidated identity is called an **Entity** and their corresponding accounts with authentication providers can be mapped as -**Aliases**. In essence, each entity is made up of zero or more aliases. +**Aliases**. In essence, each entity is made up of zero or more aliases. An entity cannot have more than one alias for +a particular authentication backend. For example, a user with accounts in both GitHub and LDAP can be mapped to a single entity in Vault with two aliases, one of type GitHub and one of type -LDAP. +LDAP. Note however, if both aliases are created on the same auth mount, say +a Github mount, both aliases cannot be mapped to the same entity. ![Entity overview](/img/vault-identity-doc-1.png) diff --git a/website/content/docs/upgrading/upgrade-to-1.7.0.mdx b/website/content/docs/upgrading/upgrade-to-1.7.x.mdx similarity index 91% rename from website/content/docs/upgrading/upgrade-to-1.7.0.mdx rename to website/content/docs/upgrading/upgrade-to-1.7.x.mdx index 07dfaf13fa65..23c8077d34c1 100644 --- a/website/content/docs/upgrading/upgrade-to-1.7.0.mdx +++ b/website/content/docs/upgrading/upgrade-to-1.7.x.mdx @@ -1,15 +1,15 @@ --- layout: docs -page_title: Upgrading to Vault 1.7.0 - Guides +page_title: Upgrading to Vault 1.7.x - Guides description: |- This page contains the list of deprecations and important or breaking changes - for Vault 1.7.0. Please read it carefully. + for Vault 1.7.x. Please read it carefully. --- # Overview This page contains the list of deprecations and important or breaking changes -for Vault 1.7.0 compared to 1.6. Please read it carefully. +for Vault 1.7.x compared to 1.6. Please read it carefully. ## Barrier Key Auto-Rotation @@ -31,6 +31,8 @@ endpoint changes is available in the [AWS Auth API docs](/api-docs/auth/aws#depr @include 'alpine-314.mdx' +@include 'entity-alias-mapping.mdx' + ## Known Issues Due to the known issue, Transform Secrets Engine users are recommended to upgrade to version 1.7.0. @@ -48,3 +50,4 @@ Due to the known issue, Lease Count Quota users with DR Secondaries are recommen @include 'transform-upgrade.mdx' @include 'lease-count-quota-upgrade.mdx' + diff --git a/website/content/docs/upgrading/upgrade-to-1.8.0.mdx b/website/content/docs/upgrading/upgrade-to-1.8.x.mdx similarity index 93% rename from website/content/docs/upgrading/upgrade-to-1.8.0.mdx rename to website/content/docs/upgrading/upgrade-to-1.8.x.mdx index df904d32eae1..8077fddf5664 100644 --- a/website/content/docs/upgrading/upgrade-to-1.8.0.mdx +++ b/website/content/docs/upgrading/upgrade-to-1.8.x.mdx @@ -1,15 +1,15 @@ --- layout: docs -page_title: Upgrading to Vault 1.8.0 - Guides +page_title: Upgrading to Vault 1.8.x - Guides description: |- This page contains the list of deprecations and important or breaking changes - for Vault 1.8.0. Please read it carefully. + for Vault 1.8.x. Please read it carefully. --- # Overview This page contains the list of deprecations and important or breaking changes -for Vault 1.8.0 compared to 1.7. Please read it carefully. +for Vault 1.8.x compared to 1.7. Please read it carefully. ## License Enhancements @@ -40,6 +40,9 @@ Notes](https://golang.org/doc/go1.16) for full details. Of particular note: @include 'alpine-314.mdx' + +@include 'entity-alias-mapping.mdx' + ## Known Issues - Vault Enterprise binaries for `arm64` architectures will crash immediately when using production-ready storage backends. This issue is addressed in Vault 1.8.1. diff --git a/website/content/docs/upgrading/upgrade-to-1.9.0.mdx b/website/content/docs/upgrading/upgrade-to-1.9.0.mdx deleted file mode 100644 index 5ab6c94da8db..000000000000 --- a/website/content/docs/upgrading/upgrade-to-1.9.0.mdx +++ /dev/null @@ -1,51 +0,0 @@ ---- -layout: docs -page_title: Upgrading to Vault 1.9.0 - Guides -description: |- - This page contains the list of deprecations and important or breaking changes - for Vault 1.9.0. Please read it carefully. ---- - -~> Note: these are **draft** notes for a future version of Vault. They should not be considered -official guidance until the release has been completed. - -# Overview - -This page contains the list of deprecations and important or breaking changes -for Vault 1.9.0 compared to 1.8. Please read it carefully. - -## Identity Tokens - -The Identity secrets engine has changed the procedure for creating Identity -token roles. When creating a role, the key parameter is required and the key -must exist. Previously, it was possible to create a role and assign it a named -key that did not yet exist despite the documentation stating otherwise. - -All calls to [create or update a role](https://www.vaultproject.io/api/secret/identity/tokens#create-or-update-a-role) -must be checked to ensure that roles are not being created or updated with -non-existent keys. - -## SSH Role Parameter `allowed_extensions` Behavior Change - -Prior versions of Vault allowed clients to specify any extension when requesting -SSH certificate [signing requests](https://www.vaultproject.io/api/secret/ssh#sign-ssh-key) -if their role had an `allowed_extensions` set to `""` or was missing. - -Now, Vault will reject a client request that specifies extensions if the role -parameter `allowed_extensions` is empty or missing from the role they are -associated with. - -To re-enable the old behavior, update the roles with a value -of `"*"` to the `allowed_extensions` parameter allowing any/all extensions to be -specified by clients. - -## HTTP Request Counter Deprecation - -In Vault 1.9, the internal HTTP Request count -[API](https://www.vaultproject.io/api-docs/system/internal-counters#http-requests) -will be removed from the product. Calls to the endpoint will result in a 404 -error with a message stating that `functionality on this path has been removed`. - -Vault does not make backwards compatible guarantees on internal APIs (those -prefaced with `sys/internal`). They are subject to change and may disappear -without notice. diff --git a/website/content/docs/upgrading/upgrade-to-1.9.x.mdx b/website/content/docs/upgrading/upgrade-to-1.9.x.mdx new file mode 100644 index 000000000000..cdb209684dbe --- /dev/null +++ b/website/content/docs/upgrading/upgrade-to-1.9.x.mdx @@ -0,0 +1,112 @@ +--- +layout: docs +page_title: Upgrading to Vault 1.9.x - Guides +description: |- + This page contains the list of deprecations and important or breaking changes + for Vault 1.9.x. Please read it carefully. +--- + +# Overview + +This page contains the list of deprecations and important or breaking changes +for Vault 1.9.x compared to 1.8. Please read it carefully. + +## OIDC Provider + +Vault 1.9.0 introduced the ability for Vault to be an OpenID Connect (OIDC) identity +provider. To support the feature, Vault's [default policy](https://www.vaultproject.io/docs/concepts/policies#default-policy) +was modified to include an ACL rule for its Authorization Endpoint. Due to the handling +of Vault's default policy during upgrades, existing deployments of Vault that are upgraded +to 1.9.0 will not have this required ACL rule. + +If you're upgrading to 1.9.0 and want to use the new OIDC provider feature, the following +ACL rule must be added to the default policy **or** a policy associated with the Vault +[Auth Method](https://www.vaultproject.io/docs/auth) used to authenticate end-users during +the OIDC flow. + +```hcl +# Allow a token to make requests to the Authorization Endpoint for OIDC providers. +path "identity/oidc/provider/+/authorize" { + capabilities = ["read", "update"] +} +``` + +## Identity Tokens + +The Identity secrets engine has changed the procedure for creating Identity +token roles. When creating a role, the key parameter is required and the key +must exist. Previously, it was possible to create a role and assign it a named +key that did not yet exist despite the documentation stating otherwise. + +All calls to [create or update a role](https://www.vaultproject.io/api/secret/identity/tokens#create-or-update-a-role) +must be checked to ensure that roles are not being created or updated with +non-existent keys. + +## SSH Role Parameter `allowed_extensions` Behavior Change + +Prior versions of Vault allowed clients to specify any extension when requesting +SSH certificate [signing requests](https://www.vaultproject.io/api/secret/ssh#sign-ssh-key) +if their role had an `allowed_extensions` set to `""` or was missing. + +Now, Vault will reject a client request that specifies extensions if the role +parameter `allowed_extensions` is empty or missing from the role they are +associated with. + +To re-enable the old behavior, update the roles with a value +of `"*"` to the `allowed_extensions` parameter allowing any/all extensions to be +specified by clients. + +@include 'entity-alias-mapping.mdx' + +## Deprecations + +### HTTP Request Counter Deprecation + +In Vault 1.9, the internal HTTP Request count +[API](https://www.vaultproject.io/api-docs/v1.8.x/system/internal-counters#http-requests) +will be removed from the product. Calls to the endpoint will result in a 404 +error with a message stating that `functionality on this path has been removed`. + +Vault does not make backwards compatible guarantees on internal APIs (those +prefaced with `sys/internal`). They are subject to change and may disappear +without notice. + +### Etcd v2 + +Support for Etcd v2 will be removed from Vault in Vault 1.10 (not this Vault +release, but the next one). The Etcd v2 API +was deprecated with the release of [Etcd +v3.5](https://etcd.io/blog/2021/announcing-etcd-3.5/), and will be +decommissioned in the Etcd v3.6 release. + +Users upgrading to Vault 1.9 and planning to eventually upgrade to Vault 1.10 +should prepare to [migrate](/docs/commands/operator/migrate) Vault storage to +an Etcd v3 cluster prior to upgrading to Vault 1.10. All storage migrations +should have [backups](/docs/concepts/storage#backing-up-vault-s-persisted-data) +taken prior to migration. + +## TLS Cipher Suites Changes + +In Vault 1.9, due to changes in Go 1.17, the `tls_prefer_server_cipher_suites` +TCP configuration parameter has been deprecated and its value will be ignored. + +Additionally, Go has begun doing automated cipher suite ordering and no longer +respects the order of suites given in `tls_cipher_suites`. + +See [this blog post](https://go.dev/blog/tls-cipher-suites) for more information. + +## Known Issues + +### Identity Token Backend Key Rotations + +Existing Vault installations that use the [Identity Token +backend](/api-docs/secret/identity/tokens) and have [named +keys](/api-docs/secret/identity/tokens#create-a-named-key) generated will +encounter a panic when any of those existing keys pass their +`rotation_period`. This issue affects Vault 1.9.0, and is fixed in Vault 1.9.1. +Users should upgrade directly to 1.9.1 or above in order to avoid this panic. + +If a panic is encountered after an upgrade to Vault 1.9.0, the named key will be +corrupted on storage and become unusable. In this case, the key will need to be +deleted and re-created. A fix to fully mitigate this panic will be addressed on +Vault 1.9.3. diff --git a/website/content/partials/entity-alias-mapping.mdx b/website/content/partials/entity-alias-mapping.mdx new file mode 100644 index 000000000000..b8b3e4e37a80 --- /dev/null +++ b/website/content/partials/entity-alias-mapping.mdx @@ -0,0 +1,7 @@ +## Entity Alias mapping + +Previously, an entity in Vault could be mapped to multiple entity aliases on the same authentication backend. This +led to a potential security vulnerability (CVE-2021-43998), as ACL policies templated with alias information would match the first +alias created. Thus, tokens created from all aliases of the entity, will have access to the paths containing alias +metadata of the first alias due to templated policies being incorrectly applied. As a result, the mapping behavior was updated +such that an entity can only have one alias per authentication backend. This change exists in Vault 1.9.0+, 1.8.5+ and 1.7.6+. \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 8d7199e8a11f..86b1ee7d26de 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1437,17 +1437,17 @@ "path": "upgrading/plugins" }, { - "title": "Upgrade to 1.9.0", - "path": "upgrading/upgrade-to-1.9.0", + "title": "Upgrade to 1.9.x", + "path": "upgrading/upgrade-to-1.9.x", "hidden": true }, { - "title": "Upgrade to 1.8.0", - "path": "upgrading/upgrade-to-1.8.0" + "title": "Upgrade to 1.8.x", + "path": "upgrading/upgrade-to-1.8.x" }, { - "title": "Upgrade to 1.7.0", - "path": "upgrading/upgrade-to-1.7.0" + "title": "Upgrade to 1.7.x", + "path": "upgrading/upgrade-to-1.7.x" }, { "title": "Upgrade to 1.6.3",