<buttonid="sidebar-toggle"class="icon-button"type="button"title="Toggle Table of Contents"aria-label="Toggle Table of Contents"aria-controls="sidebar">
<ahref="https://github.com/element-hq/synapse/edit/develop/docs/usage/configuration/user_authentication/refresh_tokens.md"title="Suggest an edit"aria-label="Suggest an edit">
<inputtype="search"id="searchbar"name="searchbar"placeholder="Search this book ..."aria-controls="searchresults-outer"aria-describedby="searchresults-header">
<p>Synapse supports refresh tokens since version 1.49 (some earlier versions had support for an earlier, experimental draft of <ahref="https://github.com/matrix-org/matrix-doc/blob/main/proposals/2918-refreshtokens.md#msc2918-refresh-tokens">MSC2918</a> which is not compatible).</p>
<h2id="background-and-motivation"><aclass="header"href="#background-and-motivation">Background and motivation</a></h2>
<p>Synapse users' sessions are identified by <strong>access tokens</strong>; 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.</p>
<p>Traditionally, these access tokens were eternally valid (at least until the user
explicitly chose to log out).</p>
<p>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.</p>
<p><strong>Refresh tokens</strong> 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
<p>The following configuration options, in the <code>registration</code> section, are related:</p>
<ul>
<li><code>session_lifetime</code>: 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).</li>
<li><code>refreshable_access_token_lifetime</code>: lifetime of access tokens that are created
by clients supporting refresh tokens.
This should be short; a good value might be 5 minutes (<code>5m</code>).</li>
<li><code>nonrefreshable_access_token_lifetime</code>: 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).</li>
<li><code>refresh_token_lifetime</code>: 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).</li>
</ul>
<p><strong>Note:</strong> All four options above only apply when tokens are created (by logging in or refreshing).
Changes to these settings do not apply retroactively.</p>
<h3id="using-refresh-token-expiry-to-log-out-inactive-sessions"><aclass="header"href="#using-refresh-token-expiry-to-log-out-inactive-sessions">Using refresh token expiry to log out inactive sessions</a></h3>
<p>If you'd like to force sessions to be logged out upon inactivity, you can enable
refreshable access token expiry and refresh token expiry.</p>
<p>This works because a client must refresh at least once within a period of
<code>refresh_token_lifetime</code> in order to maintain valid credentials to access the
account.</p>
<p>(It's suggested that <code>refresh_token_lifetime</code> should be longer than
<code>refreshable_access_token_lifetime</code> and this section assumes that to be the case
for simplicity.)</p>
<p>Note: this will only affect sessions using refresh tokens. You may wish to
set a short <code>nonrefreshable_access_token_lifetime</code> to prevent this being bypassed
by clients that do not support refresh tokens.</p>
<h4id="choosing-values-that-guarantee-permitting-some-inactivity"><aclass="header"href="#choosing-values-that-guarantee-permitting-some-inactivity">Choosing values that guarantee permitting some inactivity</a></h4>
<p>It may be desirable to permit some short periods of inactivity, for example to
accommodate brief outages in client connectivity.</p>
<p>The following model aims to provide guidance for choosing <code>refresh_token_lifetime</code>
and <code>refreshable_access_token_lifetime</code> to satisfy requirements of the form:</p>
<ol>
<li>inactivity longer than <code>L</code><strong>MUST</strong> cause the session to be logged out; and</li>
<li>inactivity shorter than <code>S</code><strong>MUST NOT</strong> cause the session to be logged out.</li>
</ol>
<p>This model makes the weakest assumption that all active clients will refresh as
needed to maintain an active access token, but no sooner.
<em>In reality, clients may refresh more often than this model assumes, but the
above requirements will still hold.</em></p>
<p>To satisfy the above model,</p>
<ul>
<li><code>refresh_token_lifetime</code> should be set to <code>L</code>; and</li>
<li><code>refreshable_access_token_lifetime</code> should be set to <code>L - S</code>.</li>
