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
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
Follow the Get started guide to install kgateway.
Follow the Sample app guide to create a gateway proxy with an HTTP listener and deploy the httpbin sample app.
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
- Complete the Set up JWT authentication steps in the Basic JWT policy guide to create the
selfminted-jwtGatewayExtension. Thejwt-policyTrafficPolicy in this guide replaces the policy of the same name from that guide. - Save the sample JWT token from that guide in an environment variable. The token is for a user named Alice, who has the
team=devclaim.export TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImtnYXRld2F5LXB1YmxpYy1rZXktMDAxIn0.eyJpc3MiOiJrZ2F0ZXdheS5kZXYiLCJvcmciOiJrZ2F0ZXdheS5kZXYiLCJzdWIiOiJhbGljZSIsInRlYW0iOiJkZXYiLCJleHAiOjIwNzQyNzQ4ODQsImxsbXMiOnsib3BlbmFpIjpbImdwdC0zLjUtdHVyYm8iXX19.lTQr9PIyDeIQYn0c_qxaNb1sAJ3-rCMzZ0jR33v_P5ZWw9eiIHm9e_LDWaBZp2s6CCeqSubJvk7QT06SeKqiq84uQNUG6o5vKVolIfep6L7LCH9GFuTsJgTLxznJPc4oh5qIum0zBC2fy_IOOGeV_FzeFh1Jidi3onGS1fxV2EhY9btbM3br8oFwkhU4Gv1d-lUK1_j0cuP0Cuyx3EoaJkarmB_chJYqFe-EoUVbKXdsYdBLGCwK8u30FOBleRUWvuekQB7atlfYG0qptG0iOPVVv4tynL44cNQ_5GBt4QfIwBqAQyoJCcqbxNrZi_Ie6UP-IMWuejlXMDgTHJggqA
Allow access based on a claim
Create a TrafficPolicy that enforces JWT authentication and allows only requests with a valid JWT that contains the
team=devclaim. 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'" EOFField Description rbac.actionThe action to take when a request matches the policy, either AlloworDeny. Defaults toAllow, 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 theenvoy.filters.http.jwt_authnfilter metadata, in the formmetadata.filter_metadata['envoy.filters.http.jwt_authn']['payload']['<claim>'].Send a request with Alice’s token. Because the JWT has a
teamclaim that equalsdev, the request matches the policy and is allowed with a 200 HTTP response. A request with a token where theteamclaim does not equaldev, or that has noteamclaim, 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 OKresponse.Save a token that does not have the
team=devclaim, then repeat the request. This example uses a token for a user named Bob, who has theteam=opsclaim. The token is signed by the same private key so that the JWT passes verification with the inline JWKS in theselfminted-jwtGatewayExtension. 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_SnAcurl -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 Forbiddenresponse.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