---
layout: default
navsection: admin
-title: Limiting user session's lifetime
+title: Setting token expiration policy
...
{% comment %}
SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}
-Whenever a user authenticates to start a session on Workbench, a token is created that grants the user access to the Arvados API. This token has an expiration date that by default isn't set.
+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.
-Depending on the local security policies where any given Arvados cluster is installed, it may be needed to restrict these access tokens by giving them a default expiration date at creation time.
+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.
-For this very purpose, the site administrator can use the @Login.TokenLifetime@ configuration, assigning a token lifetime value that will be used for newly created tokens. When setting this value to zero, the feature is disabled.
+The @Login.TokenLifetime@ configuration enables the administrator to set a expiration lifetime for tokens granted through the login flow.
-h2. Setting token's expiration
+h2. Setting token expiration
-Suppose that the organization's security policy requires that no user session should be valid for more than 12 hours from being created, the cluster configuration should be set like the following:
+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:
<pre>
Clusters:
...
</pre>
-This will force users to re-login every 12 hours and avoid any leaked token to be abused indefinitely.
+With this configuration, users will have to re-login every 12 hours.
-h2. Applying a policy to previously created tokens
+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.
-If you happen to have a previously working Arvados installation and need to set a token lifetime policy, chances are that the system has already issued user tokens without expiration. You can reset or remove these tokens using the Arvados API endpoints with the system root token, but we provide a couple of @rake@ tasks to make it easier:
+The default @TokenLifetime@ is zero, which disables this feature.
-The @db:check_long_lived_tokens@ will list users owning tokens with no expiration date.
+h2. Applying policy to existing tokens
-<pre>
-# bundle exec rake db:check_long_lived_tokens
+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.
+
+The @db:check_long_lived_tokens@ task will list which users have tokens with no expiration date.
+
+<notextile>
+<pre><code># <span class="userinput">bundle exec rake db:check_long_lived_tokens</span>
Found 6 long-lived tokens from users:
user2,user2@example.com,zzzzz-tpzed-5vzt5wc62k46p6r
admin,admin@example.com,zzzzz-tpzed-6drplgwq9nm5cox
user1,user1@example.com,zzzzz-tpzed-ftz2tfurbpf7xox
-</pre>
+</code></pre>
+</notextile>
-To apply the currently configured policy to the non-expiring tokens, you need to execute the @db:fix_long_lived_tokens@ task.
+To apply the new policy to existing tokens, use the @db:fix_long_lived_tokens@ task.
-<pre>
-# bundle exec rake db:fix_long_lived_tokens
+<notextile>
+<pre><code># <span class="userinput">bundle exec rake db:fix_long_lived_tokens</span>
Setting token expiration to: 2020-08-25 03:30:50 +0000
6 tokens updated.
-</pre>
+</code></pre>
+</notextile>
-NOTE: As there's no clear way to differentiate tokens created on user logins from other tokens, these rake tasks operate on the entire token collection so you may need to re-create special tokens, although tokens related to the system root user (@zzzzz-tpzed-000000000000000@) will be ignored.
\ No newline at end of file
+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 .
projects / arvados.git / blobdiff