For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Access token validation
Validate an access token that an API client already holds, and reject requests without a valid one.
Protect a route by validating an access token that the client already holds. Kgateway checks the token signature against Microsoft Entra ID’s signing keys. It rejects requests without a valid token instead of redirecting them to a login page. Use this flow for API clients that cannot follow browser redirects.
Before you begin
Complete the Microsoft Entra ID setup page. This flow needs the Entra ID App Registration, the test user, the API scope, the Backend, and the BackendConfigPolicy created during setup.
This flow does not need the client secret in a Kubernetes Secret. The gateway does not exchange an authorization code. The flow also works over HTTP because it does not use cookies.
Important
By default, Entra ID issues v1.0 access tokens for an API that you expose on your App Registration. A v1.0 token has the iss claim https://sts.windows.net/{tenant-id}/ and an aud claim of your Application ID URI, such as api://{client-id}. Its signing keys are at https://login.microsoftonline.com/{tenant-id}/discovery/keys. These values differ from the v2.0 values (/v2.0 and /discovery/v2.0/keys), so use the v1.0 values in the access token validation flow. To get v2.0 tokens instead, set requestedAccessTokenVersion to 2 in the App Registration manifest.
Configure access token validation
Create a GatewayExtension to configure token validation. Then create a TrafficPolicy to enforce validation on a route.
Create a GatewayExtension for JWT validation. The issuer must match the token’s
issclaim from Entra ID. The audiences list must include the token’saudclaim, which is your Application ID URI.kubectl apply -f- <<EOF apiVersion: gateway.kgateway.dev/v1alpha1 kind: GatewayExtension metadata: name: entra-id-jwt namespace: kgateway-system spec: jwt: validationMode: Strict providers: - name: entra-id issuer: https://sts.windows.net/YOUR_TENANT_ID/ jwks: remote: backendRef: group: gateway.kgateway.dev kind: Backend name: entra-id namespace: kgateway-system url: https://login.microsoftonline.com/YOUR_TENANT_ID/discovery/keys audiences: - api://YOUR_CLIENT_ID EOFReplace
YOUR_TENANT_IDandYOUR_CLIENT_IDwith the values that you copied in Entra ID setup.Field Description nameA required, unique name for the provider. issuerMust exactly match the issclaim in your tokens. For v1.0 tokens, usehttps://sts.windows.net/{tenant-id}/.jwks.remote.backendRefThe Backendthat the gateway uses to fetch the signing keys.jwks.remote.urlThe JWKS URL. For v1.0 tokens, use https://login.microsoftonline.com/{tenant-id}/discovery/keys.audiencesAccepted values for the audclaim. Use your Application ID URI, such asapi://YOUR_CLIENT_ID.Note
The
validationModefield is optional and defaults toStrict. This mode requires a valid JWT on every request. Set it toAllowMissingonly if you want requests without a token to pass through. Pair that mode with an authorization policy that restricts those requests.Create a TrafficPolicy that references the JWT GatewayExtension. Make sure that the TrafficPolicy is in the same namespace as the HTTPRoute that it targets.
kubectl apply -f- <<EOF apiVersion: gateway.kgateway.dev/v1alpha1 kind: TrafficPolicy metadata: name: entra-id-jwt-policy namespace: httpbin spec: targetRefs: - group: gateway.networking.k8s.io kind: HTTPRoute name: httpbin jwtAuth: extensionRef: name: entra-id-jwt namespace: kgateway-system EOFConfirm that the TrafficPolicy is attached.
kubectl get TrafficPolicy entra-id-jwt-policy -n httpbin -o yamlIn the
status.ancestorssection, confirm that both theAcceptedandAttachedconditions areTrue.Important
If the authorization code flow also targets this route, the OAuth2 policy runs first. API requests without a session cookie are redirected to Entra ID before JWT validation runs. To test JWT validation alone, temporarily remove the OAuth2 policy or target a different route with the JWT policy.
Verify
Verify the access token validation flow with these steps.
Verify that a request without a token is rejected.
curl -vi "http://$INGRESS_GW_ADDRESS:8080/headers" -H "host: www.example.com"Example output:
< HTTP/1.1 401 UnauthorizedIf you get
200 OK, the JWT policy is not attached to the route. Check the policy attachment step and confirm that the HTTPRoute name matches.Obtain an access token from the Entra ID authorization server.
The JWT policy validates the signature, issuer, and audience of the token that you present. Complete the authorization code flow in a browser. Then copy the value of the
AccessToken-<suffix>cookie that the gateway sets, such asAccessToken-a1b2c3d4.export TOKEN=<access-token-cookie-value>Confirm that the token’s
issandaudclaims match yourGatewayExtension.echo $TOKEN | jq -rR 'split(".")[1] | gsub("-"; "+") | gsub("_"; "/") | @base64d | fromjson | {iss, aud, ver}'Example output for a v1.0 token:
{ "iss": "https://sts.windows.net/YOUR_TENANT_ID/", "aud": "api://YOUR_CLIENT_ID", "ver": "1.0" }Send a request with the token in the
Authorizationheader.curl -vi "http://$INGRESS_GW_ADDRESS:8080/headers" \ -H "host: www.example.com" \ -H "Authorization: Bearer $TOKEN"A successful response shows the headers from the httpbin app.
< HTTP/1.1 200 OKIf the request is rejected, check the response body for the reason:
Message Meaning Jwt is missingNo Authorization: Bearerheader was sent.Jwt verification failsThe signature does not match a JWKS key, or the issuer or audience does not match the JWT policy. Double-check that you used the v1.0 issuerandjwksendpoints.
Cleanup
You can remove the resources that you created in this guide.kubectl delete TrafficPolicy entra-id-jwt-policy -n httpbin
kubectl delete GatewayExtension entra-id-jwt -n kgateway-systemTo remove Entra ID and the shared resources, see the Cleanup section of the Entra ID setup page.