Enhancement Proposal: Authentication Filter #4235

shaun-nx · 2025-11-06T18:19:55Z

Proposed changes

Status set to Implementable after merging #4136

This document proposes a solution for enabling Authentication use cases through NGINX Gateway Fabric.

Closes #4052

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.

NONE

codecov · 2025-11-06T18:22:38Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.06%. Comparing base (668d4fb) to head (a0c8c04).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4235      +/-   ##
==========================================
- Coverage   86.08%   86.06%   -0.03%     
==========================================
  Files         132      132              
  Lines       14342    14342              
  Branches       35       35              
==========================================
- Hits        12347    12344       -3     
- Misses       1791     1793       +2     
- Partials      204      205       +1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

docs/proposals/authentication-filter.md

salonichf5 · 2025-11-06T20:15:09Z

docs/proposals/authentication-filter.md

+type JWTTokenSource struct {
+	// Read token from Authorization header. Default: true.
+	//
+	// +optional


set defaults using kubebuilder: default

If this is an optional field though, it shouldn't have a default.

Is this a blanket statement? In the case of JWTTokenType, that is defined as an optional field. (i.e. it's optional for the user to set it) but we default to assigning the value to signed (e.g. auth_jwt_type signed;)

In the NGINX documentation, this directive defaults to signed when the directive is not specified.
So in my mind, making is optional for the user to specify this field, and providing a default value for it makes sense to me.

What are your thoughts?

That's fine

Thanks @sjberman
I did a review of the current optional fields with defaults. From what I can see, they should stay with those defaults. Curious what you think though.
These are:

// +optional // +kubebuilder:default="Restricted" Realm *string `json:"realm,omitempty"` // +optional // +kubebuilder:default=60s Leeway *v1alpha1.Duration `json:"leeway,omitempty"` // +optional // +kubebuilder:default=signed Type *JWTTokenType `json:"type,omitempty"` // +optional // +kubebuilder:default=access_token TokenName string `json:"tokenName,omitempty"` // +optional // +kubebuilder:default=401 StatusCode *int32 `json:"statusCode,omitempty"` // +optional // +kubebuilder:default=Basic Scheme *AuthScheme `json:"scheme,omitempty"` // +optional // +kubebuilder:default=Unauthorized BodyPolicy *AuthFailureBodyPolicy `json:"bodyPolicy,omitempty"`

docs/proposals/authentication-filter.md

ciarams87

These are mostly focussed on typos I spotted while doing a first pass, I haven't fully absorbed the content yet

docs/proposals/authentication-filter.md

ciarams87 · 2025-11-07T14:41:54Z

docs/proposals/authentication-filter.md

+This allows users to reference an external authentication services, such as Keycloak, to handle the authentication requests.
+While this API is available in the experimental channel, it is subject to change.
+
+Our decision to go forward with our own `AuthenticationFilter` was to ensure we could quckly provide authenticaiton to our users while allowing us to closley monitor progress of the ExternalAuthFilter.


Suggested change

Our decision to go forward with our own `AuthenticationFilter` was to ensure we could quckly provide authenticaiton to our users while allowing us to closley monitor progress of the ExternalAuthFilter.

Our decision to go forward with our own `AuthenticationFilter` was to ensure we could quickly provide authentication to our users while allowing us to closely monitor progress of the ExternalAuthFilter.

To be clear, this proposed AuthenticationFilter is to supply different auth methods than provided in the ExternalAuth filter, and is technically unrelated.

@sjberman that's not entirely true. If we went forward with ExternalAuth filter, we could build out an external auth service that uses NGINX. It wouldn't prevent us from supplying those auth methods.

But that is unrelated to this AuthenticationFilter. This filter is to configure our NGINX data plane to perform native auth, without the need for an external entity. The ExternalAuthFilter is for just using an external entity for auth, whatever that entity may be (it wouldn't be our direct NGINX data plane, but it could be an external NGINX instance).

These are two different solutions for implementing auth for the user, and are not technically related to each other. I only mention this because this sentence in the doc implies that this Filter is being implemented as a workaround to the ExternalAuth filter, but it's really not, it's a different auth solution. Just being pedantic.

@sjberman do you think this statement needs to be changed in any way?

This is fine

docs/proposals/authentication-filter.md

sjberman

I'll do a more thorough review once I'm back online full time.

docs/proposals/authentication-filter.md

sjberman · 2025-11-07T15:26:34Z

docs/proposals/authentication-filter.md

+This allows users to reference an external authentication services, such as Keycloak, to handle the authentication requests.
+While this API is available in the experimental channel, it is subject to change.
+
+Our decision to go forward with our own `AuthenticationFilter` was to ensure we could quckly provide authenticaiton to our users while allowing us to closley monitor progress of the ExternalAuthFilter.


To be clear, this proposed AuthenticationFilter is to supply different auth methods than provided in the ExternalAuth filter, and is technically unrelated.

docs/proposals/authentication-filter.md

sjberman · 2025-11-19T18:44:45Z

docs/proposals/authentication-filter.md

+  // Configures "realm="<realm_value>" in WWW-Authenticate header in error page location.
+  //
+  // +optional
+  // +kubebuilder:default="Restricted"


Realm has a default here but not in Basic Auth. Is that ok? And does it need to be capitalized?

Good catch. It doesn't need to be capitalized. This is mostly just for error logging from auth requests.

Should we lowercase it then?

We certainly can. The example in the nginx basic auth and jwt auth docs show the realm set as "closed site" so there really isn't any standard default for this.

This mainly is used for things like credential caching. It uses scheme + origin + realm as the cache key.

As I think about it more, it might be safer to leave this as an empty string by default so users don't get confused by behaviour.

What do you think?

sjberman · 2025-11-19T18:46:09Z

docs/proposals/authentication-filter.md

+  // Example: "auth_jwt_leeway 60s".
+  //
+  // +optional
+  // +kubebuilder:default=60s


is this the nginx default? If so, I don't think it's needed in here. Same for any other fields that may already be nginx defaults. Up until now we haven't set nginx defaults directly in the policy, because if they ever change, then we have to update our policy too.

I see. Thanks for catching that. For auth_jwt_leeway it defaults to 0s, so we can leave the default out of this one.
I'll make that same adjustment for the other fields. From what I ready up, 60s is a recommended setting in most scenarios when adjusting for clock skew. We can just document that though.

This has been changed now. The comment shows +kubebuilder:default=0s to reflect the NGINX docs

If we don't want a default, then we don't need that comment at all. just let nginx define it, we don't need to set it in the policy

sjberman · 2025-11-19T18:46:56Z

docs/proposals/authentication-filter.md

+  Realm *string `json:"realm,omitempty"`
+
+  // Mode selects how JWT keys are provided: local file or remote JWKS.
+  Mode JWTKeyMode `json:"mode,omitempty"`


I think this should probably be named KeyMode to be more specific.

Sorry, when I commented this I meant the field name, not the type. The type can stay as JWTKeyMode

Same with the other fields that I left similar comments on.

sjberman · 2025-11-19T18:47:21Z

docs/proposals/authentication-filter.md

+  // Required when Mode == File.
+  //
+  // +optional
+  File *JWTFileKeySource `json:"file,omitempty"`


I'd name this FileKeySource, since File by itself isn't really clear

sjberman · 2025-11-19T18:47:31Z

docs/proposals/authentication-filter.md

+  // Required when Mode == Remote.
+  //
+  // +optional
+  Remote *JWTRemoteKeySource `json:"remote,omitempty"`


RemoteKeySource for same reasons

sjberman · 2025-11-19T18:47:46Z

docs/proposals/authentication-filter.md

+  //
+  // +optional
+  // +kubebuilder:default=signed
+  Type *JWTTokenType `json:"type,omitempty"`


TokenType is more specific

sjberman · 2025-11-19T18:48:37Z

docs/proposals/authentication-filter.md

+  // Defaults to reading from Authorization header.
+  //
+  // +optional
+  TokenSource *JWTTokenSource `json:"tokenSource,omitempty"`


Any field types that have the name JWTToken in them should just be JWT, since the T in JWT stands for Token.

docs/proposals/authentication-filter.md

sjberman · 2025-11-20T15:09:43Z

docs/proposals/authentication-filter.md

+// KeyMode selects where JWT keys come from.
 // +kubebuilder:validation:Enum=File;Remote
-type JWTKeyMode string
+type KeyMode string


I'm not opposed to having JWT in the names of these fields. It makes it clear that they are for JWT. My only gripe was having JWTToken, which is redundant.

When I looked over it, while KeyMode was only related to JWT right now, the NGINX OIDC Module lets you specify a local secret, as well as a remote URL. So this could eventually be re-used when we implement OIDC auth

That being said, I'll look back over it and see if other fields where JWT was removed could still keep it.

sjberman · 2025-11-20T15:10:45Z

docs/proposals/authentication-filter.md

+  // Configures "realm="<realm_value>" in WWW-Authenticate header in error page location.
+  //
+  // +optional
+  // +kubebuilder:default="Restricted"


Should we lowercase it then?

sjberman · 2025-11-20T15:51:58Z

Being that JWT is an NGINX Plus feature, we should also outline that fact, and what the behavior would be if an OSS user attemps to specify it (probably reject it, make the route as invalid).

shaun-nx · 2025-11-20T16:33:07Z

Being that JWT is an NGINX Plus feature, we should also outline that fact, and what the behavior would be if an OSS user attemps to specify it (probably reject it, make the route as invalid).

Good point. I'll add that to the Status section.
Since we only process Filters that are attached to a HTTPRoute/GRPCRoute, should we reject the route itself, or can we "reject" the reference itself without needing to reject the route resource?

sjberman · 2025-11-20T16:40:12Z

Good point. I'll add that to the Status section.
Since we only process Filters that are attached to a HTTPRoute/GRPCRoute, should we reject the route itself, or can we "reject" the reference itself without needing to reject the route resource?

We should mark the rule invalid, but not the entire route. Other rules that don't use the filter can still work as intended, but this rule should not.

shaun-nx · 2025-11-20T16:41:08Z

Good point. I'll add that to the Status section.
Since we only process Filters that are attached to a HTTPRoute/GRPCRoute, should we reject the route itself, or can we "reject" the reference itself without needing to reject the route resource?

We should mark the rule invalid, but not the entire route. Other rules that don't use the filter can still work as intended, but this rule should not.

Sounds good. I'll make a note of that. Thanks @sjberman 👍

sjberman · 2025-11-20T17:37:31Z

docs/proposals/authentication-filter.md

+
+#### Attaching a JWT AuthenticationFilter to a route when using NGINX OSS
+
+If a user attempts to attach a JWT tpye AuthenticationFilter while using NGINX OSS, the rule referncing the filter will be `Rejected`.


Suggested change

If a user attempts to attach a JWT tpye AuthenticationFilter while using NGINX OSS, the rule referncing the filter will be `Rejected`.

If a user attempts to attach a JWT type AuthenticationFilter while using NGINX OSS, the rule referencing the filter will be `Rejected`.

sjberman · 2025-11-20T17:38:01Z

docs/proposals/authentication-filter.md

+
+If a user attempts to attach a JWT tpye AuthenticationFilter while using NGINX OSS, the rule referncing the filter will be `Rejected`.
+
+This can appear as `UnresolvedRef` to inform the user that the rule has been `Rejected`.


Is Invalid an option? UnresolvedRef generally means "we couldn't find this resource".

I think you want to use the ResolvedRefs condition on the Route to show an error message but condition should still be true to not mark the route invalid. You said you will just remove the route rule to handle the error. Similar to this.

salonichf5 · 2025-11-20T17:41:53Z

docs/proposals/authentication-filter.md

+
+Only a single `AuthenticationFilter` may be referened in a single rule.
+
+The `Status` the HTTPRoute/GRPCRoute in this scenario should be set to `Invalid`, and the resource should be `Rejected`.


and the route rule referencing the extensionRef should be rejected. Resource makes it sound like the route would be rejected.

salonichf5

just one small edit. Lgtm

sjberman · 2025-11-20T18:19:26Z

docs/proposals/authentication-filter.md

 type FileKeySource struct {
  // SecretRef references a Secret containing the JWKS.
-  SecretRef SecretObjectReference `json:"secretRef,omitempty"`
+  SecretRef LocalObjectReferenceWithKey `json:"secretRef,omitempty"`


Let's not use SecretRef as the name either, for flexibility.

sjberman

Just some nits

sjberman · 2025-11-20T18:21:21Z

docs/proposals/authentication-filter.md

+### Additional Fields for JWT
+
+`require`, `tokenSource` and `propagation` are some additional fields that may be incldued in future updates to the API.
+These fields allow for more customization of how the JWT auth behavtes, but aren't required for the minial delivery of JWT Auth.


Suggested change

These fields allow for more customization of how the JWT auth behavtes, but aren't required for the minial delivery of JWT Auth.

These fields allow for more customization of how the JWT auth behaves, but aren't required for the minimal delivery of JWT Auth.

sjberman · 2025-11-20T18:21:39Z

docs/proposals/authentication-filter.md

+Example GoLang API changes:
+```go


Suggested change

Example GoLang API changes:

```go

Example GoLang API changes:

```go

sjberman · 2025-11-20T18:23:28Z

docs/proposals/authentication-filter.md

+Example: Grant BasicAuth in app-ns to read a Secret in security-ns
+```yaml


Suggested change

Example: Grant BasicAuth in app-ns to read a Secret in security-ns

```yaml

Example: Grant BasicAuth in app-ns to read a Secret in security-ns

```yaml

sjberman · 2025-11-20T18:23:36Z

docs/proposals/authentication-filter.md

+AuthenticationFilter referencing the cross-namespace Secret
+```yaml


Suggested change

AuthenticationFilter referencing the cross-namespace Secret

```yaml

AuthenticationFilter referencing the cross-namespace Secret

```yaml

sjberman · 2025-11-20T18:31:20Z

docs/proposals/authentication-filter.md

+Example of what implementation of these fields might look like:
+```yaml


Suggested change

Example of what implementation of these fields might look like:

```yaml

Example of what implementation of these fields might look like:

```yaml

sjberman · 2025-11-20T18:32:23Z

docs/proposals/authentication-filter.md

+
+This example shows a single HTTPRoute, with a single `filter` defined in a `rule`
+
+![reference-1](/docs/images/authentication-filter/reference-1.png)


This image is probably outdated a bit for the field names.

It may not even be that necessary to have, up to you.

sjberman · 2025-11-20T18:34:18Z

docs/proposals/authentication-filter.md

+// with required `key` field to extract data.
+type LocalObjectReferenceWithKey struct {
+     v1.LocalObjectReference
+     Key string


I wonder if we set a default key that we can use in our docs so users don't have to specify this unless they explicitly change it.

shaun-nx added 2 commits November 6, 2025 18:16

Add Implementable Proposal for AuthenticationFilter

d91a5f4

Update auth header code block

9047c3e

shaun-nx requested review from a team as code owners November 6, 2025 18:19

github-project-automation bot added this to NGINX Gateway Fabric Nov 6, 2025

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

github-actions bot added the documentation Improvements or additions to documentation label Nov 6, 2025

Fix pre-commit and lint errors

c937366

salonichf5 requested changes Nov 6, 2025

View reviewed changes

github-project-automation bot moved this from 🆕 New to 🏗 In Progress in NGINX Gateway Fabric Nov 6, 2025

shaun-nx added 7 commits November 7, 2025 09:08

Update Golang API with defaults and CEL validation with kubebuilder

1b8bac2

Add additional defaults and CEL validations

2f143e9

Merge branch 'main' into proposal/authentication-filter

61f479c

Fix typos

47ff38b

Update comments in GolangAPI to decribe relative NGINX directives

40b8224

Update API and Security Considerations for ReferenceGrant integration

24966b8

Merge branch 'main' into proposal/authentication-filter

ecceb93

shaun-nx requested review from salonichf5 and sjberman November 7, 2025 14:18

Fix pre-commit errors

da1b17e

ciarams87 requested changes Nov 7, 2025

View reviewed changes

sjberman reviewed Nov 7, 2025

View reviewed changes

shaun-nx added 3 commits November 7, 2025 15:38

Fix typos and grammer

38dd8f7

Update BasicAuth AIP and examples to use secretRef

e362745

Update KeyCache to use v1alpha1.Duration

dd5aaa8

shaun-nx requested review from ciarams87 and sjberman November 7, 2025 16:21

sjberman reviewed Nov 10, 2025

View reviewed changes

sjberman reviewed Nov 11, 2025

View reviewed changes

docs/proposals/authentication-filter.md Outdated Show resolved Hide resolved

shaun-nx added 3 commits November 19, 2025 11:42

Add additional comments

b6fb76b

Update comments and restructure api

73594af

Update security details on headers

7aede4c

shaun-nx requested review from salonichf5 and sjberman November 19, 2025 16:53

Merge branch 'main' into proposal/authentication-filter

acbb54c

sjberman reviewed Nov 19, 2025

View reviewed changes

shaun-nx added 4 commits November 20, 2025 13:52

Merge branch 'main' into proposal/authentication-filter

4aae8e7

Remove JWT key word from fields

1029c3e

Add default Real for basic auth

c864630

Fix typo

ef57f2a

shaun-nx requested a review from sjberman November 20, 2025 14:02

sjberman reviewed Nov 20, 2025

View reviewed changes

shaun-nx added 2 commits November 20, 2025 17:24

Update Status section on using NGINX OSS with JWT auth

22d2726

Set optioanl JWT fields as stretch goals

9e6b3c9

sjberman reviewed Nov 20, 2025

View reviewed changes

salonichf5 reviewed Nov 20, 2025

View reviewed changes

salonichf5 approved these changes Nov 20, 2025

View reviewed changes

shaun-nx added 2 commits November 20, 2025 18:09

Add stretch goals

21b5611

Update secret ref to use LocalObjectReferenceWithKey struct

65c1adc

sjberman reviewed Nov 20, 2025

View reviewed changes

Fix typo and update validation section

a0c8c04

	Our decision to go forward with our own `AuthenticationFilter` was to ensure we could quckly provide authenticaiton to our users while allowing us to closley monitor progress of the ExternalAuthFilter.
	Our decision to go forward with our own `AuthenticationFilter` was to ensure we could quickly provide authentication to our users while allowing us to closely monitor progress of the ExternalAuthFilter.


		#### Attaching a JWT AuthenticationFilter to a route when using NGINX OSS

		If a user attempts to attach a JWT tpye AuthenticationFilter while using NGINX OSS, the rule referncing the filter will be `Rejected`.

	If a user attempts to attach a JWT tpye AuthenticationFilter while using NGINX OSS, the rule referncing the filter will be `Rejected`.
	If a user attempts to attach a JWT type AuthenticationFilter while using NGINX OSS, the rule referencing the filter will be `Rejected`.


		If a user attempts to attach a JWT tpye AuthenticationFilter while using NGINX OSS, the rule referncing the filter will be `Rejected`.

		This can appear as `UnresolvedRef` to inform the user that the rule has been `Rejected`.


		Only a single `AuthenticationFilter` may be referened in a single rule.

		The `Status` the HTTPRoute/GRPCRoute in this scenario should be set to `Invalid`, and the resource should be `Rejected`.

	These fields allow for more customization of how the JWT auth behavtes, but aren't required for the minial delivery of JWT Auth.
	These fields allow for more customization of how the JWT auth behaves, but aren't required for the minimal delivery of JWT Auth.

		Example: Grant BasicAuth in app-ns to read a Secret in security-ns
		```yaml

		AuthenticationFilter referencing the cross-namespace Secret
		```yaml

		Example of what implementation of these fields might look like:
		```yaml


		This example shows a single HTTPRoute, with a single `filter` defined in a `rule`

		![reference-1](/docs/images/authentication-filter/reference-1.png)

Enhancement Proposal: Authentication Filter #4235

Are you sure you want to change the base?

Enhancement Proposal: Authentication Filter #4235

Conversation

shaun-nx commented Nov 6, 2025

Proposed changes

Checklist

Release notes

Uh oh!

codecov bot commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

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!

shaun-nx Nov 19, 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!

Uh oh!

Uh oh!

ciarams87 left a comment

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sjberman left a comment

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!

Choose a reason for hiding this comment

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

codecov bot commented Nov 6, 2025 •

edited

Loading

shaun-nx Nov 19, 2025 •

edited

Loading

shaun-nx Nov 20, 2025 •

edited

Loading

sjberman Nov 20, 2025 •

edited

Loading