Important changes

Last updated: 2025-10-04

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

Breaking changes

Renamed timestamp fields for client count activity export

Vault counts a client the first time that client makes an authenticated API during the billing period.

Previously, the Activity Export endpoint response included a timestamp field that reflected the creation time and date for the client token, which could precede the start of the billing period, rather than the time and date of the first authenticated API call.

To clarify the data returned, the endpoint now returns two timestamp parameters:

• client_first_usage_time - (new) indicates when the client first made an authenticated API call during the billing period.
• token_creation_time - (replaces timestamp) indicates the creation timestamp of the token.

Recommendation

Review your use of the timestamp field and:

1. Consider if the context makes client_first_usage_time a more appropriate timestamp.
2. Update any remaining references to timestamp to use token_creation_time.

Audiences required for Kubernetes authentication roles

All tokens for Kubernetes authentication roles must provide explicit audience details. Vault validates the audience claim in the JWT token to ensure that the token is actually intended for Vault and not another service.

If you do not provide an audience, authentication fails.

Recommendation

Update your Kubernetes authentication roles to include the audience parameter. For example:

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

Refer to the Kubernetes authentication docs for more information.

Item-by-item list comparison for allowed_parameters and denied_parameters

Previous versions of Vault only matched list parameters when the associated policy defined the list as a whole. As a result, Vault allowed lists containing denied values as long as the policy did not deny that exact list and denied lists containing allowed values because the policy did not allow the exact list.

Vault now checks each value in a list parameter against allowed/denied values in the applicable Vault policy and allows or denies requests if the policy defines the list as a whole or every/any individual element of the list. For example, if the request includes a list like ['a', 'b', 'c'], it still matches to a policy that includes ['a', 'b', 'c'] but also matches to an approve policy that includes all the individual values a, b, and c or a deny policy that includes any of the individual values.

Recommendation

Workflows that previously succeeded may now fail due to permission checks involving denied_parameters because the new matching behavior correctly identifies the fact that the list contains individually denied values even when the exact list does not appear in the policy.

To address the broken workflow:

• Check whether or not your policies are overly restrictive.
• Update your workflows to avoid including explicitly denied values in lists.

Refer to list parameter evaluation for more information.

You can temporarily revert to the deprecated matching behavior by setting the VAULT_LEGACY_EXACT_MATCHING_ON_LIST environment variable on your Vault server.

New behavior

Rotation manager schedule strings in UTC

Vault interprets rotation_schedule strings relative to UTC to match the behavior of static role rotations in the database plugin. Old rotations use their existing schedule until you manually update rotation with an API call.

Known issues

Missed events with multiple event clients EnterpriseEnterprise

Users may miss events when multiple clients subscribe to the same performance standby node in a cluster with the same namespace and event type filters because one client disconnecting effectively unsubscribes the remaining clients who no longer receive events.

Recommendation

If you have multiple event subscribers with the same namespace and event type filters you have two options:

1. Spread them out among the nodes of the Vault cluster.
2. Only subscribe to events on the active node of the cluster.

Azure static roles fail to parse metadata as a map

Affected versions

• 1.21.0

Issue

The creation/update of an Azure static role fails if the request payload includes metadata provided as a map:

{
  "application_object_id": "408bf248-dd4e-4be5-919a-7f6207a307ab",
  "ttl": "8760h",
  "metadata": {
    "team": "engineering",
    "environment": "development"
  }
}

Workaround

Provide the metadata field as a string when creating or updating an Azure static role:

{
  "application_object_id": "408bf248-dd4e-4be5-919a-7f6207a307ab",
  "ttl": "8760h",
  "metadata": "{\"team\": \"engineering\",\"environment\": \"development\"}"
}

GUI KV v2 metadata list request fails for some policies

Issue

Users cannot list KV v2 secrets in the GUI when the policy granting list access to metadata does not include a trailing slash. For example:

path "secret/metadata/:path" {   
  capabilities = ["list"] 
}

Workaround

Option 1: Use the API explorer to list KV v2 secrets instead of the KV v2 GUI page:

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 GET /:mount/metadata/{path}/ endpoint and click Try it out.
5. Input the secret path click Execute to perform the HTTP request.

Option 2: Add a trailing slash to the policy path:

path "secret/metadata/:path/" {   
  capabilities = ["list"] 
}

GUI KV v2 listing secrets fails in namespaces EnterpriseEnterprise

Issue

The GUI displays "No secrets yet" message for KV v2 engines with existing secrets when users navigate to the plugins secret list in a namespace.

Workaround

Use the CLI emulator to list KV v2 secrets:

1. Navigate to the desired namespace.
2. Toggle open the web REPL.
3. Input the command list <mount_path_to_kv_plugin_2>/metadata and press Enter.