Skip to content

Conversation

@shaun-nx
Copy link
Contributor

@shaun-nx shaun-nx commented Nov 6, 2025

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

@shaun-nx shaun-nx requested review from a team as code owners November 6, 2025 18:19
@github-actions github-actions bot added the documentation Improvements or additions to documentation label Nov 6, 2025
@codecov
Copy link

codecov bot commented Nov 6, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.11%. Comparing base (d9846a4) to head (bf3ed2b).

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #4235      +/-   ##
==========================================
+ Coverage   86.08%   86.11%   +0.03%     
==========================================
  Files         132      132              
  Lines       14342    14342              
  Branches       35       35              
==========================================
+ Hits        12346    12351       +5     
+ Misses       1791     1789       -2     
+ Partials      205      202       -3     

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

Comment on lines +125 to +128
const (
AuthTypeBasic AuthType = "Basic"
AuthTypeJWT AuthType = "JWT"
)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we should specify the nginx modules these constants associate with

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean we should add a comment or rename the constants to reflect the module?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No the nginx module should be added as reference in the comment

// NGINX module: https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html

// BasicAuth configures HTTP Basic Authentication.
type BasicAuth struct {
// Secret is the name of the Secret containing htpasswd data.
// The Secret must be in the same namespace as this filter.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why does it have to be in the same namespace? we can always resolve the secret in different namespace, unless there is another limitation assumed?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we follow the ReferenceGrant pattern for accessing Secrets in another namespace?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This comment was mostly to reflect security constraints. I noticed I didn't make note of it elsewhere in the proposal though. Mainly, we want to make sure that the AuthenticaitonFilter can only reference secrets in the same namespace by default, and like @sjberman said we can support integration with ReferenceGrant to support cross-namespace where needed.

I'll add a section to the proposal to cover that.

Copy link
Contributor Author

@shaun-nx shaun-nx Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sjberman @salonichf5 The Security Considerations section should be updated now to talk about namespace isolation as well as cross-namespace support with ReferenceGrant

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we remove or amend this comment to reflect this?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The spec should use the Gateway API's ObjectReference type instead of two separate Secret and SecretRef fields.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ciarams87 I'll amend the comment around this.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sjberman good catch. The BasicAuth spec should just have a secretRef field so that it can work with reference grants.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think he meant using the secretRef type as SecretObjectReference

// Default: File.
//
// +optional
// +kubebuilder:validation:Enum=File;Remote
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same comment as below for specifying defaults and enum

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I think about it, it might not make sense for something like this to have a default. Users should probably be very explicit about which mode they want to set. What do you think?

Path string `json:"path"`

// Levels specifies the directory hierarchy for cached files.
// Example: "1:2".
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

like 1: is for most frequently used?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This specifies the directory depth of the cache file. In the case where you have a proxy_cache_path configuration like this:

proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;

The file names in a cache will look like this: /data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c

From the docs:

The levels parameter defines hierarchy levels of a cache: from 1 to 3, each level accepts values 1 or 2. 

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

set defaults using kubebuilder: default

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment on lines +1021 to +1026
### Auth failure behaviour

3xx response codes should not be allowed and AuthenticationFilter.onFailure must not support redirect targets. This is to prevent to prevent open-redirect abuse.

401 and 403 should be the only allowable auth failure codes.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

did not see this as a rule at API level, we will allow this at API spec level?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could likely add it at a CEL validation level. What are your thoughts? I've typically seen these kind of things handled by controller level validation, but it feels like CEL validation would be better if we want to reject the resource.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah I think we can have CEL validation to allow 401 and 403 to simplify things in the later step

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

@ciarams87 ciarams87 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## Introduction

This document focuses expliclty on Authentication (AuthN) and not Authorization (AuthZ). Authentication (AuthN) defines the verification of identiy. It asks the question, "Who are you?". This is different from Authorization (AuthZ), which preceeds Authentication. It asks the question, "What are you allowed to do".
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This document focuses expliclty on Authentication (AuthN) and not Authorization (AuthZ). Authentication (AuthN) defines the verification of identiy. It asks the question, "Who are you?". This is different from Authorization (AuthZ), which preceeds Authentication. It asks the question, "What are you allowed to do".
This document focuses explicitly on Authentication (AuthN) and not Authorization (AuthZ). Authentication (AuthN) defines the verification of identity. It asks the question, "Who are you?". This is different from Authorization (AuthZ), which preceeds Authentication. It asks the question, "What are you allowed to do".

## Use Cases

- As an Application Developer, I want to secure access to my APIs and Backend Applications.
- As an Application Developer, I want to enforce authenticaiton on specific routes and matches.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- As an Application Developer, I want to enforce authenticaiton on specific routes and matches.
- As an Application Developer, I want to enforce authentication on specific routes and matches.

## API, Customer Driven Interfaces, and User Experience

This portion of the proposal will cover API design and interaction experience for use of Basic Auth and JWT.
This portioan also contains:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This portioan also contains:
This portion also contains:


1. The Golang API
2. Example spec for Basic Auth
- Example HTTPRoutes and NINGX configuration
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Example HTTPRoutes and NINGX configuration
- Example HTTPRoutes and NGINX configuration

3. Example spec for JWT Auth
- Example HTTPRoutes
- Examples for Local & Remote JWKS configration
- Example NINGX configuration for both Local & Remote JWKS
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Example NINGX configuration for both Local & Remote JWKS
- Example NGINX configuration for both Local & Remote JWKS


### Key rotation

Users sholud be advised to regularly rotate their JWKS keys in cases where they chose to reference a local JWKS via a `secrefRef` or `configMapRef`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Users sholud be advised to regularly rotate their JWKS keys in cases where they chose to reference a local JWKS via a `secrefRef` or `configMapRef`
Users should be advised to regularly rotate their JWKS keys in cases where they chose to reference a local JWKS via a `secrefRef` or `configMapRef`

### Auth failure default headers

Below are a list of default defensive headers for authentication failure reponses.
We may choose to include these headers by default for improved robustness in auth falure responses.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
We may choose to include these headers by default for improved robustness in auth falure responses.
We may choose to include these headers by default for improved robustness in auth failure responses.

add_header Content-Type "text/plain; charset=utf-8" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Cache-Control "no-store" always;
add_header Pragma "no-cache" always;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had to look this up, I had never seen it before. It's been superseded by Cache-Control, I don't think we would need it, it's legacy from HTTP/1.0

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


### Documenting filter behavour

In regards to documentation of filter behavour with the `AuthenticationFilter`, the Gateway API documentation on filters states the following:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In regards to documentation of filter behavour with the `AuthenticationFilter`, the Gateway API documentation on filters states the following:
In regards to documentation of filter behaviour with the `AuthenticationFilter`, the Gateway API documentation on filters states the following:

Copy link
Collaborator

@sjberman sjberman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

// BasicAuth configures HTTP Basic Authentication.
type BasicAuth struct {
// Secret is the name of the Secret containing htpasswd data.
// The Secret must be in the same namespace as this filter.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The spec should use the Gateway API's ObjectReference type instead of two separate Secret and SecretRef fields.

//
// +optional
// +kubebuilder:default=401
// +kubebuilder:validation:XValidation:message="statusCode must be 401 or 403",rule="self == null || self in [401, 403]"
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you use an Enum on an integer instead of CEL? I haven't tried this, maybe it only works for strings.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure. I'll see if it's possible though.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think you should be able to since they resolve as strings?

// Example: "auth_jwt_key_cache 10m;".
//
// +optional
KeyCache *string `json:"keyCache,omitempty"`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This can use the Duration type that we have defined.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good. Out of curiosity, why do we have our own Duration type?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It allows us to perform validation on the format of it.

// Example: "auth_jwt_key_cache 10m".
//
// +optional
KeyCache *string `json:"keyCache,omitempty"`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This can use the Duration type that we have defined.


### Attachment

Filters must be attached to a HTTPRoute at the `rules.matces` level.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Filters must be attached to a HTTPRoute at the `rules.matces` level.
Filters must be attached to a HTTPRoute at the `rules.matches` level.

Detailed header breakdown:

- Content-Type: "text/plain; charset=utf-8"
- This header explicitly set the body as plan text. This prevents browsers from treating the response as HTML or JavaScript, and is effective at mitigating Cross-side scrpting (XSS) through error pages
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- This header explicitly set the body as plan text. This prevents browsers from treating the response as HTML or JavaScript, and is effective at mitigating Cross-side scrpting (XSS) through error pages
- This header explicitly set the body as plain text. This prevents browsers from treating the response as HTML or JavaScript, and is effective at mitigating Cross-side scrpting (XSS) through error pages

### Validation
When referencing an `AuthenticationFilter` in either a HTTPRoute or GRPCRoute, it is important that we ensure all configurable fields are validated, and that the resulting NGINX configuration is correct and secure
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When referencing an `AuthenticationFilter` in either a HTTPRoute or GRPCRoute, it is important that we ensure all configurable fields are validated, and that the resulting NGINX configuration is correct and secure
When referencing an `AuthenticationFilter` in either a HTTPRoute or GRPCRoute, it is important that we ensure all configurable fields are validated, and that the resulting NGINX configuration is correct and secure.


We should validated that only one `AuthenticationFilter` is referenced per-rule. Multiple references to an `AuthenticationFilter` in a single rule should result in an `Invalid` HTTPRoute/GRPCRoute, and the resource should be `Rejected`.

an `AuthenticationFilter` that sets a `onFailure.statusCode` to anything other than `401` or `403` should be rejected. This relates to the "Auth failure behaviour" section in the Security Condierations section.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
an `AuthenticationFilter` that sets a `onFailure.statusCode` to anything other than `401` or `403` should be rejected. This relates to the "Auth failure behaviour" section in the Security Condierations section.
An `AuthenticationFilter` that sets a `onFailure.statusCode` to anything other than `401` or `403` should be rejected. This relates to the "Auth failure behaviour" section in the Security Considerations section.

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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

StripAuthorization *bool `json:"stripAuthorization,omitempty"`
}

// HeaderValue defines a header name and a value (may reference NGINX variables).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(may reference NGINX variables)
Are users defining these variables? What types of variables might they want to use?

I ask because for our other header filters, we currently don't support this. Though we may at some point.

// +optional
SecretRef *NamespacedSecretKeyReference `json:"secretRef,omitempty"`

// MountPath is the path where NGF will mount the data into the NGINX container.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should a user have any control over this? I'm not sure they should or why they would need to.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a good point. It's probably more secure and less error prone for us to default this directory.
As I think about that, we will want to ensure we can write to this directory when readOnlyRootfileSystem is enabled.

// Example: "/etc/nginx/keys".
MountPath string `json:"mountPath"`

// FileName is the file name of the JWKS within the mount path.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment as MountPath.

### Auth failure default headers

Below are a list of default defensive headers for authentication failure reponses.
We may choose to include these headers by default for improved robustness in auth failure responses.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We may choose to include these headers by default

That decision should be made as part of this design.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What are your thoughts on them? Do they seem overkill or would they work as secure default headers?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd like to read more about these and understand them better. Do you have some resources on them?

// Exactly one of ConfigMapRef or SecretRef must be set.
//
// +optional
ConfigMapRef *NamespacedObjectReference `json:"configMapRef,omitempty"`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we not need a Key from the ConfigMap like we do for Secret?

Also, do we need to support ConfigMap? What if we just supported Secret?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's true. It may be easier to just support Secrets. It would be more secure by default too.
I added this mostly to give users flexibility. After you asked this, I looked around for some use cases where someone might choose ConfigMapRef over SecretRef.

I found these reasons why a user might choose ConfigMapRef over SecretRef for JWKS:

  • Non-sensitive data: Verification keys are public. Storing them in a Secret implies sensitivity that doesn’t exist unless you’re handling private/decryption keys (e.g., for auth_jwt_type=encrypted or nested). For public-only JWKS, ConfigMap is appropriate.
  • Authoring convenience: ConfigMap stores raw JSON under data, while Secret requires base64-encoding. This avoids encoding errors and makes it simpler to read, diff, lint, and template the JWKS.
  • GitOps friendliness: Public configuration can be safely committed to source control and templated with Helm/Kustomize. Secrets generally shouldn’t be committed to VCS.
  • Operational visibility: Raw JSON is easier to inspect with kubectl for debugging and audits. No decoding step is needed to verify content.
  • RBAC/Policy simplification: Many clusters restrict Secret access more tightly. If your controller/policy allows reading ConfigMaps more readily than Secrets, using ConfigMap avoids broader secret-read permissions.
  • Avoiding unnecessary “secret” handling: Secrets may be encrypted at rest and trigger compliance pipelines and secret scanners. ConfigMaps avoid that overhead for public material.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think for a first pass, we just support Secret. And I think we can use a more generic object reference than SecretRef and ConfigmapRef. That way if we add ConfigMap support, we can reuse the existing object reference.

// Read token from a cookie. Default: false.
//
// +optional
// +kubebuilder:default=false
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this an optional field? If so, it shouldn't have a default.

Same comment for the rest of these fields.

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

Labels

documentation Improvements or additions to documentation

Projects

Status: 🏗 In Progress

Development

Successfully merging this pull request may close these issues.

Design for Authentication Filter

5 participants