[ARVADOS] updated: 1.3.0-2959-g3e38df9fa

Tue Aug 25 17:44:43 UTC 2020

Summary of changes:
 .../token-expiration-policy.html.textile.liquid    | 42 ++++++++------
 doc/admin/user-management-cli.html.textile.liquid  | 64 ++++++++++++++++++----
 2 files changed, 76 insertions(+), 30 deletions(-)

       via  3e38df9fabcbf421ef0b0aac2e82f92373c0e70f (commit)
      from  46fefa537c9bf8c2835a5ae26bf77a8dfb3fe10f (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.


commit 3e38df9fabcbf421ef0b0aac2e82f92373c0e70f
Author: Peter Amstutz <peter.amstutz at curii.com>
Date:   Tue Aug 25 13:44:10 2020 -0400

    16678: Wording improvements, document how to create a token at cli
    
    Arvados-DCO-1.1-Signed-off-by: Peter Amstutz <peter.amstutz at curii.com>

diff --git a/doc/admin/token-expiration-policy.html.textile.liquid b/doc/admin/token-expiration-policy.html.textile.liquid
index 7a3d79399..7c71e6801 100644
--- a/doc/admin/token-expiration-policy.html.textile.liquid
+++ b/doc/admin/token-expiration-policy.html.textile.liquid
@@ -1,7 +1,7 @@
 ---
 layout: default
 navsection: admin
-title: Limiting user session's lifetime
+title: Setting token expiration policy
 ...
 
 {% comment %}
@@ -10,15 +10,15 @@ Copyright (C) The Arvados Authors. All rights reserved.
 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:
@@ -29,28 +29,34 @@ 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@ 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 at example.com,zzzzz-tpzed-5vzt5wc62k46p6r
 admin,admin at example.com,zzzzz-tpzed-6drplgwq9nm5cox
 user1,user1 at 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 accouts that need to be long-lived, you can "create tokens that don't expire using the command line":user-management-cli.html#create-token .
diff --git a/doc/admin/user-management-cli.html.textile.liquid b/doc/admin/user-management-cli.html.textile.liquid
index 33969ea8f..689217660 100644
--- a/doc/admin/user-management-cli.html.textile.liquid
+++ b/doc/admin/user-management-cli.html.textile.liquid
@@ -16,7 +16,7 @@ ARVADOS_API_HOST={{ site.arvados_api_host }}
 ARVADOS_API_TOKEN=1234567890qwertyuiopasdfghjklzxcvbnm1234567890zzzz
 </pre>
 
-In these examples, @x1u39-tpzed-3kz0nwtjehhl0u4@ is the sample user account.  Replace with the uuid of the user you wish to manipulate.
+In these examples, @zzzzz-tpzed-3kz0nwtjehhl0u4@ is the sample user account.  Replace with the uuid of the user you wish to manipulate.
 
 See "user management":{{site.baseurl}}/admin/activation.html for an overview of how to use these commands.
 
@@ -24,28 +24,68 @@ h3. Setup a user
 
 This creates a default git repository and VM login.  Enables user to self-activate using Workbench.
 
-<pre>
-arv user setup --uuid x1u39-tpzed-3kz0nwtjehhl0u4
-</pre>
+<notextile>
+<pre><code>$ <span class="userinput">arv user setup --uuid zzzzz-tpzed-3kz0nwtjehhl0u4</span>
+</code></pre>
+</notextile>
+
 
 h3. Deactivate user
 
-<pre>
-arv user unsetup --uuid x1u39-tpzed-3kz0nwtjehhl0u4
-</pre>
+<notextile>
+<pre><code>$ <span class="userinput">arv user unsetup --uuid zzzzz-tpzed-3kz0nwtjehhl0u4</span>
+</code></pre>
+</notextile>
+
 
 When deactivating a user, you may also want to "reassign ownership of their data":{{site.baseurl}}/admin/reassign-ownership.html .
 
 h3. Directly activate user
 
-<pre>
-arv user update --uuid "x1u39-tpzed-3kz0nwtjehhl0u4" --user '{"is_active":true}'
-</pre>
+<notextile>
+<pre><code>$ <span class="userinput">arv user update --uuid "zzzzz-tpzed-3kz0nwtjehhl0u4" --user '{"is_active":true}'</span>
+</code></pre>
+</notextile>
+
+Note: this bypasses user agreements checks, and does not set up the user with a default git repository or VM login.
 
-Note this bypasses user agreements checks, and does not set up the user with a default git repository or VM login.
+h3(#create-token). Create a token for a user
 
+As an admin, you can create tokens for other users.
+
+<notextile>
+<pre><code>$ <span class="userinput">arv api_client_authorization create --api-client-authorization '{"owner_uuid": "zzzzz-tpzed-fr97h9t4m5jffxs"}'</span>
+{
+ "href":"/api_client_authorizations/zzzzz-gj3su-yyyyyyyyyyyyyyy",
+ "kind":"arvados#apiClientAuthorization",
+ "etag":"9yk144t0v6cvyp0342exoh2vq",
+ "uuid":"zzzzz-gj3su-yyyyyyyyyyyyyyy",
+ "owner_uuid":"zzzzz-tpzed-fr97h9t4m5jffxs",
+ "created_at":"2020-03-12T20:36:12.517375422Z",
+ "modified_by_client_uuid":null,
+ "modified_by_user_uuid":null,
+ "modified_at":null,
+ "user_id":3,
+ "api_client_id":7,
+ "api_token":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+ "created_by_ip_address":null,
+ "default_owner_uuid":null,
+ "expires_at":null,
+ "last_used_at":null,
+ "last_used_by_ip_address":null,
+ "scopes":["all"]
+}
+</code></pre>
+</notextile>
+
+
+To get the token string, combine the values of @uuid@ and @api_token@ in the form "v2/$uuid/$api_token".  In this example the string that goes in @ARVADOS_API_TOKEN@ would be:
+
+<pre>
+ARVADOS_API_TOKEN=v2/zzzzz-gj3su-yyyyyyyyyyyyyyy/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+</pre>
 
-h2. Permissions
+h2. Adding Permissions
 
 h3. VM login
 

-----------------------------------------------------------------------


hooks/post-receive
-- 


