Reword explanation of external authn integrations

Co-authored-by: Michael Yao <[email protected]>
Co-authored-by: Ritika <[email protected]>

Author: 3 people

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

@@ -75,11 +75,11 @@ The API server does not guarantee the order authenticators run in.
 
 The `system:authenticated` group is included in the list of groups for all authenticated users.
 
-Integrations with other authentication protocols (LDAP, SAML, Kerberos, alternate x509 schemes, etc)
-can be accomplished using an [authenticating proxy](#authenticating-proxy) or the
+[Integrations](#external-integrations) with other authentication protocols (LDAP, SAML, Kerberos, alternate x509 schemes, etc)
+are available; for example using an [authenticating proxy](#authenticating-proxy) or the
 [authentication webhook](#webhook-token-authentication).
 
-### X509 client certificates
+### X.509 client certificates {#x509-client-certificates}
 
 Client certificate authentication is enabled by passing the `--client-ca-file=SOMEFILE`
 option to API server. The referenced file must contain one or more certificate authorities
@@ -99,23 +99,6 @@ This would create a CSR for the username "jbeda", belonging to two groups, "app1
 
 See [Managing Certificates](/docs/tasks/administer-cluster/certificates/) for how to generate a client cert.
 
-### Static token file
-
-The API server reads bearer tokens from a file when given the `--token-auth-file=SOMEFILE` option
-on the command line. Currently, tokens last indefinitely, and the token list cannot be
-changed without restarting the API server.
-
-The token file is a csv file with a minimum of 3 columns: token, user name, user uid,
-followed by optional group names.
-
-{{< note >}}
-If you have more than one group, the column must be double quoted e.g.
-
-```conf
-token,user,uid,"group1,group2,group3"
-```
-{{< /note >}}
-
 #### Putting a bearer token in a request
 
 When using bearer token authentication from an http client, the API
@@ -246,7 +229,24 @@ Secrets can authenticate as the service account. Be cautious when granting permi
 to service accounts and read or write capabilities for Secrets.
 {{< /warning >}}
 
-### OpenID Connect Tokens
+## External integrations
+
+Kubernetes has native support for OpenID Connect (OIDC); see [OpenID Connect tokens](#openid-connect-tokens).
+
+Integrations with other authentication protocols (for example: LDAP, SAML, Kerberos, alternate X.509 schemes)
+can be accomplished using an [authenticating proxy](#authenticating-proxy) or by integrating with an
+[authentication webhook](#webhook-token-authentication).
+
+You can also use any custom method that issues [client X.509 certificates](#x509-client-certificates) to clients,
+provided that the API server will trust the valid certificates.
+Read [X.509 client certificates](#x509-client-certificates) to learn about how to generate a
+certificate.
+
+If you do issue certificates to clients, it is up to you (as a cloud platform administrator)
+to make sure that the certicate validity period, and other design choices you make, provide a
+suitable level of security.
+
+### OpenID Connect tokens
 
 [OpenID Connect](https://openid.net/connect/) is a flavor of OAuth2 supported by
 some OAuth2 providers, notably Microsoft Entra ID, Salesforce, and Google.
@@ -290,7 +290,7 @@ sequenceDiagram
 
 1. Log in to your identity provider
 1. Your identity provider will provide you with an `access_token`, `id_token` and a `refresh_token`
-1. When using `kubectl`, use your `id_token` with the `--token` flag or add it directly to your `kubeconfig`
+1. When using `kubectl`, use your `id_token` with the `--token` command line argument or add it directly to your `kubeconfig`
 1. `kubectl` sends your `id_token` in a header called Authorization to the API server
 1. The API server will make sure the JWT signature is valid
 1. Check to make sure the `id_token` hasn't expired
@@ -323,10 +323,10 @@ To enable the plugin, configure the following flags on the API server:
 | `--oidc-issuer-url` | URL of the provider that allows the API server to discover public signing keys. Only URLs that use the `https://` scheme are accepted. This is typically the provider's discovery URL, changed to have an empty path. | If the issuer's OIDC discovery URL is `https://accounts.provider.example/.well-known/openid-configuration`, the value should be `https://accounts.provider.example` | Yes |
 | `--oidc-client-id` |  A client id that all tokens must be issued for. | kubernetes | Yes |
 | `--oidc-username-claim` | JWT claim to use as the user name. By default `sub`, which is expected to be a unique identifier of the end user. Admins can choose other claims, such as `email` or `name`, depending on their provider. However, claims other than `email` will be prefixed with the issuer URL to prevent naming clashes with other plugins. | sub | No |
-| `--oidc-username-prefix` | Prefix prepended to username claims to prevent clashes with existing names (such as `system:` users). For example, the value `oidc:` will create usernames like `oidc:jane.doe`. If this flag isn't provided and `--oidc-username-claim` is a value other than `email` the prefix defaults to `( Issuer URL )#` where `( Issuer URL )` is the value of `--oidc-issuer-url`. The value `-` can be used to disable all prefixing. | `oidc:` | No |
+| `--oidc-username-prefix` | Prefix prepended to username claims to prevent clashes with existing names (such as `system:` users). For example, the value `oidc:` will create usernames like `oidc:jane.doe`. If this argument isn't provided and `--oidc-username-claim` is a value other than `email` the prefix defaults to `( Issuer URL )#` where `( Issuer URL )` is the value of `--oidc-issuer-url`. The value `-` can be used to disable all prefixing. | `oidc:` | No |
 | `--oidc-groups-claim` | JWT claim to use as the user's group. If the claim is present it must be an array of strings. | groups | No |
 | `--oidc-groups-prefix` | Prefix prepended to group claims to prevent clashes with existing names (such as `system:` groups). For example, the value `oidc:` will create group names like `oidc:engineering` and `oidc:infra`. | `oidc:` | No |
-| `--oidc-required-claim` | A key=value pair that describes a required claim in the ID Token. If set, the claim is verified to be present in the ID Token with a matching value. Repeat this flag to specify multiple claims. | `claim=value` | No |
+| `--oidc-required-claim` | A key=value pair that describes a required claim in the ID Token. If set, the claim is verified to be present in the ID Token with a matching value. Repeat this argument to specify multiple claims. | `claim=value` | No |
 | `--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. Allowed values are: RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512. Values are defined by RFC 7518 https://tools.ietf.org/html/rfc7518#section-3.1. | `RS512` | No |
 
@@ -356,8 +356,7 @@ The API server also automatically reloads the authenticators when the configurat
 You can use `apiserver_authentication_config_controller_automatic_reload_last_timestamp_seconds` metric
 to monitor the last time the configuration was reloaded by the API server.
 
-You must specify the path to the authentication configuration using the `--authentication-config` flag
-on the API server. If you want to use command line flags instead of the configuration file, those will
+You must specify the path to the authentication configuration using the `--authentication-config` command line argument to the API server. If you want to use command line arguments instead of the configuration file, those will
 continue to work as-is. To access the new capabilities like configuring multiple authenticators,
 setting multiple audiences for an issuer, switch to using the configuration file.
 
@@ -375,13 +374,7 @@ If you want to switch to using structured authentication configuration, you have
 command line arguments, and use the configuration file instead.
 {{< /note >}}
 
-{{< feature-state feature_gate_name="StructuredAuthenticationConfigurationEgressSelector" >}}
-
-The _egressSelectorType_ field in the JWT issuer configuration allows you to specify which egress selector
-should be used for sending all traffic related to the issuer (discovery, JWKS, distributed claims, etc).
-This feature requires the `StructuredAuthenticationConfigurationEgressSelector` feature gate to be enabled.
-
-```yaml
+{{< highlight yaml "linenos=false,hl_lines=2-5" >}}
 ---
 #
 # CAUTION: this is an example configuration.
@@ -409,7 +402,7 @@ jwt:
     discoveryURL: https://discovery.example.com/.well-known/openid-configuration
     # PEM encoded CA certificates used to validate the connection when fetching
     # discovery information. If not set, the system verifier will be used.
-    # Same value as the content of the file referenced by the --oidc-ca-file flag.
+    # Same value as the content of the file referenced by the --oidc-ca-file command line argument.
     certificateAuthority: <PEM encoded CA certificates>    
     # audiences is the set of acceptable audiences the JWT must be issued to.
     # At least one of the entries must match the "aud" claim in presented JWTs.
@@ -420,6 +413,8 @@ jwt:
     audienceMatchPolicy: MatchAny
     # egressSelectorType is an indicator of which egress selection should be used for sending all traffic related
     # to this issuer (discovery, JWKS, distributed claims, etc).  If unspecified, no custom dialer is used.
+    # The StructuredAuthenticationConfigurationEgressSelector feature gate must be enabled
+    # before you can use the egressSelectorType field.
     # When specified, the valid choices are "controlplane" and "cluster".  These correspond to the associated
     # values in the --egress-selector-config-file.
     # - controlplane: for traffic intended to go to the control plane.
@@ -498,7 +493,7 @@ jwt:
     message: 'username cannot used reserved system: prefix'
   - expression: "user.groups.all(group, !group.startsWith('system:'))"
     message: 'groups cannot used reserved system: prefix'
-```
+{{< /highlight >}}
 
 * Claim validation rule expression
 
@@ -707,7 +702,15 @@ jwt:
   {{% /tab %}}
   {{< /tabs >}}
 
-###### Limitations
+##### JWT egress selector type
+
+{{< feature-state feature_gate_name="StructuredAuthenticationConfigurationEgressSelector" >}}
+
+The _egressSelectorType_ field in the JWT issuer configuration allows you to specify which egress selector
+should be used for sending all traffic related to the issuer (discovery, JWKS, distributed claims, etc).
+This feature requires the `StructuredAuthenticationConfigurationEgressSelector` feature gate to be enabled.
+
+##### Limitations {#oidc-limitations}
 
 1. Distributed claims do not work via [CEL](/docs/reference/using-api/cel/) expressions.
 
@@ -736,14 +739,14 @@ standard certificate generation tools.
 
 #### Using kubectl
 
-##### Option 1 - OIDC Authenticator
+##### Option 1 - OIDC authenticator
 
 The first option is to use the kubectl `oidc` authenticator, which sets the `id_token` as a bearer token
 for all requests and refreshes the token once it expires. After you've logged into your provider, use
 kubectl to add your `id_token`, `refresh_token`, `client_id`, and `client_secret` to configure the plugin.
 
 Providers that don't return an `id_token` as part of their refresh token response aren't supported
-by this plugin and should use "Option 2" below.
+by this plugin and should use [Option 2](#option-2-use-the-token-option) (specifying `--token`).
 
 ```bash
 kubectl config set-credentials USER_NAME \
@@ -789,18 +792,21 @@ users:
 Once your `id_token` expires, `kubectl` will attempt to refresh your `id_token` using your `refresh_token`
 and `client_secret` storing the new values for the `refresh_token` and `id_token` in your `.kube/config`.
 
-##### Option 2 - Use the `--token` Option
+##### Option 2 - Use the `--token` command line argument {#option-2-use-the-token-option}
 
-The `kubectl` command lets you pass in a token using the `--token` option.
+The `kubectl` command lets you pass in a token using the `--token` command line argument.
 Copy and paste the `id_token` into this option:
 
 ```bash
 kubectl --token=eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL21sYi50cmVtb2xvLmxhbjo4MDQzL2F1dGgvaWRwL29pZGMiLCJhdWQiOiJrdWJlcm5ldGVzIiwiZXhwIjoxNDc0NTk2NjY5LCJqdGkiOiI2RDUzNXoxUEpFNjJOR3QxaWVyYm9RIiwiaWF0IjoxNDc0NTk2MzY5LCJuYmYiOjE0NzQ1OTYyNDksInN1YiI6Im13aW5kdSIsInVzZXJfcm9sZSI6WyJ1c2VycyIsIm5ldy1uYW1lc3BhY2Utdmlld2VyIl0sImVtYWlsIjoibXdpbmR1QG5vbW9yZWplZGkuY29tIn0.f2As579n9VNoaKzoF-dOQGmXkFKf1FMyNV0-va_B63jn-_n9LGSCca_6IVMP8pO-Zb4KvRqGyTP0r3HkHxYy5c81AnIh8ijarruczl-TK_yF5akjSTHFZD-0gRzlevBDiH8Q79NAr-ky0P4iIXS8lY9Vnjch5MF74Zx0c3alKJHJUnnpjIACByfF2SCaYzbWFMUNat-K1PaUk5-ujMBG7yYnr95xD-63n8CO8teGUAAEMx6zRjzfhnhbzX-ajwZLGwGUBT4WqjMs70-6a7_8gZmLZb2az1cZynkFRj2BaCkVT3A2RrjeEwZEtGXlMqKJ1_I2ulrOVsYx01_yD35-rw get nodes
 ```
 
-### Webhook Token Authentication
 
-Webhook authentication is a hook for verifying bearer tokens.
+### Webhook token authentication
+
+Kubernetes _webhook authentication_ is a mechanism to make an HTTP callout for verifying bearer tokens.
+
+In terms of how you configure the API server:
 
 * `--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.
@@ -1002,25 +1008,53 @@ An unsuccessful request would return:
 {{% /tab %}}
 {{< /tabs >}}
 
-### Authenticating Proxy
+### Authenticating reverse proxy {#authenticating-proxy}
+
+{{< warning >}}
+If you have a certificate authority (CA) that is also used in a different context, **do not** trust
+that certificate authority to identify authenticating proxy clients, unless you understand the
+risks and the mechanisms to protect that CA's usage.
+{{< /warning >}}
 
 The API server can be configured to identify users from request header values, such as `X-Remote-User`.
-It is designed for use in combination with an authenticating proxy, which sets the request header value.
-
-* `--requestheader-username-headers` Required, case-insensitive. Header names to check, in order,
-  for the user identity. The first header containing a value is used as the username.
-* `--requestheader-group-headers` 1.6+. Optional, case-insensitive. "X-Remote-Group" is suggested.
-  Header names to check, in order, for the user's groups. All values in all specified headers are used as group names.
-* `--requestheader-extra-headers-prefix` 1.6+. Optional, case-insensitive. "X-Remote-Extra-" is suggested.
-  Header prefixes to look for to determine extra information about the user (typically used by the configured authorization plugin).
+It is designed for use in combination with an _authenticating proxy_ that sets these headers.
+
+The command line arguments to configure this mode are:
+
+<!-- trailing whitespace (exactly two spaces) is significant in the following list -->
+
+`--requestheader-client-ca-file`
+: _Required._
+  Path to a PEM-encoded certificate bundle.  
+  A valid [client certificate](#reverse-proxy-client-certificate)
+  must be presented and validated against the certificate authorities in the specified file before the
+  request headers are checked for user names.
+
+`--requestheader-allowed-names`
+: _Optional._ Comma-separated list of Common Name values (CNs).  
+  If set, a valid client
+  certificate with a CN in the specified list must be presented before the request headers are checked
+  for user names. If empty, any CN is allowed.
+
+`--requestheader-username-headers`
+: _Required; case-insensitive._ Header names to check, in order, for the user identity.  
+  The first header containing a value is used as the username.
+
+`--requestheader-group-headers`
+: _Optional; case-insensitive._
+  Header names to check, in order, for the user's groups.  
+  `X-Remote-Group` is suggested.
+  All values in all specified headers are used as group names.
+
+`--requestheader-extra-headers-prefix`
+: _Optional; case-insensitive._
+  Header prefixes to look for to determine extra information about the user.  
+  `X-Remote-Extra-` is suggested.
+  Extra data is typically used by the configured authorization plugin(s).
   Any headers beginning with any of the specified prefixes have the prefix removed.
   The remainder of the header name is lowercased and [percent-decoded](https://tools.ietf.org/html/rfc3986#section-2.1)
   and becomes the extra key, and the header value is the extra value.
 
-{{< note >}}
-Prior to 1.11.3 (and 1.10.7, 1.9.11), the extra key could only contain characters which
-were [legal in HTTP header labels](https://tools.ietf.org/html/rfc7230#section-3.2.6).
-{{< /note >}}
 
 For example, with this configuration:
 
@@ -1057,17 +1091,53 @@ extra:
   - profile
 ```
 
+{{< note >}}
+Prior to Kubernetes 1.11.3 (and 1.10.7, 1.9.11), the `extra` key could only contain characters that
+were [legal in HTTP header labels](https://tools.ietf.org/html/rfc7230#section-3.2.6).
+{{< /note >}}
+
+#### Client certificate {#reverse-proxy-client-certificate}
+
 In order to prevent header spoofing, the authenticating proxy is required to present a valid client
 certificate to the API server for validation against the specified CA before the request headers are
-checked. WARNING: do **not** reuse a CA that is used in a different context unless you understand
+checked.
+
+<!-- deliberately repeating the earlier warning -->
+Do **not** reuse a CA that is used in a different context unless you understand
 the risks and the mechanisms to protect the CA's usage.
 
-* `--requestheader-client-ca-file` Required. PEM-encoded certificate bundle. A valid client certificate
-  must be presented and validated against the certificate authorities in the specified file before the
-  request headers are checked for user names.
-* `--requestheader-allowed-names` Optional. List of Common Name values (CNs). If set, a valid client
-  certificate with a CN in the specified list must be presented before the request headers are checked
-  for user names. If empty, any CN is allowed.
+### Static token file integration {#static-token-file}
+
+The API server reads static bearer tokens from a file when given the `--token-auth-file=<SOMEFILE>`
+option on the command line.
+In Kubernetes {{< skew currentVersion >}}, tokens last indefinitely, and the token list cannot be
+changed without restarting the API server.
+
+The token file is a CSV file with a minimum of 3 columns: token, user name, user uid,
+followed by a comma-separated list of optional group names.
+
+
+{{< note >}}
+If you have more than one group, the column must be double quoted e.g.
+
+```conf
+token,user,uid,"group1,group2,group3"
+```
+{{< /note >}}
+
+Using a static token file is appropriate for tokens that by their nature
+are long-lived, static, and perhaps may never be rotated. It is also useful
+when the client is local to a particular API server within the control plane,
+such as a monitoring agent.
+
+If you use this method during cluster provisioning, and then transition to
+a different authentication method that will be used longer term, you
+should deactivate the token that was used for bootstrapping (this requires
+a restart of each API server.
+
+For other circumstances, and especially where very prompt token rotation is
+important, the Kubernetes project recommends using a
+[webhook token authenticator](#webhook-token-authentication) instead of this mechanism.
 
 ## Anonymous requests