From 7ac8361e065ccb180a9ff5714ccba772d1603e6a Mon Sep 17 00:00:00 2001 From: Daniel DeGroff Date: Tue, 14 Jan 2025 14:59:24 -0700 Subject: [PATCH] Doc for grace period, revocation on re-use, and Lambda HTTP connect timeout configurations. --- .../docs/apis/_application-request-body.mdx | 9 +++++++ .../apis/_application-response-body-base.mdx | 8 ++++++ .../docs/apis/_tenant-request-body.mdx | 12 +++++++++ .../docs/apis/_tenant-response-body-base.mdx | 12 +++++++++ .../code/lambdas/lambda-remote-api-calls.mdx | 25 ++++++++++++++++++- .../core-concepts/_refresh-token-settings.mdx | 9 +++++++ 6 files changed, 74 insertions(+), 1 deletion(-) diff --git a/astro/src/content/docs/apis/_application-request-body.mdx b/astro/src/content/docs/apis/_application-request-body.mdx index b4e651ddba..985c42a6e3 100644 --- a/astro/src/content/docs/apis/_application-request-body.mdx +++ b/astro/src/content/docs/apis/_application-request-body.mdx @@ -110,6 +110,15 @@ import Xmlsignaturec14nmethodValues from 'src/content/docs/_shared/_xmlSignature * `SlidingWindow` - the expiration is calculated from the last time the token was used. * `SlidingWindowWithMaximumLifetime` - the expiration is calculated from the last time the token was used, or until the maximumTimeToLiveInMinutes is reached. Available since 1.46.0 + + + The length of time specified in seconds that a one time use token can be re-used. + + This value must be greater than `0` and less than `86,400` which is equal to 24 hours. Setting this value to `0` effectively disables the grace period which means a one-time token may not be reused. For security reasons, you should keep this value as small as possible, and only increase past `0` to improve reliability for an asynchronous or clustered integration that may require a brief grace period. + + Note that one-time use tokens refreshed within a grace period are not considered for revocation when tenant.jwtConfiguration.refreshTokenRevocationPolicy.onOneTimeTokenReuse is `true`. When a token is re-used within the grace period the current token will be returned on the API response and the token will not be rotated. + + The maximum lifetime of a refresh token when using a refreshTokenExpirationPolicy of `SlidingWindowWithMaximumLifetime`. Value must be greater than 0. diff --git a/astro/src/content/docs/apis/_application-response-body-base.mdx b/astro/src/content/docs/apis/_application-response-body-base.mdx index b298560643..b55516c426 100644 --- a/astro/src/content/docs/apis/_application-response-body-base.mdx +++ b/astro/src/content/docs/apis/_application-response-body-base.mdx @@ -104,6 +104,14 @@ import Xmlsignaturec14nmethodValues from 'src/content/docs/_shared/_xmlSignature * `SlidingWindowWithMaximumLifetime` - the expiration is calculated from the last time the token was used, or until the maximumTimeToLiveInMinutes is reached. Available since 1.46.0 + + The length of time specified in seconds that a one time use token can be re-used. + + This value must be greater than `0` and less than `86,400` which is equal to 24 hours. Setting this value to `0` effectively disables the grace period which means a one-time token may not be reused. For security reasons, you should keep this value as small as possible, and only increase past `0` to improve reliability for an asynchronous or clustered integration that may require a brief grace period. + + Note that one-time use tokens refreshed within a grace period are not considered for revocation when tenant.jwtConfiguration.refreshTokenRevocationPolicy.onOneTimeTokenReuse is `true`. When a token is re-used within the grace period the current token will be returned on the API response and the token will not be rotated. + + The maximum lifetime of a refresh token when using a refreshTokenExpirationPolicy of `SlidingWindowWithMaximumLifetime`. diff --git a/astro/src/content/docs/apis/_tenant-request-body.mdx b/astro/src/content/docs/apis/_tenant-request-body.mdx index 13ab4c0e73..d0647cd900 100644 --- a/astro/src/content/docs/apis/_tenant-request-body.mdx +++ b/astro/src/content/docs/apis/_tenant-request-body.mdx @@ -433,6 +433,14 @@ import TransactionTypes from 'src/content/docs/apis/_transaction-types.mdx'; * `SlidingWindowWithMaximumLifetime` - the expiration is calculated from the last time the token was used, or until the maximumTimeToLiveInMinutes is reached.   + + The length of time specified in seconds that a one time use token can be re-used. + + This value must be greater than `0` and less than `86,400` which is equal to 24 hours. Setting this value to `0` effectively disables the grace period which means a one-time token may not be reused. For security reasons, you should keep this value as small as possible, and only increase past `0` to improve reliability for an asynchronous or clustered integration that may require a brief grace period. + + Note that one-time use tokens refreshed within a grace period are not considered for revocation when tenant.jwtConfiguration.refreshTokenRevocationPolicy.onOneTimeTokenReuse is `true`. When a token is re-used within the grace period the current token will be returned on the API response and the token will not be rotated. + + When enabled, all refresh tokens will be revoked when a user action, such as locking an account based on a number of failed login attempts, prevents user login. @@ -441,6 +449,10 @@ import TransactionTypes from 'src/content/docs/apis/_transaction-types.mdx'; When enabled, all refresh tokens will be revoked when a user enables multi-factor authentication for the first time. This policy will not be applied when adding subsequent multi-factor methods to the user. + + When enabled, if a one-time use refresh token is reused, the token will be revoked. This does not cause all refresh tokens to be revoked, only the reused token is revoked. + + When enabled, all refresh tokens will be revoked when a user changes their password. diff --git a/astro/src/content/docs/apis/_tenant-response-body-base.mdx b/astro/src/content/docs/apis/_tenant-response-body-base.mdx index fdeabe5c56..2c501a74de 100644 --- a/astro/src/content/docs/apis/_tenant-response-body-base.mdx +++ b/astro/src/content/docs/apis/_tenant-response-body-base.mdx @@ -345,6 +345,14 @@ import JSON from 'src/components/JSON.astro'; * `SlidingWindowWithMaximumLifetime` - the expiration is calculated from the last time the token was used, or until the maximumTimeToLiveInMinutes is reached.   + + The length of time specified in seconds that a one time use token can be re-used. + + This value must be greater than `0` and less than `86,400` which is equal to 24 hours. Setting this value to `0` effectively disables the grace period which means a one-time token may not be reused. For security reasons, you should keep this value as small as possible, and only increase past `0` to improve reliability for an asynchronous or clustered integration that may require a brief grace period. + + Note that one-time use tokens refreshed within a grace period are not considered for revocation when tenant.jwtConfiguration.refreshTokenRevocationPolicy.onOneTimeTokenReuse is `true`. When a token is re-used within the grace period the current token will be returned on the API response and the token will not be rotated. + + When enabled, all refresh tokens will be revoked when a user action, such as locking an account based on a number of failed login attempts, prevents user login. @@ -353,6 +361,10 @@ import JSON from 'src/components/JSON.astro'; When enabled, all refresh tokens will be revoked when a user enables multi-factor authentication for the first time. This policy will not be applied when adding subsequent multi-factor methods to the user. + + When enabled, if a one-time use refresh token is reused, the token will be revoked. This does not cause all refresh tokens to be revoked, only the reused token is revoked. + + When enabled, all refresh tokens will be revoked when a user changes their password. diff --git a/astro/src/content/docs/extend/code/lambdas/lambda-remote-api-calls.mdx b/astro/src/content/docs/extend/code/lambdas/lambda-remote-api-calls.mdx index 306e3286ac..2c18892210 100644 --- a/astro/src/content/docs/extend/code/lambdas/lambda-remote-api-calls.mdx +++ b/astro/src/content/docs/extend/code/lambdas/lambda-remote-api-calls.mdx @@ -10,6 +10,7 @@ import AdvancedPlanBlurb from 'src/content/docs/_shared/_advanced-plan-blurb.ast import APIBlock from 'src/components/api/APIBlock.astro'; import APIField from 'src/components/api/APIField.astro'; import Aside from 'src/components/Aside.astro'; +import AvailableSince from 'src/components/api/AvailableSince.astro'; import InlineField from 'src/components/InlineField.astro'; import LambdaTypes from 'src/content/docs/_shared/_lambda-types.astro'; import MembershipLambda from 'src/content/docs/extend/code/_membership-lambda.md'; @@ -80,6 +81,28 @@ headers: new Headers([ ]) ``` +## Options + +### Timeouts + + + +In general you will want to be certain that any external request you make within a lambda function returns quickly. The duration of the request will be cause additional latency during the FusionAuth request and can reduce the performance of FusionAuth and cause unexpected errors. + +However, in some cases where you know a request may be slow, or the performance of the request is secondary to the request completing, you may need to extend these timeouts. These values are specified in milliseconds. + +By default, the HTTP read and connect timeouts are set to 2 seconds. The following is an example of setting the `connectTimeout` and the `readTimeout` on the HTTP request. + +```javascript +var response = fetch("https://api.example.com/api/status", { + method: "GET", + connectTimeout: 42000, // 42,000 ms, or 42 seconds + readTimeout: 42000 // 42,000 ms, or 42 seconds + }); +``` + ## Response A response object will be returned. It will have the following fields: @@ -98,7 +121,7 @@ A response object will be returned. It will have the following fields: ## Securing API Keys In Lambdas -Being able to make API requests against FusionAuth can be useful, but requires an API key to be stored in the Lambda code. +Being able to make API requests against FusionAuth can be useful, but requires an API key to be stored in the Lambda code. To secure that API key, you should: diff --git a/astro/src/content/docs/get-started/core-concepts/_refresh-token-settings.mdx b/astro/src/content/docs/get-started/core-concepts/_refresh-token-settings.mdx index afefdb5c48..dff94d7c0d 100644 --- a/astro/src/content/docs/get-started/core-concepts/_refresh-token-settings.mdx +++ b/astro/src/content/docs/get-started/core-concepts/_refresh-token-settings.mdx @@ -14,6 +14,15 @@ import InlineField from 'src/components/InlineField.astro'; The Refresh token usage may be reusable or one time use. By default, a token is reusable and the token does not change after it was issued. With a one time use token, the token value will be changed each time the token is used to refresh a JWT. This means the client must store the new value after each use. + + When Refresh token usage is set to `Reusable`, you may optionally set the grace period to something greater than `0` seconds. + + The grace period is the length of time specified in seconds that a one time use token can be re-used. + + This value must be greater than `0` and less than `86,400` which is equal to 24 hours. Setting this value to `0` effectively disables the grace period which means a one-time token may not be reused. For security reasons, you should keep this value as small as possible, and only increase past `0` to improve reliability for an asynchronous or clustered integration that may require a brief grace period. + + Note that one-time use tokens refreshed within a grace period are not considered for revocation when the Tenant Refresh Token Revocation Policy is configured to revoke a one-time use refresh token on re-use. When a token is re-used within the grace period the current token will be returned on the API response and the token will not be rotated. + The event or events that will cause refresh tokens to be revoked.