Add missing docs #1481
Merged
Add missing docs #1481
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
lcavalle
reviewed
Jul 9, 2024
CHANGELOG.md
Outdated
| ### 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) |
There was a problem hiding this comment.
Suggested change
| - 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) |
Little typo
lcavalle
reviewed
Jul 9, 2024
| @@ -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. | |||
There was a problem hiding this comment.
Suggested change
| 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. |
Little typo.
lcavalle
reviewed
Jul 9, 2024
| 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. |
There was a problem hiding this comment.
Suggested change
| * `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. | |
| * `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. |
A couple of minor edits.
lcavalle
reviewed
Jul 9, 2024
|
|
||
| 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. |
There was a problem hiding this comment.
@tkan145 This sentence sounds a bit confusing to me. I am not sure if it says:
It specifies a different Token Introspection Endpoint. As well as the Client ID and the Client Secret APIcast, it uses it to request token information.
or
Specify a different Token Introspection Endpoint, a different Client ID and a different Client Secret APIcast to request token information.
lcavalle
reviewed
Jul 9, 2024
| 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. |
There was a problem hiding this comment.
Suggested change
| * `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. | |
| * `client_secret_jwt`: It is a request token information using `client_secret_jwt` method. Prior to a token information request, APIcast will prepare a new JWT authentication token and sign-in using HMAC SHA-256 and the Client Secret as the shared key. Then, APIcast will make a token request including the generated client assertion as the value of the `client_assertion` parameter. |
A couple of edits added.
lcavalle
reviewed
Jul 9, 2024
| * `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. |
There was a problem hiding this comment.
Suggested change
| * `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. | |
| * `private_key_jwt`: When using 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-in with the key provided. Then, APIcast will make a token request including the generated client assertion as the value of the `client_assertion` parameter. |
A couple of edits added.
lcavalle
reviewed
Jul 9, 2024
| * `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 |
There was a problem hiding this comment.
Suggested change
| * `true`: The call is authorized | |
| * `true`: The call is authorized. |
Litle typo.
lcavalle
reviewed
Jul 9, 2024
|
|
||
| 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 |
There was a problem hiding this comment.
Suggested change
| * `false`: The call is rejected with the Authentication Failed error | |
| * `false`: The call is rejected with the Authentication Failed error |
Little typo.
lcavalle
reviewed
Jul 9, 2024
| * `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. |
There was a problem hiding this comment.
Suggested change
| 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 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. |
A couple of minor edits.
|
@tkan145 I have just left a couple of edits and suggestion. I hope they make sense to you. Thanks! |
|
Thanks @lcavalle, I've updated the docs based on your feedback. |
|
@lcavalle If everything looks good, could you please approve this PR? Thanks in advance |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What
Verification steps
No verification steps