synapse/docs/usage/configuration/user_authentication/refresh_tokens.md

# Refresh Tokens

Synapse supports refresh tokens since version 1.49 (some earlier versions had support for an earlier, experimental draft of [MSC2918] which is not compatible).


[MSC2918]: https://github.com/matrix-org/matrix-doc/blob/main/proposals/2918-refreshtokens.md#msc2918-refresh-tokens


## Background and motivation

Synapse users' sessions are identified by **access tokens**; access tokens are
issued to users on login. Each session gets a unique access token which identifies
it; the access token must be kept secret as it grants access to the user's account.

Traditionally, these access tokens were eternally valid (at least until the user
explicitly chose to log out).

In some cases, it may be desirable for these access tokens to expire so that the
potential damage caused by leaking an access token is reduced.
On the other hand, forcing a user to re-authenticate (log in again) often might
be too much of an inconvenience.

**Refresh tokens** are a mechanism to avoid some of this inconvenience whilst
still getting most of the benefits of short access token lifetimes.
Refresh tokens are also a concept present in OAuth 2 — further reading is available
[here](https://datatracker.ietf.org/doc/html/rfc6749#section-1.5).

When refresh tokens are in use, both an access token and a refresh token will be
issued to users on login. The access token will expire after a predetermined amount
of time, but otherwise works in the same way as before. When the access token is
close to expiring (or has expired), the user's client should present the homeserver
(Synapse) with the refresh token.

The homeserver will then generate a new access token and refresh token for the user
and return them. The old refresh token is invalidated and can not be used again*.

Finally, refresh tokens also make it possible for sessions to be logged out if they
are inactive for too long, before the session naturally ends; see the configuration
guide below.


*To prevent issues if clients lose connection half-way through refreshing a token,
the refresh token is only invalidated once the new access token has been used at
least once. For all intents and purposes, the above simplification is sufficient.


## Caveats

There are some caveats:

* If a third party gets both your access token and refresh token, they will be able to
  continue to enjoy access to your session.
  * This is still an improvement because you (the user) will notice when *your*
    session expires and you're not able to use your refresh token.
    That would be a giveaway that someone else has compromised your session.
    You would be able to log in again and terminate that session.
    Previously (with long-lived access tokens), a third party that has your access
    token could go undetected for a very long time.
* Clients need to implement support for refresh tokens in order for them to be a
  useful mechanism.
  * It is up to homeserver administrators if they want to issue long-lived access
    tokens to clients not implementing refresh tokens.
    * For compatibility, it is likely that they should, at least until client support
      is widespread.
      * Users with clients that support refresh tokens will still benefit from the
        added security; it's not possible to downgrade a session to using long-lived
        access tokens so this effectively gives users the choice.
    * In a closed environment where all users use known clients, this may not be
      an issue as the homeserver administrator can know if the clients have refresh
      token support. In that case, the non-refreshable access token lifetime
      may be set to a short duration so that a similar level of security is provided.


## Configuration Guide

The following configuration options, in the `registration` section, are related:

* `session_lifetime`: maximum length of a session, even if it's refreshed.
  In other words, the client must log in again after this time period.
  In most cases, this can be unset (infinite) or set to a long time (years or months).
* `refreshable_access_token_lifetime`: lifetime of access tokens that are created
  by clients supporting refresh tokens.
  This should be short; a good value might be 5 minutes (`5m`).
* `nonrefreshable_access_token_lifetime`: lifetime of access tokens that are created
  by clients which don't support refresh tokens.
  Make this short if you want to effectively force use of refresh tokens.
  Make this long if you don't want to inconvenience users of clients which don't
  support refresh tokens (by forcing them to frequently re-authenticate using
  login credentials).
* `refresh_token_lifetime`: lifetime of refresh tokens.
  In other words, the client must refresh within this time period to maintain its session.
  Unless you want to log inactive sessions out, it is often fine to use a long
  value here or even leave it unset (infinite).
  Beware that making it too short will inconvenience clients that do not connect
  very often, including mobile clients and clients of infrequent users (by making
  it more difficult for them to refresh in time, which may force them to need to
  re-authenticate using login credentials).

**Note:** All four options above only apply when tokens are created (by logging in or refreshing).
Changes to these settings do not apply retroactively.


### Using refresh token expiry to log out inactive sessions

If you'd like to force sessions to be logged out upon inactivity, you can enable
refreshable access token expiry and refresh token expiry.

This works because a client must refresh at least once within a period of
`refresh_token_lifetime` in order to maintain valid credentials to access the
account.

(It's suggested that `refresh_token_lifetime` should be longer than
`refreshable_access_token_lifetime` and this section assumes that to be the case
for simplicity.)

Note: this will only affect sessions using refresh tokens. You may wish to
set a short `nonrefreshable_access_token_lifetime` to prevent this being bypassed
by clients that do not support refresh tokens.


#### Choosing values that guarantee permitting some inactivity

It may be desirable to permit some short periods of inactivity, for example to
accommodate brief outages in client connectivity.

The following model aims to provide guidance for choosing `refresh_token_lifetime`
and `refreshable_access_token_lifetime` to satisfy requirements of the form:

1. inactivity longer than `L` **MUST** cause the session to be logged out; and
2. inactivity shorter than `S` **MUST NOT** cause the session to be logged out.

This model makes the weakest assumption that all active clients will refresh as
needed to maintain an active access token, but no sooner.
*In reality, clients may refresh more often than this model assumes, but the
above requirements will still hold.*

To satisfy the above model,
* `refresh_token_lifetime` should be set to `L`; and
* `refreshable_access_token_lifetime` should be set to `L - S`.