About API keys

API keys are secure, long-lived UUIDs that clients provide when they send a request to your service. You might use API keys in the following scenarios:

  • You know the set of users that need access to your service. These users do not change often, or you have automation that easily generates or deletes the API key when the users do change.
  • You want direct control over how the credentials are generated and expire.

API keys in Gloo Gateway

To secure your services with API keys, first provide Gloo Gateway with your API keys in the form of Kubernetes secrets. Then in the external auth policy, you refer to the secrets in one of two ways.

  • Specify a label selector that matches the label of one or more API key secrets. Labels are the more flexible, scalable approach.
  • Refer to the name and namespace of each secret.

Gloo Gateway matches a request to a route that is secured by the external auth policy. The request must have a valid API key in a header. You can configure the name of the expected header. If the header is missing, or the API key is invalid, Gloo Gateway denies the request and returns a 401 response.

Internally, Gloo Gateway maps API keys to user identities for all API keys in the system. The user identity for an API key is the name of the secret that has the API key. Gloo Gateway adds the user identity to the request as a header, x-user-id by default. Gloo Gateway can use this header in subsequent filters. The extauth plugin that handles the API key flow is part of the AuthNStage stage. All filters after this stage have access to the user identity header. For example, this functionality is used in Gloo Gateway’s rate limiting API to provide different rate limits for anonymous vs. authorized users. Note that for security purposes, Gloo Gateway sanitizes the header from the response before the response leaves the gateway proxy.

Before you begin

  1. Follow the Get started guide to install Gloo Gateway.

  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 gloo-system gloo-proxy-http -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
echo $INGRESS_GW_ADDRESS  
  
      kubectl port-forward deployment/gloo-proxy-http -n gloo-system 8080:8080

Step 1: Set up your API keys

Store your API keys in a Kubernetes secret so that the external auth service can access them to check incoming requests.

  1. From your API management tool such as Gloo Portal, generate an API key to use for your app’s domain. The examples in this guide use N2YwMDIxZTEtNGUzNS1jNzgzLTRkYjAtYjE2YzRkZGVmNjcy.

  2. Create a Kubernetes secret to store your 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

  3. Verify that the secret is created. Note that the data.api-key value is base64 encoded.

      kubectl get secret infra-apikey -n httpbin -oyaml

    Example output:

      apiVersion: v1
kind: Secret
metadata:
  name: infra-apikey
  namespace: httpbin
  labels:
    team: infrastructure
type: extauth.solo.io/apikey
data:
  api-key: TjJZd01ESXhaVEV0TkdVek5TMWpOemd6TFRSa1lqQXRZakUyWXpSa1pHVm1OamN5

Step 2: Enforce API key authentication

Use AuthConfig and GlooTrafficPolicy resources to apply the auth rules to the routes that you want to secure.

  1. Create an AuthConfig resource with your API key authentication rules. When a request comes in for a route that is secured by this AuthConfig, Gloo Gateway extracts the API key from the api-key request header. Then, it uses the Kubernetes secret with the label team: infrastructure to check if the API key in that Kubernetes secret matches the API key from the request.

      kubectl apply -f- <<EOF
apiVersion: extauth.solo.io/v1
kind: AuthConfig
metadata:
  name: apikey-auth
  namespace: httpbin
spec:
  configs:
    - apiKeyAuth:
        # The request header name that holds the API key.
        # This field is optional and defaults to api-key if not present.
        headerName: api-key
        labelSelector:
          team: infrastructure
EOF

  2. Create a GlooTrafficPolicy resource that refers to the AuthConfig that you created. The following policy applies external auth to all routes that the Gateway serves.

      kubectl apply -f - <<EOF
apiVersion: gloo.solo.io/v1alpha1
kind: GlooTrafficPolicy
metadata:
  name: test-extauth-policy
  namespace: gloo-system
spec:
  targetRefs:
    - name: http
      group: gateway.networking.k8s.io
      kind: Gateway
  glooExtAuth:
    authConfigRef:
      name: apikey-auth
      namespace: httpbin
EOF

Step 3: Verify that your routes are secured

Send various requests to verify that API key auth is enforced for your routes.

  1. Send a request to the httpbin app without any API key. Verify that your request is denied and that you get back a 401 HTTP response code.

      curl -i http://$INGRESS_GW_ADDRESS:8080/status/200 -H "host: www.example.com"
  
      curl -i localhost:8080/status/200 -H "host: www.example.com"

    Example output:

      * Mark bundle as not supporting multiuse
< HTTP/1.1 401 Unauthorized
< date: Fri, 19 Apr 2024 17:41:01 GMT
< server: envoy
< content-length: 0

  2. Send another request to the httpbin app. This time, you include the API key in the api-key header. Verify that the request succeeds and that you get back a 200 HTTP response code.

      curl -i http://$INGRESS_GW_ADDRESS:8080/status/200 -H "host: www.example.com" \
-H "api-key: N2YwMDIxZTEtNGUzNS1jNzgzLTRkYjAtYjE2YzRkZGVmNjcy"
  
      curl -i localhost:8080/status/200 -H "host: www.example.com" -H "api-key: N2YwMDIxZTEtNGUzNS1jNzgzLTRkYjAtYjE2YzRkZGVmNjcy"

    Example output:

      * Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< access-control-allow-credentials: true
< access-control-allow-origin: *
< date: Fri, 19 Apr 2024 17:44:06 GMT
< content-length: 0
< x-envoy-upstream-service-time: 0
< server: envoy

Cleanup

You can optionally remove the resources that you set up as part of this guide.
  kubectl delete authconfig apikey-auth -n httpbin
kubectl delete glootrafficpolicy test-extauth-policy -n gloo-system
kubectl delete secret infra-apikey -n httpbin