Skip to content

Commit

Permalink
docs(hydra): add refresh token rotation
Browse files Browse the repository at this point in the history
  • Loading branch information
aeneasr committed Jul 26, 2022
1 parent 10f0258 commit 1075e59
Showing 1 changed file with 37 additions and 0 deletions.
37 changes: 37 additions & 0 deletions docs/hydra/guides/token-expiration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,43 @@ Key `ttl.refresh_token` configures how long refresh tokens are valid. Set to -1
#....
```

### Refresh Token rotation

When a refresh token is used it's deactivated, which is known as Refresh Token Rotation. By default, Ory Hydra deactivates the
refresh token it receives and issues a new token. If a deactivated refresh token is used again, all tokens related to that refresh
token will also be deactivated. More information on Refresh Token Rotation can be found in the recommendation section of the OAuth
2.0 Security Best Practices document
[here](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#section-4.13.2).

There are some cases when a one time use refresh token may be undesirable, such as when a networking error occurs and the newly
issued refresh token isn't received. Hydra may be configured to use a refresh token grace period which allows a refresh token to
be reused for the duration of the grace period. Note that a new refresh token is still generated and sent back in the response;
clients **must** store and use the new refresh token.

**WARNING** Using the refresh token grace period is an increased security risk, as an intercepted refresh token may be reused by a
bad actor. Use this feature with appropriate consideration.

```
oauth2:
## refresh_token_rotation
#
# By default Refresh Tokens are rotated and invalidated with each use.
# See https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#section-4.13.2 for more details
#
refresh_token_rotation:
#
## grace_period
#
# Set the grace period for a refresh token to allow it to be used for the duration of this configuration after
# its first use. New refresh tokens will continue to be issued.
#
# Examples:
# - 5s
# - 1m
# - 0s (default; grace period disabled)
grace_period: 0s
```

## ID Token Expiration

Key `ttl.id_token` configures how long id tokens are valid.
Expand Down

0 comments on commit 1075e59

Please sign in to comment.