Skip to content

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

Page as Markdown

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.

  1. Create a GatewayExtension for JWT validation. The issuer must match the token’s iss claim from Entra ID. The audiences list must include the token’s aud claim, 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
    EOF

    Replace YOUR_TENANT_ID and YOUR_CLIENT_ID with the values that you copied in Entra ID setup.

    FieldDescription
    nameA required, unique name for the provider.
    issuerMust exactly match the iss claim in your tokens. For v1.0 tokens, use https://sts.windows.net/{tenant-id}/.
    jwks.remote.backendRefThe Backend that 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 aud claim. Use your Application ID URI, such as api://YOUR_CLIENT_ID.

    Note

    The validationMode field is optional and defaults to Strict. This mode requires a valid JWT on every request. Set it to AllowMissing only if you want requests without a token to pass through. Pair that mode with an authorization policy that restricts those requests.

  2. 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
    EOF
  3. Confirm that the TrafficPolicy is attached.

    kubectl get TrafficPolicy entra-id-jwt-policy -n httpbin -o yaml

    In the status.ancestors section, confirm that both the Accepted and Attached conditions are True.

    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.

  1. 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 Unauthorized

    If 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.

  2. 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 as AccessToken-a1b2c3d4.

    export TOKEN=<access-token-cookie-value>
  3. Confirm that the token’s iss and aud claims match your GatewayExtension.

    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"
    }
  4. Send a request with the token in the Authorization header.

    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 OK

    If the request is rejected, check the response body for the reason:

    MessageMeaning
    Jwt is missingNo Authorization: Bearer header 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 issuer and jwks endpoints.

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-system

To remove Entra ID and the shared resources, see the Cleanup section of the Entra ID setup page.

Was this page helpful?