Skip to content

Revise authn reference mentions of JWT #53350

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Revise authn reference mentions of JWT #53350

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 33 additions & 24 deletions content/en/docs/reference/access-authn-authz/authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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)
"<username-claim>": "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.
Expand Down Expand Up @@ -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)
"<username-claim>": "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.
Expand Down Expand Up @@ -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}

Expand Down