From a21ee80f123d8ead379c4a95699a623098f4ac18 Mon Sep 17 00:00:00 2001 From: aeneasr <3372410+aeneasr@users.noreply.github.com> Date: Thu, 7 Nov 2024 10:23:24 +0100 Subject: [PATCH 1/4] docs: graceful token refresh --- docs/hydra/guides/graceful-token-refresh.mdx | 72 ++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/hydra/guides/graceful-token-refresh.mdx diff --git a/docs/hydra/guides/graceful-token-refresh.mdx b/docs/hydra/guides/graceful-token-refresh.mdx new file mode 100644 index 000000000..9e6f3ae07 --- /dev/null +++ b/docs/hydra/guides/graceful-token-refresh.mdx @@ -0,0 +1,72 @@ +--- +id: graceful-token-refresh +title: Graceful token refresh +--- + +# Graceful refresh token rotation in Ory OAuth2 / Ory Hydra + +Graceful refresh token rotation is a feature in Ory OAuth2 / Ory Hydra that allows for a smoother transition during refresh token +usage. With this feature enabled, a refresh token remains valid within a defined grace period, allowing multiple usages without +immediate invalidation. This can be beneficial in scenarios where network issues or delayed token exchanges may otherwise disrupt +session continuity. + +When enabled, using a refresh token marks it as "used" in the database and extends its expiration time by the duration of the +configured grace period. As long as the grace period is active, subsequent token refreshes will return new access and refresh +tokens. All tokens issued in this grace period remain linked in a single token chain, so revoking one refresh token or consent +will invalidate all associated tokens. + +## Enabling graceful refresh token rotation + +To enable graceful refresh token rotation with a specific grace period (for example, 60 seconds), run the following command: + +```shell +ory patch oauth2-config --project --workspace \ + --replace "/oauth2/grant/refresh_token/rotation_grace_period=60s" +``` + +In this command: + +- `` and `` should be replaced with your specific project and workspace identifiers. +- The `rotation_grace_period` specifies the grace period duration. Here, `60s` sets a 60-second grace period. + +## Disabling graceful refresh token rotation + +To disable the graceful refresh token rotation, remove the `rotation_grace_period` parameter using the command below: + +```shell +ory patch oauth2-config --project --workspace \ + --remove "/oauth2/grant/refresh_token/rotation_grace_period" +``` + +## Configuration in self-hosted deployments (Ory Enterprise License / DIY) + +For self-hosted deployments, you can configure graceful refresh token rotation in your configuration file: + +```yaml +oauth2: + grant: + refresh_token: + rotation_grace_period: 60s # Set grace period. Omit this line to disable. +``` + +If `rotation_grace_period` is set to a positive duration, the refresh token remains valid within this period, providing clients +with new tokens for each request without immediate invalidation of the original token. + +## Example behavior with grace period + +- **Using the refresh token within the grace period**: If a refresh token is used twice within the configured grace period (for + example, 60 seconds), each usage results in a new set of access and refresh tokens. +- **Revocation implications**: Any refresh token issued within the grace period is part of the same token chain. Revoking one + token or consent associated with the chain will revoke all tokens in the chain, including those issued through graceful refresh. + +## Use cases for graceful refresh token rotation + +Graceful refresh token rotation can be particularly useful in: + +- High-availability applications where token exchange delays could interrupt user experience. +- Distributed systems with multiple servers handling refresh tokens, minimizing the risk of accidental token invalidation. +- Single-page applications, where network connectivity or token exchange delays may cause token rotation issues. +- Mobile applications, where intermittent network connectivity can delay refresh token exchange, risking session continuity. + +Enabling this feature helps ensure smoother token lifecycle management while maintaining secure and efficient token rotation +behavior. From 2395ca365ee1513dd7db70cd9cc6d17cea989705 Mon Sep 17 00:00:00 2001 From: aeneasr <3372410+aeneasr@users.noreply.github.com> Date: Thu, 7 Nov 2024 10:29:53 +0100 Subject: [PATCH 2/4] chore: synchronize workspaces --- src/sidebar.ts | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/src/sidebar.ts b/src/sidebar.ts index 879907d5e..62e7f0c3f 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -400,17 +400,12 @@ const guidesSidebar = (flat: boolean): ExtendSidebar => { : [ "oauth2-oidc/revoke-consent", "oauth2-oidc/skip-consent", - { - type: "category", - label: "Configure tokens", - items: [ - "oauth2-oidc/jwt-access-token", - "hydra/guides/audiences", - "hydra/guides/jwt", - "hydra/guides/client-token-expiration", - "oauth2-oidc/claims-scope", - ], - }, + "oauth2-oidc/jwt-access-token", + "hydra/guides/audiences", + "hydra/guides/jwt", + "hydra/guides/client-token-expiration", + "hydra/guides/graceful-token-refresh", + "oauth2-oidc/claims-scope", ], }, { From 712875b3edb805bcd1acf2d2ac0b9deae80c518d Mon Sep 17 00:00:00 2001 From: Vincent Date: Fri, 8 Nov 2024 13:21:18 +0100 Subject: [PATCH 3/4] chore: apply suggestions from code review --- docs/hydra/guides/graceful-token-refresh.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/hydra/guides/graceful-token-refresh.mdx b/docs/hydra/guides/graceful-token-refresh.mdx index 9e6f3ae07..987761966 100644 --- a/docs/hydra/guides/graceful-token-refresh.mdx +++ b/docs/hydra/guides/graceful-token-refresh.mdx @@ -15,7 +15,7 @@ configured grace period. As long as the grace period is active, subsequent token tokens. All tokens issued in this grace period remain linked in a single token chain, so revoking one refresh token or consent will invalidate all associated tokens. -## Enabling graceful refresh token rotation +## Enable graceful refresh token rotation To enable graceful refresh token rotation with a specific grace period (for example, 60 seconds), run the following command: @@ -29,7 +29,7 @@ In this command: - `` and `` should be replaced with your specific project and workspace identifiers. - The `rotation_grace_period` specifies the grace period duration. Here, `60s` sets a 60-second grace period. -## Disabling graceful refresh token rotation +## Disable graceful refresh token rotation To disable the graceful refresh token rotation, remove the `rotation_grace_period` parameter using the command below: @@ -38,9 +38,9 @@ ory patch oauth2-config --project --workspace \ --remove "/oauth2/grant/refresh_token/rotation_grace_period" ``` -## Configuration in self-hosted deployments (Ory Enterprise License / DIY) +## Configuration in self-hosted deployments -For self-hosted deployments, you can configure graceful refresh token rotation in your configuration file: +For self-hosted deployments with Ory Enterprise License or Ory OSS, you can configure graceful refresh token rotation in your configuration file: ```yaml oauth2: From 18789e3d93dec7e680b54faa7793af6f81d0f8da Mon Sep 17 00:00:00 2001 From: vinckr Date: Fri, 8 Nov 2024 13:22:49 +0100 Subject: [PATCH 4/4] chore: format --- docs/hydra/guides/graceful-token-refresh.mdx | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/hydra/guides/graceful-token-refresh.mdx b/docs/hydra/guides/graceful-token-refresh.mdx index 987761966..d44bfd458 100644 --- a/docs/hydra/guides/graceful-token-refresh.mdx +++ b/docs/hydra/guides/graceful-token-refresh.mdx @@ -3,12 +3,12 @@ id: graceful-token-refresh title: Graceful token refresh --- -# Graceful refresh token rotation in Ory OAuth2 / Ory Hydra +# Graceful refresh token rotation -Graceful refresh token rotation is a feature in Ory OAuth2 / Ory Hydra that allows for a smoother transition during refresh token -usage. With this feature enabled, a refresh token remains valid within a defined grace period, allowing multiple usages without -immediate invalidation. This can be beneficial in scenarios where network issues or delayed token exchanges may otherwise disrupt -session continuity. +Graceful refresh token rotation is a feature in Ory OAuth2 and Ory Hydra that allows for a smoother transition during refresh +token usage. With this feature enabled, a refresh token remains valid within a defined grace period, allowing multiple usages +without immediate invalidation. This can be beneficial in scenarios where network issues or delayed token exchanges may otherwise +disrupt session continuity. When enabled, using a refresh token marks it as "used" in the database and extends its expiration time by the duration of the configured grace period. As long as the grace period is active, subsequent token refreshes will return new access and refresh @@ -17,7 +17,7 @@ will invalidate all associated tokens. ## Enable graceful refresh token rotation -To enable graceful refresh token rotation with a specific grace period (for example, 60 seconds), run the following command: +To enable graceful refresh token rotation with a specific grace period, for example 60 seconds, run the following command: ```shell ory patch oauth2-config --project --workspace \ @@ -38,9 +38,10 @@ ory patch oauth2-config --project --workspace \ --remove "/oauth2/grant/refresh_token/rotation_grace_period" ``` -## Configuration in self-hosted deployments +## Configuration in self-hosted deployments -For self-hosted deployments with Ory Enterprise License or Ory OSS, you can configure graceful refresh token rotation in your configuration file: +For self-hosted deployments with Ory Enterprise License or Ory OSS, you can configure graceful refresh token rotation in your +configuration file: ```yaml oauth2: