Important changes

Last updated: 2025-06-30

Always review important or breaking changes and remediation recommendations before upgrading Vault.

New behavior

Key pair authentication for Snowflake DB secrets engine

As of version 1.20.0, Vault supports Snowflake database authentication using key pairs as an alternative to password authentication, which Snowflake plans to disable in November 2025. Vault support for password authentication with Snowflake is now deprecated and will be removed in a future release.

Vault currently does not support rotate root for key pairs. To manually rotate key pairs, users can:

• update the root configuration in Vault with the new private key
• update the public key associated with the user in Snowflake

For more information on rotating key pairs, please refer to the official Snowflake documentation.

Breaking changes

Breaking configuration change for disable_mlock

In Vault 1.20.0 disable_mlock is a required configuration setting for clusters using integrated storage. This means that if you are not explicitly setting a value for disable_mlock, the following changes must be made prior to upgrading.

Before upgrading to Vault 1.20.0, administrators must explicitly add a value for disable_mlock to the outermost level of the server configuration. Refer to the documentation. This must be done for all server nodes. Prior to Vault 1.20, the default setting for disable_mlock was false. Therefore, if you do not currently have a value set for disable_mlock, you are using the default setting. If you wish to maintain this behavior, you will need to explicitly set disable_mlock = false prior to upgrade.

For clusters that already set a value for disable_mlock, no change is required.

One of bound_group_ids or bound_service_principal_ids Must Be Specified in the Role Definition for Azure Authentication Roles

Azure authentication roles must specify either bound_group_ids or bound_service_principal_ids in the role definition to prevent excessively permissive access. This ensures that the role is tailored to the specific needs of the application or service. More information about Azure authentication roles can be found here. Here's an updated example for reference:

$ vault write auth/azure/role/dev-role \
    policies="prod,dev" \
    bound_subscription_ids=6a1d5988-5917-4221-b224-904cd7e24a25 \
    bound_resource_groups=vault \
    bound_service_principal_ids=3cb88732-1356-4782-b671-4877166be01a

Audiences Will Be Required for Kubernetes Authentication Roles in Vault 1.21+

Starting in Vault 1.21+, specifying an audience will be mandatory for all Kubernetes authentication roles. This ensures that the JWT token's aud (audience) claim is explicitly validated, confirming that the token is intended for Vault and not another service.

Currently, creating or updating a Kubernetes auth role without an audience will result in a warning. However, once Vault 1.21 is released, any role that does not specify an audience will fail authentication.

To prepare for this change, make sure to include the audience parameter when defining Kubernetes auth roles. More information about Kubernetes authentication roles can be found here. Here's an updated example:

vault write auth/kubernetes/role/demo \
    bound_service_account_names=myapp \
    bound_service_account_namespaces=default \
    policies=default \
    ttl=1h

Additional Considerations

• Autopilot - New 1.20.0 nodes are added to the cluster until there is a quorum of upgraded nodes. Each of these new nodes will need to have a value for disable_mlock set.

• Rolling upgrades - Standby nodes are stopped and upgraded one at a time. These node configurations will need to be updated before restarting the vault process on the node.

• dev mode - If no config is provided, dev mode will start as usual. If a config is provided, it must have a value for disable_mlock.

Rekey cancellations use a nonce

Vault 1.20.0, 1.19.6, 1.18.11, 1.17.18, and 1.16.21 require a nonce to cancel rekey and rekey recovery key operations within 10 minutes of initializing a rekey request. Cancellation requests after the 10 minute window do not require a nonce and succeed as expected.

Recommendation

To cancel a rekey operation, provide the nonce value from the /sys/rekey/init or sys/rekey-recovery-key/init response.

Bugs

None.

Known issues

UI KV v2 overview for secret paths containing underscores

Users receive an error when navigating to a KV v2 secret with an underscore in the name (e.g. my_secret) if the user does not have policy permissions granting read access to the /subkeys endpoint.

Recommendation

As a workaround, you can use the GUI CLI emulator to read secret data or metadata.

You can also use the API explorer to make any HTTP request:

1. Select Tools from the Vault GUI sidebar.
2. Click API Explorer.
3. Enter the KV v2 plugin mount path in the "Filter by tag" search bar.
4. Expand the endpoint for the action you wish to perform and click Try it out.
5. Provide the required parameters. For example, to read a KV v2 secret the path must be provided.
6. Provide any optional parameters desired.
7. Click Execute to perform the HTTP request.

UI login fails for auth mounts with underscores and unauthenticated listing

Login requests to auth methods mounted at paths using underscores (e.g. oidc_test) with listing_visibility="unauth" fail because the GUI calls the wrong endpoint. Mounts with dashes (e.g. oidc-test) work correctly.

Recommendation

As a workaround, you can log in to the GUI using the following steps:

1. Navigate directly to the URL for the desired method type (e.g. ${VAULT_ADDR}/ui/vault/auth?with=oidc)
2. Click "Sign in with other methods ->"
3. Select the method type from the dropdown
4. Click Advanced settings and provide the correct path (e.g., oidc_test).

We also recommend creating a custom GUI message describing the workaround steps for users.

Duplicate unseal/seal wrap HSM keys EnterpriseEnterprise

In HSM-HA configurations migrating from Shamir to HSM-backed unseal/seal wraps, Vault may create duplicate HSM keys when you migrate from Shamir to an HSM-backed unseal configuration for high availability (HA) HSM deployments. Key duplication can happen even after a seal migration to HSM that initially appears successful.

Duplicate HSM keys can cause the following errors:

• intermittent read failures with errors such as CKR_SIGNATURE_INVALID and CKR_KEY_HANDLE_INVALID for seal-wrapped values.
• nodes fail to unseal after a restart with errors such as CKR_DATA_INVALID.

Recommendation

Always run Vault with generate_key = false and manually create all required keys within the HSM during the setup process.

Duplicate LDAP Password Rotations on Standby Node Check-In

Vault check-ins for LDAP service accounts performed on a performance standby node or a node in a performance replication secondary cluster can trigger duplicate password changes on the LDAP server. Duplication occurs because the LDAP client on the local node successfully modifies the password before Vault forwards the check-in request to the active node, which then performs a second password update. While users still receive the latest password, it may lead to unexpected LDAP activity and cause confusion interpreting audit logs.

Recommendation:

Send check-in requests directly to the active node of the primary cluster to prevent duplicate password rotations on the LDAP server.

Development cluster setting overwritten on secondary cluster reload

If the Vault process receives a SIGHUP and reloads a secondary performance replication cluster, the cluster reverts to the locally configured development_cluster value instead of following the value configured on the primary cluster.

Recommendation:

Ensure all clusters in a performance replication group have the same development_cluster value configured in HCL to prevent unexpected changes to the reported value.