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

Mark HTTPRoutes as requiring authentication so that requests are denied with a 403 response when no valid auth policy is applied.

About require-auth

You can mark an HTTPRoute as requiring authentication by adding the kgateway.dev/require-auth: "true" annotation to the HTTPRoute resource. The annotation instructs Solo Enterprise for kgateway to deny all requests to that route with an 403 HTTP response, unless a valid auth policy is applied to the route and successfully authenticates the request at runtime. This behavior is sometimes referred to as fail-closed.

Without this annotation, a misconfigured, missing, or deleted auth policy can silently leave a route unprotected, which lets unauthenticated traffic reach the upstream backend. The annotation provides another layer of defense. Even if the auth policy fails to translate, sync, or is accidentally deleted, requests are automatically denied by default.

The following table shows the auth policies that support the require-auth check. The policy must be specified by using one of the following EnterpriseKgatewayTrafficPolicy fields.

Considerations

Route delegation: The annotation must be placed on the child HTTPRoute, not on a parent that delegates to child routes. If you add the annotation to a parent route, it has no effect on delegated routes and unauthenticated traffic is allowed through. Annotate each child HTTPRoute individually.

JWT AllowMissing validation policy: The kgateway.dev/require-auth annotation is incompatible with the validationPolicy: AllowMissing mode. In AllowMissing mode, the JWT filter silently passes the request through without performing any authentication, which satisfies the require-auth check, even when no credentials are provided. To use require-auth with JWT, use validationPolicy: RequireValid.

Multi-rule HTTPRoutes: The annotation applies to all rules in the HTTPRoute. If you need some rules to allow unauthenticated traffic and others to require auth, split them into separate HTTPRoutes.

Before you begin

1. Follow the Get started guide to install Solo Enterprise for 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  

   kubectl port-forward deployment/http -n kgateway-system 8080:8080

Step 1: Enable require-auth

To enable the require-auth feature, you must set the KGW_ENABLE_AUTH_METADATA: true environment variable on the Solo Enterprise for kgateway controller.

1. Get your current Helm values and save them to a file.

   helm get values enterprise-kgateway -n kgateway-system -o yaml > values.yaml
   open values.yaml

2. Add the following snippet to enable the require-auth feature.

   controller:
     extraEnv:
       KGW_ENABLE_AUTH_METADATA: "true"

3. Upgrade the Helm installation with the updated values.

   helm upgrade -i -n kgateway-system enterprise-kgateway oci://us-docker.pkg.dev/solo-public/enterprise-kgateway/charts/enterprise-kgateway \
     --version 2.2.6 \
     -f values.yaml

4. Verify that the controller pod restarts successfully.

   kubectl get pods -n kgateway-system

Step 2: Configure a route to require auth

1. Add the kgateway.dev/require-auth: "true" annotation to the HTTPRoute of your app. This example adds the annotation to the httpbin route that you created when you began.

   kubectl apply -f - <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: httpbin
     namespace: httpbin
     annotations:
       kgateway.dev/require-auth: "true"
   spec:
     parentRefs:
       - name: http
         namespace: kgateway-system
     hostnames:
       - www.example.com
     rules:
       - backendRefs:
           - name: httpbin
             port: 8000
   EOF
   Review the following table to understand this configuration.

   Field	Description
   annotations: kgateway.dev/require-auth: "true"	Marks the route as requiring authentication. Requests are denied with a 403 unless a valid auth policy successfully authenticates the request at runtime.

2. Send a request to the httpbin app. Verify that the request is denied with a 403 HTTP response code, because no auth policy is applied to that route.

   curl -v http://$INGRESS_GW_ADDRESS:8080/get -H "host: www.example.com:8080"

   curl -v localhost:8080/get -H "host: www.example.com"

   Example output:

   < HTTP/1.1 403 Forbidden
   ...
   RBAC: access denied%     

Step 3: Add an auth policy

Set up any of the supported auth policies for the httpbin app. In this example, you apply API key authentication to the httpbin app.

1. Create a Kubernetes secret to store the API key.

   kubectl apply -f - <<EOF
   apiVersion: v1
   kind: Secret
   metadata:
     name: infra-apikey
     namespace: httpbin
     labels:
       team: infrastructure
   type: extauth.solo.io/apikey
   stringData:
     api-key: N2YwMDIxZTEtNGUzNS1jNzgzLTRkYjAtYjE2YzRkZGVmNjcy
   EOF

2. Create an AuthConfig that looks up the API key from secrets with the team: infrastructure label.

   kubectl apply -f - <<EOF
   apiVersion: extauth.solo.io/v1
   kind: AuthConfig
   metadata:
     name: apikey-auth
     namespace: httpbin
   spec:
     configs:
       - apiKeyAuth:
           headerName: api-key
           labelSelector:
             team: infrastructure
   EOF

3. Create an EnterpriseKgatewayTrafficPolicy that references the AuthConfig and targets the HTTPRoute.

   kubectl apply -f - <<EOF
   apiVersion: enterprisekgateway.solo.io/v1alpha1
   kind: EnterpriseKgatewayTrafficPolicy
   metadata:
     name: require-auth-policy
     namespace: httpbin
   spec:
     targetRefs:
       - name: httpbin
         group: gateway.networking.k8s.io
         kind: HTTPRoute
     entExtAuth:
       authConfigRef:
         name: apikey-auth
         namespace: httpbin
   EOF

4. Send a request with the API key in the api-key header. Verify that the request now succeeds with a 200 HTTP response code.

   curl -v http://$INGRESS_GW_ADDRESS:8080/get -H "host: www.example.com:8080" \
     -H "api-key: N2YwMDIxZTEtNGUzNS1jNzgzLTRkYjAtYjE2YzRkZGVmNjcy"

   curl -v localhost:8080/get -H "host: www.example.com" \
     -H "api-key: N2YwMDIxZTEtNGUzNS1jNzgzLTRkYjAtYjE2YzRkZGVmNjcy"

   Example output:

   < HTTP/1.1 200 OK

Cleanup

kubectl delete EnterpriseKgatewayTrafficPolicy require-auth-policy -n httpbin
kubectl delete authconfig apikey-auth -n httpbin
kubectl delete secret infra-apikey -n httpbin

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin
  namespace: httpbin
spec:
  parentRefs:
    - name: http
      namespace: kgateway-system
  hostnames:
    - www.example.com
  rules:
    - backendRefs:
        - name: httpbin
          port: 8000
EOF