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

   1 ---
   2 layout: default
   3 navsection: admin
   4 title: Setting token expiration policy
   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 that grants access to the Arvados API on behalf of that user.  By default, this token does not expire until the user explicitly logs off.
  14
  15 Security policies, such as for GxP Compliance, may require that tokens expire by default in order to limit the risk associated with a token being leaked.
  16
  17 The @Login.TokenLifetime@ configuration enables the administrator to set a expiration lifetime for tokens granted through the login flow.
  18
  19 h2. Setting token expiration
  20
  21 Suppose that the organization's security policy requires that user sessions should not be valid for more than 12 hours, the cluster configuration should be set like the following:
  22
  23 <pre>
  24 Clusters:
  25   zzzzz:
  26     ...
  27     Login:
  28       TokenLifetime: 12h
  29     ...
  30 </pre>
  31
  32 With this configuration, users will have to re-login every 12 hours.
  33
  34 When this configuration is active, the workbench client will also be "untrusted" by default.  This means tokens issued to workbench 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.
  35
  36 The default @TokenLifetime@ is zero, which disables this feature.
  37
  38 h2. Applying policy to existing tokens
  39
  40 If you have an existing Arvados installation and want to set a token lifetime policy, there may be user tokens already granted.  The administrator can use the following @rake@ tasks to enforce the new policy.
  41
  42 The @db:check_long_lived_tokens@ task will list which users have tokens with no expiration date.
  43
  44 <notextile>
  45 <pre><code># <span class="userinput">bundle exec rake db:check_long_lived_tokens</span>
  46 Found 6 long-lived tokens from users:
  47 user2,user2@example.com,zzzzz-tpzed-5vzt5wc62k46p6r
  48 admin,admin@example.com,zzzzz-tpzed-6drplgwq9nm5cox
  49 user1,user1@example.com,zzzzz-tpzed-ftz2tfurbpf7xox
  50 </code></pre>
  51 </notextile>
  52
  53 To apply the new policy to existing tokens, use the @db:fix_long_lived_tokens@ task.
  54
  55 <notextile>
  56 <pre><code># <span class="userinput">bundle exec rake db:fix_long_lived_tokens</span>
  57 Setting token expiration to: 2020-08-25 03:30:50 +0000
  58 6 tokens updated.
  59 </code></pre>
  60 </notextile>
  61
  62 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 .