Fix typos and indentation

shaun-nx · shaun-nx · commit eb0b8eee4503 · 2025-12-09T10:06:34.000Z
diff --git a/docs/proposals/authentication-filter.md b/docs/proposals/authentication-filter.md
@@ -14,7 +14,7 @@ This new filter should eventually expose all forms of authentication available t
 - Design Authentication CRD with Basic Auth and JWT Auth in mind
 - Determine initial resource specification
 - Evaluate filter early in request processing, occurring before URLRewrite, header modifiers and backend selection
-- Authentication failures returns 401 Unauthorized by default
+- Authentication failures return 401 Unauthorized by default
 - Ensure response codes are configurable
 
 ## Non-Goals
@@ -25,9 +25,9 @@ This new filter should eventually expose all forms of authentication available t
 
 ## Introduction
 
-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".
+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 follows Authentication. It asks the question, "What are you allowed to do?"
 
-This document also focus on HTTP Basic Authentication and JWT Authentication. Other authentication methods such as OpenID Connect (OIDC) are mentioned, but are not part of the CRD design. These will be covered in future design and implementation tasks.
+This document also focuses on HTTP Basic Authentication and JWT Authentication. Other authentication methods such as OpenID Connect (OIDC) are mentioned, but are not part of the CRD design. These will be covered in future design and implementation tasks.
 
 
 ## Use Cases
@@ -68,7 +68,7 @@ This portion also contains:
     - Example HTTPRoutes and NGINX configuration
 3. Example spec for JWT Auth
     - Example HTTPRoutes
-    - Examples for Local & Remote JWKS configration
+    - Examples for Local & Remote JWKS configuration
     - Example NGINX configuration for both Local & Remote JWKS
     - Example of additional optional fields
 
@@ -80,7 +80,7 @@ Below is the Golang API for the `AuthenticationFilter` API:
 package v1alpha1
 
 import (
-	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+  metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
   "github.com/nginx/nginx-gateway-fabric/v2/apis/v1alpha1"
 )
 
@@ -111,9 +111,9 @@ type AuthenticationFilter struct {
 
 // AuthenticationFilterList contains a list of AuthenticationFilter resources.
 type AuthenticationFilterList struct {
-	metav1.TypeMeta `json:",inline"`
-	metav1.ListMeta `json:"metadata,omitempty"`
-	Items           []AuthenticationFilter `json:"items"`
+  metav1.TypeMeta `json:",inline"`
+  metav1.ListMeta `json:"metadata,omitempty"`
+  Items           []AuthenticationFilter `json:"items"`
 }
 
 // AuthenticationFilterSpec defines the desired configuration.
@@ -151,19 +151,19 @@ const (
 
 // BasicAuth configures HTTP Basic Authentication.
 type BasicAuth struct {
-	// SecretRef allows referencing a Secret in the same namespace.
-	SecretRef LocalObjectReference `json:"secretRef"`
+  // 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"`
+  // 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.
 type LocalObjectReference struct {
-	// Name is the referenced object.
-	Name string `json:"name"`
+  // Name is the referenced object.
+  Name string `json:"name"`
 }
 
 // JWTKeyMode selects where JWT keys come from.
@@ -296,9 +296,9 @@ type JWKSCache struct {
 type JWTType string
 
 const (
-	JWTTypeSigned    JWTType = "signed"
-	JWTTypeEncrypted JWTType = "encrypted"
-	JWTTypeNested    JWTType = "nested"
+  JWTTypeSigned    JWTType = "signed"
+  JWTTypeEncrypted JWTType = "encrypted"
+  JWTTypeNested    JWTType = "nested"
 )
 
 // AuthScheme enumerates supported WWW-Authenticate schemes.
@@ -364,20 +364,20 @@ In the case of Basic Auth, the deployed Secret and HTTPRoute may look like this:
 
 #### Secret referenced by filter
 
-To create this kind of secreet for Basic Auth first run this command:
+To create this kind of secret for Basic Auth first run this command:
 
 ```bash
 htpasswd -c auth user
 ```
 
-This will create a file called `auth` with the user name and an MD5 hashes password:
+This will create a file called `auth` with the username and an MD5-hashed password:
 
 ```bash
 cat auth
 user:$apr1$prQ3Bh4t$A6bmTv7VgmemGe5eqR61j0
 ```
 
-Use these options in the `htpasswd` command for stronger hashing algorithims:
+Use these options in the `htpasswd` command for stronger hashing algorithms:
 
 ```bash
  -2  Force SHA-256 hashing of the password (secure).
@@ -391,7 +391,7 @@ You can then run this command to generate the secret from the `auth` file:
 kubectl create secret generic basic-auth --from-file=auth
 ```
 
-Note: `auth` will be the default key for secrets referenced `AuthenticationFilters` of `Type: Basic`.
+Note: `auth` will be the default key for secrets referenced by `AuthenticationFilters` of `Type: Basic`.
 
 Example secret:
 
@@ -437,7 +437,7 @@ spec:
 
 Note: For Basic Auth, NGF will store the file used by `auth_basic_user_file` in `/etc/nginx/secrets/`
 The full path will use the `name` and `key` of the secret referenced by `AuthenticationFilter`
-In this case, the full path will be `/etc/nginx/secrets/basic-auth-users/htpasswd`
+In this case, the full path will be `/etc/nginx/secrets/basic-auth-users/auth`
 
 ```nginx
 http {
@@ -475,9 +475,9 @@ http {
 
 ### Example spec for JWT Auth
 
-For JWT Auth, there is two options.
+For JWT Auth, there are two options.
 
-1. Local JWKS file stored as as a Secret
+1. Local JWKS file stored as a Secret
 2. Remote JWKS from an IdP provider like Keycloak
 
 #### Example JWT AuthenticationFilter with Local JWKS
@@ -534,7 +534,7 @@ To create the example secret, run the following command:
 kubectl create secret generic basic-auth --from-file=jwks.json
 ```
 
-Note: `jwks.json` will be the default key for secrets referenced `AuthenticationFilters` of `Type: JWT`.
+Note: `jwks.json` will be the default key for secrets referenced by `AuthenticationFilters` of `Type: JWT`.
 
 ```yaml
 apiVersion: v1
@@ -610,7 +610,7 @@ http {
 
             # File-based JWKS
             # Path is generated by NGF using the name and key from the secret
-            auth_jwt_key_file /etc/nginx/keys/jwt-keys-secure/jwks;
+            auth_jwt_key_file /etc/nginx/keys/jwt-keys-secure/jwks.json;
 
             # Optional: key cache duration
             auth_jwt_key_cache 10m;
@@ -650,8 +650,8 @@ http {
 
 These are some directives the `Remote` mode uses over the `File` mode:
 
-- `auth_jwt_key_request`: When using the `Remote` mode, this is used in place of `auth_jwt_key_file`. This will call the `internal` NGINX location `/_ngf-internal_jwks_uri` to redirect the request to the external auth provider (e.g. KeyCloak)
-- `proxy_cache_path`: This is used to configuring caching of the JWKS after an initial request allowing subsequent requests to not request re-authenticaiton for a time
+- `auth_jwt_key_request`: When using the `Remote` mode, this is used in place of `auth_jwt_key_file`. This will call the `internal` NGINX location `/_ngf-internal_jwks_uri` to redirect the request to the external auth provider (e.g. Keycloak)
+- `proxy_cache_path`: This is used to configure caching of the JWKS after an initial request, allowing subsequent requests to avoid re-authentication for a time
 
 ```nginx
 http {
@@ -753,8 +753,8 @@ spec:
 
 ### Attachment
 
-Filters must be attached to a HTTPRoute at the `rules.matches` level.
-This means that a single `AuthenticationFilter` may be attached mutliple times to a single HTTPRoute.
+Filters must be attached to an HTTPRoute at the `rules.matches` level.
+This means that a single `AuthenticationFilter` may be attached multiple times to a single HTTPRoute.
 
 #### Basic example
 
@@ -766,10 +766,10 @@ This example shows a single HTTPRoute, with a single `filter` defined in a `rule
 
 #### Referencing multiple AuthenticationFilter resources in a single rule
 
-Only a single `AuthenticationFilter` may be referened in a single rule.
+Only a single `AuthenticationFilter` may be referenced in a single rule.
 
-The `Status` the HTTPRoute/GRPCRoute in this scenario should be set to `Invalid`, and the resource should be `Rejected`.
-In this scenario, the route rule that is referencing multiple `AuthenticationFilter` resources will be `Rejected`/
+The Status of the HTTPRoute/GRPCRoute in this scenario should be set to `Invalid`, and the resource should be `Rejected`.
+In this scenario, the route rule that is referencing multiple `AuthenticationFilter` resources will be `Rejected`.
 All other route rules will remain working.
 
 The HTTPRoute/GRPCRoute resource will display an `UnresolvedRef` message to inform the user that the rule has been `Rejected`.
@@ -812,7 +812,7 @@ spec:
 #### Referencing an AuthenticationFilter resource that is invalid
 
 Note: With appropriate use of CEL validation, we are less likely to encounter a scenario where an AuthenticationFilter has been deployed to the cluster with an invalid configuration.
-If this does happen, and a route rule references this AuthenticationFilter, the route rule will be set to `Invalid` and the the HTTPRoute/GRPCRoute will display the `UnresolvedRef` status.
+If this does happen, and a route rule references this AuthenticationFilter, the route rule will be set to `Invalid` and the HTTPRoute/GRPCRoute will display the `UnresolvedRef` status.
 
 #### Attaching a JWT AuthenticationFilter to a route when using NGINX OSS
 
@@ -836,13 +836,13 @@ For a filter to be considered "resolved", it must:
 Invalid resolved filter scenarios:
 
 - Resolved filter that references a secret that does not exist
-- Resolved filter that referenced a secret with the incorrect data key
+- Resolved filter that references a secret with the incorrect data key
 
 Valid reference scenarios:
 
 - Resolved filter referenced by a single route rule within a single HTTP/GRPCRoute
 - Resolved filter referenced by multiple route rules within a single HTTP/GRPCRoute
-- Resolved filter reference by multiple HTTP/GRPCRoutes
+- Resolved filter referenced by multiple HTTP/GRPCRoutes
 
 Invalid reference scenarios:
 
@@ -871,12 +871,12 @@ Proxy cache TTL should be configurable and set to a reasonable default, reducing
 
 ### Key rotation
 
-Users should be advised to regularly rotate their JWKS keys in cases where they chose to reference a local JWKS via a `secrefRef`
+Users should be advised to regularly rotate their JWKS keys in cases where they choose to reference a local JWKS via a `secretRef`.
 
 ### Optional headers
 
-Below are a list of optional defensive headers that user's may choose to include.
-In certain scenarios, these headers may be deployed to improve overall security from client reponses.
+Below are a list of optional defensive headers that users may choose to include.
+In certain scenarios, these headers may be deployed to improve overall security from client responses.
 
 ```nginx
 add_header Content-Type "text/plain; charset=utf-8" always;
@@ -887,42 +887,42 @@ add_header Cache-Control "no-store" always;
 Detailed header breakdown:
 
 - Content-Type: "text/plain; charset=utf-8"
-  - 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
+  - This header explicitly sets the body as plain text. This prevents browsers from treating the response as HTML or JavaScript, and is effective at mitigating Cross-site scripting (XSS) through error pages
 
 - X-Content-Type-Options: "nosniff"
-  - This header prevents content type confusion. This occurrs when browsers guesses HTML & JavaScript, and executes it despite a benign type.
+  - This header prevents content type confusion. This occurs when browsers guess HTML and JavaScript, and execute it despite a benign type.
 
 - Cache-Control: "no-store"
-  - This header informs browsers and proxies not to cache the response. Avoids sensitive, auth-related content, from being being stored and served later to unintended recipients.
+  - This header informs browsers and proxies not to cache the response. Avoids sensitive, auth-related content from being stored and served later to unintended recipients.
 
 
 ### 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.
+When referencing an `AuthenticationFilter` in either an HTTPRoute or GRPCRoute, it is important that we ensure all configurable fields are validated, and that the resulting NGINX configuration is correct and secure.
 
-All fields in the `AuthenticationFilter` will be validated with Open API Schema.
+All fields in the `AuthenticationFilter` will be validated with OpenAPI Schema.
 We should also include [CEL](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation-rules) validation where required.
 
-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 rule should be `Rejected`.
+We should validate 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 rule should be `Rejected`.
 
 This scenario can use the status `RouteConditionPartiallyInvalid` defined in the Gateway API here: https://github.com/nginx/nginx-gateway-fabric/blob/3934c5c8c60b5aea91be4337d63d4e1d8640baa8/internal/controller/state/conditions/conditions.go#L402
 
 ## Alternatives
 
 The Gateway API defines a means to standardise authentication through use of the [HTTPExternalAuthFilter](https://gateway-api.sigs.k8s.io/reference/spec/#httpexternalauthfilter) available in the HTTPRoute specification.
 
-This allows users to reference an external authentication services, such as Keycloak, to handle the authentication requests.
+This allows users to reference an external authentication service, 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 quickly provide authentication to our users while allowing us to closely monitor progress of the ExternalAuthFilter.
 
-It is certainly possible for us to provide an External Authentication Services that leverages NGINX and is something we can further investigate as the API progresses.
+It is certainly possible for us to provide an External Authentication Service that leverages NGINX and is something we can further investigate as the API progresses.
 
 ## Additional considerations
 
-### Documenting filter behavour
+### Documenting filter behavior
 
-In regards to documentation of filter behaviour with the `AuthenticationFilter`, the Gateway API documentation on filters states the following:
+In regards to documentation of filter behavior with the `AuthenticationFilter`, the Gateway API documentation on filters states the following:
 
 ```text
 Wherever possible, implementations SHOULD implement filters in the order they are specified.
@@ -935,10 +935,10 @@ document that behavior.
 
 ## Stretch Goals
 
-### Custom authentiation failure response
+### Custom authentication failure response
 
 By default, authentication failures return a 401 response.
-If a used wanted to change this response code, or include additioanl headers in this response, we can include a custom named location that can be called by the [error_page](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page) directive.
+If a user wanted to change this response code, or include additional headers in this response, we can include a custom named location that can be called by the [error_page](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page) directive.
 
 Example AuthenticationFilter configuration:
 
@@ -977,15 +977,15 @@ server{
 }
 ```
 
-If we support this configuration, 3xx response codes should not be allowed and AuthenticationFilter.onFailure must not support redirect targets. This is to prevent to prevent open-redirect abuse.
+If we support this configuration, 3xx response codes should not be allowed and AuthenticationFilter.onFailure must not support redirect targets. This is to prevent open-redirect abuse.
 
 We should only allow 401 and 403 response codes.
 
 ### Cross namespace access
 
 When referencing secrets for Basic Auth and JWT Auth, the initial implementation will use `LocalObjectReference`.
 
-Future updates to this will use the `NamespacedSecretKeyReference` in conjunction with `ReferenceGrants` to support access to secrets in different namespace`
+Future updates to this will use the `NamespacedSecretKeyReference` in conjunction with `ReferenceGrants` to support access to secrets in different namespaces.
 
 Struct for `NamespacedSecretKeyReference`:
 
@@ -1001,9 +1001,8 @@ type NamespacedSecretKeyReference struct {
 }
 ```
 
-For initial implementaion, both Basic Auth and Local JWKS should will only  have access to Secrets in the same namespace.
+For the initial implementation, both Basic Auth and Local JWKS will only have access to Secrets in the same namespace.
 
-Example: Grant BasicAuth in app-ns to read a Secret in security-ns
 Example: Grant BasicAuth in app-ns to read a Secret in security-ns
 
 ```yaml
@@ -1023,7 +1022,6 @@ spec:
     name: basic-auth-users
 ```
 
-AuthenticationFilter referencing the cross-namespace Secret
 AuthenticationFilter referencing the cross-namespace Secret
 
 ```yaml
@@ -1043,10 +1041,9 @@ spec:
 
 ### Additional Fields for JWT
 
-`require`, `tokenSource` and `propagation` are some additional fields that may be incldued in future updates to the API.
+`require`, `tokenSource` and `propagation` are some additional fields that may be included in future updates to the API.
 These fields allow for more customization of how the JWT auth behaves, but aren't required for the minimal delivery of JWT Auth.
 
-Example of what implementation of these fields might look like:
 Example of what implementation of these fields might look like:
 
 ```yaml
@@ -1073,7 +1070,7 @@ spec:
         - "cli"
 
     # Where client presents the token
-    # By defaults to reading from Authorization header (Bearer)
+    # By default, reading from Authorization header (Bearer)
     tokenSource:
       type: Header
       # Alternative: read from a cookie named tokenName
@@ -1194,7 +1191,7 @@ type HeaderValue struct {
 
 - [Gateway API ExternalAuthFilter GEP](https://gateway-api.sigs.k8s.io/geps/gep-1494/)
 - [HTTPExternalAuthFilter Specification](https://gateway-api.sigs.k8s.io/reference/spec/#httpexternalauthfilter)
-- [Kubernetes documentation on CEL validaton](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation-rules)
+- [Kubernetes documentation on CEL validation](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation-rules)
 - [NGINX HTTP Basic Auth Module](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html)
 - [NGINX JWT Auth Module](https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html)
 - [NGINX OIDC Module](https://nginx.org/en/docs/http/ngx_http_oidc_module.html)
