From 681d372f7cc5010ccb6089e9cfe7f2d68bc8eaa0 Mon Sep 17 00:00:00 2001 From: Taufik Mulyana Date: Sun, 19 Jan 2025 20:21:58 +0700 Subject: [PATCH 1/2] docs: add api key auth instruction Signed-off-by: Taufik Mulyana --- .../en/latest/tasks/security/apikey-auth.md | 190 ++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 site/content/en/latest/tasks/security/apikey-auth.md 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..3353363c647 --- /dev/null +++ b/site/content/en/latest/tasks/security/apikey-auth.md @@ -0,0 +1,190 @@ +--- +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 +[http Basic authentication]: https://tools.ietf.org/html/rfc2617 +[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 +[.htpasswd]: https://httpd.apache.org/docs/current/programs/htpasswd.html From 1e016f67f1752083b3afe314c1b3a88a2c289161 Mon Sep 17 00:00:00 2001 From: Taufik Mulyana Date: Sun, 19 Jan 2025 20:31:13 +0700 Subject: [PATCH 2/2] fix: remove unrelated links Signed-off-by: Taufik Mulyana --- site/content/en/latest/tasks/security/apikey-auth.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/site/content/en/latest/tasks/security/apikey-auth.md b/site/content/en/latest/tasks/security/apikey-auth.md index 3353363c647..9d934635b54 100644 --- a/site/content/en/latest/tasks/security/apikey-auth.md +++ b/site/content/en/latest/tasks/security/apikey-auth.md @@ -183,8 +183,6 @@ kubectl delete secret/apikey-secret Checkout the [Developer Guide](../../../contributions/develop) to get involved in the project. [SecurityPolicy]: ../../../contributions/design/security-policy -[http Basic authentication]: https://tools.ietf.org/html/rfc2617 [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 -[.htpasswd]: https://httpd.apache.org/docs/current/programs/htpasswd.html