refresh_tokens.html 30 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326
  1. <!DOCTYPE HTML>
  2. <html lang="en" class="sidebar-visible no-js light">
  3. <head>
  4. <!-- Book generated using mdBook -->
  5. <meta charset="UTF-8">
  6. <title>Refresh Tokens - Synapse</title>
  7. <!-- Custom HTML head -->
  8. <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
  9. <meta name="description" content="">
  10. <meta name="viewport" content="width=device-width, initial-scale=1">
  11. <meta name="theme-color" content="#ffffff" />
  12. <link rel="icon" href="../../../favicon.svg">
  13. <link rel="shortcut icon" href="../../../favicon.png">
  14. <link rel="stylesheet" href="../../../css/variables.css">
  15. <link rel="stylesheet" href="../../../css/general.css">
  16. <link rel="stylesheet" href="../../../css/chrome.css">
  17. <link rel="stylesheet" href="../../../css/print.css" media="print">
  18. <!-- Fonts -->
  19. <link rel="stylesheet" href="../../../FontAwesome/css/font-awesome.css">
  20. <link rel="stylesheet" href="../../../fonts/fonts.css">
  21. <!-- Highlight.js Stylesheets -->
  22. <link rel="stylesheet" href="../../../highlight.css">
  23. <link rel="stylesheet" href="../../../tomorrow-night.css">
  24. <link rel="stylesheet" href="../../../ayu-highlight.css">
  25. <!-- Custom theme stylesheets -->
  26. <link rel="stylesheet" href="../../../docs/website_files/table-of-contents.css">
  27. <link rel="stylesheet" href="../../../docs/website_files/remove-nav-buttons.css">
  28. <link rel="stylesheet" href="../../../docs/website_files/indent-section-headers.css">
  29. <link rel="stylesheet" href="../../../docs/website_files/version-picker.css">
  30. </head>
  31. <body>
  32. <!-- Provide site root to javascript -->
  33. <script type="text/javascript">
  34. var path_to_root = "../../../";
  35. var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
  36. </script>
  37. <!-- Work around some values being stored in localStorage wrapped in quotes -->
  38. <script type="text/javascript">
  39. try {
  40. var theme = localStorage.getItem('mdbook-theme');
  41. var sidebar = localStorage.getItem('mdbook-sidebar');
  42. if (theme.startsWith('"') && theme.endsWith('"')) {
  43. localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
  44. }
  45. if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
  46. localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
  47. }
  48. } catch (e) { }
  49. </script>
  50. <!-- Set the theme before any content is loaded, prevents flash -->
  51. <script type="text/javascript">
  52. var theme;
  53. try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
  54. if (theme === null || theme === undefined) { theme = default_theme; }
  55. var html = document.querySelector('html');
  56. html.classList.remove('no-js')
  57. html.classList.remove('light')
  58. html.classList.add(theme);
  59. html.classList.add('js');
  60. </script>
  61. <!-- Hide / unhide sidebar before it is displayed -->
  62. <script type="text/javascript">
  63. var html = document.querySelector('html');
  64. var sidebar = 'hidden';
  65. if (document.body.clientWidth >= 1080) {
  66. try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
  67. sidebar = sidebar || 'visible';
  68. }
  69. html.classList.remove('sidebar-visible');
  70. html.classList.add("sidebar-" + sidebar);
  71. </script>
  72. <nav id="sidebar" class="sidebar" aria-label="Table of contents">
  73. <div class="sidebar-scrollbox">
  74. <ol class="chapter"><li class="chapter-item expanded affix "><li class="part-title">Introduction</li><li class="chapter-item expanded "><a href="../../../welcome_and_overview.html">Welcome and Overview</a></li><li class="chapter-item expanded affix "><li class="part-title">Setup</li><li class="chapter-item expanded "><a href="../../../setup/installation.html">Installation</a></li><li class="chapter-item expanded "><a href="../../../postgres.html">Using Postgres</a></li><li class="chapter-item expanded "><a href="../../../reverse_proxy.html">Configuring a Reverse Proxy</a></li><li class="chapter-item expanded "><a href="../../../setup/forward_proxy.html">Configuring a Forward/Outbound Proxy</a></li><li class="chapter-item expanded "><a href="../../../turn-howto.html">Configuring a Turn Server</a></li><li class="chapter-item expanded "><a href="../../../delegate.html">Delegation</a></li><li class="chapter-item expanded affix "><li class="part-title">Upgrading</li><li class="chapter-item expanded "><a href="../../../upgrade.html">Upgrading between Synapse Versions</a></li><li class="chapter-item expanded affix "><li class="part-title">Usage</li><li class="chapter-item expanded "><a href="../../../federate.html">Federation</a></li><li class="chapter-item expanded "><a href="../../../usage/configuration/index.html">Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../../usage/configuration/config_documentation.html">Configuration Manual</a></li><li class="chapter-item expanded "><a href="../../../usage/configuration/homeserver_sample_config.html">Homeserver Sample Config File</a></li><li class="chapter-item expanded "><a href="../../../usage/configuration/logging_sample_config.html">Logging Sample Config File</a></li><li class="chapter-item expanded "><a href="../../../structured_logging.html">Structured Logging</a></li><li class="chapter-item expanded "><a href="../../../templates.html">Templates</a></li><li class="chapter-item expanded "><a href="../../../usage/configuration/user_authentication/index.html">User Authentication</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../../usage/configuration/user_authentication/single_sign_on/index.html">Single-Sign On</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../../openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><a href="../../../usage/configuration/user_authentication/single_sign_on/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="../../../usage/configuration/user_authentication/single_sign_on/cas.html">CAS</a></li><li class="chapter-item expanded "><a href="../../../sso_mapping_providers.html">SSO Mapping Providers</a></li></ol></li><li class="chapter-item expanded "><a href="../../../password_auth_providers.html">Password Auth Providers</a></li><li class="chapter-item expanded "><a href="../../../jwt.html">JSON Web Tokens</a></li><li class="chapter-item expanded "><a href="../../../usage/configuration/user_authentication/refresh_tokens.html" class="active">Refresh Tokens</a></li></ol></li><li class="chapter-item expanded "><a href="../../../CAPTCHA_SETUP.html">Registration Captcha</a></li><li class="chapter-item expanded "><a href="../../../application_services.html">Application Services</a></li><li class="chapter-item expanded "><a href="../../../server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="../../../consent_tracking.html">Consent Tracking</a></li><li class="chapter-item expanded "><a href="../../../user_directory.html">User Directory</a></li><li class="chapter-item expanded "><a href="../../../message_retention_policies.html">Message Retention Policies</a></li><li class="chapter-item expanded "><a href="../../../modules/index.html">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../../modules/writing_a_module.html">Writing a module</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../../modules/spam_checker_callbacks.html">Spam checker callbacks</a></li><li class="chapter-item expanded "><a href="../../../modules/third_party_rules_callbacks.html">Third-party rules callbacks</a></li><li class="chapter-item expanded "><a href="../../../modules/presence_router_callbacks.html">Presence router callbacks</a></li><li class="chapter-item expanded "><a href="../../../modules/account_validity_callbacks.html">Account validity callbacks</a></li><li class="chapter-item expanded "><a href="../../../modules/password_auth_provider_callbacks.html">Password auth provider callbacks</a></li><li class="chapter-item expanded "><a href="../../../modules/background_update_controller_callbacks.html">Background update controller callbacks</a></li><li class="chapter-item expanded "><a href="../../../modules/account_data_callbacks.html">Account data callbacks</a></li><li class="chapter-item expanded "><a href="../../../modules/porting_legacy_module.html">Porting a legacy module to the new interface</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="../../../workers.html">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../../synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="../../../systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="../../../usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../../usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../../admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="../../../usage/administration/admin_api/background_updates.html">Background Updates</a></li><li class="chapter-item expanded "><a href="../../../admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="../../../admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="../../../admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="../../../admin_api/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="../../../usage/administration/admin_api/registration_tokens.html">Registration Tokens</a></li><li class="chapter-item expanded "><a href="../../../admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="../../../admin_api/rooms.html">Rooms</a></li><li class="chapter-item expanded "><a href="../../../admin_api/server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="../../../admin_api/statistics.html">Statistics</a></li><li class="chapter-item expanded "><a href="../../../admin_api/user_admin_api.html">Users</a></li><li class="chapter-item expanded "><a href="../../../admin_api/version_api.html">Server Version</a></li><li class="chapter-item expanded "><a href="../../../usage/administration/admin_api/federation.html">Federation</a></li></ol></li><li class="chapter-item expanded "><a href="../../../manhole.html">Manhole</a></li><li class="chapter-item expanded "><a href="../../../metrics-howto.html">Monitoring</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../../usage/administration/monitoring/reporting_homeserver_usage_statistics.html">Reporting Homeserver Usage Statistics</a></li></ol></li><li class="chapter-item expanded "><a href="../../../usage/administration/understanding_synapse_through_grafana_graphs.html">Understanding Synapse Through Grafana Graphs</a></li><li class="chapter-item expanded "><a href="../../../usage/administration/useful_sql_for_admins.html">Useful SQL for Admins</a></li><li class="chapter-item expanded "><a href="../../../usage/administration/database_maintenance_tools.html">Database Maintenance Tools</a></li><li class="chapter-item expanded "><a href="../../../usage/administration/state_groups.html">State Groups</a></li><li class="chapter-item expanded "><a href="../../../usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><a href="../../../usage/administration/admin_faq.html">Admin FAQ</a></li><li class="chapter-item expanded "><div>Scripts</div></li></ol></li><li class="chapter-item expanded "><li class="part-title">Development</li><li class="chapter-item expanded "><a href="../../../development/contributing_guide.html">Contributing Guide</a></li><li class="chapter-item expanded "><a href="../../../code_style.html">Code Style</a></li><li class="chapter-item expanded "><a href="../../../development/reviews.html">Reviewing Code</a></li><li class="chapter-item expanded "><a href="../../../development/releases.html">Release Cycle</a></li><li class="chapter-item expanded "><a href="../../../development/git.html">Git Usage</a></li><li class="chapter-item expanded "><div>Testing</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../../development/demo.html">Demo scripts</a></li></ol></li><li class="chapter-item expanded "><a href="../../../opentracing.html">OpenTracing</a></li><li class="chapter-item expanded "><a href="../../../development/database_schema.html">Database Schemas</a></li><li class="chapter-item expanded "><a href="../../../development/experimental_features.html">Experimental features</a></li><li class="chapter-item expanded "><a href="../../../development/dependencies.html">Dependency management</a></li><li class="chapter-item expanded "><div>Synapse Architecture</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../../development/synapse_architecture/cancellation.html">Cancellation</a></li><li class="chapter-item expanded "><a href="../../../log_contexts.html">Log Contexts</a></li><li class="chapter-item expanded "><a href="../../../replication.html">Replication</a></li><li class="chapter-item expanded "><a href="../../../tcp_replication.html">TCP Replication</a></li></ol></li><li class="chapter-item expanded "><a href="../../../development/internal_documentation/index.html">Internal Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single Sign-On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../../development/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="../../../development/cas.html">CAS</a></li></ol></li><li class="chapter-item expanded "><a href="../../../development/room-dag-concepts.html">Room DAG concepts</a></li><li class="chapter-item expanded "><div>State Resolution</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../../auth_chain_difference_algorithm.html">The Auth Chain Difference Algorithm</a></li></ol></li><li class="chapter-item expanded "><a href="../../../media_repository.html">Media Repository</a></li><li class="chapter-item expanded "><a href="../../../room_and_user_statistics.html">Room and User Statistics</a></li></ol></li><li class="chapter-item expanded "><div>Scripts</div></li><li class="chapter-item expanded affix "><li class="part-title">Other</li><li class="chapter-item expanded "><a href="../../../deprecation_policy.html">Dependency Deprecation Policy</a></li><li class="chapter-item expanded "><a href="../../../other/running_synapse_on_single_board_computers.html">Running Synapse on a Single-Board Computer</a></li></ol>
  75. </div>
  76. <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
  77. </nav>
  78. <div id="page-wrapper" class="page-wrapper">
  79. <div class="page">
  80. <div id="menu-bar-hover-placeholder"></div>
  81. <div id="menu-bar" class="menu-bar sticky bordered">
  82. <div class="left-buttons">
  83. <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
  84. <i class="fa fa-bars"></i>
  85. </button>
  86. <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
  87. <i class="fa fa-paint-brush"></i>
  88. </button>
  89. <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
  90. <li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
  91. <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
  92. <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
  93. <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
  94. <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
  95. </ul>
  96. <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
  97. <i class="fa fa-search"></i>
  98. </button>
  99. <div class="version-picker">
  100. <div class="dropdown">
  101. <div class="select">
  102. <span></span>
  103. <i class="fa fa-chevron-down"></i>
  104. </div>
  105. <input type="hidden" name="version">
  106. <ul class="dropdown-menu">
  107. <!-- Versions will be added dynamically in version-picker.js -->
  108. </ul>
  109. </div>
  110. </div>
  111. </div>
  112. <h1 class="menu-title">Synapse</h1>
  113. <div class="right-buttons">
  114. <a href="../../../print.html" title="Print this book" aria-label="Print this book">
  115. <i id="print-button" class="fa fa-print"></i>
  116. </a>
  117. <a href="https://github.com/matrix-org/synapse" title="Git repository" aria-label="Git repository">
  118. <i id="git-repository-button" class="fa fa-github"></i>
  119. </a>
  120. <a href="https://github.com/matrix-org/synapse/edit/develop/docs/usage/configuration/user_authentication/refresh_tokens.md" title="Suggest an edit" aria-label="Suggest an edit">
  121. <i id="git-edit-button" class="fa fa-edit"></i>
  122. </a>
  123. </div>
  124. </div>
  125. <div id="search-wrapper" class="hidden">
  126. <form id="searchbar-outer" class="searchbar-outer">
  127. <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
  128. </form>
  129. <div id="searchresults-outer" class="searchresults-outer hidden">
  130. <div id="searchresults-header" class="searchresults-header"></div>
  131. <ul id="searchresults">
  132. </ul>
  133. </div>
  134. </div>
  135. <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
  136. <script type="text/javascript">
  137. document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
  138. document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
  139. Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
  140. link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
  141. });
  142. </script>
  143. <div id="content" class="content">
  144. <main>
  145. <!-- Page table of contents -->
  146. <div class="sidetoc">
  147. <nav class="pagetoc"></nav>
  148. </div>
  149. <h1 id="refresh-tokens"><a class="header" href="#refresh-tokens">Refresh Tokens</a></h1>
  150. <p>Synapse supports refresh tokens since version 1.49 (some earlier versions had support for an earlier, experimental draft of <a href="https://github.com/matrix-org/matrix-doc/blob/main/proposals/2918-refreshtokens.md#msc2918-refresh-tokens">MSC2918</a> which is not compatible).</p>
  151. <h2 id="background-and-motivation"><a class="header" href="#background-and-motivation">Background and motivation</a></h2>
  152. <p>Synapse users' sessions are identified by <strong>access tokens</strong>; access tokens are
  153. issued to users on login. Each session gets a unique access token which identifies
  154. it; the access token must be kept secret as it grants access to the user's account.</p>
  155. <p>Traditionally, these access tokens were eternally valid (at least until the user
  156. explicitly chose to log out).</p>
  157. <p>In some cases, it may be desirable for these access tokens to expire so that the
  158. potential damage caused by leaking an access token is reduced.
  159. On the other hand, forcing a user to re-authenticate (log in again) often might
  160. be too much of an inconvenience.</p>
  161. <p><strong>Refresh tokens</strong> are a mechanism to avoid some of this inconvenience whilst
  162. still getting most of the benefits of short access token lifetimes.
  163. Refresh tokens are also a concept present in OAuth 2 — further reading is available
  164. <a href="https://datatracker.ietf.org/doc/html/rfc6749#section-1.5">here</a>.</p>
  165. <p>When refresh tokens are in use, both an access token and a refresh token will be
  166. issued to users on login. The access token will expire after a predetermined amount
  167. of time, but otherwise works in the same way as before. When the access token is
  168. close to expiring (or has expired), the user's client should present the homeserver
  169. (Synapse) with the refresh token.</p>
  170. <p>The homeserver will then generate a new access token and refresh token for the user
  171. and return them. The old refresh token is invalidated and can not be used again*.</p>
  172. <p>Finally, refresh tokens also make it possible for sessions to be logged out if they
  173. are inactive for too long, before the session naturally ends; see the configuration
  174. guide below.</p>
  175. <p>*To prevent issues if clients lose connection half-way through refreshing a token,
  176. the refresh token is only invalidated once the new access token has been used at
  177. least once. For all intents and purposes, the above simplification is sufficient.</p>
  178. <h2 id="caveats"><a class="header" href="#caveats">Caveats</a></h2>
  179. <p>There are some caveats:</p>
  180. <ul>
  181. <li>If a third party gets both your access token and refresh token, they will be able to
  182. continue to enjoy access to your session.
  183. <ul>
  184. <li>This is still an improvement because you (the user) will notice when <em>your</em>
  185. session expires and you're not able to use your refresh token.
  186. That would be a giveaway that someone else has compromised your session.
  187. You would be able to log in again and terminate that session.
  188. Previously (with long-lived access tokens), a third party that has your access
  189. token could go undetected for a very long time.</li>
  190. </ul>
  191. </li>
  192. <li>Clients need to implement support for refresh tokens in order for them to be a
  193. useful mechanism.
  194. <ul>
  195. <li>It is up to homeserver administrators if they want to issue long-lived access
  196. tokens to clients not implementing refresh tokens.
  197. <ul>
  198. <li>For compatibility, it is likely that they should, at least until client support
  199. is widespread.
  200. <ul>
  201. <li>Users with clients that support refresh tokens will still benefit from the
  202. added security; it's not possible to downgrade a session to using long-lived
  203. access tokens so this effectively gives users the choice.</li>
  204. </ul>
  205. </li>
  206. <li>In a closed environment where all users use known clients, this may not be
  207. an issue as the homeserver administrator can know if the clients have refresh
  208. token support. In that case, the non-refreshable access token lifetime
  209. may be set to a short duration so that a similar level of security is provided.</li>
  210. </ul>
  211. </li>
  212. </ul>
  213. </li>
  214. </ul>
  215. <h2 id="configuration-guide"><a class="header" href="#configuration-guide">Configuration Guide</a></h2>
  216. <p>The following configuration options, in the <code>registration</code> section, are related:</p>
  217. <ul>
  218. <li><code>session_lifetime</code>: maximum length of a session, even if it's refreshed.
  219. In other words, the client must log in again after this time period.
  220. In most cases, this can be unset (infinite) or set to a long time (years or months).</li>
  221. <li><code>refreshable_access_token_lifetime</code>: lifetime of access tokens that are created
  222. by clients supporting refresh tokens.
  223. This should be short; a good value might be 5 minutes (<code>5m</code>).</li>
  224. <li><code>nonrefreshable_access_token_lifetime</code>: lifetime of access tokens that are created
  225. by clients which don't support refresh tokens.
  226. Make this short if you want to effectively force use of refresh tokens.
  227. Make this long if you don't want to inconvenience users of clients which don't
  228. support refresh tokens (by forcing them to frequently re-authenticate using
  229. login credentials).</li>
  230. <li><code>refresh_token_lifetime</code>: lifetime of refresh tokens.
  231. In other words, the client must refresh within this time period to maintain its session.
  232. Unless you want to log inactive sessions out, it is often fine to use a long
  233. value here or even leave it unset (infinite).
  234. Beware that making it too short will inconvenience clients that do not connect
  235. very often, including mobile clients and clients of infrequent users (by making
  236. it more difficult for them to refresh in time, which may force them to need to
  237. re-authenticate using login credentials).</li>
  238. </ul>
  239. <p><strong>Note:</strong> All four options above only apply when tokens are created (by logging in or refreshing).
  240. Changes to these settings do not apply retroactively.</p>
  241. <h3 id="using-refresh-token-expiry-to-log-out-inactive-sessions"><a class="header" href="#using-refresh-token-expiry-to-log-out-inactive-sessions">Using refresh token expiry to log out inactive sessions</a></h3>
  242. <p>If you'd like to force sessions to be logged out upon inactivity, you can enable
  243. refreshable access token expiry and refresh token expiry.</p>
  244. <p>This works because a client must refresh at least once within a period of
  245. <code>refresh_token_lifetime</code> in order to maintain valid credentials to access the
  246. account.</p>
  247. <p>(It's suggested that <code>refresh_token_lifetime</code> should be longer than
  248. <code>refreshable_access_token_lifetime</code> and this section assumes that to be the case
  249. for simplicity.)</p>
  250. <p>Note: this will only affect sessions using refresh tokens. You may wish to
  251. set a short <code>nonrefreshable_access_token_lifetime</code> to prevent this being bypassed
  252. by clients that do not support refresh tokens.</p>
  253. <h4 id="choosing-values-that-guarantee-permitting-some-inactivity"><a class="header" href="#choosing-values-that-guarantee-permitting-some-inactivity">Choosing values that guarantee permitting some inactivity</a></h4>
  254. <p>It may be desirable to permit some short periods of inactivity, for example to
  255. accommodate brief outages in client connectivity.</p>
  256. <p>The following model aims to provide guidance for choosing <code>refresh_token_lifetime</code>
  257. and <code>refreshable_access_token_lifetime</code> to satisfy requirements of the form:</p>
  258. <ol>
  259. <li>inactivity longer than <code>L</code> <strong>MUST</strong> cause the session to be logged out; and</li>
  260. <li>inactivity shorter than <code>S</code> <strong>MUST NOT</strong> cause the session to be logged out.</li>
  261. </ol>
  262. <p>This model makes the weakest assumption that all active clients will refresh as
  263. needed to maintain an active access token, but no sooner.
  264. <em>In reality, clients may refresh more often than this model assumes, but the
  265. above requirements will still hold.</em></p>
  266. <p>To satisfy the above model,</p>
  267. <ul>
  268. <li><code>refresh_token_lifetime</code> should be set to <code>L</code>; and</li>
  269. <li><code>refreshable_access_token_lifetime</code> should be set to <code>L - S</code>.</li>
  270. </ul>
  271. </main>
  272. <nav class="nav-wrapper" aria-label="Page navigation">
  273. <!-- Mobile navigation buttons -->
  274. <a rel="prev" href="../../../jwt.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
  275. <i class="fa fa-angle-left"></i>
  276. </a>
  277. <a rel="next" href="../../../CAPTCHA_SETUP.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
  278. <i class="fa fa-angle-right"></i>
  279. </a>
  280. <div style="clear: both"></div>
  281. </nav>
  282. </div>
  283. </div>
  284. <nav class="nav-wide-wrapper" aria-label="Page navigation">
  285. <a rel="prev" href="../../../jwt.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
  286. <i class="fa fa-angle-left"></i>
  287. </a>
  288. <a rel="next" href="../../../CAPTCHA_SETUP.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
  289. <i class="fa fa-angle-right"></i>
  290. </a>
  291. </nav>
  292. </div>
  293. <script type="text/javascript">
  294. window.playground_copyable = true;
  295. </script>
  296. <script src="../../../elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
  297. <script src="../../../mark.min.js" type="text/javascript" charset="utf-8"></script>
  298. <script src="../../../searcher.js" type="text/javascript" charset="utf-8"></script>
  299. <script src="../../../clipboard.min.js" type="text/javascript" charset="utf-8"></script>
  300. <script src="../../../highlight.js" type="text/javascript" charset="utf-8"></script>
  301. <script src="../../../book.js" type="text/javascript" charset="utf-8"></script>
  302. <!-- Custom JS scripts -->
  303. <script type="text/javascript" src="../../../docs/website_files/table-of-contents.js"></script>
  304. <script type="text/javascript" src="../../../docs/website_files/version-picker.js"></script>
  305. <script type="text/javascript" src="../../../docs/website_files/version.js"></script>
  306. </body>
  307. </html>