add docs for StructuredAuthenticationConfig v1alpha1

Signed-off-by: Anish Ramasekar <[email protected]>

content/en/docs/reference/access-authn-authz/authentication.md

@@ -241,7 +241,7 @@ and are assigned to the groups `system:serviceaccounts` and `system:serviceaccou
 
 {{< warning >}}
 Because service account tokens can also be stored in Secret API objects, any user with
-write access to Secrets can request a token, and any user with read access to those 
+write access to Secrets can request a token, and any user with read access to those
 Secrets can authenticate as the service account. Be cautious when granting permissions
 to service accounts and read or write capabilities for Secrets.
 {{< /warning >}}
@@ -308,6 +308,8 @@ Since all of the data needed to validate who you are is in the `id_token`, Kuber
 
 #### Configuring the API Server
 
+##### Using flags
+
 To enable the plugin, configure the following flags on the API server:
 
 | Parameter | Description | Example | Required |
@@ -322,6 +324,65 @@ To enable the plugin, configure the following flags on the API server:
 | `--oidc-ca-file` | The path to the certificate for the CA that signed your identity provider's web certificate.  Defaults to the host's root CAs. | `/etc/kubernetes/ssl/kc-ca.pem` | No |
 | `--oidc-signing-algs` | The signing algorithms accepted. Default is "RS256". | `RS512` | No |
 
+##### Using Authentication Configuration
+
+{{< feature-state for_k8s_version="v1.29" state="alpha" >}}
+
+The API server can be configured to use a JWT authenticator via the `--authentication-config` flag. This flag takes a path to a file containing the `AuthenticationConfiguration`. An example configuration is provided below.
+Ensure the `StructuredAuthenticationConfiguration` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled.
+
+```yaml
+---
+#
+# CAUTION: this is an example configuration.
+#          Do not use this for your own cluster!
+#
+apiVersion: apiserver.config.k8s.io/v1alpha1
+kind: AuthenticationConfiguration
+jwt:
+- issuer:
+    url: https://example.com # Same as --oidc-issuer-url.
+    audiences:
+    - my-app # Same as --oidc-client-id.
+  claimValidationRules: # Same as --oidc-required-claim. CEL expressions are supported in addition to simple key-value pairs.
+  - claim: hd
+    requiredValue: example.com
+  - expression: 'claims.hd == "example.com"'
+    message: the hd claim must be set to example.com
+  - expression: 'claims.exp - claims.nbf <= 86400'
+    message: total token lifetime must not exceed 24 hours
+  claimMappings: # Same as --oidc-username-claim and --oidc-groups-claim.
+    username: # if username.claim is set, username.prefix is required.
+      expression: 'claims.username + ":external-user"'
+    groups:
+      expression: 'claims.roles.split(",")'
+    uid:
+      claim: 'sub'
+    extra: # extra attributes to be added to the UserInfo object. Keys must be domain-prefix path and must be unique.
+    - key: 'example.com/tenant'
+      valueExpression: 'claims.tenant'
+  userValidationRules: # validation rules applied to the final user object.
+  - expression: "!user.username.startsWith('system:')"
+    message: 'username cannot used reserved system: prefix'
+  - expression: "user.groups.all(group, !group.startsWith('system:'))"
+    message: 'groups cannot used reserved system: prefix'
+```
+
+* Claim validation rule expression
+  `jwt.claimValidationRules[i].expression` represents the expression which will be evaluated by CEL.
+  CEL expressions have access to the contents of the token claims, organized into `claims` CEL variable.
+  `claims` is a map of claim names to claim values.
+* User validation rule expression
+  `jwt.userValidationRules[i].expression` represents the expression which will be evaluated by CEL.
+  CEL expressions have access to the contents of userInfo, organized into `user` CEL variable.
+* Claim mapping expression
+  `jwt.claimMappings.username.expression`, `jwt.claimMappings.groups.expression`, `jwt.claimMappings.uid.expression`
+  `jwt.claimMappings.extra[i].valueExpression` represents the expression which will be evaluated by CEL.
+  CEL expressions have access to the contents of the token claims, organized into `claims` CEL variable.
+  `claims` is a map of claim names to claim values.
+
+  To learn more, see the [CEL language specification](https://github.com/google/cel-spec)
+
 Importantly, the API server is not an OAuth2 client, rather it can only be
 configured to trust a single issuer. This allows the use of public providers,
 such as Google, without trusting credentials issued to third parties. Admins who
@@ -418,7 +479,7 @@ Webhook authentication is a hook for verifying bearer tokens.
 
 * `--authentication-token-webhook-config-file` a configuration file describing how to access the remote webhook service.
 * `--authentication-token-webhook-cache-ttl` how long to cache authentication decisions. Defaults to two minutes.
-* `--authentication-token-webhook-version` determines whether to use `authentication.k8s.io/v1beta1` or `authentication.k8s.io/v1` 
+* `--authentication-token-webhook-version` determines whether to use `authentication.k8s.io/v1beta1` or `authentication.k8s.io/v1`
   `TokenReview` objects to send/receive information from the webhook. Defaults to `v1beta1`.
 
 The configuration file uses the [kubeconfig](/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
@@ -474,9 +535,9 @@ To opt into receiving `authentication.k8s.io/v1` token reviews, the API server m
   "spec": {
     # Opaque bearer token sent to the API server
     "token": "014fbff9a07c...",
-   
+
     # Optional list of the audience identifiers for the server the token was presented to.
-    # Audience-aware token authenticators (for example, OIDC token authenticators) 
+    # Audience-aware token authenticators (for example, OIDC token authenticators)
     # should verify the token was intended for at least one of the audiences in this list,
     # and return the intersection of this list and the valid audiences for the token in the response status.
     # This ensures the token is valid to authenticate to the server it was presented to.
@@ -494,9 +555,9 @@ To opt into receiving `authentication.k8s.io/v1` token reviews, the API server m
   "spec": {
     # Opaque bearer token sent to the API server
     "token": "014fbff9a07c...",
-   
+
     # Optional list of the audience identifiers for the server the token was presented to.
-    # Audience-aware token authenticators (for example, OIDC token authenticators) 
+    # Audience-aware token authenticators (for example, OIDC token authenticators)
     # should verify the token was intended for at least one of the audiences in this list,
     # and return the intersection of this list and the valid audiences for the token in the response status.
     # This ensures the token is valid to authenticate to the server it was presented to.
@@ -838,7 +899,7 @@ rules:
 {{< note >}}
 Impersonating a user or group allows you to perform any action as if you were that user or group;
 for that reason, impersonation is not namespace scoped.
-If you want to allow impersonation using Kubernetes RBAC, 
+If you want to allow impersonation using Kubernetes RBAC,
 this requires using a `ClusterRole` and a `ClusterRoleBinding`,
 not a `Role` and `RoleBinding`.
 {{< /note >}}
@@ -1335,7 +1396,7 @@ status:
 {{% /tab %}}
 {{< /tabs >}}
 
-This feature is extremely useful when a complicated authentication flow is used in a Kubernetes cluster, 
+This feature is extremely useful when a complicated authentication flow is used in a Kubernetes cluster,
 for example, if you use [webhook token authentication](/docs/reference/access-authn-authz/authentication/#webhook-token-authentication) or [authenticating proxy](/docs/reference/access-authn-authz/authentication/#authenticating-proxy).
 
 {{< note >}}
@@ -1345,7 +1406,7 @@ If you, or an authentication proxy, make a SelfSubjectReview using impersonation
 you see the user details and properties for the user that was impersonated.
 {{< /note >}}
 
-By default, all authenticated users can create `SelfSubjectReview` objects when the `APISelfSubjectReview` feature is enabled. It is allowed by the `system:basic-user` cluster role. 
+By default, all authenticated users can create `SelfSubjectReview` objects when the `APISelfSubjectReview` feature is enabled. It is allowed by the `system:basic-user` cluster role.
 
 {{< note >}}
 You can only make `SelfSubjectReview` requests if:
@@ -1365,4 +1426,3 @@ You can only make `SelfSubjectReview` requests if:
 
 * Read the [client authentication reference (v1beta1)](/docs/reference/config-api/client-authentication.v1beta1/)
 * Read the [client authentication reference (v1)](/docs/reference/config-api/client-authentication.v1/)
-