Add document to configure Basic Auth #1634

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Open

shaun-nx wants to merge 12 commits into ngf-release-2.4 from ngf/authentication-filter-basic-auth

+355 −0

Contributor

shaun-nx commented Jan 6, 2026

Proposed changes

This change adds a new document to the NGF traffic security section, which details on to configure Basic Authentication for NGF using the AuthenticationFilter CR

Closes nginx/nginx-gateway-fabric#4345

Checklist

Before sharing this pull request, I completed the following checklist:

I read the Contributing guidelines
My branch adheres to the Git conventions
My content changes adhere to the F5 NGINX Documentation style guide
If my changes involve potentially sensitive information¹, I have assessed the possible impact
I have waited to ensure my changes pass tests, and addressed any discovered issues

Potentially sensitive information includes personally identify information (PII), authentication credentials, and live URLs. Refer to the style guide for guidance about placeholder content. ↩

shaun-nx added 2 commits

January 6, 2026 15:53


          Add document to configure Basic Auth

4bb46cc


          Fix references and add important note for secret type and key

7c66f30

shaun-nx requested a review from a team as a code owner

January 6, 2026 16:06

github-actions bot added documentation product/ngf labels

github-actions bot commented Jan 6, 2026

✅ Deploy Preview will be available once build job completes!

Name	Link
😎 Deploy Preview	https://frontdoor-test-docs.nginx.com/previews/docs/1634/

shaun-nx changed the title ~~auth~~ Add document to configure Basic Auth

ADubhlaoich reviewed

View reviewed changes

Member

ADubhlaoich left a comment

Initial bit of metadata feedback - more feedback coming.

There's a lot of stuff to be changed.

content/ngf/traffic-security/basic-authentication.md Outdated

+              toc: true
+              nd-content-type: how-to
+              nd-product: FABRIC
+              nd-docs: DOCS-1848

Member

ADubhlaoich Jan 7, 2026

Suggested change

nd-docs: DOCS-1848

If this was not generated by docs automation, it should not be included.

Duplicate IDs cause issues.

content/ngf/traffic-security/basic-authentication.md Outdated Show resolved Hide resolved

content/ngf/traffic-security/basic-authentication.md Show resolved Hide resolved

shaun-nx and others added 2 commits

January 7, 2026 12:04


          Apply suggestions from code review

Co-authored-by: Alan Dooley <[email protected]>


          Merge branch 'ngf-release-2.4' into ngf/authentication-filter-basic-auth

39d1062

shaun-nx requested a review from a team

January 7, 2026 17:09

salonichf5 reviewed

View reviewed changes

Contributor

salonichf5 left a comment

looks good to me overall, just a couple of comments

content/ngf/traffic-security/basic-authentication.md Outdated Show resolved Hide resolved

content/ngf/traffic-security/basic-authentication.md Outdated Show resolved Hide resolved

content/ngf/traffic-security/basic-authentication.md Outdated Show resolved Hide resolved

content/ngf/traffic-security/basic-authentication.md Outdated

Comment on lines 25 to 51

+              ## 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.

Contributor

salonichf5 Jan 7, 2026

this could be part where authentication filter is added and we check the status and show the config.

Maybe we could talk about the nginx directives being used here like we do for other guides.

Contributor Author

shaun-nx Jan 8, 2026

That's a good idea. I'll see if I can change that.

content/ngf/traffic-security/basic-authentication.md Show resolved Hide resolved

content/ngf/traffic-security/basic-authentication.md Show resolved Hide resolved

content/ngf/traffic-security/basic-authentication.md Show resolved Hide resolved


          Add details to check pod and application status. Add more details to …

a3cfbf8

…Verify Basic Authentication section

shaun-nx requested a review from salonichf5

January 8, 2026 10:17

shaun-nx added 2 commits

January 8, 2026 10:22


          Fix typo in kubectl command

f689e7e


          Correct typos

36a8dc1

Contributor Author

shaun-nx commented Jan 8, 2026

Initial bit of metadata feedback - more feedback coming.

There's a lot of stuff to be changed.

Thanks Alan! Appreciate you taking the time to look over it all 😄


          Remove optional step

6ca5610

sjberman reviewed

View reviewed changes

content/ngf/traffic-security/basic-authentication.md Outdated

Comment on lines 21 to 22

		- Ensure the Gateway API CRDs are installed on your cluster.
		- Ensure the latest NGINX Gateway Fabric CRDs are installed on your cluster.

Contributor

sjberman Jan 8, 2026

This is kind of vague. Do we say this in other docs?

Contributor

salonichf5 Jan 8, 2026

I think you can just use this instead of these lines.

## Before you begin

- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric.

Contributor Author

shaun-nx Jan 9, 2026

That's a good catch, thanks guys. The steps to install NGF cover the CRD installs, so these can be removed.

content/ngf/traffic-security/basic-authentication.md Outdated


		### Deploy demo applications

		To deploy both the `coffee` and `tea` applications, copy the blow yaml into your terminal:

Contributor

sjberman Jan 8, 2026

Suggested change

      
            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:

content/ngf/traffic-security/basic-authentication.md Outdated


		### Create a Gateway

		To create your gateway resource, and provision the NGINX pod, copy the below yaml into your terminal:

Contributor

sjberman Jan 8, 2026

Suggested change

      
            To create your gateway resource, and provision the NGINX pod, copy the below yaml into your terminal:
          
            To create your gateway resource, and provision the NGINX pod, copy the following yaml into your terminal:

content/ngf/traffic-security/basic-authentication.md Outdated


		## Verify Basic Authentication

		Before verifying the traffic of the application, we'll first make sure the NGINX config is correct.

Contributor

sjberman Jan 8, 2026

Do we do this in other docs as well? I wonder if we really need users to check the nginx conf. Our main purpose is to essentially hide this so users don't need to care.

Contributor

salonichf5 Jan 8, 2026

We do check NGINX configuration in other guides and feels like a good debugging practice

Contributor

sjberman Jan 8, 2026

In that case, I'd suggest using easier commands for users to copy/paste to get the config, since they won't have the specific pod name. You can use the deployment name to do the same, and that would be consistent with what a user has.

salonichf5 reviewed

View reviewed changes

content/ngf/traffic-security/basic-authentication.md Outdated


		### Create a Gateway

		To create your gateway resource, and provision the NGINX pod, copy the below yaml into your terminal:

Contributor

salonichf5 Jan 8, 2026

Suggested change

      
            To create your gateway resource, and provision the NGINX pod, copy the below yaml into your terminal:
          
            To create your gateway resource, and provision the NGINX pod, copy the below YAML into your terminal:

salonichf5 reviewed

View reviewed changes

content/ngf/traffic-security/basic-authentication.md

+              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.

Contributor

salonichf5 Jan 8, 2026

Suggested change

      
            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.

Contributor

salonichf5 Jan 9, 2026

nit:

salonichf5 reviewed

View reviewed changes

content/ngf/traffic-security/basic-authentication.md Outdated

+              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.

Contributor

salonichf5 Jan 8, 2026

Suggested change

      
            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.

salonichf5 reviewed

View reviewed changes

content/ngf/traffic-security/basic-authentication.md Outdated


		### Create a Gateway

		To create your gateway resource, and provision the NGINX pod, copy the below yaml into your terminal:

Contributor

salonichf5 Jan 8, 2026

lets capitalize k8s resource names - Pods, Service

salonichf5 reviewed

View reviewed changes

content/ngf/traffic-security/basic-authentication.md Outdated

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

Contributor

salonichf5 Jan 8, 2026

Suggested change

      
            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

salonichf5 reviewed

View reviewed changes

content/ngf/traffic-security/basic-authentication.md Outdated

+              Accessing `/coffee` with valid credentials:
+              ```shell
+              curl -i -u user1:password1 -H "Host: cafe.example.com http://$GW_IP:$GW_PORT/coffee"

Contributor

salonichf5 Jan 8, 2026

Suggested change

      
            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

salonichf5 reviewed

View reviewed changes

content/ngf/traffic-security/basic-authentication.md Outdated

+              Since tea has no AuthenticationFilter attached, responses are processed normally:
+              ```shell
+              curl -i -H "Host: cafe.example.com" http://$GW_IP:$GW_PORT/coffee

Contributor

salonichf5 Jan 8, 2026

the curl is for coffee

Suggested change

      
            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

salonichf5 reviewed

View reviewed changes

Contributor

salonichf5 left a comment

To make this easier for users, let’s ensure every curl command is copy/paste ready and works exactly as written. I recommended some edits but it would be better if you cross check again on your end.

shaun-nx added 3 commits

January 9, 2026 09:14


          Correct grammar

d8e89c0


          Remove NGINX config verification

741a6a9


          Fix curl commands

d3e3a71


          Update curl commands

b29e63f

shaun-nx requested review from salonichf5 and sjberman

January 9, 2026 11:10

salonichf5 approved these changes

View reviewed changes

Contributor

salonichf5 left a comment

looks good to me

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation product/ngf