For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Use WIMSE Workload Identity Tokens with agentgateway to authenticate service-to-service and egress traffic in your ambient mesh.

WIMSE (Workload Identity in Multi-System Environments) is an IETF working group that defines standards for carrying workload identity across system boundaries. The core problem it addresses is that mTLS-based identity (SPIFFE/X.509) is scoped to a single connection. When a workload makes an outbound HTTP call to an external service or crosses a trust boundary, the originating workload’s identity is not automatically carried with the request. WIMSE defines the Workload Identity Token (WIT), a structured token format that encodes workload identity claims so they can travel as an HTTP header (Workload-Identity-Token) alongside the request, independently of the underlying transport security.

When Solo Enterprise for agentgateway is deployed as a waypoint, it can extract workload identity claims from the mTLS peer certificate SAN, expose those claims in CEL policy expressions, and forward or exchange the WIT for outbound requests to external services.

This feature requires Solo Enterprise for agentgateway as a waypoint proxy. For setup, see Install agentgateway as a waypoint.

How it works

The trust chain involves three components working together:

1. Istiod embeds workload identity claims in the certificate SAN when it mints workload certificates.
2. Ztunnel reads those SAN claims for L4 policy and forwards the WIT header on outbound HBONE connections.
3. Agentgateway extracts the claims at L7 from the peer TLS certificate SAN and exposes them in CEL policy expressions.

Inbound policy with workload claims

When agentgateway receives a request, it extracts workload identity claims from the peer certificate and makes them available to EnterpriseAgentgatewayPolicy expressions as CEL attributes:

These attributes are available in EnterpriseAgentgatewayPolicy expressions targeted at a Gateway, HTTPRoute, or Service.

Enable workload claims on the waypoint proxy

• Ztunnel: Set ENABLE_WORKLOAD_CLAIMS=true in your ztunnel Helm values. For setup instructions and ztunnel-level enforcement of the same claims, see CEL and workload claims authorization for L4 traffic.
• Agentgateway waypoint proxy: Enable workload claims on the waypoint proxy by using EnterpriseAgentgatewayParameters. Without this reference, source.claims is never populated, and all claims-based authorization expressions evaluate to false.

To enable workload claims on the agentgateway waypoint proxy, create an EnterpriseAgentgatewayParameters resource and reference it from your waypoint Gateway.

1. Create the EnterpriseAgentgatewayParameters resource.

   apiVersion: enterpriseagentgateway.solo.io/v1alpha1
   kind: EnterpriseAgentgatewayParameters
   metadata:
     name: waypoint-params
     namespace: ${NAMESPACE}
   spec:
     workloadClaims:
       enabled: true

2. Reference the parameters from your waypoint Gateway.

   spec:
     infrastructure:
       parametersRef:
         group: enterpriseagentgateway.solo.io
         kind: EnterpriseAgentgatewayParameters
         name: waypoint-params

The following EnterpriseAgentgatewayPolicy example combines workload claims with JWT validation to allow requests only when the source workload carries the eu jurisdiction claim and the end-user JWT subject ends with @example.com.

apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata:
  name: upstream-authz
  namespace: ${NAMESPACE}
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: <gateway_name>
  traffic:
    authorization:
      action: Allow
      policy:
        matchExpressions:
        - 'jwt.sub.endsWith("@example.com") && source.claims["solo.io.security-claims.jurisdiction"] == "eu"'

Workload identity propagation

To carry workload identity claims on outbound requests, configure backend.workloadIdentity in an EnterpriseAgentgatewayPolicy. Target the policy at a Service when you don’t need routing rules, or at an HTTPRoute when you do. These modes control the Workload-Identity-Token HTTP header sent to the upstream service. The mTLS identity of the outbound HBONE connection always uses agentgateway’s own workload certificate and is not affected by this setting.

SourceDelegation

Forwards the inbound Workload-Identity-Token from the source workload to the upstream service. Use this when the upstream service needs to verify the source workload’s identity independently, for example when calling an in-mesh service or an external API that accepts WIMSE tokens.

apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata:
  name: forward-wit
  namespace: ${NAMESPACE}
spec:
  targetRefs:
  - kind: Service
    name: <svc_name>
    group: ""
  backend:
    workloadIdentity:
      mode: SourceDelegation

SelfIdentification

Uses agentgateway’s own WIT as the outbound identity rather than delegating the source workload’s identity. Use this when the upstream should authorize the gateway as the caller, not the original source workload. If agentgateway has no minted WIT available, it logs a warning and sends no Workload-Identity-Token header on that request.

apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata:
  name: self-identification
  namespace: ${NAMESPACE}
spec:
  targetRefs:
  - kind: Service
    name: <svc_name>
    group: ""
  backend:
    workloadIdentity:
      mode: SelfIdentification

Workload Proof Tokens (WPT)

A WIT states who a workload is, but it does not prove that the sender holds the key that the token was issued to. A workload that obtains a copy of a valid WIT can replay it. The WIMSE Workload Proof Token (WPT) closes that gap. A WPT is a short-lived JSON Web Signature that proves possession of the key bound to a WIT for one request, and it carries no identity claims of its own. Senders mint a WPT in the Workload-Proof-Token header, and receivers validate it.

A WPT binds to the tokens that travel with it by hash, so a stolen token cannot be paired with a different proof:

A gateway does not hold the source workload’s private key, so it signs the proof with its own key under its own WIT. A WPT from a gateway therefore asserts that the gateway received the identity over authenticated mTLS and is forwarding it within a bounded time window. Proofs are single-hop, and each gateway on the path mints a new one.

Enforce proofs on received requests

To validate proofs on the receive side, set traffic.entWptEnforcement in an EnterpriseAgentgatewayPolicy. Attach the policy to a Gateway or ListenerSet to enforce at that listener, or to a Service or ServiceEntry to enforce at the Service’s waypoint. Enforcement runs with the other authentication policies and before authorization, so an authorization expression sees the verified identities.

apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata:
  name: wpt-peer-bound
  namespace: ${NAMESPACE}
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: <gateway_name>
  traffic:
    entWptEnforcement:
      mode: PeerBound

Three modes trade strictness against how much of the mesh already emits proofs.

Full validation requires the proof to arrive over authenticated mesh transport (HBONE) alongside the WIT that it binds. The proxy checks the signature, the typ header, wth, aud, exp, jti, and oth; confirms that the bound WIT belongs to the mTLS peer; and verifies the x5c chain of any forwarded original WIT.

Rejections use two status codes, which distinguish a caller that presented nothing from a caller that presented something invalid:

To disable enforcement, omit the entWptEnforcement block or remove the policy.

Override the accepted audience

By default the enforcement point derives the audience that it accepts from the policy attachment, which is a Service hostname or a Gateway listener hostname. On the supported mesh paths that derived audience already matches what senders mint, so most policies need no audiences list.

Set audiences only when your topology decouples the two, such as a non-empty HBONE listener hostname, a BackendTLS SNI override, or an external peer-bound WPT client that targets a concrete virtual host. The list holds up to 64 host patterns that are matched against the authority in the received aud claim, and it replaces the derived audience rather than adding to it.

apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata:
  name: wpt-audiences
  namespace: ${NAMESPACE}
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: <gateway_name>
  traffic:
    entWptEnforcement:
      mode: PeerBound
      audiences:
      - ingress-gw.gateway-system.svc.cluster.local
      - "*.svc.cluster.local"

Authorize on token-verified identity

WPT enforcement stashes the identities that it verified, and CEL policy expressions read them under workloadIdentity. These attributes differ from source.identity and source.claims, which come from the mTLS peer certificate and the transport alone. A workloadIdentity attribute is present only where WPT enforcement validated a token for that request.

The following policy allows a request only when the previous hop is in the local trust domain and the request originated from a named workload.

apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata:
  name: authorize-on-verified-identity
  namespace: ${NAMESPACE}
spec:
  targetRefs:
  - kind: Service
    name: <svc_name>
    group: ""
  traffic:
    authorization:
      action: Allow
      policy:
        matchExpressions:
        - 'workloadIdentity.sender.trustDomain == "cluster.local"'
        - 'workloadIdentity.chain.origin.endsWith("/ns/frontend/sa/web")'

Monitor WPT enforcement

Two Prometheus counters report what enforcement did. Both are unstable metrics, so their names and labels can change between releases.

The reason label separates a configuration problem from an attack:

A rejection also logs a warning that names the proxy’s reason, so the proxy logs are the place to confirm which token in the request failed.

Emit a proof

To mint a WPT alongside the WIT, set emitProof on the backend.workloadIdentity block that already selects the propagation mode. Emission works with both SourceDelegation and SelfIdentification.

apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata:
  name: forward-wit-with-proof
  namespace: ${NAMESPACE}
spec:
  targetRefs:
  - kind: Service
    name: <svc_name>
    group: ""
  backend:
    workloadIdentity:
      mode: SourceDelegation
      emitProof: true
      proofLifetime: 60s
      bindAccessToken: true
      bindTransactionToken: true

Under SourceDelegation with emitProof: true, the gateway presents its own WIT in Workload-Identity-Token and moves the inbound peer-bound WIT to X-Original-Workload-Identity-Token. A receiver that reads the source workload’s identity from the header must therefore read the CEL attributes that WPT enforcement populates rather than parse the header itself.

JWT propagation for end-user identity

WITs carry workload identity and identify the calling service, not an end user or external application. When external callers present an OIDC or OAuth2 bearer JWT (for example, from Keycloak, Entra ID, or a cloud identity provider), that is a separate identity layer that requires different handling. For this identity layer, you can add JWT validation in addition to WIT.

When agentgateway is deployed as a waypoint, it can validate inbound JWTs and make claims from the validated token available in EnterpriseAgentgatewayPolicy CEL expressions, alongside the workload identity claims in the claims map. This lets you combine both layers in a single policy: enforce that the source workload is a trusted service account (WIT) and that the end-user token carries the expected role or scope (JWT).

JWT passthrough: By default, agentgateway forwards the inbound Authorization header to the upstream service. No additional policy is needed if you only want to pass the token through for the upstream to validate independently.

JWT validation and claim-based policy: To validate JWTs at the waypoint and use their claims in authorization decisions, configure JWT validation in agentgateway with a JWKS endpoint. For configuration steps, see the agentgateway JWT authentication documentation.

JWT token exchange: To exchange an inbound JWT for a different credential before forwarding (for example, to call a downstream service that requires a different issuer or token format), configure backend.tokenExchange in an EnterpriseAgentgatewayPolicy. The inbound JWT can serve as the subject_token passed to the STS.

Trust domain verification for WIT x5c chains

When VALIDATE_SPIFFE_TRUST_DOMAIN_NAMES=STRICT is set on agentgateway and a request carries a WIT, agentgateway verifies the x5c certificate chain that is embedded in the WIT in addition to the mTLS certificate chain. During the verification, agentgateway walks the x5c chain from the signing certificate up to the configured root and rejects the request if no ancestor certificate carries a SAN that matches the SPIFFE trust domain that is declared in the WIT. The proxy uses the same SAN matching rules that are used during the mTLS certificate chain verification. For more information, see SPIFFE trust domain chain verification.

Requests that do not carry a WIT are not affected by this check.