From 4a912fb9b110c7d32d1e694b88b116b06dc52a86 Mon Sep 17 00:00:00 2001 From: Justin Cranford Date: Thu, 21 Jul 2022 11:27:58 -0400 Subject: [PATCH 01/14] Add PKC JWKSet reloading to JWT authentication doc --- .../authentication/jwt-realm.asciidoc | 49 ++++++++++++++----- 1 file changed, 37 insertions(+), 12 deletions(-) diff --git a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc index 24edf2b2a9597..d06af54837edc 100644 --- a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc @@ -12,7 +12,11 @@ between the _client_ that is connecting to {es}, and the _user_ on whose behalf the request should run. The JWT identifies the user, and a separate credential is used to authenticate the client. -A common scenario that uses JWTs is when an existing front-end application uses +TIP: If JWTs are issued for the client, then the client is the JWT user. +To identify a different user, use the `es-security-runas-user` header. +See <>. + +A common scenario for JWTs is when an existing front-end application uses OpenID Connect (OIDC) as an authentication method, and then accesses {es} on behalf of the authenticated user. @@ -27,7 +31,7 @@ _ID token_, which uses the JWT format. If the ID token is presented to a JWT realm, {es} can use it to authenticate, identify, and authorize an individual user. -NOTE: Because JWTs are external to {es}, you can define a custom workflow +NOTE: Because JWTs are obtained external to {es}, you can define a custom workflow instead of using the OIDC workflow. However, the JWT format must still be JSON Web Signature (JWS). The JWS header and JWS signature are validated using OIDC ID token validation rules. @@ -196,6 +200,10 @@ NOTE: You can relax validation of any of the time-based claims by setting validating JWTs with respect to their authentication time (`auth_time`), creation (`iat`), not before (`nbf`), and expiration times (`exp`). +`iss`:: +(Required, String) Denotes the issuer that created the ID token. The value must +be an exact, case-sensitive match to the value in the `allowed_issuer` setting. + `aud`:: (Required, String) Indicates the audiences that the ID token is for, expressed as a comma-separated value (CSV). One of the values must be an exact, case-sensitive @@ -209,10 +217,6 @@ milliseconds since epoch. (Required, integer) Time that the ID token was issued, expressed in UTC milliseconds since epoch. -`iss`:: -(Required, String) Denotes the issuer that created the ID token. The value must -be an exact, case-sensitive match to the value in the `allowed_issuer` setting. - `nbf`:: (Optional, integer) Indicates the time before which the JWT must not be accepted, expressed as UTC milliseconds since epoch. @@ -259,7 +263,7 @@ setting `claims.dn_pattern` to extract a substring value. ==== JWT realm authorization The JWT realm supports authorization with the create or update role mappings API, or delegating authorization to another realm. You cannot use these methods -simultaneously, so choose whichever works best for your environment. +simultaneously, so choose whichever works best for your environment. IMPORTANT: You cannot map roles in the JWT realm using the `role_mapping.yml` file. @@ -352,7 +356,7 @@ linked to realm `native1`. [[jwt-realm-runas]] ===== Applying the `run_as` privilege to JWT realm users -{es} can retrieve roles for a JWT user through either role mapping or +{es} can retrieve roles for a JWT user through either role mapping or delegated authorization. Regardless of which option you choose, you can apply the <> to a role so that a user can submit authenticated requests to "run as" a different user. To submit requests as @@ -415,7 +419,7 @@ the `jwt_role1` role that you mapped to this user in the JWT realm: "metadata":{"jwt_claim_email":"user2@something.example.com","jwt_claim_aud":["es01","es02","es03"], "jwt_claim_sub":"user2","jwt_claim_iss":"my-issuer"},"enabled":true,"authentication_realm": {"name":"jwt2","type":"jwt"},"lookup_realm":{"name":"jwt2","type":"jwt"},"authentication_type":"realm"} -% +% ---- If you want to specify a request as the `run_as` user, include the @@ -435,9 +439,30 @@ and {es} used the `jwt_role1` role: ---- {"username":"user123_runas","roles":["jwt_role1"],"full_name":null,"email":null,"metadata":{}, "enabled":true,"authentication_realm":{"name":"jwt2","type":"jwt"},"lookup_realm":{"name":"native", -"type":"native"},"authentication_type":"realm"}% +"type":"native"},"authentication_type":"realm"}% ---- +[[jwt-realm-jwkset-reloading]] +===== JWKSet reloading +{es} loads PKC JWKSet, HMAC JWKSet, and HMAC OIDC JWK at startup. Load failures, parse errors, +and configuration errors will prevent a node from starting (and restarting). + +At runtime, JWT realms can also reload PKC JWKSet. Reloading of RSA and EC public keys is +supported for HTTPS URL or local file only. + +CAUTION: HMAC reloading from {es} keystore is not supported at this time. + +JWT issuers may rotate their PKC JWKs frequently (ex: daily). Since frequent {es} restarts are +undesirable, PKC JWKSet reloads are supported at runtime. PKC JWKSet reload is triggered by +signature validation failure. + +IMPORTANT: All other validations must pass before a signature failure can trigger a PKC JWKSet reload. +Client authentication is strongly recommended. Narrow scope for allowed algorithms, allowed issuer, +allowed audiences, and clock skew are also strongly recommended. + +If concurrent JWT authentication signature failures trigger reloads within an {es} node, a single +reload is done. If consecutive requests trigger reloads, each one triggers a reload attempt. + [[hmac-oidc-example]] ==== Authorizing to the JWT realm with an OIDC HMAC key The following settings are for a JWT issuer, {es}, and a client of {es}. The @@ -477,7 +502,7 @@ xpack.security.authc.realms.jwt.jwt8.client_authentication.type: shared_secret realm chain on {ecloud}. ===== JWT realm secure settings -After defining the realm settings, use the +After defining the realm settings, use the {ref}/elasticsearch-keystore.html[`elasticsearch-keystore`] tool to add the following secure settings to the {es} keystore. In {ecloud}, you define settings for the {es} keystore under **Security** in your deployment. @@ -536,5 +561,5 @@ JWT realm itself. "metadata":{"jwt_claim_email":"user2@something.example.com","jwt_claim_aud":["es01","es02","es03"], "jwt_claim_sub":"user2","jwt_claim_iss":"my-issuer"},"enabled":true,"authentication_realm": {"name":"jwt2","type":"jwt"},"lookup_realm":{"name":"jwt2","type":"jwt"},"authentication_type":"realm"} -% +% ---- From 714b4d4d47f835659f2db9e134eca390bb336816 Mon Sep 17 00:00:00 2001 From: Justin Cranford Date: Fri, 22 Jul 2022 13:01:54 -0400 Subject: [PATCH 02/14] Clarify TIP about JWTs issued for client applications instead of end-users. Also, do another pass over the JWKSet reloading section. --- .../authentication/jwt-realm.asciidoc | 45 +++++++++++-------- 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc index d06af54837edc..0b5dcc1e9bebd 100644 --- a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc @@ -12,10 +12,6 @@ between the _client_ that is connecting to {es}, and the _user_ on whose behalf the request should run. The JWT identifies the user, and a separate credential is used to authenticate the client. -TIP: If JWTs are issued for the client, then the client is the JWT user. -To identify a different user, use the `es-security-runas-user` header. -See <>. - A common scenario for JWTs is when an existing front-end application uses OpenID Connect (OIDC) as an authentication method, and then accesses {es} on behalf of the authenticated user. @@ -23,6 +19,12 @@ on behalf of the authenticated user. TIP: If the front-end application does not exist, you can use the <> instead. +TIP: If JWTs are issued for the front-end application, the JWT realm client is +the JWT user. That is not supported by OIDC flows. However, it may be supported +by bespoke JWT issuer flows. Use the JWT for authentication, and the +`es-security-runas-user` HTTP request header to specify a different user. +See <>. + [[jwt-realm-oidc]] ==== JWT uses OIDC workflows JWT authentication in {es} is derived from OIDC workflows, where different @@ -443,25 +445,32 @@ and {es} used the `jwt_role1` role: ---- [[jwt-realm-jwkset-reloading]] -===== JWKSet reloading -{es} loads PKC JWKSet, HMAC JWKSet, and HMAC OIDC JWK at startup. Load failures, parse errors, -and configuration errors will prevent a node from starting (and restarting). - -At runtime, JWT realms can also reload PKC JWKSet. Reloading of RSA and EC public keys is -supported for HTTPS URL or local file only. +===== PKC JWKSet reloading +JWT authentication supports signature verification using PKC (Public Key Cryptography) or HMAC algorithms. +PKC JWKSet can contain public RSA and EC keys. HMAC JWKSet or HMAC OIDC JWK contain secret keys. +JWT realms load their PKC JWKSet, and HMAC JWKSet or HMAC OIDC JWK, at startup. +JWT realms can also reload PKC JWKSet contents at runtime. CAUTION: HMAC reloading from {es} keystore is not supported at this time. -JWT issuers may rotate their PKC JWKs frequently (ex: daily). Since frequent {es} restarts are -undesirable, PKC JWKSet reloads are supported at runtime. PKC JWKSet reload is triggered by -signature validation failure. +Load failures, parse errors, and configuration errors will prevent a node from starting (and restarting); +that applies equally to PKC or HMAC. At runtime, though, only PKC reloads are supported, and errors +are handled gracefully. + +JWT issuers typically rotate PKC JWKs more frequently (ex: daily) than HMAC JWKs, because PKC is designed +for easy distribution and sharing of public keys. Since frequent {es} restarts would be undesirable, +PKC JWKSet reloading is supported at runtime. Reload is triggered by signature validation failure. + +IMPORTANT: All other JWT realm validations must be checked and pass before a signature failure can trigger +a PKC JWKSet reload. Client authentication is strongly recommended. Narrow scoping of allowed algorithms, +allowed issuer, allowed audiences, and clock skew are also strongly recommended. -IMPORTANT: All other validations must pass before a signature failure can trigger a PKC JWKSet reload. -Client authentication is strongly recommended. Narrow scope for allowed algorithms, allowed issuer, -allowed audiences, and clock skew are also strongly recommended. +If multiple JWT authentication signature failures happen at the same time within an {es} node, reloads are +combined to reduce the reloads sent externally. -If concurrent JWT authentication signature failures trigger reloads within an {es} node, a single -reload is done. If consecutive requests trigger reloads, each one triggers a reload attempt. +In other words, if JWT signature failures trigger PKC JWKSet reloads in different {es} nodes, that means +separate reload requests will be sent externally. If JWT signature failures trigger PKC JWKSet reload at +different times within a single {es} node, that also means separate reload requests will be sent externally. [[hmac-oidc-example]] ==== Authorizing to the JWT realm with an OIDC HMAC key From 081c6f05105fec510e734f795cee5faf6055bacd Mon Sep 17 00:00:00 2001 From: Justin Cranford Date: Fri, 22 Jul 2022 15:06:15 -0400 Subject: [PATCH 03/14] Another pass over JWKSet reloading section. --- .../authentication/jwt-realm.asciidoc | 44 +++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc index 0b5dcc1e9bebd..5333beab76b66 100644 --- a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc @@ -19,15 +19,9 @@ on behalf of the authenticated user. TIP: If the front-end application does not exist, you can use the <> instead. -TIP: If JWTs are issued for the front-end application, the JWT realm client is -the JWT user. That is not supported by OIDC flows. However, it may be supported -by bespoke JWT issuer flows. Use the JWT for authentication, and the -`es-security-runas-user` HTTP request header to specify a different user. -See <>. - [[jwt-realm-oidc]] ==== JWT uses OIDC workflows -JWT authentication in {es} is derived from OIDC workflows, where different +JWT authentication in {es} is derived from OIDC user workflows, where different tokens can be issued by an OIDC Provider (OP). One possible token is an _ID token_, which uses the JWT format. If the ID token is presented to a JWT realm, {es} can use it to authenticate, identify, and authorize an individual @@ -43,6 +37,11 @@ stronger security guarantees than the JWT realm and is preferred for any use case where {es} can act as an OIDC RP. The OIDC realm is the only supported way to enable OIDC authentication in {kib}. +TIP: If JWTs are issued for the front-end application, the realm client is the JWT user. +That is not supported by OIDC flows, but it may be supported by bespoke JWT issuers. +In that case, use the client secret and JWT for the client application, and the +`es-security-runas-user` HTTP request header for the different user. See <>. + [[jwt-realm-configuration]] ==== Configure {es} to use a JWT realm @@ -448,29 +447,30 @@ and {es} used the `jwt_role1` role: ===== PKC JWKSet reloading JWT authentication supports signature verification using PKC (Public Key Cryptography) or HMAC algorithms. PKC JWKSet can contain public RSA and EC keys. HMAC JWKSet or HMAC OIDC JWK contain secret keys. -JWT realms load their PKC JWKSet, and HMAC JWKSet or HMAC OIDC JWK, at startup. -JWT realms can also reload PKC JWKSet contents at runtime. +JWT issuers typically rotate PKC JWKs more frequently (ex: daily), because RSA and EC public keys are +easier to distribute than HMAC secret keys. -CAUTION: HMAC reloading from {es} keystore is not supported at this time. +JWT realms load a PKC JWKSet, and a HMAC JWKSet or HMAC OIDC JWK, at startup. +JWT realms can also reload PKC JWKSet contents at runtime; reload is triggered by signature validation failures. -Load failures, parse errors, and configuration errors will prevent a node from starting (and restarting); -that applies equally to PKC or HMAC. At runtime, though, only PKC reloads are supported, and errors -are handled gracefully. +CAUTION: HMAC JWKSet or HMAC OIDC JWK reloading is not supported at this time. -JWT issuers typically rotate PKC JWKs more frequently (ex: daily) than HMAC JWKs, because PKC is designed -for easy distribution and sharing of public keys. Since frequent {es} restarts would be undesirable, -PKC JWKSet reloading is supported at runtime. Reload is triggered by signature validation failure. +Load failures, parse errors, and configuration errors prevent a node from starting (and restarting). +However, runtime PKC reload errors and recoveries are handled gracefully. -IMPORTANT: All other JWT realm validations must be checked and pass before a signature failure can trigger -a PKC JWKSet reload. Client authentication is strongly recommended. Narrow scoping of allowed algorithms, -allowed issuer, allowed audiences, and clock skew are also strongly recommended. +IMPORTANT: All other JWT realm validations are checked before a signature failure can trigger a +PKC JWKSet reload. Client authentication is strongly recommended. Narrow scoping of allowed algorithms, +allowed issuer, allowed audiences, and clock skew are all strongly recommended too. That way only trusted +client applications and realm-specific JWT will be able to trigger PKC reload attempts. If multiple JWT authentication signature failures happen at the same time within an {es} node, reloads are combined to reduce the reloads sent externally. -In other words, if JWT signature failures trigger PKC JWKSet reloads in different {es} nodes, that means -separate reload requests will be sent externally. If JWT signature failures trigger PKC JWKSet reload at -different times within a single {es} node, that also means separate reload requests will be sent externally. +IMPORTANT: If JWT signature failures trigger PKC JWKSet reloads in different {es} nodes, reload +requests cannot be combined. + +IMPORTANT: If JWT signature failures trigger PKC JWKSet reloads in the same {es} node, but at different +times, separate reload requests will not be combined. [[hmac-oidc-example]] ==== Authorizing to the JWT realm with an OIDC HMAC key From 5bf0615595cd00b41b2802ec91a94c9077f42406 Mon Sep 17 00:00:00 2001 From: Justin Cranford Date: Fri, 22 Jul 2022 15:12:03 -0400 Subject: [PATCH 04/14] Use JWKs and UTF-8 consistently throughout the document. --- .../authentication/jwt-realm.asciidoc | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc index 5333beab76b66..5c1977473d2b0 100644 --- a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc @@ -129,7 +129,7 @@ The file can be removed after you load the contents into the {es} keystore. [NOTE] ==== Using the JWKS is preferred. However, you can add an HMAC key in string format -using the following command. This format is compatible with OIDC HMAC keys, but +using the following command. This format is compatible with HMAC UTF-8 keys, but only supports a single key with no attributes. You can only use one HMAC format (either `hmac_jwkset` or `hmac_key`) simultaneously. @@ -444,36 +444,36 @@ and {es} used the `jwt_role1` role: ---- [[jwt-realm-jwkset-reloading]] -===== PKC JWKSet reloading +===== PKC JWKS reloading JWT authentication supports signature verification using PKC (Public Key Cryptography) or HMAC algorithms. -PKC JWKSet can contain public RSA and EC keys. HMAC JWKSet or HMAC OIDC JWK contain secret keys. +PKC JWKS can contain public RSA and EC keys. HMAC JWKS or HMAC UTF-8 JWK contain secret keys. JWT issuers typically rotate PKC JWKs more frequently (ex: daily), because RSA and EC public keys are -easier to distribute than HMAC secret keys. +designed to be easier to distribute than secret keys like HMAC. -JWT realms load a PKC JWKSet, and a HMAC JWKSet or HMAC OIDC JWK, at startup. -JWT realms can also reload PKC JWKSet contents at runtime; reload is triggered by signature validation failures. +JWT realms load a PKC JWKS, and a HMAC JWKS or HMAC UTF-8 JWK, at startup. +JWT realms can also reload PKC JWKS contents at runtime; reload is triggered by signature validation failures. -CAUTION: HMAC JWKSet or HMAC OIDC JWK reloading is not supported at this time. +CAUTION: HMAC JWKS or HMAC UTF-8 JWK reloading is not supported at this time. Load failures, parse errors, and configuration errors prevent a node from starting (and restarting). However, runtime PKC reload errors and recoveries are handled gracefully. IMPORTANT: All other JWT realm validations are checked before a signature failure can trigger a -PKC JWKSet reload. Client authentication is strongly recommended. Narrow scoping of allowed algorithms, +PKC JWKS reload. Client authentication is strongly recommended. Narrow scoping of allowed algorithms, allowed issuer, allowed audiences, and clock skew are all strongly recommended too. That way only trusted client applications and realm-specific JWT will be able to trigger PKC reload attempts. If multiple JWT authentication signature failures happen at the same time within an {es} node, reloads are combined to reduce the reloads sent externally. -IMPORTANT: If JWT signature failures trigger PKC JWKSet reloads in different {es} nodes, reload +IMPORTANT: If JWT signature failures trigger PKC JWKS reloads in different {es} nodes, reload requests cannot be combined. -IMPORTANT: If JWT signature failures trigger PKC JWKSet reloads in the same {es} node, but at different +IMPORTANT: If JWT signature failures trigger PKC JWKS reloads in the same {es} node, but at different times, separate reload requests will not be combined. [[hmac-oidc-example]] -==== Authorizing to the JWT realm with an OIDC HMAC key +==== Authorizing to the JWT realm with an HMAC UTF-8 key The following settings are for a JWT issuer, {es}, and a client of {es}. The example HMAC key is in an OIDC format that's compatible with HMAC. The key bytes are the UTF-8 encoding of the UNICODE characters. @@ -490,7 +490,7 @@ The following values are for the bespoke JWT issuer. Issuer: iss8 Audiences: aud8 Algorithms: HS256 -HMAC OIDC: hmac-oidc-key-string-for-hs256-algorithm +HMAC UTF-8: hmac-oidc-key-string-for-hs256-algorithm ---- // NOTCONSOLE From f723b86fdb0dda172bf36836f1cf3d88dde4645a Mon Sep 17 00:00:00 2001 From: Justin Cranford Date: Fri, 22 Jul 2022 15:34:34 -0400 Subject: [PATCH 05/14] Nit. --- x-pack/docs/en/security/authentication/jwt-realm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc index 5c1977473d2b0..3ffcfce279aeb 100644 --- a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc @@ -461,7 +461,7 @@ However, runtime PKC reload errors and recoveries are handled gracefully. IMPORTANT: All other JWT realm validations are checked before a signature failure can trigger a PKC JWKS reload. Client authentication is strongly recommended. Narrow scoping of allowed algorithms, allowed issuer, allowed audiences, and clock skew are all strongly recommended too. That way only trusted -client applications and realm-specific JWT will be able to trigger PKC reload attempts. +client applications and realm-specific user JWT will be able to trigger PKC reload attempts. If multiple JWT authentication signature failures happen at the same time within an {es} node, reloads are combined to reduce the reloads sent externally. From b08c7a9079b4329770c36827a970600be300268d Mon Sep 17 00:00:00 2001 From: Justin Cranford <89857999+justincr-elastic@users.noreply.github.com> Date: Fri, 22 Jul 2022 17:34:10 -0400 Subject: [PATCH 06/14] Update x-pack/docs/en/security/authentication/jwt-realm.asciidoc Co-authored-by: Adam Locke --- x-pack/docs/en/security/authentication/jwt-realm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc index 3ffcfce279aeb..7e7ae7622dac6 100644 --- a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc @@ -446,7 +446,7 @@ and {es} used the `jwt_role1` role: [[jwt-realm-jwkset-reloading]] ===== PKC JWKS reloading JWT authentication supports signature verification using PKC (Public Key Cryptography) or HMAC algorithms. -PKC JWKS can contain public RSA and EC keys. HMAC JWKS or HMAC UTF-8 JWK contain secret keys. +PKC JSON Web Token Key Sets (JWKS) can contain public RSA and EC keys. HMAC JWKS or an HMAC UTF-8 JWK contain secret keys. JWT issuers typically rotate PKC JWKs more frequently (ex: daily), because RSA and EC public keys are designed to be easier to distribute than secret keys like HMAC. From f4b76ec7b0bf43a3bf85916f7a88bafaa5575daf Mon Sep 17 00:00:00 2001 From: Justin Cranford <89857999+justincr-elastic@users.noreply.github.com> Date: Fri, 22 Jul 2022 17:34:15 -0400 Subject: [PATCH 07/14] Update x-pack/docs/en/security/authentication/jwt-realm.asciidoc Co-authored-by: Adam Locke --- x-pack/docs/en/security/authentication/jwt-realm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc index 7e7ae7622dac6..b0872abba5779 100644 --- a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc @@ -447,7 +447,7 @@ and {es} used the `jwt_role1` role: ===== PKC JWKS reloading JWT authentication supports signature verification using PKC (Public Key Cryptography) or HMAC algorithms. PKC JSON Web Token Key Sets (JWKS) can contain public RSA and EC keys. HMAC JWKS or an HMAC UTF-8 JWK contain secret keys. -JWT issuers typically rotate PKC JWKs more frequently (ex: daily), because RSA and EC public keys are +JWT issuers typically rotate PKC JWKS more frequently (such as daily), because RSA and EC public keys are designed to be easier to distribute than secret keys like HMAC. JWT realms load a PKC JWKS, and a HMAC JWKS or HMAC UTF-8 JWK, at startup. From 9e19410a1bebd9478b69e4fafb1ad3d853456e1c Mon Sep 17 00:00:00 2001 From: Justin Cranford <89857999+justincr-elastic@users.noreply.github.com> Date: Fri, 22 Jul 2022 17:34:20 -0400 Subject: [PATCH 08/14] Update x-pack/docs/en/security/authentication/jwt-realm.asciidoc Co-authored-by: Adam Locke --- x-pack/docs/en/security/authentication/jwt-realm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc index b0872abba5779..3164044643642 100644 --- a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc @@ -450,7 +450,7 @@ PKC JSON Web Token Key Sets (JWKS) can contain public RSA and EC keys. HMAC JWKS JWT issuers typically rotate PKC JWKS more frequently (such as daily), because RSA and EC public keys are designed to be easier to distribute than secret keys like HMAC. -JWT realms load a PKC JWKS, and a HMAC JWKS or HMAC UTF-8 JWK, at startup. +JWT realms load a PKC JWKS, and an HMAC JWKS or HMAC UTF-8 JWK, at startup. JWT realms can also reload PKC JWKS contents at runtime; reload is triggered by signature validation failures. CAUTION: HMAC JWKS or HMAC UTF-8 JWK reloading is not supported at this time. From 22549504f7a66e582b4bf3000a520d6674486860 Mon Sep 17 00:00:00 2001 From: Justin Cranford <89857999+justincr-elastic@users.noreply.github.com> Date: Fri, 22 Jul 2022 17:34:27 -0400 Subject: [PATCH 09/14] Update x-pack/docs/en/security/authentication/jwt-realm.asciidoc Co-authored-by: Adam Locke --- x-pack/docs/en/security/authentication/jwt-realm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc index 3164044643642..2154edfcc47b4 100644 --- a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc @@ -453,7 +453,7 @@ designed to be easier to distribute than secret keys like HMAC. JWT realms load a PKC JWKS, and an HMAC JWKS or HMAC UTF-8 JWK, at startup. JWT realms can also reload PKC JWKS contents at runtime; reload is triggered by signature validation failures. -CAUTION: HMAC JWKS or HMAC UTF-8 JWK reloading is not supported at this time. +NOTE: HMAC JWKS or HMAC UTF-8 JWK reloading is not supported at this time. Load failures, parse errors, and configuration errors prevent a node from starting (and restarting). However, runtime PKC reload errors and recoveries are handled gracefully. From b5a996149ea6994aef925ba2833b86cc45ac7fe7 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Wed, 27 Jul 2022 16:43:20 -0400 Subject: [PATCH 10/14] Update PKC JWKS reloading section --- .../authentication/jwt-realm.asciidoc | 50 ++++++++++++------- 1 file changed, 32 insertions(+), 18 deletions(-) diff --git a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc index 2154edfcc47b4..42b7218c760e5 100644 --- a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc @@ -445,32 +445,46 @@ and {es} used the `jwt_role1` role: [[jwt-realm-jwkset-reloading]] ===== PKC JWKS reloading -JWT authentication supports signature verification using PKC (Public Key Cryptography) or HMAC algorithms. -PKC JSON Web Token Key Sets (JWKS) can contain public RSA and EC keys. HMAC JWKS or an HMAC UTF-8 JWK contain secret keys. -JWT issuers typically rotate PKC JWKS more frequently (such as daily), because RSA and EC public keys are -designed to be easier to distribute than secret keys like HMAC. +JWT authentication supports signature verification using PKC (Public Key Cryptography) +or HMAC algorithms. -JWT realms load a PKC JWKS, and an HMAC JWKS or HMAC UTF-8 JWK, at startup. -JWT realms can also reload PKC JWKS contents at runtime; reload is triggered by signature validation failures. +PKC JSON Web Token Key Sets (JWKS) can contain public RSA and EC keys. HMAC JWKS +or an HMAC UTF-8 JWK contain secret keys. JWT issuers typically rotate PKC JWKS +more frequently (such as daily), because RSA and EC public keys are designed to +be easier to distribute than secret keys like HMAC. + +JWT realms load a PKC JWKS and an HMAC JWKS or HMAC UTF-8 JWK at startup. JWT +realms can also reload PKC JWKS contents at runtime; a reload is triggered by +signature validation failures. NOTE: HMAC JWKS or HMAC UTF-8 JWK reloading is not supported at this time. -Load failures, parse errors, and configuration errors prevent a node from starting (and restarting). -However, runtime PKC reload errors and recoveries are handled gracefully. +Load failures, parse errors, and configuration errors prevent a node from +starting (and restarting). However, runtime PKC reload errors and recoveries are +handled gracefully. -IMPORTANT: All other JWT realm validations are checked before a signature failure can trigger a -PKC JWKS reload. Client authentication is strongly recommended. Narrow scoping of allowed algorithms, -allowed issuer, allowed audiences, and clock skew are all strongly recommended too. That way only trusted -client applications and realm-specific user JWT will be able to trigger PKC reload attempts. +All other JWT realm validations are checked before a signature failure can +trigger a PKC JWKS reload. If multiple JWT authentication signature failures +occur simultaneously with a single {es} node, reloads are combined to reduce +the reloads that are sent externally. -If multiple JWT authentication signature failures happen at the same time within an {es} node, reloads are -combined to reduce the reloads sent externally. +Separate reload requests cannot be combined if JWT signature failures trigger: -IMPORTANT: If JWT signature failures trigger PKC JWKS reloads in different {es} nodes, reload -requests cannot be combined. +* PKC JWKS reloads in different {es} nodes +* PKC JWKS reloads in the same {es} node at different times -IMPORTANT: If JWT signature failures trigger PKC JWKS reloads in the same {es} node, but at different -times, separate reload requests will not be combined. +[IMPORTANT] +==== +Enabling client authentication (`client_authentication.type`) is strongly +recommended. Only trusted client applications and realm-specific JWT users can +trigger PKC reload attempts. Additionally, configuring the following +<> is recommended: + +* `allowed_audiences` +* `allowed_clock_skew` +* `allowed_issuer` +* `allowed_signature_algorithms` +==== [[hmac-oidc-example]] ==== Authorizing to the JWT realm with an HMAC UTF-8 key From 8fe00f252d9714ee9cb53967dd18ab24782f5b26 Mon Sep 17 00:00:00 2001 From: Justin Cranford <89857999+justincr-elastic@users.noreply.github.com> Date: Mon, 1 Aug 2022 20:09:39 -0400 Subject: [PATCH 11/14] Minor clean up --- .../authentication/jwt-realm.asciidoc | 64 ++++++++----------- 1 file changed, 25 insertions(+), 39 deletions(-) diff --git a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc index 42b7218c760e5..b62dfe91b62ee 100644 --- a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc @@ -9,11 +9,11 @@ authentication credential from an external service. When a JWT realm is used to authenticate with {es}, a distinction is made between the _client_ that is connecting to {es}, and the _user_ on whose behalf -the request should run. The JWT identifies the user, and a separate credential -is used to authenticate the client. +the request should run. The JWT authenticates the user, and a client credential +authenticates the client. A common scenario for JWTs is when an existing front-end application uses -OpenID Connect (OIDC) as an authentication method, and then accesses {es} +OpenID Connect (OIDC) to identify an authenticated user, and then accesses {es} on behalf of the authenticated user. TIP: If the front-end application does not exist, you can use the @@ -24,7 +24,7 @@ TIP: If the front-end application does not exist, you can use the JWT authentication in {es} is derived from OIDC user workflows, where different tokens can be issued by an OIDC Provider (OP). One possible token is an _ID token_, which uses the JWT format. If the ID token is presented to a JWT -realm, {es} can use it to authenticate, identify, and authorize an individual +realm, {es} can use as a bearer token to authenticate, identify, and authorize an individual user. NOTE: Because JWTs are obtained external to {es}, you can define a custom workflow @@ -33,11 +33,11 @@ Web Signature (JWS). The JWS header and JWS signature are validated using OIDC ID token validation rules. {es} supports a separate <>, which provides -stronger security guarantees than the JWT realm and is preferred for any +stronger security guarantees than the JWT realm, and is preferred for any use case where {es} can act as an OIDC RP. The OIDC realm is the only supported way to enable OIDC authentication in {kib}. -TIP: If JWTs are issued for the front-end application, the realm client is the JWT user. +TIP: If JWTs are issued for the front-end application, the application is the realm client and JWT user. That is not supported by OIDC flows, but it may be supported by bespoke JWT issuers. In that case, use the client secret and JWT for the client application, and the `es-security-runas-user` HTTP request header for the different user. See <>. @@ -445,46 +445,32 @@ and {es} used the `jwt_role1` role: [[jwt-realm-jwkset-reloading]] ===== PKC JWKS reloading -JWT authentication supports signature verification using PKC (Public Key Cryptography) -or HMAC algorithms. +JWT authentication supports signature verification using PKC (Public Key Cryptography) or HMAC algorithms. +PKC JWKS can contain public RSA and EC keys. HMAC JWKS or HMAC UTF-8 JWK contain secret keys. +JWT issuers typically rotate PKC JWKs more frequently (ex: daily), because RSA and EC public keys are +designed to be easier to distribute than secret keys like HMAC. -PKC JSON Web Token Key Sets (JWKS) can contain public RSA and EC keys. HMAC JWKS -or an HMAC UTF-8 JWK contain secret keys. JWT issuers typically rotate PKC JWKS -more frequently (such as daily), because RSA and EC public keys are designed to -be easier to distribute than secret keys like HMAC. +JWT realms load a PKC JWKS, and a HMAC JWKS or HMAC UTF-8 JWK, at startup. +JWT realms can also reload PKC JWKS contents at runtime; reload is triggered by signature validation failures. -JWT realms load a PKC JWKS and an HMAC JWKS or HMAC UTF-8 JWK at startup. JWT -realms can also reload PKC JWKS contents at runtime; a reload is triggered by -signature validation failures. +CAUTION: HMAC JWKS or HMAC UTF-8 JWK reloading is not supported at this time. -NOTE: HMAC JWKS or HMAC UTF-8 JWK reloading is not supported at this time. +Load failures, parse errors, and configuration errors prevent a node from starting (and restarting). +However, runtime PKC reload errors and recoveries are handled gracefully. -Load failures, parse errors, and configuration errors prevent a node from -starting (and restarting). However, runtime PKC reload errors and recoveries are -handled gracefully. +IMPORTANT: All other JWT realm validations are checked before a signature failure can trigger a +PKC JWKS reload. Client authentication is strongly recommended. Narrow scoping of allowed algorithms, +allowed issuer, allowed audiences, and clock skew are all strongly recommended too. That way only trusted +client applications and realm-specific user JWT will be able to trigger PKC reload attempts. -All other JWT realm validations are checked before a signature failure can -trigger a PKC JWKS reload. If multiple JWT authentication signature failures -occur simultaneously with a single {es} node, reloads are combined to reduce -the reloads that are sent externally. +If multiple JWT authentication signature failures happen at the same time within an {es} node, reloads are +combined to reduce the reloads sent externally. -Separate reload requests cannot be combined if JWT signature failures trigger: +IMPORTANT: If JWT signature failures trigger PKC JWKS reloads in different {es} nodes, reload +requests cannot be combined. -* PKC JWKS reloads in different {es} nodes -* PKC JWKS reloads in the same {es} node at different times - -[IMPORTANT] -==== -Enabling client authentication (`client_authentication.type`) is strongly -recommended. Only trusted client applications and realm-specific JWT users can -trigger PKC reload attempts. Additionally, configuring the following -<> is recommended: - -* `allowed_audiences` -* `allowed_clock_skew` -* `allowed_issuer` -* `allowed_signature_algorithms` -==== +IMPORTANT: If JWT signature failures trigger PKC JWKS reloads in the same {es} node, but at different +times, separate reload requests will not be combined. [[hmac-oidc-example]] ==== Authorizing to the JWT realm with an HMAC UTF-8 key From 785ba960d3cc529741d00dc091b6bca92b113f8a Mon Sep 17 00:00:00 2001 From: Justin Cranford <89857999+justincr-elastic@users.noreply.github.com> Date: Mon, 1 Aug 2022 20:11:54 -0400 Subject: [PATCH 12/14] Re-add missing work. --- x-pack/docs/en/security/authentication/jwt-realm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc index b62dfe91b62ee..57aac6f8f91a7 100644 --- a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc @@ -24,7 +24,7 @@ TIP: If the front-end application does not exist, you can use the JWT authentication in {es} is derived from OIDC user workflows, where different tokens can be issued by an OIDC Provider (OP). One possible token is an _ID token_, which uses the JWT format. If the ID token is presented to a JWT -realm, {es} can use as a bearer token to authenticate, identify, and authorize an individual +realm, {es} can use it as a bearer token to authenticate, identify, and authorize an individual user. NOTE: Because JWTs are obtained external to {es}, you can define a custom workflow From e17cdc822f02efb841608632a1f9ce4c7069d6b1 Mon Sep 17 00:00:00 2001 From: Justin Cranford <89857999+justincr-elastic@users.noreply.github.com> Date: Tue, 2 Aug 2022 09:24:39 -0400 Subject: [PATCH 13/14] Revert overwrite of Adam's changes --- .../authentication/jwt-realm.asciidoc | 64 +++++++++++-------- 1 file changed, 39 insertions(+), 25 deletions(-) diff --git a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc index 57aac6f8f91a7..42b7218c760e5 100644 --- a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc @@ -9,11 +9,11 @@ authentication credential from an external service. When a JWT realm is used to authenticate with {es}, a distinction is made between the _client_ that is connecting to {es}, and the _user_ on whose behalf -the request should run. The JWT authenticates the user, and a client credential -authenticates the client. +the request should run. The JWT identifies the user, and a separate credential +is used to authenticate the client. A common scenario for JWTs is when an existing front-end application uses -OpenID Connect (OIDC) to identify an authenticated user, and then accesses {es} +OpenID Connect (OIDC) as an authentication method, and then accesses {es} on behalf of the authenticated user. TIP: If the front-end application does not exist, you can use the @@ -24,7 +24,7 @@ TIP: If the front-end application does not exist, you can use the JWT authentication in {es} is derived from OIDC user workflows, where different tokens can be issued by an OIDC Provider (OP). One possible token is an _ID token_, which uses the JWT format. If the ID token is presented to a JWT -realm, {es} can use it as a bearer token to authenticate, identify, and authorize an individual +realm, {es} can use it to authenticate, identify, and authorize an individual user. NOTE: Because JWTs are obtained external to {es}, you can define a custom workflow @@ -33,11 +33,11 @@ Web Signature (JWS). The JWS header and JWS signature are validated using OIDC ID token validation rules. {es} supports a separate <>, which provides -stronger security guarantees than the JWT realm, and is preferred for any +stronger security guarantees than the JWT realm and is preferred for any use case where {es} can act as an OIDC RP. The OIDC realm is the only supported way to enable OIDC authentication in {kib}. -TIP: If JWTs are issued for the front-end application, the application is the realm client and JWT user. +TIP: If JWTs are issued for the front-end application, the realm client is the JWT user. That is not supported by OIDC flows, but it may be supported by bespoke JWT issuers. In that case, use the client secret and JWT for the client application, and the `es-security-runas-user` HTTP request header for the different user. See <>. @@ -445,32 +445,46 @@ and {es} used the `jwt_role1` role: [[jwt-realm-jwkset-reloading]] ===== PKC JWKS reloading -JWT authentication supports signature verification using PKC (Public Key Cryptography) or HMAC algorithms. -PKC JWKS can contain public RSA and EC keys. HMAC JWKS or HMAC UTF-8 JWK contain secret keys. -JWT issuers typically rotate PKC JWKs more frequently (ex: daily), because RSA and EC public keys are -designed to be easier to distribute than secret keys like HMAC. +JWT authentication supports signature verification using PKC (Public Key Cryptography) +or HMAC algorithms. -JWT realms load a PKC JWKS, and a HMAC JWKS or HMAC UTF-8 JWK, at startup. -JWT realms can also reload PKC JWKS contents at runtime; reload is triggered by signature validation failures. +PKC JSON Web Token Key Sets (JWKS) can contain public RSA and EC keys. HMAC JWKS +or an HMAC UTF-8 JWK contain secret keys. JWT issuers typically rotate PKC JWKS +more frequently (such as daily), because RSA and EC public keys are designed to +be easier to distribute than secret keys like HMAC. -CAUTION: HMAC JWKS or HMAC UTF-8 JWK reloading is not supported at this time. +JWT realms load a PKC JWKS and an HMAC JWKS or HMAC UTF-8 JWK at startup. JWT +realms can also reload PKC JWKS contents at runtime; a reload is triggered by +signature validation failures. -Load failures, parse errors, and configuration errors prevent a node from starting (and restarting). -However, runtime PKC reload errors and recoveries are handled gracefully. +NOTE: HMAC JWKS or HMAC UTF-8 JWK reloading is not supported at this time. -IMPORTANT: All other JWT realm validations are checked before a signature failure can trigger a -PKC JWKS reload. Client authentication is strongly recommended. Narrow scoping of allowed algorithms, -allowed issuer, allowed audiences, and clock skew are all strongly recommended too. That way only trusted -client applications and realm-specific user JWT will be able to trigger PKC reload attempts. +Load failures, parse errors, and configuration errors prevent a node from +starting (and restarting). However, runtime PKC reload errors and recoveries are +handled gracefully. -If multiple JWT authentication signature failures happen at the same time within an {es} node, reloads are -combined to reduce the reloads sent externally. +All other JWT realm validations are checked before a signature failure can +trigger a PKC JWKS reload. If multiple JWT authentication signature failures +occur simultaneously with a single {es} node, reloads are combined to reduce +the reloads that are sent externally. -IMPORTANT: If JWT signature failures trigger PKC JWKS reloads in different {es} nodes, reload -requests cannot be combined. +Separate reload requests cannot be combined if JWT signature failures trigger: -IMPORTANT: If JWT signature failures trigger PKC JWKS reloads in the same {es} node, but at different -times, separate reload requests will not be combined. +* PKC JWKS reloads in different {es} nodes +* PKC JWKS reloads in the same {es} node at different times + +[IMPORTANT] +==== +Enabling client authentication (`client_authentication.type`) is strongly +recommended. Only trusted client applications and realm-specific JWT users can +trigger PKC reload attempts. Additionally, configuring the following +<> is recommended: + +* `allowed_audiences` +* `allowed_clock_skew` +* `allowed_issuer` +* `allowed_signature_algorithms` +==== [[hmac-oidc-example]] ==== Authorizing to the JWT realm with an HMAC UTF-8 key From 39eed908b3dd9be905b1a7fabf655a3fb6b445d0 Mon Sep 17 00:00:00 2001 From: Justin Cranford <89857999+justincr-elastic@users.noreply.github.com> Date: Tue, 2 Aug 2022 09:35:07 -0400 Subject: [PATCH 14/14] Reapply minor updates. --- .../security/authentication/jwt-realm.asciidoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc index 42b7218c760e5..897047c0de974 100644 --- a/x-pack/docs/en/security/authentication/jwt-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/jwt-realm.asciidoc @@ -4,16 +4,16 @@ beta::[] -{es} can be configured to trust JSON Web Tokens (JWTs) that are issued as an -authentication credential from an external service. +{es} can be configured to trust JSON Web Tokens (JWTs) issued from an external service +as bearer tokens for authentication. When a JWT realm is used to authenticate with {es}, a distinction is made between the _client_ that is connecting to {es}, and the _user_ on whose behalf -the request should run. The JWT identifies the user, and a separate credential -is used to authenticate the client. +the request should run. The JWT authenticates the user, and a separate credential +authenticates the client. A common scenario for JWTs is when an existing front-end application uses -OpenID Connect (OIDC) as an authentication method, and then accesses {es} +OpenID Connect (OIDC) to authenticate and identify a user, and then accesses {es} on behalf of the authenticated user. TIP: If the front-end application does not exist, you can use the @@ -24,7 +24,7 @@ TIP: If the front-end application does not exist, you can use the JWT authentication in {es} is derived from OIDC user workflows, where different tokens can be issued by an OIDC Provider (OP). One possible token is an _ID token_, which uses the JWT format. If the ID token is presented to a JWT -realm, {es} can use it to authenticate, identify, and authorize an individual +realm, {es} can use it as a bearer token to authenticate, identify, and authorize an individual user. NOTE: Because JWTs are obtained external to {es}, you can define a custom workflow @@ -33,11 +33,11 @@ Web Signature (JWS). The JWS header and JWS signature are validated using OIDC ID token validation rules. {es} supports a separate <>, which provides -stronger security guarantees than the JWT realm and is preferred for any +stronger security guarantees than the JWT realm, and is preferred for any use case where {es} can act as an OIDC RP. The OIDC realm is the only supported way to enable OIDC authentication in {kib}. -TIP: If JWTs are issued for the front-end application, the realm client is the JWT user. +TIP: If JWTs are issued for the front-end application, the application is the realm client and JWT user. That is not supported by OIDC flows, but it may be supported by bespoke JWT issuers. In that case, use the client secret and JWT for the client application, and the `es-security-runas-user` HTTP request header for the different user. See <>.