|
| 1 | +# API Key Authentication |
| 2 | + |
| 3 | +NGINX supports authenticating requests with |
| 4 | +[ngx_http_auth_request_module](https://nginx.org/en/docs/http/ngx_http_auth_request_module.html). In this example, we deploy |
| 5 | +a web application, configure load balancing for it via a VirtualServer, and apply an API Key Auth policy. |
| 6 | + |
| 7 | +## Prerequisites |
| 8 | + |
| 9 | +1. Follow the [installation](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) |
| 10 | + instructions to deploy the Ingress Controller. In this example we will be using a snippet to turn the policy off on a specific path so ensure that the `enable-snippets` flag is set. |
| 11 | +1. Save the public IP address of the Ingress Controller into a shell variable: |
| 12 | + |
| 13 | + ```console |
| 14 | + IC_IP=XXX.YYY.ZZZ.III |
| 15 | + ``` |
| 16 | + |
| 17 | +1. Save the HTTP port of the Ingress Controller into a shell variable: |
| 18 | + |
| 19 | + ```console |
| 20 | + IC_HTTP_PORT=<port number> |
| 21 | + ``` |
| 22 | + |
| 23 | +## Step 1 - Deploy a Web Application |
| 24 | + |
| 25 | +Create the application deployment and service: |
| 26 | + |
| 27 | +```console |
| 28 | +kubectl apply -f cafe.yaml |
| 29 | +``` |
| 30 | + |
| 31 | +## Step 2 - Deploy the API Key Auth Secret |
| 32 | + |
| 33 | +Create a secret of type `nginx.org/apikey` with the name `api-key-client-secret` that will be used for authorization on the server level. |
| 34 | + |
| 35 | +This secret will contain a mapping of client IDs to base64 encoded API Keys. |
| 36 | + |
| 37 | +```console |
| 38 | +kubectl apply -f api-key-secret.yaml |
| 39 | +``` |
| 40 | + |
| 41 | +## Step 3 - Deploy the API Key Auth Policy |
| 42 | + |
| 43 | +Create a policy with the name `api-key-policy` that references the secret from the previous step in the clientSecret field. |
| 44 | +Provide an array of headers and queries in the header and query fields of the suppliedIn field, indicating where the API key can be sent |
| 45 | + |
| 46 | +```console |
| 47 | +kubectl apply -f api-key-policy.yaml |
| 48 | +``` |
| 49 | + |
| 50 | +## Step 4 - Configure Load Balancing |
| 51 | + |
| 52 | +Create a VirtualServer resource for the web application: |
| 53 | + |
| 54 | +```console |
| 55 | +kubectl apply -f cafe-virtual-server.yaml |
| 56 | +``` |
| 57 | + |
| 58 | +Note that the VirtualServer references the policy `api-key-policy` created in Step 3. |
| 59 | + |
| 60 | +## Step 5 - Test the Configuration |
| 61 | + |
| 62 | +If you attempt to access the application without providing a valid API Key in a expected header or query param for that VirtualServer: |
| 63 | + |
| 64 | +```console |
| 65 | +curl --resolve cafe.example.com:$IC_HTTP_PORT:$IC_IP http://cafe.example.com:$IC_HTTP_PORT/ |
| 66 | +``` |
| 67 | + |
| 68 | +```text |
| 69 | +<html> |
| 70 | +<head><title>401 Authorization Required</title></head> |
| 71 | +<body> |
| 72 | +<center><h1>401 Authorization Required</h1></center> |
| 73 | +<hr><center>nginx/1.21.5</center> |
| 74 | +</body> |
| 75 | +</html> |
| 76 | +``` |
| 77 | + |
| 78 | +If you attempt to access the application providing an incorrect API Key in an expected header or query param for that VirtualServer: |
| 79 | + |
| 80 | +```console |
| 81 | +curl --resolve cafe.example.com:$IC_HTTP_PORT:$IC_IP -H "X-header-name: wrongpassword" http://cafe.example.com:$IC_HTTP_PORT/coffee |
| 82 | +``` |
| 83 | + |
| 84 | +```text |
| 85 | +<html> |
| 86 | +<head><title>403 Forbidden</title></head> |
| 87 | +<body> |
| 88 | +<center><h1>403 Forbidden</h1></center> |
| 89 | +<hr><center>nginx/1.27.0</center> |
| 90 | +</body> |
| 91 | +</html> |
| 92 | +``` |
| 93 | + |
| 94 | +If you provide a valid API Key in an a header or query defined in the policy, your request will succeed: |
| 95 | + |
| 96 | +```console |
| 97 | +curl --resolve cafe.example.com:$IC_HTTPS_PORT:$IC_IP -H "X-header-name: password" https://cafe.example.com:$IC_HTTPS_PORT/coffee |
| 98 | +``` |
| 99 | + |
| 100 | +```text |
| 101 | +Server address: 10.244.0.6:8080 |
| 102 | +Server name: coffee-56b44d4c55-vjwxd |
| 103 | +Date: 13/Jun/2024:13:12:17 +0000 |
| 104 | +URI: /coffee |
| 105 | +Request ID: 4feedb3265a0430a1f58831d016e846d |
| 106 | +``` |
| 107 | + |
| 108 | +If you attempt to access the /tea path, the request will be allowed without an API Key, because the auth_request directive is turned off for that path with a location snippet: |
| 109 | + |
| 110 | +```console |
| 111 | +curl --resolve cafe.example.com:$IC_HTTP_PORT:$IC_IP http://cafe.example.com:$IC_HTTP_PORT/tea |
| 112 | +``` |
| 113 | + |
| 114 | +```text |
| 115 | +Server address: 10.244.0.5:8080 |
| 116 | +Server name: tea-596697966f-dmq7t |
| 117 | +Date: 13/Jun/2024:13:16:46 +0000 |
| 118 | +URI: /tea |
| 119 | +Request ID: 26e6d7dd0272eca82f31f33bf90698c9 |
| 120 | +``` |
| 121 | + |
| 122 | +Additionally you can set [error pages](https://docs.nginx.com/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/#errorpage) to handle the 401 and 403 responses. |
0 commit comments