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 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 used to authenticate end-users during the OIDC flow.

# 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 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 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.

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+.

Deprecations

HTTP request counter deprecation

In Vault 1.9, the internal HTTP Request count API 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, 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 Vault storage to an Etcd v3 cluster prior to upgrading to Vault 1.10. All storage migrations should have backups 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 for more information.

PKI certificate generation forwarding regression

A bug introduced in Vault 1.8 causes certificate generation requests to the PKI secrets engine made on a performance secondary node to be forwarded to the cluster's primary node. The resulting certificates are stored on the primary node, and thus visible to list and read certificate requests only on the primary node rather than the secondary node as intended. Furthermore, if a certificate is subsequently revoked on a performance secondary node, the secondary's certificate revocation list is updated, rather than the primary's where the certificate is stored. This bug is fixed in Vault 1.8.8 and 1.9.3.
Certificates issued after the fix are correctly stored locally to the performance secondary.

Known issues

Integrated storage panic related to old TLS key

Raft in Vault uses its own set of TLS certificates, independent of those that the user controls to protect the API port and those used for replication and clustering. These certs get rotated daily, but to ensure that nodes which were down or behind on Raft log replication don't lose the ability to speak with other nodes, the newly generated daily TLS cert only starts being used once we see that all nodes have received it.

A recent security audit related change results in this rotation code getting a panic when the current cert is more than 24h old. This can happen if the cluster as a whole is down for a day or more. It can also happen if a single node is unreachable 24h, or sufficiently backlogged in applying raft logs that it's more than a day behind.

Impacted versions: 1.10.1, 1.9.5, 1.8.10. Versions prior to these are unaffected.

New releases addressing this panic are coming soon.

Identity token backend key rotations

Existing Vault installations that use the Identity Token backend and have named keys 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.

Activity log Non-Entity tokens

When upgrading Vault from 1.8 (or earlier) to 1.9 (or later), client counts of non-entity tokens will only include the tokens used after the upgrade.

Starting in Vault 1.9, the activity log records and de-duplicates non-entity tokens by using the namespace and token's policies to generate a unique identifier. Because Vault did not create identifiers for these tokens before 1.9, the activity log cannot know whether this token has been seen pre-1.9. To prevent inaccurate and inflated counts, the activity log will ignore any counts of non-entity tokens that were created before the upgrade and only the non-entity tokens from versions 1.9 and later will be counted.

Before upgrading, you should query Vault usage metrics and report the usage data for billing purposes.

See the client count overview and FAQ for more information.