diff --git a/content/en/docs/reference/access-authn-authz/authentication.md b/content/en/docs/reference/access-authn-authz/authentication.md index f1c773515729e..8fa5206d0f7c8 100644 --- a/content/en/docs/reference/access-authn-authz/authentication.md +++ b/content/en/docs/reference/access-authn-authz/authentication.md @@ -270,7 +270,7 @@ kubectl create token jenkins eyJhbGciOiJSUzI1NiIsImtp... ``` -The created token is a signed JSON Web Token (JWT). +The created token is a signed [JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519) (JWT). The signed JWT can be used as a bearer token to authenticate as the given service account. See [above](#putting-a-bearer-token-in-a-request) for how the token is included @@ -287,9 +287,11 @@ Secrets can authenticate as the service account. Be cautious when granting permi to service accounts and read or write capabilities for Secrets. {{< /warning >}} + + ## External integrations -Kubernetes has native support for OpenID Connect (OIDC); see [OpenID Connect tokens](#openid-connect-tokens). +Kubernetes has native support for JWT and for OpenID Connect (OIDC); see [JSON Web Token authentication](#json-web-token-authentication). 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 @@ -304,7 +306,35 @@ If you do issue certificates to clients, it is up to you (as a cloud platform ad to make sure that the certificate validity period, and other design choices you make, provide a suitable level of security. -### OpenID Connect tokens +### JSON Web Token authentication + +You can configure Kubernetes to authenticate users using [JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519) +(JWT) compliant tokens. JWT authentication mechanism is used for the ServiceAccount tokens that Kubernetes itself issues, +and you can also use it to integrate with other identity sources. + +The authenticator attempts to parse a raw ID token, verify it's been signed by the configured issuer. +For externally issued tokens, the public key to verify the signature is discovered from the issuer's public endpoint using OIDC discovery. + +The minimum valid JWT payload **must** contain the following claims: + +```javascript +{ + "iss": "https://example.com", // must match the issuer.url + "aud": ["my-app"], // at least one of the entries in issuer.audiences must match the "aud" claim in presented JWTs. + "exp": 1234567890, // token expiration as Unix time (the number of seconds elapsed since January 1, 1970 UTC) + "": "user" // this is the username claim configured in the claimMappings.username.claim or claimMappings.username.expression +} +``` + +#### 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. + +#### 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. @@ -392,21 +422,6 @@ To enable the plugin, configure the following command line arguments for the API {{< feature-state feature_gate_name="StructuredAuthenticationConfiguration" >}} -JWT Authenticator is an authenticator to authenticate Kubernetes users using JWT compliant tokens. -The authenticator will attempt to parse a raw ID token, verify it's been signed by the configured issuer. -The public key to verify the signature is discovered from the issuer's public endpoint using OIDC discovery. - -The minimum valid JWT payload must contain the following claims: - -```json -{ - "iss": "https://example.com", // must match the issuer.url - "aud": ["my-app"], // at least one of the entries in issuer.audiences must match the "aud" claim in presented JWTs. - "exp": 1234567890, // token expiration as Unix time (the number of seconds elapsed since January 1, 1970 UTC) - "": "user" // this is the username claim configured in the claimMappings.username.claim or claimMappings.username.expression -} -``` - The configuration file approach allows you to configure multiple JWT authenticators, each with a unique `issuer.url` and `issuer.discoveryURL`. The configuration file even allows you to specify [CEL](/docs/reference/using-api/cel/) expressions to map claims to user attributes, and to validate claims and user information. @@ -756,13 +771,7 @@ jwt: {{% /tab %}} {{< /tabs >}} -##### 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}