From 4bb46ccf20a670ff029b78d4acdca7d797308539 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Tue, 6 Jan 2026 15:53:26 +0000 Subject: [PATCH 01/15] Add document to configure Basic Auth --- .../traffic-security/basic-authentication.md | 349 ++++++++++++++++++ 1 file changed, 349 insertions(+) create mode 100644 content/ngf/traffic-security/basic-authentication.md diff --git a/content/ngf/traffic-security/basic-authentication.md b/content/ngf/traffic-security/basic-authentication.md new file mode 100644 index 000000000..a082385d4 --- /dev/null +++ b/content/ngf/traffic-security/basic-authentication.md @@ -0,0 +1,349 @@ +--- +title: Configure Basic Authentication +weight: 800 +toc: true +nd-content-type: how-to +nd-product: FABRIC +nd-docs: DOCS-1848 +--- + +This page introduces how to configure basic authentication for your applications using the AuthenticationFilter CRD. + +## Overview + +Authentication is crucial for modern application security and allows you to be confident that only trusted and authorized users are accessing your applications, or API backends. +Through this document, you'll learn how to protect your application endpoints with NGINX Gateway Fabric using the AuthenticationFilter CRD. +We will use our sample `tea` and `coffee` applications, where we protect the `/coffee` endpoint with Basic Authentication. + +## Before you begin + +- Install NGINX Gateway Fabric (OSS or Plus), with [Helm]({{< ref "/ngf/install/helm.md" >}}) or [Manifest]({{< ref "/ngf/install/manifest.md" >}}) +- Ensure the Gateway API CRDs are installed on your cluster. +- Ensure the latest NGINX Gateway Fabric CRDs are installed on your cluster. +- Ensure `kubectl` is installed on your cluster. + +## How it works + +For Basic Authentication, NGINX uses the [ngx_http_auth_basic](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html) module. +Below is an example NGINX configuration using this module: + +```nginx +http { + upstream backend_default { + server 10.0.0.10:80; + server 10.0.0.11:80; + } + + server { + listen 80; + server_name cafe.example.com; + + location /coffee { + auth_basic "Restricted"; + auth_basic_user_file /etc/nginx/secrets/basic_auth_default_basic_auth_user; + proxy_pass http://backend_default; + } + } +} +``` + +All requests made to `/coffee` will require credentials that match those stored in `/etc/nginx/secrets/basic_auth_default_basic_auth_user` defined by the `auth_basic_user_file` directive. Any request that contains invalid or missing credentials will be rejected. + +## Setup + +### Deploy demo applications + +```yaml +kubectl apply -f - < +``` + +### Create a Basic Authentication secret and AuthenticationFilter + +Deploy secret with user credentials, and the AuthenticationFilter: + +```yaml +kubectl apply -f - < +``` + +## Verify Basic Authentication + +Accessing `/coffee` without credentials: + +```shell +curl -i -H "Host: cafe.example.com" http://$GW_IP:$GW_PORT/coffee +``` + +Response: + +```text + +401 Authorization Required + +

401 Authorization Required

+
nginx
+ + +``` + +Accessing `/coffee` with incorrect credentials: + +```shell +curl -i -u user1:wrong -H "Host: cafe.example.com http://$GW_IP:$GW_PORT/coffee" +``` + +Response: + +```text + +401 Authorization Required + +

401 Authorization Required

+
nginx
+ + +``` + +Accessing `/coffee` with valid credentials: + +```shell +curl -i -u user1:password1 -H "Host: cafe.example.com http://$GW_IP:$GW_PORT/coffee" +``` + +Response: + +```text +Server address: 10.244.0.7:8080 +Server name: coffee-654ddf664b-nhhvr +Date: 06/Jan/2026:15:20:15 +0000 +URI: /coffee +Request ID: 13a925b2514b62c45ea4a79800248d5c +``` + +Accessing `/tea` + +Since tea has no AuthenticationFilter attached, responses are processed normally: + +```shell +curl -i -H "Host: cafe.example.com" http://$GW_IP:$GW_PORT/coffee +``` + +Response: + +```text +Server address: 10.244.0.10:8080 +Server name: tea-75bc9f4b6d-ms2n8 +Date: 06/Jan/2026:15:36:26 +0000 +URI: /tea +Request ID: c7eb0509303de1c160cb7e7d2ac1d99f +``` + + +## Troubleshooting + +- Ensure the HTTPRoute is Accepted and references the correct AuthenticationFilter name and group. +- Confirm the secret key is named `auth` and is of type `nginx.org/htpasswd`. +- Ensure the secret referenced by the AuthenticationFilter is in the same namespace. + +## Further reading + +- [Example deployment files for AuthenticationFilter](https://github.com/nginx/nginx-gateway-fabric/tree/main/examples/basic-authentication) +- [NGINX HTTP Basic Auth Module](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html) From 7c66f3056aed595b9a5683631b120b790ad43339 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Tue, 6 Jan 2026 16:04:55 +0000 Subject: [PATCH 02/15] Fix references and add important note for secret type and key --- content/ngf/traffic-security/basic-authentication.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/content/ngf/traffic-security/basic-authentication.md b/content/ngf/traffic-security/basic-authentication.md index a082385d4..086a0d63e 100644 --- a/content/ngf/traffic-security/basic-authentication.md +++ b/content/ngf/traffic-security/basic-authentication.md @@ -17,7 +17,7 @@ We will use our sample `tea` and `coffee` applications, where we protect the `/c ## Before you begin -- Install NGINX Gateway Fabric (OSS or Plus), with [Helm]({{< ref "/ngf/install/helm.md" >}}) or [Manifest]({{< ref "/ngf/install/manifest.md" >}}) +- Install NGINX Gateway Fabric (OSS or Plus), with [Helm]({{< ref "/ngf/install/helm.md" >}}) or [Manifest]({{< ref "/ngf/install/manifests.md" >}}) - Ensure the Gateway API CRDs are installed on your cluster. - Ensure the latest NGINX Gateway Fabric CRDs are installed on your cluster. - Ensure `kubectl` is installed on your cluster. @@ -161,7 +161,9 @@ GW_PORT= ### Create a Basic Authentication secret and AuthenticationFilter -Deploy secret with user credentials, and the AuthenticationFilter: +Deploy secret with user credentials, and the AuthenticationFilter. + +{{< call-out "important" >}} Ensure the secret deployed is of type `nginx.org/htpasswd` and the key is `auth` {{< /call-out >}} ```yaml kubectl apply -f - < Date: Wed, 7 Jan 2026 12:04:07 +0000 Subject: [PATCH 03/15] Apply suggestions from code review Co-authored-by: Alan Dooley --- content/ngf/traffic-security/basic-authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ngf/traffic-security/basic-authentication.md b/content/ngf/traffic-security/basic-authentication.md index 086a0d63e..385c4cac5 100644 --- a/content/ngf/traffic-security/basic-authentication.md +++ b/content/ngf/traffic-security/basic-authentication.md @@ -1,5 +1,5 @@ --- -title: Configure Basic Authentication +title: Configure basic authentication weight: 800 toc: true nd-content-type: how-to From a3cfbf8b50b1f7577e984fbd44067a6ed02dbc00 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Thu, 8 Jan 2026 10:16:56 +0000 Subject: [PATCH 04/15] Add details to check pod and application status. Add more details to Verify Basic Authentication section --- .../traffic-security/basic-authentication.md | 101 ++++++++++++------ 1 file changed, 69 insertions(+), 32 deletions(-) diff --git a/content/ngf/traffic-security/basic-authentication.md b/content/ngf/traffic-security/basic-authentication.md index 385c4cac5..3ce36f900 100644 --- a/content/ngf/traffic-security/basic-authentication.md +++ b/content/ngf/traffic-security/basic-authentication.md @@ -4,55 +4,29 @@ weight: 800 toc: true nd-content-type: how-to nd-product: FABRIC -nd-docs: DOCS-1848 --- -This page introduces how to configure basic authentication for your applications using the AuthenticationFilter CRD. +This guide introduces how to configure basic authentication for your applications using the AuthenticationFilter CRD. ## Overview Authentication is crucial for modern application security and allows you to be confident that only trusted and authorized users are accessing your applications, or API backends. Through this document, you'll learn how to protect your application endpoints with NGINX Gateway Fabric using the AuthenticationFilter CRD. -We will use our sample `tea` and `coffee` applications, where we protect the `/coffee` endpoint with Basic Authentication. +In this guide we will create two sample applications, `tea` and `coffee`, where we will enable basic authenticaiton on the `/coffee` endpoint. The `/tea` endpoint will not have any authentication. This is to help demonstrate how the application behaves both with and without authenticaiton. +The `/coffee` endpoint will use the `ExtensionRef` filter to reference and `AuthenticationFilter` CRD which is configured for Basic Authentication. ## Before you begin - Install NGINX Gateway Fabric (OSS or Plus), with [Helm]({{< ref "/ngf/install/helm.md" >}}) or [Manifest]({{< ref "/ngf/install/manifests.md" >}}) - Ensure the Gateway API CRDs are installed on your cluster. - Ensure the latest NGINX Gateway Fabric CRDs are installed on your cluster. -- Ensure `kubectl` is installed on your cluster. - -## How it works - -For Basic Authentication, NGINX uses the [ngx_http_auth_basic](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html) module. -Below is an example NGINX configuration using this module: - -```nginx -http { - upstream backend_default { - server 10.0.0.10:80; - server 10.0.0.11:80; - } - - server { - listen 80; - server_name cafe.example.com; - - location /coffee { - auth_basic "Restricted"; - auth_basic_user_file /etc/nginx/secrets/basic_auth_default_basic_auth_user; - proxy_pass http://backend_default; - } - } -} -``` - -All requests made to `/coffee` will require credentials that match those stored in `/etc/nginx/secrets/basic_auth_default_basic_auth_user` defined by the `auth_basic_user_file` directive. Any request that contains invalid or missing credentials will be rejected. ## Setup ### Deploy demo applications +To deploy both the `coffee` and `tea` applications, copy the blow yaml into your terminal: + ```yaml kubectl apply -f - < +``` + +### Deploy HTTPRoute referencing an AuthenticationFilter Deploy an HTTPRoute which references the AuthenticationFilter. This uses the `ExtensionRef` filter type. In this example, we set this filter to the `/coffee` path: @@ -268,6 +278,33 @@ Events: ## Verify Basic Authentication +Before verifying the traiffc of the application, we'll first make sure the NGINX config is correct. + +First, get the name of the NGINX Pod. The name of this pods should start with `cafe-gateway` + +```shell +kubetctl get pods | grep "cafe-gateway" -B1 +``` + +```text +NAME READY STATUS RESTARTS AGE +cafe-gateway-nginx-5d9855f458-chggl 1/1 Running 0 55s +``` + +Run this command to check the configuration of the NGINX upstreams and loactions: + +```shell +kubectl exec -it cafe-gateway-nginx-5d9855f458-chggl -- cat /etc/nginx/conf.d/http.conf | grep "/coffee" -A5 +``` + +From this output, we can see the `/coffee` route has sets the `auth_basic` directive, which enabled basic authentication in NGINX. +```nginx +location = /coffee { + auth_basic "Restricted basic-auth"; + auth_basic_user_file /etc/nginx/secrets/default_basic-auth; +} +``` + Accessing `/coffee` without credentials: ```shell From f689e7e6019be79dafc7068664160bfd58fcd5e8 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Thu, 8 Jan 2026 10:22:16 +0000 Subject: [PATCH 05/15] Fix typo in kubectl command --- content/ngf/traffic-security/basic-authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ngf/traffic-security/basic-authentication.md b/content/ngf/traffic-security/basic-authentication.md index 3ce36f900..fa1e39106 100644 --- a/content/ngf/traffic-security/basic-authentication.md +++ b/content/ngf/traffic-security/basic-authentication.md @@ -283,7 +283,7 @@ Before verifying the traiffc of the application, we'll first make sure the NGINX First, get the name of the NGINX Pod. The name of this pods should start with `cafe-gateway` ```shell -kubetctl get pods | grep "cafe-gateway" -B1 +kubectl get pods | grep "cafe-gateway" -B1 ``` ```text From 36a8dc173582458c65a569867b9f4f1c2286e396 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Thu, 8 Jan 2026 10:24:31 +0000 Subject: [PATCH 06/15] Correct typos --- content/ngf/traffic-security/basic-authentication.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/ngf/traffic-security/basic-authentication.md b/content/ngf/traffic-security/basic-authentication.md index fa1e39106..8dd98aed3 100644 --- a/content/ngf/traffic-security/basic-authentication.md +++ b/content/ngf/traffic-security/basic-authentication.md @@ -12,7 +12,7 @@ This guide introduces how to configure basic authentication for your application Authentication is crucial for modern application security and allows you to be confident that only trusted and authorized users are accessing your applications, or API backends. Through this document, you'll learn how to protect your application endpoints with NGINX Gateway Fabric using the AuthenticationFilter CRD. -In this guide we will create two sample applications, `tea` and `coffee`, where we will enable basic authenticaiton on the `/coffee` endpoint. The `/tea` endpoint will not have any authentication. This is to help demonstrate how the application behaves both with and without authenticaiton. +In this guide we will create two sample applications, `tea` and `coffee`, where we will enable basic authentication on the `/coffee` endpoint. The `/tea` endpoint will not have any authentication. This is to help demonstrate how the application behaves both with and without authentication. The `/coffee` endpoint will use the `ExtensionRef` filter to reference and `AuthenticationFilter` CRD which is configured for Basic Authentication. ## Before you begin @@ -278,9 +278,9 @@ Events: ## Verify Basic Authentication -Before verifying the traiffc of the application, we'll first make sure the NGINX config is correct. +Before verifying the traffic of the application, we'll first make sure the NGINX config is correct. -First, get the name of the NGINX Pod. The name of this pods should start with `cafe-gateway` +First, get the name of the NGINX Pod. The name of this pod should start with `cafe-gateway` ```shell kubectl get pods | grep "cafe-gateway" -B1 From 6ca5610b9fa590fd868880b968ef1650def9de94 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Thu, 8 Jan 2026 13:41:54 +0000 Subject: [PATCH 07/15] Remove optional step --- content/ngf/traffic-security/basic-authentication.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/content/ngf/traffic-security/basic-authentication.md b/content/ngf/traffic-security/basic-authentication.md index 8dd98aed3..423b6f38b 100644 --- a/content/ngf/traffic-security/basic-authentication.md +++ b/content/ngf/traffic-security/basic-authentication.md @@ -179,12 +179,6 @@ spec: EOF ``` -(Optional) The secret can also be created using kubectl command: - -```shell -kubectl create secret generic basic-auth --type='nginx.org/htpasswd' --from-literal=auth="$(htpasswd -bn user1 password1)" -``` - Verify the AuthenticationFilter is Accepted, and there are no errors: ```shell From d8e89c0d4d129d267ccdc55633fb02ada23de6c9 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Fri, 9 Jan 2026 09:14:39 +0000 Subject: [PATCH 08/15] Correct grammar --- content/ngf/traffic-security/basic-authentication.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/content/ngf/traffic-security/basic-authentication.md b/content/ngf/traffic-security/basic-authentication.md index 423b6f38b..8b11c4671 100644 --- a/content/ngf/traffic-security/basic-authentication.md +++ b/content/ngf/traffic-security/basic-authentication.md @@ -17,15 +17,13 @@ The `/coffee` endpoint will use the `ExtensionRef` filter to reference and `Auth ## Before you begin -- Install NGINX Gateway Fabric (OSS or Plus), with [Helm]({{< ref "/ngf/install/helm.md" >}}) or [Manifest]({{< ref "/ngf/install/manifests.md" >}}) -- Ensure the Gateway API CRDs are installed on your cluster. -- Ensure the latest NGINX Gateway Fabric CRDs are installed on your cluster. +- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric. ## Setup ### Deploy demo applications -To deploy both the `coffee` and `tea` applications, copy the blow yaml into your terminal: +To deploy both the `coffee` and `tea` applications, copy the following YAML into your terminal: ```yaml kubectl apply -f - < Date: Fri, 9 Jan 2026 09:43:34 +0000 Subject: [PATCH 09/15] Remove NGINX config verification --- .../traffic-security/basic-authentication.md | 29 +------------------ 1 file changed, 1 insertion(+), 28 deletions(-) diff --git a/content/ngf/traffic-security/basic-authentication.md b/content/ngf/traffic-security/basic-authentication.md index 8b11c4671..ebc1e7b78 100644 --- a/content/ngf/traffic-security/basic-authentication.md +++ b/content/ngf/traffic-security/basic-authentication.md @@ -13,7 +13,7 @@ This guide introduces how to configure basic authentication for your application Authentication is crucial for modern application security and allows you to be confident that only trusted and authorized users are accessing your applications, or API backends. Through this document, you'll learn how to protect your application endpoints with NGINX Gateway Fabric using the AuthenticationFilter CRD. In this guide we will create two sample applications, `tea` and `coffee`, where we will enable basic authentication on the `/coffee` endpoint. The `/tea` endpoint will not have any authentication. This is to help demonstrate how the application behaves both with and without authentication. -The `/coffee` endpoint will use the `ExtensionRef` filter to reference and `AuthenticationFilter` CRD which is configured for Basic Authentication. +The `/coffee` endpoint will use the `ExtensionRef` filter to reference an AuthenticationFilter CRD which is configured for Basic Authentication. ## Before you begin @@ -270,33 +270,6 @@ Events: ## Verify Basic Authentication -Before verifying the traffic of the application, we'll first make sure the NGINX config is correct. - -First, get the name of the NGINX Pod. The name of this pod should start with `cafe-gateway` - -```shell -kubectl get pods | grep "cafe-gateway" -B1 -``` - -```text -NAME READY STATUS RESTARTS AGE -cafe-gateway-nginx-5d9855f458-chggl 1/1 Running 0 55s -``` - -Run this command to check the configuration of the NGINX upstreams and loactions: - -```shell -kubectl exec -it cafe-gateway-nginx-5d9855f458-chggl -- cat /etc/nginx/conf.d/http.conf | grep "/coffee" -A5 -``` - -From this output, we can see the `/coffee` route has sets the `auth_basic` directive, which enabled basic authentication in NGINX. -```nginx -location = /coffee { - auth_basic "Restricted basic-auth"; - auth_basic_user_file /etc/nginx/secrets/default_basic-auth; -} -``` - Accessing `/coffee` without credentials: ```shell From d3e3a71b8e9552bf2ea052c1932e61ff756e9739 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Fri, 9 Jan 2026 09:45:20 +0000 Subject: [PATCH 10/15] Fix curl commands --- content/ngf/traffic-security/basic-authentication.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/ngf/traffic-security/basic-authentication.md b/content/ngf/traffic-security/basic-authentication.md index ebc1e7b78..4bf4c7b86 100644 --- a/content/ngf/traffic-security/basic-authentication.md +++ b/content/ngf/traffic-security/basic-authentication.md @@ -291,7 +291,7 @@ Response: Accessing `/coffee` with incorrect credentials: ```shell -curl -i -u user1:wrong -H "Host: cafe.example.com http://$GW_IP:$GW_PORT/coffee" +curl -i -u user1:wrong -H "Host: cafe.example.com" http://$GW_IP:$GW_PORT/coffee ``` Response: @@ -309,7 +309,7 @@ Response: Accessing `/coffee` with valid credentials: ```shell -curl -i -u user1:password1 -H "Host: cafe.example.com http://$GW_IP:$GW_PORT/coffee" +curl -i -u user1:password1 -H "Host: cafe.example.com" http://$GW_IP:$GW_PORT/coffee ``` Response: @@ -327,7 +327,7 @@ Accessing `/tea` Since tea has no AuthenticationFilter attached, responses are processed normally: ```shell -curl -i -H "Host: cafe.example.com" http://$GW_IP:$GW_PORT/coffee +curl -i -H "Host: cafe.example.com" http://$GW_IP:$GW_PORT/tea ``` Response: From b29e63f1d4a3e8963ae1d0d2275a033121584a79 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Fri, 9 Jan 2026 09:57:45 +0000 Subject: [PATCH 11/15] Update curl commands --- .../traffic-security/basic-authentication.md | 40 ++++++++++--------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/content/ngf/traffic-security/basic-authentication.md b/content/ngf/traffic-security/basic-authentication.md index 4bf4c7b86..66a867073 100644 --- a/content/ngf/traffic-security/basic-authentication.md +++ b/content/ngf/traffic-security/basic-authentication.md @@ -270,28 +270,28 @@ Events: ## Verify Basic Authentication -Accessing `/coffee` without credentials: +{{< call-out "note" >}}Your clients should be able to resolve the domain name "cafe.example.com" to the public IP of the NGINX Service. In this guide we will simulate that using curl's `--resolve` option. {{< /call-out >}} + +Accessing `/coffee` with valid credentials: ```shell -curl -i -H "Host: cafe.example.com" http://$GW_IP:$GW_PORT/coffee +curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee -u user1:password1 ``` Response: ```text - -401 Authorization Required - -

401 Authorization Required

-
nginx
- - +Server address: 10.244.0.7:8080 +Server name: coffee-654ddf664b-nhhvr +Date: 06/Jan/2026:15:20:15 +0000 +URI: /coffee +Request ID: 13a925b2514b62c45ea4a79800248d5c ``` -Accessing `/coffee` with incorrect credentials: +Accessing `/coffee` without credentials: ```shell -curl -i -u user1:wrong -H "Host: cafe.example.com" http://$GW_IP:$GW_PORT/coffee +curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee ``` Response: @@ -306,20 +306,22 @@ Response: ``` -Accessing `/coffee` with valid credentials: +Accessing `/coffee` with incorrect credentials: ```shell -curl -i -u user1:password1 -H "Host: cafe.example.com" http://$GW_IP:$GW_PORT/coffee +curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee -u user1:wrong ``` Response: ```text -Server address: 10.244.0.7:8080 -Server name: coffee-654ddf664b-nhhvr -Date: 06/Jan/2026:15:20:15 +0000 -URI: /coffee -Request ID: 13a925b2514b62c45ea4a79800248d5c + +401 Authorization Required + +

401 Authorization Required

+
nginx
+ + ``` Accessing `/tea` @@ -327,7 +329,7 @@ Accessing `/tea` Since tea has no AuthenticationFilter attached, responses are processed normally: ```shell -curl -i -H "Host: cafe.example.com" http://$GW_IP:$GW_PORT/tea +curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea ``` Response: From a5b553c8bb018b8923102537446fa016d756c894 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Mon, 12 Jan 2026 10:21:45 +0000 Subject: [PATCH 12/15] Update YAML files to reflect those in examples --- .../traffic-security/basic-authentication.md | 37 ++++++++++--------- 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/content/ngf/traffic-security/basic-authentication.md b/content/ngf/traffic-security/basic-authentication.md index 66a867073..524e04c56 100644 --- a/content/ngf/traffic-security/basic-authentication.md +++ b/content/ngf/traffic-security/basic-authentication.md @@ -161,7 +161,7 @@ metadata: name: basic-auth type: nginx.org/htpasswd data: - # Base64 of output from: htpasswd -bn user1 password1 + # Base64 of "htpasswd -bn user1 password1" auth: dXNlcjE6JGFwcjEkWEFKeU5yekgkY0Rjdy9YMVBCZTFmTjltQVBweXpxMA== --- apiVersion: gateway.nginx.org/v1alpha1 @@ -210,29 +210,30 @@ metadata: spec: parentRefs: - name: cafe-gateway + sectionName: http + hostnames: + - "cafe.example.com" rules: - matches: - # Coffee configured with Basic Auth - - path: - type: PathPrefix - value: /coffee + - path: + type: PathPrefix + value: /coffee backendRefs: - - name: coffee - port: 80 + - name: coffee + port: 80 filters: - - type: ExtensionRef - extensionRef: - group: gateway.nginx.org - kind: AuthenticationFilter - name: basic-auth + - type: ExtensionRef + extensionRef: + group: gateway.nginx.org + kind: AuthenticationFilter + name: basic-auth - matches: - # Tea with no authentication configured - - path: - type: PathPrefix - value: /tea + - path: + type: PathPrefix + value: /tea backendRefs: - - name: tea - port: 80 + - name: tea + port: 80 EOF ``` From 8998484675362fa7c758561d167cbaaccc85d813 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Mon, 12 Jan 2026 13:19:43 +0000 Subject: [PATCH 13/15] Add intro text to setup section --- content/ngf/traffic-security/basic-authentication.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/content/ngf/traffic-security/basic-authentication.md b/content/ngf/traffic-security/basic-authentication.md index 524e04c56..785f30baf 100644 --- a/content/ngf/traffic-security/basic-authentication.md +++ b/content/ngf/traffic-security/basic-authentication.md @@ -6,11 +6,12 @@ nd-content-type: how-to nd-product: FABRIC --- -This guide introduces how to configure basic authentication for your applications using the AuthenticationFilter CRD. - ## Overview +This guide introduces how to configure basic authentication for your applications using the AuthenticationFilter CRD. + Authentication is crucial for modern application security and allows you to be confident that only trusted and authorized users are accessing your applications, or API backends. + Through this document, you'll learn how to protect your application endpoints with NGINX Gateway Fabric using the AuthenticationFilter CRD. In this guide we will create two sample applications, `tea` and `coffee`, where we will enable basic authentication on the `/coffee` endpoint. The `/tea` endpoint will not have any authentication. This is to help demonstrate how the application behaves both with and without authentication. The `/coffee` endpoint will use the `ExtensionRef` filter to reference an AuthenticationFilter CRD which is configured for Basic Authentication. @@ -21,6 +22,8 @@ The `/coffee` endpoint will use the `ExtensionRef` filter to reference an Authen ## Setup +In this part of the document, we will set up several resources in your cluster to demonstrate usage of the AuthenticationFilter CRD. + ### Deploy demo applications To deploy both the `coffee` and `tea` applications, copy the following YAML into your terminal: From b943954f7fafffe3f1561f7d3b6c5d5a323ea2e4 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Mon, 12 Jan 2026 17:22:18 +0000 Subject: [PATCH 14/15] Update details on saving Gateway IP --- .../ngf/traffic-security/basic-authentication.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/content/ngf/traffic-security/basic-authentication.md b/content/ngf/traffic-security/basic-authentication.md index 785f30baf..bc012f53c 100644 --- a/content/ngf/traffic-security/basic-authentication.md +++ b/content/ngf/traffic-security/basic-authentication.md @@ -13,7 +13,7 @@ This guide introduces how to configure basic authentication for your application Authentication is crucial for modern application security and allows you to be confident that only trusted and authorized users are accessing your applications, or API backends. Through this document, you'll learn how to protect your application endpoints with NGINX Gateway Fabric using the AuthenticationFilter CRD. -In this guide we will create two sample applications, `tea` and `coffee`, where we will enable basic authentication on the `/coffee` endpoint. The `/tea` endpoint will not have any authentication. This is to help demonstrate how the application behaves both with and without authentication. +In this guide, we will create two sample applications, `tea` and `coffee`, where we will enable basic authentication on the `/coffee` endpoint. The `/tea` endpoint will not have any authentication. This is to help demonstrate how the application behaves both with and without authentication. The `/coffee` endpoint will use the `ExtensionRef` filter to reference an AuthenticationFilter CRD which is configured for Basic Authentication. ## Before you begin @@ -132,18 +132,19 @@ spec: EOF ``` -After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. Verify the gateway is created: +Confirm that the Gateway was assigned an IP address and reports a `Programmed=True` status: ```shell -kubectl get gateways.gateway.networking.k8s.io cafe-gateway +kubectl describe gateways.gateway.networking.k8s.io cafe-gateway | grep "Addresses:" -A2 ``` ```text -NAME CLASS ADDRESS PROGRAMMED AGE -cafe-gateway nginx 10.96.187.113 True 10m +Addresses: + Type: IPAddress + Value: 10.96.20.187 ``` -Save the public IP address and port of the NGINX Service into shell variables: +Save the public IP address and port(s) of the Gateway into shell variables: ```text GW_IP=XXX.YYY.ZZZ.III From d5c6addf0494a5899d58946e37ca566cd081c0f6 Mon Sep 17 00:00:00 2001 From: Shaun Date: Tue, 13 Jan 2026 15:45:10 +0000 Subject: [PATCH 15/15] Apply suggestions from code review Co-authored-by: Alan Dooley --- .../traffic-security/basic-authentication.md | 41 +++++++++++-------- 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/content/ngf/traffic-security/basic-authentication.md b/content/ngf/traffic-security/basic-authentication.md index bc012f53c..dbb3af97b 100644 --- a/content/ngf/traffic-security/basic-authentication.md +++ b/content/ngf/traffic-security/basic-authentication.md @@ -6,15 +6,12 @@ nd-content-type: how-to nd-product: FABRIC --- -## Overview -This guide introduces how to configure basic authentication for your applications using the AuthenticationFilter CRD. +This page describes how to configure basic authentication in NGINX Gateway Fabric using the AuthenticationFilter custom resource definition (CRD). -Authentication is crucial for modern application security and allows you to be confident that only trusted and authorized users are accessing your applications, or API backends. +Authentication can be used to secure applications and APIs, ensuring only trusted and authorized users have access. -Through this document, you'll learn how to protect your application endpoints with NGINX Gateway Fabric using the AuthenticationFilter CRD. -In this guide, we will create two sample applications, `tea` and `coffee`, where we will enable basic authentication on the `/coffee` endpoint. The `/tea` endpoint will not have any authentication. This is to help demonstrate how the application behaves both with and without authentication. -The `/coffee` endpoint will use the `ExtensionRef` filter to reference an AuthenticationFilter CRD which is configured for Basic Authentication. +By following these instructions, you will create two sample application endpoints. One will include basic authentication and the other will not, allowing you to review how each behaves. ## Before you begin @@ -24,9 +21,9 @@ The `/coffee` endpoint will use the `ExtensionRef` filter to reference an Authen In this part of the document, we will set up several resources in your cluster to demonstrate usage of the AuthenticationFilter CRD. -### Deploy demo applications +## Deploy sample applications -To deploy both the `coffee` and `tea` applications, copy the following YAML into your terminal: +To deploy the `coffee` and `tea` applications, run the following YAML with `kubectl apply`: ```yaml kubectl apply -f - < ``` -### Create a Basic Authentication secret and AuthenticationFilter +## Create a user credentials secret and AuthenticationFilter -Deploy secret with user credentials, and the AuthenticationFilter. +Deploy a secret with user credentials, and the AuthenticationFilter by running the following YAML with `kubectl apply`: {{< call-out "important" >}} Ensure the secret deployed is of type `nginx.org/htpasswd` and the key is `auth` {{< /call-out >}} @@ -181,7 +178,7 @@ spec: EOF ``` -Verify the AuthenticationFilter is Accepted, and there are no errors: +Verify the AuthenticationFilter is _Accepted_ and has no errors using `kubectl describe`: ```shell kubectl describe authenticationfilters.gateway.nginx.org | grep "Status:" -A10 @@ -201,9 +198,11 @@ Status: Events: ``` -### Deploy HTTPRoute referencing an AuthenticationFilter +## Deploy a HTTPRoute referencing the AuthenticationFilter -Deploy an HTTPRoute which references the AuthenticationFilter. This uses the `ExtensionRef` filter type. In this example, we set this filter to the `/coffee` path: +Deploy a HTTPRoute resource which references the AuthenticationFilter using the `ExtensionRef` filter type. + +In this example, the filter is applied to the `/coffee` path: run the following YAML with `kubectl apply` ```yaml kubectl apply -f - < ## Verify Basic Authentication -{{< call-out "note" >}}Your clients should be able to resolve the domain name "cafe.example.com" to the public IP of the NGINX Service. In this guide we will simulate that using curl's `--resolve` option. {{< /call-out >}} +{{< call-out "note" >}} + +Your clients should be able to resolve the domain name "cafe.example.com" to the public IP of the NGINX Service. + +This guide simulates it using curl's `--resolve` option. + +{{< /call-out >}} Accessing `/coffee` with valid credentials: