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.

Restrict access based on claims

Page as Markdown

Allow or deny requests based on JWT claims by using a CEL rbac policy.

Use an rbac policy with Common Expression Language (CEL) expressions to allow or deny requests based on the claims in a verified JWT. The JWT filter writes the verified token payload to Envoy dynamic metadata, and your CEL expressions read the claims from that metadata. Because the rules depend on a verified token, configure rbac together with jwtAuth in the same TrafficPolicy.

Before you begin

  1. Follow the Get started guide to install kgateway.

  2. Follow the Sample app guide to create a gateway proxy with an HTTP listener and deploy the httpbin sample app.

  3. Get the external address of the gateway and save it in an environment variable.

    export INGRESS_GW_ADDRESS=$(kubectl get svc -n kgateway-system http -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
    echo $INGRESS_GW_ADDRESS  

  1. Complete the Set up JWT authentication steps in the Basic JWT policy guide to create the selfminted-jwt GatewayExtension. The jwt-policy TrafficPolicy in this guide replaces the policy of the same name from that guide.
  2. Save the sample JWT token from that guide in an environment variable. The token is for a user named Alice, who has the team=dev claim.
    export TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImtnYXRld2F5LXB1YmxpYy1rZXktMDAxIn0.eyJpc3MiOiJrZ2F0ZXdheS5kZXYiLCJvcmciOiJrZ2F0ZXdheS5kZXYiLCJzdWIiOiJhbGljZSIsInRlYW0iOiJkZXYiLCJleHAiOjIwNzQyNzQ4ODQsImxsbXMiOnsib3BlbmFpIjpbImdwdC0zLjUtdHVyYm8iXX19.lTQr9PIyDeIQYn0c_qxaNb1sAJ3-rCMzZ0jR33v_P5ZWw9eiIHm9e_LDWaBZp2s6CCeqSubJvk7QT06SeKqiq84uQNUG6o5vKVolIfep6L7LCH9GFuTsJgTLxznJPc4oh5qIum0zBC2fy_IOOGeV_FzeFh1Jidi3onGS1fxV2EhY9btbM3br8oFwkhU4Gv1d-lUK1_j0cuP0Cuyx3EoaJkarmB_chJYqFe-EoUVbKXdsYdBLGCwK8u30FOBleRUWvuekQB7atlfYG0qptG0iOPVVv4tynL44cNQ_5GBt4QfIwBqAQyoJCcqbxNrZi_Ie6UP-IMWuejlXMDgTHJggqA

Allow access based on a claim

  1. Create a TrafficPolicy that enforces JWT authentication and allows only requests with a valid JWT that contains the team=dev claim. If the JWT does not include this claim, the request is denied.

    kubectl apply -f- <<EOF
    apiVersion: gateway.kgateway.dev/v1alpha1
    kind: TrafficPolicy
    metadata:
      name: jwt-policy
      namespace: kgateway-system
    spec:
      targetRefs:
        - group: gateway.networking.k8s.io
          kind: Gateway
          name: http
      jwtAuth:
        extensionRef:
          name: selfminted-jwt
      rbac:
        action: Allow
        policy:
          matchExpressions:
            - "metadata.filter_metadata['envoy.filters.http.jwt_authn']['payload']['team'] == 'dev'"
    EOF
    FieldDescription
    rbac.actionThe action to take when a request matches the policy, either Allow or Deny. Defaults to Allow, which permits only matching requests and denies all others.
    rbac.policy.matchExpressionsA list of CEL expressions. The policy matches when any one of the expressions evaluates to true. Reference verified JWT claims through the envoy.filters.http.jwt_authn filter metadata, in the form metadata.filter_metadata['envoy.filters.http.jwt_authn']['payload']['<claim>'].
  2. Send a request with Alice’s token. Because the JWT has a team claim that equals dev, the request matches the policy and is allowed with a 200 HTTP response. A request with a token where the team claim does not equal dev, or that has no team claim, is denied with a 403 HTTP response.

    curl -vik http://$INGRESS_GW_ADDRESS:8080/headers \
      -H "host: www.example.com:8080" \
      --header "Authorization: Bearer $TOKEN"

    Verify that you get a 200 OK response.

  3. Save a token that does not have the team=dev claim, then repeat the request. This example uses a token for a user named Bob, who has the team=ops claim. The token is signed by the same private key so that the JWT passes verification with the inline JWKS in the selfminted-jwt GatewayExtension. Verify that the request is denied with a 403 HTTP response.

    export BOB_TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImtnYXRld2F5LXB1YmxpYy1rZXktMDAxIn0.eyJpc3MiOiJrZ2F0ZXdheS5kZXYiLCJvcmciOiJrZ2F0ZXdheS5kZXYiLCJzdWIiOiJib2IiLCJ0ZWFtIjoib3BzIiwiZXhwIjoyMDc0Mjc0OTU0LCJsbG1zIjp7Im1pc3RyYWxhaSI6WyJtaXN0cmFsLWxhcmdlLWxhdGVzdCJdfX0.pKtqiC1EZh1Rjz5B19DbtM_ixfeHc9UgyGeHa3sFxFZoqRne1p_sCNgnRK0GMFTv5-rVaneIfhgcCK2ytRPFMe-wQZ4eX_O_1Cm2Yz_9yKsJJ0VVgIcqGgWQvp0UQXsFBBONrsjIz2kEZBxR3t_phzXhbxe-5JeFKCRoC9zN6Bmyr_LzrJUNaqSIUsy3hmpsTE8zkI2besj88UtgHf1LZ9MAon76bJp45R34mf9ZZh58hFip5QyddYhKnOI3-OVSbwT3zRX39EDvxr8-jbNm5nZa2nquIWclpN497JtAfFHryONxtl3KO66YWGwkftxYUCe6q5oP26WeR9mtba_SnA
    curl -vik http://$INGRESS_GW_ADDRESS:8080/headers \
      -H "host: www.example.com:8080" \
      --header "Authorization: Bearer $BOB_TOKEN"

    Verify that the request is denied with a 403 Forbidden response.

    HTTP/1.1 403 Forbidden
    RBAC: access denied

Other configurations

The following examples show other ways to write the rbac policy. Each one replaces the rbac block in the TrafficPolicy from the previous section.

Deny access based on a claim

Set action to Deny to deny requests that match the expressions and allow everything else. The following policy denies requests with a JWT where the team claim equals ops.

rbac:
  action: Deny
  policy:
    matchExpressions:
      - "metadata.filter_metadata['envoy.filters.http.jwt_authn']['payload']['team'] == 'ops'"

Match more than one claim

List multiple expressions to match on more than one condition. The policy matches when any expression evaluates to true (OR logic). The following policy allows requests if the JWT has a team=dev or sub=alice claim.

rbac:
  action: Allow
  policy:
    matchExpressions:
      - "metadata.filter_metadata['envoy.filters.http.jwt_authn']['payload']['team'] == 'dev'"
      - "metadata.filter_metadata['envoy.filters.http.jwt_authn']['payload']['sub'] == 'alice'"

Match an OAuth scope

You can authorize requests based on an OAuth scope that your identity provider issues. The sample tokens in this guide do not have a scope claim, so to try this example, use a token from your identity provider. OAuth scopes are commonly represented in the standard scope claim as a single string of space-delimited scopes, such as read write admin. However, Envoy’s CEL runtime does not include the split() string function.

To match one scope exactly, configure your identity provider or token minter to emit scope (or another claim) as a JSON array, decode a token to verify that the claim is an array rather than a space-delimited string, and test for membership in that list. The following policy allows requests with a JWT where the scope claim includes admin.

rbac:
  action: Allow
  policy:
    matchExpressions:
      - "'admin' in metadata.filter_metadata['envoy.filters.http.jwt_authn']['payload']['scope']"

For example, the JWT payload includes an array-shaped claim similar to the following.

{
  "scope": ["read", "write", "admin"]
}

Note

Avoid matching a space-delimited scope string with substring checks such as contains('admin') because that can match longer scope values, such as superadmin.

Cleanup

kubectl delete TrafficPolicy jwt-policy -n kgateway-system
kubectl delete gatewayextension selfminted-jwt -n kgateway-system
Was this page helpful?