API Key Authentication
3 minute read
This task provides instructions for configuring API Key Authentication. API Key Authentication verifies whether an incoming request includes a valid API key in the header, parameter, or cookie before routing the request to a backend service.
Envoy Gateway introduces a new CRD called SecurityPolicy that allows the user to configure Api Key authentication. This instantiated resource can be linked to a Gateway, HTTPRoute or GRPCRoute resource.
Prerequisites
Follow the steps from the Quickstart task to install Envoy Gateway and the example manifest. Before proceeding, you should be able to query the example backend using HTTP.
Verify the Gateway status:
kubectl get gateway/eg -o yaml
egctl x status gateway -v
Configuration
API Key must be stored in a kubernetes secret and referenced in the SecurityPolicy configuration. The secret is an Opaque secret, with each API key stored under a key corresponding to the client ID.
Create a API Key Secret
Create an Opaque Secret containing the client ID and its corresponding API key
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
type: Opaque
metadata:
name: apikey-secret
namespace: envoy-gateway-system
stringData:
client1: supersecret
EOF
Save and apply the following resource to your cluster:
---
apiVersion: v1
kind: Secret
type: Opaque
metadata:
name: apikey-secret
namespace: envoy-gateway-system
stringData:
client1: supersecret
Create a SecurityPolicy
The below example defines a SecurityPolicy that authenticates requests against the client list in the kubernetes secret created in the previous step.
cat <<EOF | kubectl apply -f -
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
name: apikey-auth-example
spec:
targetRefs:
- group: gateway.networking.k8s.io
kind: HTTPRoute
name: backend
apiKeyAuth:
credentialRefs:
- group: ""
kind: Secret
name: apikey-secret
namespace: envoy-gateway-system
extractFrom:
- headers:
- x-api-key
EOF
Save and apply the following resource to your cluster:
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
name: apikey-auth-example
spec:
targetRefs:
- group: gateway.networking.k8s.io
kind: HTTPRoute
name: backend
apiKeyAuth:
credentialRefs:
- group: ""
kind: Secret
name: apikey-secret
namespace: envoy-gateway-system
extractFrom:
- headers:
- x-api-key
Verify the SecurityPolicy configuration:
kubectl get securitypolicy/apikey-auth-example -o yaml
Testing
Ensure the GATEWAY_HOST
environment variable from the Quickstart is set. If not, follow the
Quickstart instructions to set the variable.
echo $GATEWAY_HOST
Send a request to the backend service without x-api-key
header:
curl -kv -H "Host: www.example.com" "http://${GATEWAY_HOST}/"
You should see 401 Unauthorized
in the response, indicating that the request is not allowed without providing valid API Key in x-api-key
header.
* Connected to 127.0.0.1 (127.0.0.1) port 80
...
> GET / HTTP/2
> Host: www.example.com
> User-Agent: curl/8.7.1
> Accept: */*
...
< HTTP/2 401
< content-length: 58
< content-type: text/plain
< date: Sun, 19 Jan 2025 12:55:39 GMT
<
* Connection #0 to host 127.0.0.1 left intact
Client authentication failed.
Send a request to the backend service with x-api-key
header:
curl -v -H "Host: www.example.com" -H 'x-api-key: supersecret' "http://${GATEWAY_HOST}/"
The request should be allowed and you should see the response from the backend service.
Clean-Up
Follow the steps from the Quickstart to uninstall Envoy Gateway and the example manifest.
Delete the SecurityPolicy and the secret
kubectl delete securitypolicy/apikey-auth-example
kubectl delete secret/apikey-secret
Next Steps
Checkout the Developer Guide to get involved in the project.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.