Skip to content

Commit 01fc1f6

Browse files
committed
Revise authn reference mentions of JWT
Moving existing content to explain it better.
1 parent 1194953 commit 01fc1f6

File tree

1 file changed

+33
-24
lines changed

1 file changed

+33
-24
lines changed

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

Lines changed: 33 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -270,7 +270,7 @@ kubectl create token jenkins
270270
eyJhbGciOiJSUzI1NiIsImtp...
271271
```
272272

273-
The created token is a signed JSON Web Token (JWT).
273+
The created token is a signed [JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519) (JWT).
274274

275275
The signed JWT can be used as a bearer token to authenticate as the given service
276276
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
287287
to service accounts and read or write capabilities for Secrets.
288288
{{< /warning >}}
289289

290+
291+
290292
## External integrations
291293

292-
Kubernetes has native support for OpenID Connect (OIDC); see [OpenID Connect tokens](#openid-connect-tokens).
294+
Kubernetes has native support for JWT and for OpenID Connect (OIDC); see [JSON Web Token authentication](#json-web-token-authentication).
293295

294296
Integrations with other authentication protocols (for example: LDAP, SAML, Kerberos, alternate X.509 schemes)
295297
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
304306
to make sure that the certificate validity period, and other design choices you make, provide a
305307
suitable level of security.
306308

307-
### OpenID Connect tokens
309+
### JSON Web Token authentication
310+
311+
You can configure Kubernetes to authenticate users using [JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519)
312+
(JWT) compliant tokens. JWT authentication mechanism is used for the ServiceAccount tokens that Kubernetes itself issues,
313+
and you can also use it to integrate with other identity sources.
314+
315+
The authenticator attempts to parse a raw ID token, verify it's been signed by the configured issuer.
316+
For externally issued tokens, the public key to verify the signature is discovered from the issuer's public endpoint using OIDC discovery.
317+
318+
The minimum valid JWT payload **must** contain the following claims:
319+
320+
```javascript
321+
{
322+
"iss": "https://example.com", // must match the issuer.url
323+
"aud": ["my-app"], // at least one of the entries in issuer.audiences must match the "aud" claim in presented JWTs.
324+
"exp": 1234567890, // token expiration as Unix time (the number of seconds elapsed since January 1, 1970 UTC)
325+
"<username-claim>": "user" // this is the username claim configured in the claimMappings.username.claim or claimMappings.username.expression
326+
}
327+
```
328+
329+
#### JWT egress selector type
330+
331+
{{< feature-state feature_gate_name="StructuredAuthenticationConfigurationEgressSelector" >}}
332+
333+
The `egressSelectorType` field in the JWT issuer configuration allows you to specify which _egress selector_
334+
should be used for sending all traffic related to the issuer (discovery, JWKS, distributed claims, etc).
335+
This feature requires the `StructuredAuthenticationConfigurationEgressSelector` feature gate to be enabled.
336+
337+
#### OpenID Connect tokens
308338

309339
[OpenID Connect](https://openid.net/connect/) is a flavor of OAuth2 supported by
310340
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
392422

393423
{{< feature-state feature_gate_name="StructuredAuthenticationConfiguration" >}}
394424

395-
JWT Authenticator is an authenticator to authenticate Kubernetes users using JWT compliant tokens.
396-
The authenticator will attempt to parse a raw ID token, verify it's been signed by the configured issuer.
397-
The public key to verify the signature is discovered from the issuer's public endpoint using OIDC discovery.
398-
399-
The minimum valid JWT payload must contain the following claims:
400-
401-
```json
402-
{
403-
"iss": "https://example.com", // must match the issuer.url
404-
"aud": ["my-app"], // at least one of the entries in issuer.audiences must match the "aud" claim in presented JWTs.
405-
"exp": 1234567890, // token expiration as Unix time (the number of seconds elapsed since January 1, 1970 UTC)
406-
"<username-claim>": "user" // this is the username claim configured in the claimMappings.username.claim or claimMappings.username.expression
407-
}
408-
```
409-
410425
The configuration file approach allows you to configure multiple JWT authenticators, each with a unique
411426
`issuer.url` and `issuer.discoveryURL`. The configuration file even allows you to specify [CEL](/docs/reference/using-api/cel/)
412427
expressions to map claims to user attributes, and to validate claims and user information.
@@ -756,13 +771,7 @@ jwt:
756771
{{% /tab %}}
757772
{{< /tabs >}}
758773

759-
##### JWT egress selector type
760774

761-
{{< feature-state feature_gate_name="StructuredAuthenticationConfigurationEgressSelector" >}}
762-
763-
The _egressSelectorType_ field in the JWT issuer configuration allows you to specify which egress selector
764-
should be used for sending all traffic related to the issuer (discovery, JWKS, distributed claims, etc).
765-
This feature requires the `StructuredAuthenticationConfigurationEgressSelector` feature gate to be enabled.
766775

767776
##### Limitations {#oidc-limitations}
768777

0 commit comments

Comments
 (0)