address comments on code review

nomad/structs/workload_id.go

@@ -76,6 +76,8 @@ type IdentityClaims struct {
 	VaultNamespace  string `json:"vault_namespace,omitempty"`
 	VaultRole       string `json:"vault_role,omitempty"`
 
+	// ExtraClaims are added based on this identity's
+	// WorkloadIdentityConfiguration, controlled by server configuration
 	ExtraClaims map[string]string `json:"extra_claims,omitempty"`
 
 	jwt.Claims
@@ -227,7 +229,9 @@ func strAttrGet[T any](x *T, fn func(x *T) string) string {
 }
 
 func (b *IdentityClaimsBuilder) interpolate() {
-
+	if len(b.extras) == 0 {
+		return
+	}
 	r := strings.NewReplacer(
 		// attributes that always exist
 		"${job.region}", b.job.Region,
@@ -310,7 +314,8 @@ type WorkloadIdentity struct {
 	TTL time.Duration
 
 	// Note: ExtraClaims is available on config/WorkloadIdentity but not
-	// available here on jobspecs
+	// available here on jobspecs because that might allow a job author to
+	// escalate their privileges if they know what claim mappings to expect.
 }
 
 // IsConsul returns true if the identity name starts with the standard prefix

website/content/docs/configuration/vault.mdx

@@ -192,11 +192,11 @@ will be removed in a future release.
 
 - `extra_claims` `(map[string]string: optional)` - A set of key-value pairs that
   will be provided as extra identity claims for workloads. You can use the keys
-  as user claims in Vault role configurations. The values are interpolated. For
-  example, if you include the extra claim `unique_id =
-  "${job.region}:${job.namespace}:${job.id}"`, you could set the user claim
-  field to `/extra_claims/unique_id` to map that identifier to an entity
-  alias. The available attributes for interpolation are:
+  as [user claims in Vault role configurations][vault-jwt-user-claim]. The
+  values are interpolated. For example, if you include the extra claim
+  `unique_id = "${job.region}:${job.namespace}:${job.id}"`, you could set the
+  user claim field to `/extra_claims/unique_id` to map that identifier to an
+  entity alias. The available attributes for interpolation are:
 
   - `${job.region}` - The region where the job is running.
   - `${job.namespace}` - The job's namespace.
@@ -342,3 +342,4 @@ can be accomplished by sending the process a `SIGHUP` signal.
 [vault_bound_aud]: /vault/api-docs/auth/jwt#bound_audiences
 [vault_auth_enable_path]: /vault/docs/commands/auth/enable#path
 [workload_id]: /nomad/docs/concepts/workload-identity
+[vault-jwt-user-claim]: /vault/api-docs/auth/jwt#user_claim