Add support for Basic Auth through AuthenticationFilter #4436

shaun-nx · 2025-12-10T14:36:08Z

Proposed changes

This change adds support for Basic Authentication using the new AuthenticationFilter CRD.

For both HTTPRoute and GRPCRoute resource, requests made to route rules that reference an AuthenticationFilter using type: Basic will require credentials sent as part of the request.

Example HTTP requests:

# With credentials provided
curl --resolve cafe.example.com:8080:127.0.0.1 http://cafe.example.com:8080/coffee1 -u user1:password1
Server address: 10.244.0.18:8080
Server name: coffee-5b9c74f9d9-bf6bl
Date: 10/Dec/2025:14:32:31 +0000
URI: /coffee1
Request ID: 1dab2e14a2893e71f9a5a4992b477adc

# Without credentials provided
curl --resolve cafe.example.com:8080:127.0.0.1 http://cafe.example.com:8080/coffee1
<html>
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
<hr><center>nginx</center>
</body>
</html>

Example GRPC requests:

# With credentials provided
grpcurl -plaintext -proto grpc.proto -authority bar.com  -H "Authorization: Basic dXNlcjE6cGFzc3dvcmQx" -d '{"name": "exact"}' ${GW_IP}:${GW_PORT} helloworld.Greeter/SayHello
{
  "message": "Hello exact"
}

# Without credential provided
grpcurl -plaintext -proto grpc.proto -authority bar.com -d '{"name": "exact"}' ${GW_IP}:${GW_PORT} helloworld.Greeter/SayHello
ERROR:
  Code: Unknown
  Message: unexpected HTTP status code received from server: 204 (No Content)

Closes #4312

Checklist

Before creating a PR, run through this checklist and mark each as complete.

I have read the CONTRIBUTING doc
I have added tests that prove my fix is effective or that my feature works
I have checked that all unit tests pass after adding my changes
I have updated necessary documentation
I have rebased my branch onto main
I will ensure my PR is targeting the main branch and pulling from my branch from my own fork

Release notes

If this PR introduces a change that affects users and needs to be mentioned in the release notes,
please add a brief note that summarizes the change.

Support Basic Auth through AuthenticationFilter

…auth

internal/controller/state/graph/graph.go

Copilot

Pull request overview

This PR implements support for Basic Authentication through a new AuthenticationFilter CRD. Routes (both HTTPRoute and GRPCRoute) can now reference an AuthenticationFilter to require Basic Auth credentials on requests. The implementation includes validation of the filter configuration, secret references, and NGINX configuration generation to enforce authentication at the location level.

Key Changes

Introduces the AuthenticationFilter CRD for configuring Basic Auth via secret references
Extends HTTPRoute and GRPCRoute processing to support the new filter type
Adds NGINX configuration generation for auth_basic directives and user file management

Reviewed changes

Copilot reviewed 30 out of 30 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
apis/v1alpha1/authenticationfilter_types.go	Adds constant for Basic Auth secret key
apis/v1alpha1/register.go	Registers AuthenticationFilter types with the scheme
internal/framework/kinds/kinds.go	Adds AuthenticationFilter kind constant
internal/controller/state/graph/authentication_filter.go	Implements validation and processing logic for AuthenticationFilters
internal/controller/state/graph/secret.go	Updates secret validation to accept Opaque secrets with "auth" key
internal/controller/state/graph/extension_ref_filter.go	Adds AuthenticationFilter support to extension ref validation
internal/controller/state/graph/common_filter.go	Updates filter resolution to use map-based resolver lookup
internal/controller/state/graph/httproute.go	Threads AuthenticationFilter support through HTTP route processing
internal/controller/state/graph/grpcroute.go	Threads AuthenticationFilter support through GRPC route processing
internal/controller/state/graph/route_common.go	Updates route building to accept AuthenticationFilters
internal/controller/state/graph/graph.go	Adds AuthenticationFilters to cluster state and graph
internal/controller/state/dataplane/types.go	Defines AuthenticationFilter and BasicAuth dataplane types
internal/controller/state/dataplane/convert.go	Implements conversion from graph to dataplane representation
internal/controller/state/dataplane/configuration.go	Threads authentication filters through configuration building
internal/controller/state/conditions/conditions.go	Adds condition constructors for AuthenticationFilter status
internal/controller/state/status/status_setters.go	Implements status setter for AuthenticationFilter
internal/controller/state/status/prepare_requests.go	Prepares status update requests for AuthenticationFilters
internal/controller/state/change_processor.go	Adds AuthenticationFilter to change processing
internal/controller/handler.go	Updates status handling to include AuthenticationFilters
internal/controller/manager.go	Registers AuthenticationFilter controller and initial sync
internal/controller/nginx/config/servers.go	Implements NGINX configuration for Basic Auth
internal/controller/nginx/config/servers_template.go	Adds template directives for auth_basic
internal/controller/nginx/config/http/config.go	Adds AuthBasic configuration types
internal/controller/nginx/config/generator.go	Generates auth user files for Basic Auth
charts/nginx-gateway-fabric/templates/clusterrole.yaml	Adds RBAC permissions for AuthenticationFilter resources
Test files	Updates tests to pass nil for new AuthenticationFilter parameters

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

internal/controller/state/graph/secret.go

internal/controller/state/graph/common_filter.go

internal/controller/state/change_processor.go

internal/controller/nginx/config/servers.go

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

sjberman · 2025-12-10T21:44:58Z

apis/v1alpha1/authenticationfilter_types.go

 )

+const (
+	AuthKeyBasic = "auth" // Key in the Secret data for Basic Auth credentials.


Let's add a properly formatted comment above the field. And why "Basic" in the name?

Sounds good. I chose the word AuthKeyBasic so we can distinguish between the key for JWT when we introduce that. So that new key might be set to `AuthKeyJWT = "jwks.json"

I though we decided we were just going to use auth as the generic field name for both Basic and JWT?

The JWT is going to be base64 encoded anyway, and technically not a JSON format in the Secret itself.

I don't think that's something we agreed on. The proposal has the key for JWT auth to be jwks.json.
As I think about it, since now we're defining specific secret types for both Basic and JWT, we could keep auth as the same key for both.

internal/controller/nginx/config/http/config.go

internal/controller/nginx/config/generator.go

internal/controller/nginx/config/servers.go

internal/controller/nginx/config/http/config.go

internal/controller/state/graph/authentication_filter.go

internal/controller/state/graph/secret.go

internal/controller/state/graph/authentication_filter.go

sjberman

Overall looks good! Just a few new comments, and a couple of old ones that haven't been addressed yet.

internal/controller/nginx/config/http/config.go

sjberman · 2025-12-17T18:48:10Z

internal/controller/state/dataplane/configuration.go

+func generateAuthBasicUserFileID(id string) AuthBasicUserFileID {
+	return AuthBasicUserFileID(id)
+}


Why is this wrapper needed? Maybe it would make more sense to pass the namespace/name here so you don't have to format it elsewhere.

If I remember, I did this to follow the same pattern that we had for the CertBundle. It's likely that there's more "wrapping" happening here than is needed. I'll see if I can make this more simple.

sjberman · 2025-12-17T18:54:05Z

internal/controller/nginx/config/servers.go

+			userFilePathAndName := fmt.Sprintf(
+				"%s/%s_%s",
+				secretsFolder,
+				authenticationFilter.Basic.SecretNamespace,
+				authenticationFilter.Basic.SecretName,


You're building this path/ID in a few different places, in a few different ways. We should use shared logic so they don't have the risk of drifting.

Glad you pointed this out. I was feeling the same way about it, but I couldn't think of a clean way to do this. I'll re-think this and see if we can make this more generic.

internal/controller/state/graph/authentication_filter_test.go

sjberman · 2025-12-17T20:19:59Z

internal/controller/state/graph/common_filter_test.go

+				},
+			},
+			expectErrCount: 0,
+			name:           "valid AuthenticationFilter HTTP extension ref filter",


Can we add a test case for multiple auth filters being invalid?

yeah a mixed combination of invalid & valid would be nice to have

Can we add a test case for multiple auth filters being invalid?

I have a test case for that covered in http/grpc test files. I'll see if I can do the same in here. Thanks for catching that!

These tests seem to be structured to validate a filter independently, and not the interaction with other filters.
There are four tests cases in httproute_test.go that cover these mixed scenarios: https://github.com/nginx/nginx-gateway-fabric/pull/4436/changes#diff-dcec4792f1cac5c101cfdfe57fd3dc12325b6ae336ab7d7b8d8e4385627832c5R1207-R1415

These are also covered in grpcroute_test.go.

These cover:

Invalid + Unresolved

Valid + Invalid

Valid + Unresolved

Valid + Valid

This seems like the more appropriate place to cover these since we can also verify the error messages we get back.

sjberman · 2025-12-17T20:24:17Z

internal/controller/state/graph/secret.go

+				Source: secret,
+			},
+			err: validationErr,
+		}


I think we can reduce a bit of duplication in this function.

The common pieces could all be done at the end. It looks like the certBundle field is the only unique part, so that could be the one difference.

Sounds good. I'll see what I can do.

You pointed out correctly here that it doesn't make sense for the Basic Auth case.
The way this code was previously looks to be the only way to accomplish this.

It would just mean the value for CertBundle would be nil for any situation that isn't the TLS case.

salonichf5

Looks to be in good shape. With a couple of minor nits addressed and Saylor’s comments addressed, it should be ready to go.

internal/controller/state/graph/authentication_filter.go

salonichf5 · 2025-12-18T00:17:28Z

internal/controller/state/graph/common_filter_test.go

+				},
+			},
+			expectErrCount: 0,
+			name:           "valid AuthenticationFilter HTTP extension ref filter",


yeah a mixed combination of invalid & valid would be nice to have

salonichf5 · 2025-12-18T01:25:14Z

internal/controller/state/graph/httproute_test.go

 			name: "rule with valid snippets filter extension ref filter",
 		},
+		{
+			validator: validatorInvalidFieldsInRule,


should we be using &validationfakes.FakeHTTPFieldsValidator{} here since it is a valid case?

Good catch, I didn't notice this.
I templated this test from the "rule with valid snippets filter extension ref filter" test, which is also using validatorInvalidFieldsInRule. I wonder if this was just a mistake. It also makes me think how that works...

I'll look into this more.

internal/controller/state/dataplane/configuration.go

apis/v1alpha1/register.go

internal/controller/nginx/config/http/config.go

tataruty · 2025-12-18T11:01:04Z

internal/controller/nginx/config/generator.go

 	return filepath.Join(secretsFolder, string(id)+".crt")
 }
+
+func generateAuthBasicUserFile(id dataplane.AuthBasicUserFileID, data []byte) agent.File {


same, why user?

tataruty · 2025-12-18T11:03:20Z

internal/controller/nginx/config/servers_template.go


+        {{- if $l.AuthBasic }}
+        auth_basic "{{ $l.AuthBasic.Realm }}";
+        auth_basic_user_file {{ $l.AuthBasic.UserFile }};


why user?

I call used it UserFile to keep it consistent with the name of the directive,
So the struct is AuthBasic.UserFile and the directive is auth_basic_user_file

yes, but my question started from UserFile, since it is not created by user. Same we need to call UserProxySettings then?

This has been changed now. So should just be AuthBasic.File

tataruty · 2025-12-18T11:05:04Z

internal/controller/state/conditions/conditions.go

+		Message: "The AuthenticationFilter is accepted",
+	}
+}
+


Can be partially Invalid/Accepted in any case?

I don't think there is a scenario where the filter itself can be partially invalid.

internal/controller/state/dataplane/configuration_test.go

internal/controller/state/dataplane/convert.go

bjee19

nice job! a couple of outstanding comments from others, but this looks pretty good to me, ill approve after other comments are resolved

internal/framework/kinds/kinds.go

internal/controller/status/prepare_requests_test.go

internal/controller/status/status_setters_test.go

internal/controller/state/graph/grpcroute_test.go

tataruty · 2025-12-19T10:30:35Z

internal/controller/state/conditions/conditions.go

 		Message: "The SnippetsFilter is accepted",
 	}
 }



Any chance Programmed condition is also related to AuthFilter?

That's a really good point actually.
From what I read up, we set the Programmed status when "the resource or part thereof has been Accepted and programmed into the underlying dataplane. Users should expect the configuration to be ready for traffic to flow at some point in the near future".

We set this status for the Gateway resource when the NGINX configuration is loaded and ready to accept traffic. So it makes sense in that scenario.

If we set Programmed on the AuthenticationFilter, we would be telling the user that "Yes, this filter has programmed the underlying dataplane".

I'd love to know what everyone thinks about this. @salonichf5 @sjberman @bjee19

Are we sure that Programmed isn't just meant for policies? This is technically a filter, not a policy, so the status conditions are potentially treated differently.

Yea I'm pretty sure we'll only set Programmed for policies.

Which are described here https://gateway-api.sigs.k8s.io/geps/gep-713/#status-conditions.

And is described there as

// PolicyConditionProgrammed indicated whether the policy's spec is guaranteed by the controller to // be fully programmed for enforcement.

If we were to add in the programmed condition, I think that would affect all other filters, since they affect the underlying dataplane, and that might be a precedence we don't want to start.

Filters may not be defined yet in this aspect.

Copilot

Pull request overview

Copilot reviewed 50 out of 50 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

sjberman · 2025-12-19T15:58:33Z

tests/Makefile

 		--image=$(CONFORMANCE_PREFIX):$(CONFORMANCE_TAG) --image-pull-policy=Never \
 		--overrides='{ "spec": { "serviceAccountName": "conformance" }	}' \
-		--restart=Never -- sh -c "go test -v . -tags conformance,experimental -args --gateway-class=$(GATEWAY_CLASS) \
+		--restart=Never -- sh -c "go test -v -timeout 45m . -tags conformance,experimental -args --gateway-class=$(GATEWAY_CLASS) \


Why was this needed? I'd like to understand the culprit if we can. These tests should never take this long, they're usually done in just a couple of minutes.

I more added this to see if it had an affect. I hadn't planned on keeping it there. It was strange though the timeout issue happened more often for me locally than it did in the pipeline.

Add support for Basic Auth through AuthenticationFilter

bb4607a

github-project-automation bot added this to NGINX Gateway Fabric Dec 10, 2025

nginx-bot bot added the release-notes label Dec 10, 2025

github-project-automation bot moved this to 🆕 New in NGINX Gateway Fabric Dec 10, 2025

github-actions bot added enhancement New feature or request helm-chart Relates to helm chart labels Dec 10, 2025

Merge branch 'feat/authentication-filter-basic-auth' into feat/basic-…

23ab285

…auth

shaun-nx commented Dec 10, 2025

View reviewed changes

internal/controller/state/graph/graph.go Show resolved Hide resolved

shaun-nx requested a review from Copilot December 10, 2025 15:44

Copilot AI reviewed Dec 10, 2025

View reviewed changes

shaun-nx and others added 3 commits December 10, 2025 15:51

make generate-all

0a48fff

Set dest from location.AuthBasic.Data.FileName

0e5f51e

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update dest value

5a4903c

sjberman reviewed Dec 10, 2025

View reviewed changes

shaun-nx added 14 commits December 11, 2025 09:26

Remove duplicate call to secret resolved

e35da99

Remove duplicate call to secret resolver

1b7dd25

Re-add removed comment

edb8348

Process custom secret type

816382d

Update basicAuthUserFile const

3fa25c0

Ensure secrets are resolved

d2f170b

Resolve nil pointer error

a681ba5

Remove redundant error handling

5effdbc

Do not resolve Opaque secrets

b8f26a6

Add secret namespace to file path

50dfd77

Update status variable name

5b6ccd1

Update logic for generating auth basic user file

12d6e54

Update AuthBasic struct. Remove debug log lines

a341ea4

Resolve lint errors

2e57114

github-actions bot added the dependencies Pull requests that update a dependency file label Dec 15, 2025

Add additional comments

2a43510

shaun-nx added 5 commits December 17, 2025 13:59

Unit tests for common_filter, extensions_ref_filter and httproute

523d5a5

Update comments in test

4044987

Unit tests for grpcroute

05e7ee8

Enesure resolved secrets map is updated for each case. Update unit tests

04b3983

Unit tests for prepare_requests and status_setters

d4b7f59

shaun-nx marked this pull request as ready for review December 17, 2025 16:02

shaun-nx requested a review from a team as a code owner December 17, 2025 16:02

sjberman reviewed Dec 17, 2025

View reviewed changes

salonichf5 reviewed Dec 18, 2025

View reviewed changes

tataruty reviewed Dec 18, 2025

View reviewed changes

shaun-nx added 7 commits December 18, 2025 11:46

Add function to genereate file name for auth basic file

f50ea25

Remove duplicate function in tests

3647812

Set lenght to maps. Remove duplicate entries

f83e853

Restore comments for HTTPFilters struct

3f7c232

Update comment for AuthenticationFilter in HTTPFilters struct

ee63844

Update occurrances of UserFile and UserData to File and FileData

1912215

Deduplicate refernces to resolves secrets map

feb0469

bjee19 reviewed Dec 18, 2025

View reviewed changes

shaun-nx added 5 commits December 19, 2025 07:46

Add t.Parallel() to test run

1e2e7c0

Add t.Parallel() and move AuthenticationFilter into correct const block

c71fc54

Fix lint errors

a2bc05f

Re-add comments removed by linter

9ae699a

Preserve field order (govet) in HTTPFilters struct

9dbcc7c

tataruty reviewed Dec 19, 2025

View reviewed changes

Add longer timeout to conformance test run

50125ba

github-actions bot added the tests Pull requests that update tests label Dec 19, 2025

shaun-nx requested a review from Copilot December 19, 2025 11:16

Copilot AI reviewed Dec 19, 2025

View reviewed changes

sjberman reviewed Dec 19, 2025

View reviewed changes

Fix field order for HTTPFilters

4636466

Add support for Basic Auth through AuthenticationFilter #4436

Are you sure you want to change the base?

Add support for Basic Auth through AuthenticationFilter #4436

Uh oh!

Conversation

shaun-nx commented Dec 10, 2025

Proposed changes

Checklist

Release notes

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sjberman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shaun-nx Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

salonichf5 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

shaun-nx Dec 18, 2025 •

edited

Loading

shaun-nx Dec 19, 2025 •

edited

Loading

bjee19 Dec 19, 2025 •

edited

Loading