doc/admin/token-expiration-policy.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: admin
   4 title: Automatic logout and token expiration
   5 ...
   6
   7 {% comment %}
   8 Copyright (C) The Arvados Authors. All rights reserved.
   9
  10 SPDX-License-Identifier: CC-BY-SA-3.0
  11 {% endcomment %}
  12
  13 When a user logs in to Workbench, they receive a newly created token (a long string of random characters) which grants access to the Arvados API on behalf of that user.  In the default configuration, this token does not expire until the user explicitly logs out.
  14
  15 Security policies, such as those required to comply with regulations such as HIPAA and GxP, may include policies for "automatic logoff".  In order to limit the window of risk associated with unauthorized access of the desktop of an Arvados user, or a token being leaked, Arvados offers options for automatic logout from the web app, and to configure access tokens to expire by default.
  16
  17 The @Workbench.IdleTimeout@, @Login.TokenLifetime@, and @API.MaxTokenLifetime@ options give the administrator ways to control automatic expiration of tokens granted through the login flow.
  18
  19 If you are looking for information on how to expire a token manually, see how to "delete a single token":user-management-cli.html#delete-token and "delete all tokens belonging to a user":user-management-cli.html#delete-all-tokens .
  20
  21 h2. Automatic logout
  22
  23 Use @Workbench.IdleTimeout@ to configure Workbench 2 for automatic logout after a period of idle time.  For example, this configuration would log the user out after five minutes of no keyboard or pointer activity:
  24
  25 <pre>
  26 Clusters:
  27   zzzzz:
  28     ...
  29     Workbench:
  30       IdleTimeout: 5m
  31     ...
  32 </pre>
  33
  34 When idle timeout is set, several behaviors and considerations apply:
  35
  36 * The user will be automatically logged out after a period of inactivity.  When the automatic logout happens, the token associated with that session will be revoked.
  37 * Users should use the "open in new tab" functionality of Workbench 2.  This will share the same token between tabs without requiring the user to log in again.  Logging out will apply to all browser tabs that use the same token.
  38 * If the user closes a Workbench tab without first logging out, the browser will forget the token, but not expire the token (this is desirable if the user has several tabs open).
  39 * If the user closes all Workbench tabs, they will be required to log in again.
  40 * This only affects browser behavior.  Automatic logout should be used together automatic token expiration described below.
  41
  42 The default value for @Workbench.IdleTimeout@ is zero, which disables auto-logout.
  43
  44 h2. Automatic expiration of login tokens
  45
  46 Use @Login.TokenLifetime@ to set the lifetime for tokens issued through the login process.  This is the maximum amount of time a user can maintain a session before having to log in again.  This setting applies to both regular and admin user logins.  Here is an example configuration that would require the user to log in again after 12 hours:
  47
  48 <pre>
  49 Clusters:
  50   zzzzz:
  51     ...
  52     Login:
  53       TokenLifetime: 12h
  54     ...
  55 </pre>
  56
  57 This is independent of @Workbench.IdleTimeout@.  Even if Workbench auto-logout is disabled, this option will ensure that the user is always required to log in again after the configured amount of time.
  58
  59 h2. Untrusted login tokens
  60
  61 <pre>
  62 Clusters:
  63   zzzzz:
  64     ...
  65     Login:
  66       TrustLoginTokens: false
  67     ...
  68 </pre>
  69
  70 When `TrustLoginTokens` is `false`, tokens issued through login will be "untrusted" by default.  Untrusted tokens cannot be used to list other tokens issued to the user, and cannot be used to grant new tokens.  This stops an attacker from leveraging a leaked token to aquire other tokens, but also interferes with some Workbench features that create new tokens on behalf of the user.
  71
  72 The default value @Login.TokenLifetime@ is zero, meaning login tokens do not expire (unless @API.MaxTokenLifetime@ is set).
  73
  74 h2. Automatic expiration of all tokens
  75
  76 Use @API.MaxTokenLifetime@ to set the maximum lifetime for any access token created by regular (non-admin) users.  For example, this configuration would require that all tokens expire after 24 hours:
  77
  78 <pre>
  79 Clusters:
  80   zzzzz:
  81     ...
  82     API:
  83       MaxTokenLifetime: 24h
  84     ...
  85 </pre>
  86
  87 Tokens created without an explicit expiration time, or that exceed maximum lifetime, will be set to @API.MaxTokenLifetime@.
  88
  89 Similar to @Login.TokenLifetime@, this option ensures that the user is always required to log in again after the configured amount of time.
  90
  91 Unlike @Login.TokenLifetime@, this applies to all API operations that manipulate tokens, regardless of whether the token was created by logging in, or by using the API.  If @Login.TokenLifetime@ is greater than @API.MaxTokenLifetime@, MaxTokenLifetime takes precedence.
  92
  93 Admin users are permitted to create tokens with expiration times further in the future than @MaxTokenLifetime@.
  94
  95 The default value @MaxTokenLifetime@ is zero, which means there is no maximum token lifetime.
  96
  97 h2. Choosing a policy
  98
  99 @Workbench.IdleTimeout@ only affects browser behavior.  It is strongly recommended that automatic browser logout be used together with @Login.TokenLifetime@, which is enforced on API side.
 100
 101 @TrustLoginTokens: true@ (default value) is less restrictive.  Be aware that an unrestricted token can be "refreshed" to gain access for an indefinite period.  This means, during the window that the token is valid, the user is permitted to create a new token, which will have a new expiration further in the future (of course, once the token has expired, this is no longer possible).  Unrestricted tokens are required for some Workbench features, as well as ease of use in other contexts, such as the Arvados command line.  This option is recommended if many users will interact with the system through the command line.
 102
 103 @TrustLoginTokens: false@ is more restrictive.  A token obtained by logging into Workbench cannot be "refreshed" to gain access for an indefinite period.  However, it interferes with some Workbench features, as well as ease of use in other contexts, such as the Arvados command line.  This option is recommended only if most users will only ever interact with the system through Workbench or WebShell.  For users or service accounts that need to tokens with fewer restrictions, the admin can "create a token at the command line":user-management-cli.html#create-token using the @SystemRootToken@.
 104
 105 In every case, admin users may always create tokens with expiration dates far in the future.
 106
 107 These policies do not apply to tokens created by the API server for the purposes of authorizing a container to run, as those tokens are automatically expired when the container is finished.
 108
 109 h2. Applying policy to existing tokens
 110
 111 If you have an existing Arvados installation and want to set a token lifetime policy, there may be long-lived user tokens already granted.  The administrator can use the following @rake@ tasks to enforce the new policy.
 112
 113 The @db:check_long_lived_tokens@ task will list which users have tokens with no expiration date.
 114
 115 <notextile>
 116 <pre><code># <span class="userinput">bin/rake db:check_long_lived_tokens</span>
 117 Found 6 long-lived tokens from users:
 118 user2,user2@example.com,zzzzz-tpzed-5vzt5wc62k46p6r
 119 admin,admin@example.com,zzzzz-tpzed-6drplgwq9nm5cox
 120 user1,user1@example.com,zzzzz-tpzed-ftz2tfurbpf7xox
 121 </code></pre>
 122 </notextile>
 123
 124 To apply the new policy to existing tokens, use the @db:fix_long_lived_tokens@ task.
 125
 126 <notextile>
 127 <pre><code># <span class="userinput">bin/rake db:fix_long_lived_tokens</span>
 128 Setting token expiration to: 2020-08-25 03:30:50 +0000
 129 6 tokens updated.
 130 </code></pre>
 131 </notextile>
 132
 133 NOTE: These rake tasks adjust the expiration of all tokens except those belonging to the system root user (@zzzzz-tpzed-000000000000000@).  If you have tokens used by automated service accounts that need to be long-lived, you can "create tokens that don't expire using the command line":user-management-cli.html#create-token .