From c4ba45c2ed52a29d9a0ab783fb539b03a0ccbdc5 Mon Sep 17 00:00:00 2001 From: An Tran Date: Tue, 9 Jul 2024 13:08:07 +1000 Subject: [PATCH 1/3] [token_introspection] Add README file --- .../policy/token_introspection/README.md | 73 +++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 gateway/src/apicast/policy/token_introspection/README.md diff --git a/gateway/src/apicast/policy/token_introspection/README.md b/gateway/src/apicast/policy/token_introspection/README.md new file mode 100644 index 000000000..2ea0e5ff3 --- /dev/null +++ b/gateway/src/apicast/policy/token_introspection/README.md @@ -0,0 +1,73 @@ +# OAuth 2.0 Token Introspection + + The OAuth 2.0 Token Introspection policy allows validating the JSON Web Token (JWT) token used for services with the OpenID Connect (OIDC) authentication option using the Token Introspection Endpoint of the token issuer. + +APIcast supports the following authentication types in the `auth_type` field to determine the Token Introspection Endpoint and the credentials APIcast uses when calling this endpoint: +* `use_3scale_oidc_issuer_endpoint`: APIcast uses the client credentials, Client ID and Client Secret, as well as the Token Introspection Endpoint from the OIDC Issuer setting configured on the Service Integration page. APIcast discovers the Token Introspection endpoint from the token_introspection_endpoint field. This field is located in the .well-known/openid-configuration endpoint that is returned by the OIDC issuer. +* `client_id+client_secret`: specify a different Token Introspection Endpoint, as well as the Client ID and Client Secret APIcast uses to request token information. +* `client_secret_jwt`: Request token information using `client_secret_jwt` method. Prior to a token information request, APIcast will prepare a new JWT authentication token and sign using HMAC SHA-256 and with Client Secret as the shared key. APIcast will then make a token request including the generated client assertion as the value of the `client_assertion` parameter. +* `private_key_jwt`: using asymmetric key to request token information from OIDC provider. Prior to a token information request, APIcast will prepare a new JWT authentication token and sign with the key provided. APIcast will then make a token request including the generated client assertion as the value of the `client_assertion` parameter. + + The response of the Token Introspection Endpoint contains the active attribute. APIcast checks the value of this attribute. Depending on the value of the attribute, APIcast authorizes or rejects the call: +* `true`: The call is authorized +* `false`: The call is rejected with the Authentication Failed error + +The policy allows enabling caching of the tokens to avoid calling the Token Introspection Endpoint on every call for the same JWT token. To enable token caching for the Token Introspection Policy, set the max_cached_tokens field to a value from 0, which disables the feature, and 10000. Additionally, you can set a Time to Live (TTL) value from 1 to 3600 seconds for tokens in the max_ttl_tokens field. + +## Examples: + +- With `use_3scale_oidc_issuer_endpoint` + +``` +{ + "name": "apicast.policy.token_introspection", + "configuration": { + "auth_type": "use_3scale_oidc_issuer_endpoint", + } +} +``` + +- With `client_id+client_secret` + +``` +{ + "name": "apicast.policy.token_introspection", + "configuration": { + "auth_type": "client_id+client_secret", + "client_id": "myclient", + "client_secret": "mysecret", + "introspection_url": "http://red_hat_single_sign-on/token/introspection" + } +} +``` + +- With `client_secret_jwt` + +``` +{ + "name": "apicast.policy.token_introspection", + "configuration": { + "auth_type": "client_secret_jwt", + "client_id": "myclient", + "client_secret": "mysecret", + "introspection_url": "http://red_hat_single_sign-on/token/introspection", + "client_jwt_assertion_audience": "http://red_hat_single_sign-on/auth/realms/basic" + } +} +``` + +- With `private_key_jwt` + +``` +{ + "name": "apicast.policy.token_introspection", + "configuration": { + "auth_type": "private_key_jwt", + "client_id": "myclient", + "client_secret": "mysecret", + "introspection_url": "http://red_hat_single_sign-on/token/introspection" + "certificate_type": "embedded", + "certificate": "data:application/x-x509-ca-cert;name=rsa.pem;base64,XXXXXXXXXxx", + } +} +``` From fc69973a1d57dbd2314f7fe78f8d78194ff9a5c0 Mon Sep 17 00:00:00 2001 From: An Tran Date: Tue, 9 Jul 2024 13:14:56 +1000 Subject: [PATCH 2/3] Add missing entries to CHANGELOG --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 31def373e..515c41fba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,12 +13,16 @@ and this project adheres to [Semantic Versioning](http://semver.org/). - Fixed APIcast send request through proxy server even when `NO_PROXY` is used [PR #1478](https://github.com/3scale/APIcast/pull/1478) [THREESCALE-11128](https://issues.redhat.com/browse/THREESCALE-11128) +- Fixed config reloading even when reloading is disabled [PR #1468](https://github.com/3scale/APIcast/pull/1468) + ### Added - Bump openresty to 1.21.4.3 [PR #1461](https://github.com/3scale/APIcast/pull/1461) [THREESCALE-10601](https://issues.redhat.com/browse/THREESCALE-10601) - Support Financial-grade API (FAPI) - Baseline profile [PR #1465](https://github.com/3scale/APIcast/pull/1465) [THREESCALE-10973](https://issues.redhat.com/browse/THREESCALE-10973) +- Token Introspection Policy - support `private_key_jwt` and `client_secret_jwt` authentication mode [PR #1464](https://github.com/3scale/APIcast/pull/1464) [THREESCALE-11015](https://issues.redhat.com/browse/THREESCALE-11015) + ## [3.15.0] 2024-04-04 ### Fixed From 95c1041acee98190b39c1281690f621db82e2d33 Mon Sep 17 00:00:00 2001 From: An Tran Date: Wed, 10 Jul 2024 16:48:15 +1000 Subject: [PATCH 3/3] Update docs based on PR review feedback --- CHANGELOG.md | 2 +- .../apicast/policy/token_introspection/README.md | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 515c41fba..cfe68a2f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,7 +21,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/). - Support Financial-grade API (FAPI) - Baseline profile [PR #1465](https://github.com/3scale/APIcast/pull/1465) [THREESCALE-10973](https://issues.redhat.com/browse/THREESCALE-10973) -- Token Introspection Policy - support `private_key_jwt` and `client_secret_jwt` authentication mode [PR #1464](https://github.com/3scale/APIcast/pull/1464) [THREESCALE-11015](https://issues.redhat.com/browse/THREESCALE-11015) +- Token Introspection Policy - Support `private_key_jwt` and `client_secret_jwt` authentication mode [PR #1464](https://github.com/3scale/APIcast/pull/1464) [THREESCALE-11015](https://issues.redhat.com/browse/THREESCALE-11015) ## [3.15.0] 2024-04-04 diff --git a/gateway/src/apicast/policy/token_introspection/README.md b/gateway/src/apicast/policy/token_introspection/README.md index 2ea0e5ff3..329a1c701 100644 --- a/gateway/src/apicast/policy/token_introspection/README.md +++ b/gateway/src/apicast/policy/token_introspection/README.md @@ -1,18 +1,18 @@ # OAuth 2.0 Token Introspection - The OAuth 2.0 Token Introspection policy allows validating the JSON Web Token (JWT) token used for services with the OpenID Connect (OIDC) authentication option using the Token Introspection Endpoint of the token issuer. + The OAuth 2.0 Token Introspection Policy allows validating the JSON Web Token (JWT) used for services with the OpenID Connect (OIDC) authentication option using the Token Introspection Endpoint of the token issuer. APIcast supports the following authentication types in the `auth_type` field to determine the Token Introspection Endpoint and the credentials APIcast uses when calling this endpoint: -* `use_3scale_oidc_issuer_endpoint`: APIcast uses the client credentials, Client ID and Client Secret, as well as the Token Introspection Endpoint from the OIDC Issuer setting configured on the Service Integration page. APIcast discovers the Token Introspection endpoint from the token_introspection_endpoint field. This field is located in the .well-known/openid-configuration endpoint that is returned by the OIDC issuer. -* `client_id+client_secret`: specify a different Token Introspection Endpoint, as well as the Client ID and Client Secret APIcast uses to request token information. -* `client_secret_jwt`: Request token information using `client_secret_jwt` method. Prior to a token information request, APIcast will prepare a new JWT authentication token and sign using HMAC SHA-256 and with Client Secret as the shared key. APIcast will then make a token request including the generated client assertion as the value of the `client_assertion` parameter. -* `private_key_jwt`: using asymmetric key to request token information from OIDC provider. Prior to a token information request, APIcast will prepare a new JWT authentication token and sign with the key provided. APIcast will then make a token request including the generated client assertion as the value of the `client_assertion` parameter. +* `use_3scale_oidc_issuer_endpoint`: APIcast uses the client credentials, Client ID, and Client Secret, as well as the Token Introspection Endpoint from the OIDC Issuer setting configured on the Service Integration page. APIcast discovers the Token Introspection Endpoint from the `token_introspection_endpoint` field. This field is located in the `.well-known/openid-configuration` endpoint that is returned by the OIDC issuer. +* `client_id+client_secret`: This option enables you to specify a different Token Introspection Endpoint. As well as the Client ID and Client Secret that APIcast uses to request token information. +* `client_secret_jwt`: This option uses `client_secret_jwt` method to request token information. Prior to a token information request, APIcast will prepare a new JWT authentication token and sign with the Client Secret using an HMAC SHA-256 algorithm. Then, APIcast will make a token information request with the generated JWT as the value for the `client_assertion` parameter. +* `private_key_jwt`: This option uses asymmetric key to request token information from the OIDC provider. Prior to a token information request, APIcast will prepare a new JWT authentication token and sign the token with the private key provided. Then, APIcast will make a token information request with the generated token as the value for the `client_assertion` parameter. The response of the Token Introspection Endpoint contains the active attribute. APIcast checks the value of this attribute. Depending on the value of the attribute, APIcast authorizes or rejects the call: -* `true`: The call is authorized -* `false`: The call is rejected with the Authentication Failed error +* `true`: The call is authorized. +* `false`: The call is rejected with the Authentication Failed error. -The policy allows enabling caching of the tokens to avoid calling the Token Introspection Endpoint on every call for the same JWT token. To enable token caching for the Token Introspection Policy, set the max_cached_tokens field to a value from 0, which disables the feature, and 10000. Additionally, you can set a Time to Live (TTL) value from 1 to 3600 seconds for tokens in the max_ttl_tokens field. +The policy enables caching of the tokens to avoid calling the Token Introspection Endpoint on every call for the same JWT token. To enable token caching for the Token Introspection Policy, set the `max_cached_tokens` field to a value between `0`, which disables the feature, and `10000`. Additionally, you can set a Time to Live (TTL) value from `1` to `3600` seconds for tokens in the `max_ttl_tokens` field. ## Examples: