Skip to main content

Configuring Expiration

In the Hydra config.yaml - located in your Hydra directory - you can set times for how long a login/consent flow may take, expiration times for access tokens, refresh tokens, id tokens and auth codes.

Key ttl.login_consent_request configures how long a user login and consent flow may take.

path/to/hydra/config.yaml
#....
  ## login_consent_request ##
  #
  # Configures how long a user login and consent flow may take.
  #
  # Default value: 1h
  #
  # Set this value using environment variables on
  # - Linux/macOS:
  #    export TTL_LOGIN_CONSENT_REQUEST=<value>
  # - Windows Command Line (CMD):
  #    > set TTL_LOGIN_CONSENT_REQUEST=<value>
  #
  login_consent_request: 1h
 #....

Access Token Expiration​

Key ttl.access_token configures how long access tokens are valid.

path/to/hydra/config.yaml
#....
  ## access_token ##
  #
  # Configures how long access tokens are valid.
  #
  # Default value: 1h
  #
  # Set this value using environment variables on
  # - Linux/macOS:
  #    export TTL_ACCESS_TOKEN=<value>
  # - Windows Command Line (CMD):
  #    > set TTL_ACCESS_TOKEN=<value>
  #
  access_token: 1h
   #....

Refresh Token Expiration​

Key ttl.refresh_token configures how long refresh tokens are valid. Set to -1 for refresh tokens to never expire.

path/to/hydra/config.yaml
#....
  ## refresh_token ##
  #
  # Configures how long refresh tokens are valid. Set to -1 for refresh tokens to never expire.
  #
  # Default value: 720h
  #
  # Set this value using environment variables on
  # - Linux/macOS:
  #    export TTL_REFRESH_TOKEN=<value>
  # - Windows Command Line (CMD):
  #    > set TTL_REFRESH_TOKEN=<value>
  #
  refresh_token: "-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.

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.

path/to/hydra/config.yaml
#....
  ## id_token ##
  #
  # Configures how long id tokens are valid.
  #
  # Default value: 1h
  #
  # Set this value using environment variables on
  # - Linux/macOS:
  #    export TTL_ID_TOKEN=<value>
  # - Windows Command Line (CMD):
  #    > set TTL_ID_TOKEN=<value>
  #
  id_token: 1h
     #....

Auth Code Expiration​

Key ttl.auth_code configures how long auth codes are valid.

path/to/hydra/config.yaml
#....
  ## auth_code ##
  #
  # Configures how long auth codes are valid.
  #
  # Default value: 10m
  #
  # Set this value using environment variables on
  # - Linux/macOS:
  #    export TTL_AUTH_CODE=<value>
  # - Windows Command Line (CMD):
  #    > set TTL_AUTH_CODE=<value>
  #
  auth_code: 1h
     #....