hashicorp · jaireddjawed · Oct 5, 2025 · Oct 5, 2025 · Oct 6, 2025 · Oct 6, 2025
@@ -146,7 +146,7 @@ entities attempting to login.
   [LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#labelselector-v1-meta). Currently, label selectors with `matchExpressions` are not supported.
   To use label selectors, **Vault must have permission to read namespaces** on the Kubernetes
   cluster. If set with `bound_service_account_namespaces`, the conditions are `OR`ed.
-- `audience` `(string: "")` - Audience claim to verify in the JWT. Will be required in Vault 1.21+.
+- `audience` `(string: "")` - Audience claim to verify in the JWT.
 - `alias_name_source` `(string: "serviceaccount_uid")` - Configures how identity aliases are generated.
   Valid choices are: `serviceaccount_uid` and `serviceaccount_name`.
 

@@ -111,9 +111,6 @@ management tool.
       ttl=1h
   ```
 
-  !> **Note:** `audience` will be a required field in Vault 1.21+. This field is used
-  to verify the JWT token's audience claim.
-
   This role authorizes the "myapp" service account in the default
   namespace and it gives it the default policy.
 

@@ -192,19 +192,27 @@ audience.
 
 #### Recommendation
 
-We recommend updating your policies before Vault makes the audience value
-required for all Kubernetes authentication roles so Vault can explicitly
-validate that the audience claim in JWT tokens (`aud`) is intended for Vault and
-not another service. For example:
+We recommend configuring an audience value for Kubernetes authentication roles when possible.
+This enables Vault to validate that the aud (audience) claim in JWT tokens is explicitly intended for Vault,
+reducing the risk of token misuse by other services. While not required, setting an audience is considered a security
+best practice and is encouraged when it doesn't interfere with your workflow. For example, tokens created using
+kubernetes.io/service-account-token do not include an aud claim, so it's appropriate to omit the audience field in this case.
+Here's an example configuration.
-We recommend configuring an audience value for Kubernetes authentication roles when possible.
-This enables Vault to validate that the aud (audience) claim in JWT tokens is explicitly intended for Vault,
-reducing the risk of token misuse by other services. While not required, setting an audience is considered a security
-best practice and is encouraged when it doesn't interfere with your workflow. For example, tokens created using
-kubernetes.io/service-account-token do not include an aud claim, so it's appropriate to omit the audience field in this case.
-Here's an example configuration.
+There are cases where configuring audience details can interfere with your
+workflow. For example, tokens created using `kubernetes.io/service-account-token`
+do not include an aud claim. But we recommend configuring an audience value for
+Kubernetes authentication roles whenever possible. Setting explicit audience
+details is best practice because it reduces the risk of token misuse by other
+services. Vault can use the configured values to validate that the `aud`
+(audience) claim in JWT tokens is intended for Vault.
+
+For example:
-We recommend configuring an audience value for Kubernetes authentication roles when possible.
-This enables Vault to validate that the aud (audience) claim in JWT tokens is explicitly intended for Vault,
-reducing the risk of token misuse by other services. While not required, setting an audience is considered a security
-best practice and is encouraged when it doesn't interfere with your workflow. For example, tokens created using
-kubernetes.io/service-account-token do not include an aud claim, so it's appropriate to omit the audience field in this case.
-Here's an example configuration.
+There are cases where configuring audience details can interfere with your
+workflow. For example, tokens created using `kubernetes.io/service-account-token`
+do not include an aud claim. But we recommend configuring an audience value for
+Kubernetes authentication roles whenever possible. Setting explicit audience
+details is best practice because it reduces the risk of token misuse by other
+services. Vault can use the configured values to validate that the `aud`
+(audience) claim in JWT tokens is intended for Vault.
+
+For example:
 
 ```shell-session
 $ vault write auth/kubernetes/role/demo      \
     bound_service_account_names=myapp        \
     bound_service_account_namespaces=default \
     policies=default                         \
+    audience="my_audience"                   \
     ttl=1h
 ```
 
+You would then authenticate with the command below.
+
+```shell-session
+$ vault write auth/kubernetes/login role=demo audience="my_audience" jwt=...
+```
 
 ---