diff --git a/site/content/en/latest/tasks/security/apikey-auth.md b/site/content/en/latest/tasks/security/apikey-auth.md new file mode 100644 index 00000000000..9d934635b54 --- /dev/null +++ b/site/content/en/latest/tasks/security/apikey-auth.md @@ -0,0 +1,188 @@ +--- +title: "API Key Authentication" +--- + +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][SecurityPolicy] that allows the user to configure Api Key +authentication. +This instantiated resource can be linked to a [Gateway][Gateway], [HTTPRoute][HTTPRoute] or [GRPCRoute][GRPCRoute] resource. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Configuration + +API Key must be stored in a kubernetes secret and referenced in the [SecurityPolicy][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 + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### 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. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the SecurityPolicy configuration: + +```shell +kubectl get securitypolicy/apikey-auth-example -o yaml +``` + +## Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +Send a request to the backend service without `x-api-key` header: + +```shell +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. + +```shell +* 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: + +```shell +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](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the SecurityPolicy and the secret + +```shell +kubectl delete securitypolicy/apikey-auth-example +kubectl delete secret/apikey-secret +``` + +## Next Steps + +Checkout the [Developer Guide](../../../contributions/develop) to get involved in the project. + +[SecurityPolicy]: ../../../contributions/design/security-policy +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute