Generate CRD for AuthenticationFilter with BasicAuth

[shaun-nx]

Proposed changes

This change adds a new GoLang API type to apis/v1alpha1 for the AuthenticationFilter
This change only adds the types required for Basic Auth to work, and does not include types specific to JWT Auth. These will be added in future work.

Closes #4309

Example manifest for basic auth

apiVersion: gateway.nginx.org/v1alpha1
kind: AuthenticationFilter
metadata:
  name: basic-auth
spec:
  type: Basic
  basic:
    secretRef:
      name: basic-auth-users
    realm: "Restricted"
    onFailure:
      statusCode: 401
      scheme: Basic

Example output from kubectl describe authenticationfilters.gateway.nginx.org basic-auth

Name:         basic-auth
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  gateway.nginx.org/v1alpha1
Kind:         AuthenticationFilter
Metadata:
  Creation Timestamp:  2025-11-27T10:49:42Z
  Generation:          1
  Resource Version:    58448
  UID:                 b0f0a18a-ba43-453c-b315-dcecf39ad06f
Spec:
  Basic:
    On Failure:
      Body Policy:  Unauthorized
      Scheme:       Basic
      Status Code:  401
    Realm:          Restricted
    Secret Ref:
      Name:  basic-auth-users
  Type:      Basic
Events:      <none>

Validation

Performed manual checks on x-Kubernetes-Validations for CRD:

1. Rule: for type=Basic, spec.basic must be set

File used:

apiVersion: gateway.nginx.org/v1alpha1
kind: AuthenticationFilter
metadata:
  name: basic-auth
spec:
  type: Basic
  # spec.basic is missing

Result:

The AuthenticationFilter "basic-auth" is invalid: 
* spec.basic: Required value
* <nil>: Invalid value: null: some validation rules were not checked because the object was invalid; correct the existing errors to complete validation

2. Rule: when spec.basic is set, type must be 'Basic'

Files used:

1. where type is not defined
2. where type is set to `Blah

apiVersion: gateway.nginx.org/v1alpha1
kind: AuthenticationFilter
metadata:
  name: basic-auth-empty-type
spec:
  # type field is missing
  basic:
    secretRef:
      name: basic-auth-users
    realm: "Restricted"    
    onFailure:                
      statusCode: 401
      scheme: Basic
---
apiVersion: gateway.nginx.org/v1alpha1
kind: AuthenticationFilter
metadata:
  name: basic-auth-empty-blah
spec:
  type: Blah  # type field is invalid
  basic:
    secretRef:
      name: basic-auth-users
    realm: "Restricted"    
    onFailure:                
      statusCode: 401
      scheme: Basic

Results:

Error from server (Invalid): error when creating "STDIN": AuthenticationFilter.gateway.nginx.org "basic-auth-empty-type" is invalid: [spec.type: Required value, <nil>: Invalid value: null: some validation rules were not checked because the object was invalid; correct the existing errors to complete validation]

Error from server (Invalid): error when creating "STDIN": AuthenticationFilter.gateway.nginx.org "basic-auth-empty-blah" is invalid: [spec.type: Unsupported value: "Blah": supported values: "Basic", <nil>: Invalid value: null: some validation rules were not checked because the object was invalid; correct the existing errors to complete validation]

3. Rule: statusCode must be 401 or 403

Files used:

1. where statusCode is 301.
2. where statusCode is 500

apiVersion: gateway.nginx.org/v1alpha1
kind: AuthenticationFilter
metadata:
  name: basic-auth-301
spec:
  type: Basic
  basic:
    secretRef:
      name: basic-auth-users
      key: htpasswd
    realm: "Restricted"
    onFailure:
      statusCode: 301  # statusCode is not 401 or 403
      scheme: Basic
---
apiVersion: gateway.nginx.org/v1alpha1
kind: AuthenticationFilter
metadata:
  name: basic-auth-500
spec:
  type: Basic
  basic:
    secretRef:
      name: basic-auth-users
      key: htpasswd
    realm: "Restricted"
    onFailure:
      statusCode: 500 # statusCode is not 401 or 403
      scheme: Basic

Results:

Error from server (Invalid): error when creating "STDIN": AuthenticationFilter.gateway.nginx.org "basic-auth-301" is invalid: spec.basic.onFailure.statusCode: Invalid value: "integer": statusCode must be 401 or 403

Error from server (Invalid): error when creating "STDIN": AuthenticationFilter.gateway.nginx.org "basic-auth-500" is invalid: spec.basic.onFailure.statusCode: Invalid value: "integer": statusCode must be 401 or 403

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]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.08%. Comparing base (f612e19) to head (1c6843d).

Additional details and impacted files

@@                          Coverage Diff                           @@
##           feat/authentication-filter-basic-auth    #4349   +/-   ##
======================================================================
  Coverage                                  86.08%   86.08%           
======================================================================
  Files                                        132      132           
  Lines                                      14342    14342           
  Branches                                      35       35           
======================================================================
  Hits                                       12346    12346           
  Misses                                      1792     1792           
  Partials                                     204      204           

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

[tataruty]

the target should be feat/authentication-filter-basic-auth i guess

[shaun-nx]

The linter seemed to have problems with the comments the AuthenticationFilterSpec and BasicAuth structs: a127e6b
This does affect the description given for secret ref. See here: https://github.com/nginx/nginx-gateway-fabric/pull/4349/commits/da972012a91784412d617785b81d79210db1fb10#diff-085e561f7a49fee[…]9fc1703ae43dbL97-R93
I'm not sure if there is a way around this. What do you all think?

[sjberman]

The linter seemed to have problems with the comments the AuthenticationFilterSpec and BasicAuth structs

@shaun-nx I think I wrote about this on another PR, but the linter (fieldalignment) does not have a problem with comments. The linter automatically reorganizes fields within a struct to optimize it for the compiler. There is a bug that causes comments to be removed when it does this, so you have to manually add the comments back in.

[shaun-nx]

The linter seemed to have problems with the comments the AuthenticationFilterSpec and BasicAuth structs

@shaun-nx I think I wrote about this on another PR, but the linter (fieldalignment) does not have a problem with comments. The linter automatically reorganizes fields within a struct to optimize it for the compiler. There is a bug that causes comments to be removed when it does this, so you have to manually add the comments back in.

Thanks Saylor. We managed to fix it too. @tataruty pointed out the same thing. Will probably be one of those things that I need to see a few times before I remember haha.