Update API spec for Basic Auth only

Author: shaun-nx

docs/proposals/authentication-filter.md

@@ -74,14 +74,14 @@ This portion also contains:
 
 ### Golang API
 
-Below is the Golang API for the `AuthenticationFilter` API:
+Below is the Golang API for the `AuthenticationFilter` API.
+This is currently designed for Basic Auth.
 
 ```go
 package v1alpha1
 
 import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
-  "github.com/nginx/nginx-gateway-fabric/v2/apis/v1alpha1"
 )
 
 // +genclient
@@ -91,278 +91,76 @@ import (
 // +kubebuilder:resource:categories=nginx-gateway-fabric,shortName=authfilter;authenticationfilter
 // +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
 
-// AuthenticationFilter configures request authentication (Basic or JWT) and is
-// referenced by HTTPRoute filters via ExtensionRef.
+// AuthenticationFilter configures request authentication and is
+// referenced by HTTPRoute and GRPCRoute filters using ExtensionRef.
 type AuthenticationFilter struct {
-  metav1.TypeMeta   `json:",inline"`
-  metav1.ObjectMeta `json:"metadata,omitempty"`
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata"`
 
-  // Spec defines the desired state of the AuthenticationFilter.
-  Spec AuthenticationFilterSpec `json:"spec"`
+	// Spec defines the desired state of the AuthenticationFilter.
+	Spec AuthenticationFilterSpec `json:"spec"`
 
-  // Status defines the state of the AuthenticationFilter, following the same
-  // pattern as SnippetsFilter: per-controller conditions with an Accepted condition.
-  //
-  // +optional
-  Status AuthenticationFilterStatus `json:"status,omitempty"`
+	// Status defines the state of the AuthenticationFilter.
+	Status AuthenticationFilterStatus `json:"status,omitempty"`
 }
 
 // +kubebuilder:object:root=true
 
 // AuthenticationFilterList contains a list of AuthenticationFilter resources.
 type AuthenticationFilterList struct {
 	metav1.TypeMeta `json:",inline"`
-	metav1.ListMeta `json:"metadata,omitempty"`
+	metav1.ListMeta `json:"metadata"`
 	Items           []AuthenticationFilter `json:"items"`
 }
 
 // AuthenticationFilterSpec defines the desired configuration.
-// Exactly one of Basic or JWT must be set according to Type.
-// +kubebuilder:validation:XValidation:message="for type=Basic, spec.basic must be set and spec.jwt must be empty; for type=JWT, spec.jwt must be set and spec.basic must be empty",rule="self.type == 'Basic' ? self.basic != null && self.jwt == null : self.type == 'JWT' ? self.jwt != null && self.basic == null : false"
-// +kubebuilder:validation:XValidation:message="type 'Basic' requires spec.basic to be set. All other spec types must be unset",rule="self.type == 'Basic' ? self.type != null && self.jwt == null : true"
-// +kubebuilder:validation:XValidation:message="type 'JWT' requires spec.jwt to be set. All other spec types must be unset",rule="self.type == 'JWT' ? self.type != null && self.basic == null : true"
-// +kubebuilder:validation:XValidation:message="when spec.basic is set, type must be 'Basic'",rule="self.basic != null ? self.type == 'Basic' : true"
-// +kubebuilder:validation:XValidation:message="when spec.jwt is set, type must be 'JWT'",rule="self.jwt != null ? self.type == 'JWT' : true"
+// +kubebuilder:validation:XValidation:message="for type=Basic, spec.basic must be set",rule="!(!has(self.basic) && self.type == 'Basic')"
+//
+//nolint:lll
 type AuthenticationFilterSpec struct {
-  // Type selects the authentication mechanism.
-  Type AuthType `json:"type"`
-
-  // Basic configures HTTP Basic Authentication.
-  // Required when Type == Basic.
-  //
-  // +optional
-  Basic *BasicAuth `json:"basic,omitempty"`
+	// Basic configures HTTP Basic Authentication.
+	//
+	// +optional
+	Basic *BasicAuth `json:"basic,omitempty"`
 
-  // JWT configures JSON Web Token authentication (NGINX Plus).
-  // Required when Type == JWT.
-  //
-  // +optional
-  JWT *JWTAuth `json:"jwt,omitempty"`
+	// Type selects the authentication mechanism.
+	Type AuthType `json:"type"`
 }
 
 // AuthType defines the authentication mechanism.
-// +kubebuilder:validation:Enum=Basic;JWT
+//
+// +kubebuilder:validation:Enum=Basic;
 type AuthType string
 
 const (
-  AuthTypeBasic AuthType = "Basic"
-  AuthTypeJWT   AuthType = "JWT"
+	// AuthTypeBasic is the HTTP Basic Authentication mechanism.
+	AuthTypeBasic AuthType = "Basic"
 )
 
 // BasicAuth configures HTTP Basic Authentication.
 type BasicAuth struct {
-  // SecretRef allows referencing a Secret in the same namespace
-  SecretRef LocalObjectReference `json:"secretRef"`
-
-  // Realm used by NGINX `auth_basic` directive.
-  // https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html#auth_basic
-  // Also configures "realm="<realm_value>" in WWW-Authenticate header in error page location.
-  Realm string `json:"realm"`
-
-  // OnFailure customizes the 401 response for failed authentication.
-  //
-  // +optional
-  OnFailure *AuthFailureResponse `json:"onFailure,omitempty"`
-}
-
-// JWTKeyMode selects where JWT keys come from.
-// +kubebuilder:validation:Enum=File;Remote
-type JWTKeyMode string
-
-const (
-  JWTKeyModeFile   JWTKeyMode = "File"
-  JWTKeyModeRemote JWTKeyMode = "Remote"
-)
-
-// JWTAuth configures JWT-based authentication (NGINX Plus).
-// +kubebuilder:validation:XValidation:message="mode 'File' requires file set and remote unset",rule="self.mode == 'File' ? self.file != null && self.remote == null : true"
-// +kubebuilder:validation:XValidation:message="mode 'Remote' requires remote set and file unset",rule="self.mode == 'Remote' ? self.remote != null && self.file == null : true"
-// +kubebuilder:validation:XValidation:message="when file is set, mode must be 'File'",rule="self.file != null ? self.mode == 'File' : true"
-// +kubebuilder:validation:XValidation:message="when remote is set, mode must be 'Remote'",rule="self.remote != null ? self.mode == 'Remote' : true"
-type JWTAuth struct {
-  // Realm used by NGINX `auth_jwt` directive
-  // https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt
-  // Configures "realm="<realm_value>" in WWW-Authenticate header in error page location.
-  Realm string `json:"realm"`
-
-  // Mode selects how JWT keys are provided: local file or remote JWKS.
-  Mode JWTKeyMode `json:"mode"`
-
-  // File specifies local JWKS configuration.
-  // Required when Mode == File.
-  //
-  // +optional
-  File *JWTFileKeySource `json:"file,omitempty"`
-
-  // Remote specifies remote JWKS configuration.
-  // Required when Mode == Remote.
-  //
-  // +optional
-  Remote *RemoteKeySource `json:"remote,omitempty"`
-
-  // Leeway is the acceptable clock skew for exp/nbf checks.
-  // Configures `auth_jwt_leeway` directive.
-  // https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_leeway
-  // Example: "auth_jwt_leeway 60s".
-  //
-  // +optional
-  Leeway *v1alpha1.Duration `json:"leeway,omitempty"`
-
-  // Type sets token type: signed | encrypted | nested.
-  // Default: signed.
-  // Configures `auth_jwt_type` directive.
-  // https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_type
-  // Example: "auth_jwt_type signed;".
-  //
-  // +optional
-  // +kubebuilder:default=signed
-  Type *JWTType `json:"type,omitempty"`
-
-  // KeyCache is the cache duration for keys.
-  // Configures auth_jwt_key_cache directive.
-  // https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_cache
-  // Example: "auth_jwt_key_cache 10m".
-  //
-  // +optional
-  KeyCache *v1alpha1.Duration `json:"keyCache,omitempty"`
+	// SecretRef allows referencing a Secret in the same namespace.
+	SecretRef LocalObjectReference `json:"secretRef"`
 
-  // OnFailure customizes the 401 response for failed authentication.
-  //
-  // +optional
-  OnFailure *AuthFailureResponse `json:"onFailure,omitempty"`
-}
-
-// JWTFileKeySource specifies local JWKS key configuration.
-type JWTFileKeySource struct {
-  // SecretRef references a Secret containing the JWKS.
-  SecretRef LocalObjectReference `json:"secretRef"`
-
-  // KeyCache is the cache duration for keys.
-  // Configures `auth_jwt_key_cache` directive.
-  // https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_cache
-  // Example: "auth_jwt_key_cache 10m;".
-  //
-  // +optional
-  KeyCache *v1alpha1.Duration `json:"keyCache,omitempty"`
+	// Realm used by NGINX `auth_basic` directive.
+	// https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html#auth_basic
+	// Also configures "realm="<realm_value>" in WWW-Authenticate header in error page location.
+	Realm string `json:"realm"`
 }
 
-// LocalObjectReference specifies a local Kubernetes object
-// with a required `key` field to extract data.
+// LocalObjectReference specifies a local Kubernetes object.
 type LocalObjectReference struct {
-    Name string: `json:"name"`
-}
-
-
- // RemoteKeySource specifies remote JWKS configuration.
-type RemoteKeySource struct {
-  // URL is the JWKS endpoint, e.g. "https://issuer.example.com/.well-known/jwks.json".
-  URL string `json:"url"`
-
-  // Cache configures NGINX proxy_cache for JWKS fetches made via auth_jwt_key_request.
-  // When set, NGF will render proxy_cache_path in http{} and attach proxy_cache to the internal JWKS location.
-  //
-  // +optional
-  Cache *JWKSCache `json:"cache,omitempty"`
-}
-
- // JWKSCache controls NGINX `proxy_cache_path` and `proxy_cache` settings used for JWKS responses.
-type JWKSCache struct {
-  // Levels specifies the directory hierarchy for cached files.
-  // Used in `proxy_cache_path` directive.
-  // https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path
-  // Example: "levels=1:2".
-  //
-  // +optional
-  Levels *string `json:"levels,omitempty"`
-
-  // KeysZoneName is the name of the cache keys zone.
-  // If omitted, the controller SHOULD derive a unique, stable name per filter instance.
-  //
-  // +optional
-  KeysZoneName *string `json:"keysZoneName,omitempty"`
-
-  // KeysZoneSize is the size of the cache keys zone (e.g. "10m").
-  // This is required to avoid unbounded allocations.
-  KeysZoneSize string `json:"keysZoneSize"`
-
-  // MaxSize limits the total size of the cache (e.g. "50m").
-  //
-  // +optional
-  MaxSize *string `json:"maxSize,omitempty"`
-
-  // Inactive defines the inactivity timeout before cached items are evicted (e.g. "10m").
-  //
-  // +optional
-  Inactive *string `json:"inactive,omitempty"`
-
-  // UseTempPath controls whether a temporary file is used for cache writes.
-  // Maps to use_temp_path=(on|off). Default: false (off).
-  //
-  // +optional
-  UseTempPath *bool `json:"useTempPath,omitempty"`
-}
-
-// JWTType represents NGINX auth_jwt_type.
-// +kubebuilder:validation:Enum=signed;encrypted;nested
-type JWTType string
-
-const (
-	JWTTypeSigned    JWTType = "signed"
-	JWTTypeEncrypted JWTType = "encrypted"
-	JWTTypeNested    JWTType = "nested"
-)
-
-// AuthScheme enumerates supported WWW-Authenticate schemes.
-// +kubebuilder:validation:Enum=Basic;Bearer
-type AuthScheme string
-
-const (
-  AuthSchemeBasic  AuthScheme = "Basic"
-  AuthSchemeBearer AuthScheme = "Bearer"
-)
-
-// AuthFailureBodyPolicy controls the failure response body behavior.
-// +kubebuilder:validation:Enum=Unauthorized;Forbidden;Empty
-type AuthFailureBodyPolicy string
-
-const (
-  AuthFailureBodyPolicyUnauthorized AuthFailureBodyPolicy = "Unauthorized"
-  AuthFailureBodyPolicyForbidden    AuthFailureBodyPolicy = "Forbidden"
-  AuthFailureBodyPolicyEmpty        AuthFailureBodyPolicy = "Empty"
-)
-
-// AuthFailureResponse customizes 401/403 failures.
-type AuthFailureResponse struct {
-  // Allowed: 401, 403.
-  // Default: 401.
-  //
-  // +optional
-  // +kubebuilder:default=401
-  // +kubebuilder:validation:XValidation:message="statusCode must be 401 or 403",rule="self == null || self in [401, 403]"
-  StatusCode *int32 `json:"statusCode,omitempty"`
-
-  // Challenge scheme. If omitted, inferred from filter Type (Basic|Bearer).
-  // Configures WWW-Authenticate header in error page location.
-  //
-  // +optional
-  // +kubebuilder:default=Basic
-  Scheme *AuthScheme `json:"scheme,omitempty"`
-
-  // Controls whether a default canned body is sent or an empty body.
-  // Default: Unauthorized.
-  //
-  // +optional
-  // +kubebuilder:default=Unauthorized
-  BodyPolicy *AuthFailureBodyPolicy `json:"bodyPolicy,omitempty"`
+	// Name is the referenced object.
+	Name string `json:"name"`
 }
 
 // AuthenticationFilterStatus defines the state of AuthenticationFilter.
 type AuthenticationFilterStatus struct {
-  // Controllers is a list of Gateway API controllers that processed the AuthenticationFilter
-  // and the status of the AuthenticationFilter with respect to each controller.
-  //
-  // +kubebuilder:validation:MaxItems=16
-  Controllers []ControllerStatus `json:"controllers,omitempty"`
+	// Controllers is a list of Gateway API controllers that processed the AuthenticationFilter
+	// and the status of the AuthenticationFilter with respect to each controller.
+	//
+	// +kubebuilder:validation:MaxItems=16
+	Controllers []ControllerStatus `json:"controllers,omitempty"`
 }
 
 // AuthenticationFilterConditionType is a type of condition associated with AuthenticationFilter.
@@ -372,22 +170,22 @@ type AuthenticationFilterConditionType string
 type AuthenticationFilterConditionReason string
 
 const (
-  // AuthenticationFilterConditionTypeAccepted indicates that the AuthenticationFilter is accepted.
-  //
-  // Possible reasons for this condition to be True:
-  // * Accepted
-  //
-  // Possible reasons for this condition to be False:
-  // * Invalid
-  AuthenticationFilterConditionTypeAccepted AuthenticationFilterConditionType = "Accepted"
-
-  // AuthenticationFilterConditionReasonAccepted is used with the Accepted condition type when
-  // the condition is true.
-  AuthenticationFilterConditionReasonAccepted AuthenticationFilterConditionReason = "Accepted"
-
-  // AuthenticationFilterConditionReasonInvalid is used with the Accepted condition type when
-  // the filter is invalid.
-  AuthenticationFilterConditionReasonInvalid AuthenticationFilterConditionReason = "Invalid"
+	// AuthenticationFilterConditionTypeAccepted indicates that the AuthenticationFilter is accepted.
+	//
+	// Possible reasons for this condition to be True:
+	// * Accepted
+	//
+	// Possible reasons for this condition to be False:
+	// * Invalid.
+	AuthenticationFilterConditionTypeAccepted AuthenticationFilterConditionType = "Accepted"
+
+	// AuthenticationFilterConditionReasonAccepted is used with the Accepted condition type when
+	// the condition is true.
+	AuthenticationFilterConditionReasonAccepted AuthenticationFilterConditionReason = "Accepted"
+
+	// AuthenticationFilterConditionReasonInvalid is used with the Accepted condition type when
+	// the filter is invalid.
+	AuthenticationFilterConditionReasonInvalid AuthenticationFilterConditionReason = "Invalid"
 )
 ```