[ARVADOS] updated: 1.3.0-1794-gc216fcdd3
Git user
git at public.curoverse.com
Fri Oct 25 15:09:25 UTC 2019
Summary of changes:
doc/_config.yml | 1 +
doc/admin/activation.html.textile.liquid | 73 +++++++++++-----------
doc/admin/reassign-ownership.html.textile.liquid | 47 ++++++++++++++
.../methods/user_agreements.html.textile.liquid | 44 +++++++++++++
doc/install/cheat_sheet.html.textile.liquid | 20 ++++++
5 files changed, 149 insertions(+), 36 deletions(-)
create mode 100644 doc/admin/reassign-ownership.html.textile.liquid
create mode 100644 doc/api/methods/user_agreements.html.textile.liquid
via c216fcdd36316b4d1a26904adcc4a2d847711442 (commit)
from 9e80ece5eae04261e562bf98445e03f3c8165a48 (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 c216fcdd36316b4d1a26904adcc4a2d847711442
Author: Peter Amstutz <pamstutz at veritasgenetics.com>
Date: Fri Oct 25 10:48:23 2019 -0400
15577: Add user_agreements API page
Lots more work on describing user setup/activation.
Arvados-DCO-1.1-Signed-off-by: Peter Amstutz <pamstutz at veritasgenetics.com>
diff --git a/doc/_config.yml b/doc/_config.yml
index 905edd389..9a1471b3a 100644
--- a/doc/_config.yml
+++ b/doc/_config.yml
@@ -114,6 +114,7 @@ navbar:
- api/methods/authorized_keys.html.textile.liquid
- api/methods/groups.html.textile.liquid
- api/methods/users.html.textile.liquid
+ - api/methods/user_agreements.html.textile.liquid
- System resources:
- api/methods/keep_services.html.textile.liquid
- api/methods/links.html.textile.liquid
diff --git a/doc/admin/activation.html.textile.liquid b/doc/admin/activation.html.textile.liquid
index b665040ee..4f9d2b2c0 100644
--- a/doc/admin/activation.html.textile.liquid
+++ b/doc/admin/activation.html.textile.liquid
@@ -12,52 +12,44 @@ SPDX-License-Identifier: CC-BY-SA-3.0
This page describes how new users are created and activated.
-"Browser login and management of API tokens is described here.":{{site.baseurl}}/api/tokens.html
-
h3. Authentication
-After completing the authentication process, a callback is made from the SSO server to the API server, providing a user record and @identity_url@ (despite the name, this is actually an Arvados user uuid).
-
-The API server searches for a user record with the @identity_url@ supplied by the SSO. If found, that user account will be used, unless the account has @redirect_to_user_uuid@ set, in which case it will use the user in @redirect_to_user_uuid@ instead (this is used for the "link account":{{site.baseurl}}/user/topics/link-accounts.html feature).
+"Browser login and management of API tokens is described here.":{{site.baseurl}}/api/tokens.html
-Next, it searches by email address for a "pre-activated account.":#pre-activated
+After completing the log in and authentication process, the API server receives a user record from the upstream identity provider (Google OAuth, LDAP, etc) consisting of the user's name, email address, and unique identifier called the @identity_url at .
-If no existing user record is found, a new user object will be created.
+The API server searches for a user record with the @identity_url@ supplied by the identity provider. If found, that user account will be used, unless the account has @redirect_to_user_uuid@ set, in which case it will use the user in @redirect_to_user_uuid@ instead (this is used for the "link account":{{site.baseurl}}/user/topics/link-accounts.html feature).
-A federated user follows a slightly different flow, whereby a special token is presented and the API server verifies user's identity with the home cluster, however it also results in a user object (representing the remote user) being created.
+If no matching @identity_url@ is found, it searches by email address. This allows for "provider migration":migrating-providers.html and a "pre-activated accounts.":#pre-activated
-h3. User setup
+If no existing user record is found, a new user object will be created.
-If @Users.AutoSetupNewUsers@ is true, as part of creating the new user object, the user is immediately set up with:
+A federated user follows a slightly different flow, whereby a special token is presented and the API server verifies user's identity with the home cluster. This results in a user object (representing the remote user) being created on the local cluster.
-* @can_login@ @permission@ link going (email address → user uuid) which records @identity_url_prefix@
-* Membership in the "All users" group (can read all users, all users can see new user)
-* A new git repo and @can_manage@ permission to that repo if @Users.AutoSetupNewUsersWithRepository@ is true
-* @can_login@ permission to a shell node if @Users.AutoSetupNewUsersWithVmUUID@ is set to the uuid of a vm
+h3. User activation
-Otherwise, an admin must explicitly invoke "setup" on the user via workbench or the API.
+A newly created user is inactive (@is_active@ is false) by default.
-h3. User activation
+An inactive user cannot create or update any object, but can read Arvados objects that the user account has permission to read.
-A newly created user is inactive (@is_active@ is false) unless explicitly set by the admin.
+There are three ways a user can be activated:
-An inactive user cannot create or update any object, but can read Arvados objects that the user account has permission to read. As a result, when @Users.AutoSetupNewUsers@ is true, an user who has been set up but is not activate may still be able to do things, such as read things shared with "All users", clone and push to the git repository, or login to a VM.
+# Self-activation. When a user logs in to Workbench, checks for "user agreements":#user_agreements and Workbench automatically attempts to self-activate.
+# An admin can invoke the @activate@ method of the users controller using @arv user activate --uuid=...@ (this also checks for user agreements)
+# An admin can set the @is_active@ field directly (bypassing user agreements)
-{% comment %}
-Maybe these services should check is_active.
+A user which has already been set up (either @Users.AutoSetupNewUsers@ is true, or an admin has invoked @setup@) can self-activate. The @activate@ method checks that the user has "signed" any user agreements, it will fail if they are not yet signed.
-I believe that when this was originally designed, being able to access git and VM required an ssh key, and an inactive user could not register an ssh key because that required creating a record. However, it is now possible to authenticate to shell VMs and http+git with just an API token.
-{% endcomment %}
+If the user has _not_ yet been set up (@Users.AutoSetupNewUsers@ is false) the user cannot self-activate, and requires an admin to either @setup@ the user (enabling self activation), or directly @activate@ the user.
-There are three ways a user can be activated.
+When a user is activated, some basic setup is done, but does not perform full "user setup":#setup .
-# Self-activation by Workbench. When an inactive user logs, Workbench attempts to self-activate. Successful activation creates the git repo and vm login for the user.
-# An admin can invoke the @activate@ method of the users controller using @arv user activate --uuid=...@
-# An admin can set the @is_active@ field directly. This runs @setup_on_activate@ which sets up oid_login_perm and group membership, but does not set repo or vm (even if if @Users.AutoSetupNewUsersWithRepository@ and/or @Users.AutoSetupNewUsersWithVmUUID@ are set). The admin can invoke "setup" separately (or use the "Setup" button on Workbench).
+* @can_login@ @permission@ link going (email address → user uuid) which records @identity_url_prefix@
+* Adding membership to the "All users" group (can read all users, all users can see new user)
h3(#deactivating_users). Deactivate a user
-Setting @is_active@ to @false@ is not sufficient to lock out a user. The user may be able to use re-activate themself. The correct way is to use @unsetup at .
+Setting @is_active@ to @false@ is *not* sufficient to lock out a user. The user may be able to use re-activate themself. The correct way is to use @unsetup at .
Note: also make sure that @is_admin: false at . If the user still has @is_admin: true@ the user may be able to re-activate themself.
@@ -77,7 +69,7 @@ Unsetup does not revoke API tokens.
An "inactive" user with a valid API token can still read the database, but is barred from creating or modifying records. User deactivation with "unsetup" should be done together with "ownership reassignment.":reassign-ownership.html
-h3(#user_agreements). User agreements
+h3(#user_agreements). User agreements and self-activation
The @activate@ method of the users controller checks if the user @is_invited@ and whether the user has "signed" all the user agreements.
@@ -86,22 +78,22 @@ The @activate@ method of the users controller checks if the user @is_invited@ an
* @Users.NewUsersAreActive@ is true
* The user account has permission to view the membership of the "All Users" group.
-User agreements are accessed by getting a listing on the @user_agreements@ endpoint. This returns a list of collection uuids. This is executed as a system user, so it bypasses normal read permission checks.
+User agreements are accessed through the "user_agreements API":{{site.baseurl}}/api/methods/user_agreements.html . This returns a list of collection records. This is executed as a system user, so it bypasses normal read permission checks.
-The available user agreements are represented in the Links table as
+The user agreements that users are required to sign should be added to the @links@ table this way:
<pre>
-{
+$ arv link create --link '{
"link_class": "signature",
"name": "require",
"tail_uuid": "*system user uuid*",
"head_uuid: "*collection uuid*"
-}
+}'
</pre>
-The collection contains the user agreement text file.
+The collection contains a single HTML file with the user agreement text.
-On workbench, it checks @is_invited at . If true, it displays the clickthrough agreements which the user can "sign". If @is_invited@ is false, the user ends up at the "inactive user" page.
+Workbench checks @is_invited at . If true, it displays the clickthrough agreements which the user can "sign". If @is_invited@ is false, the user ends up at the "inactive user" page.
The @user_agreements/sign@ endpoint creates a Link object:
@@ -114,10 +106,19 @@ The @user_agreements/sign@ endpoint creates a Link object:
}
</pre>
-This is executed as a system user, so it bypasses the restriction that inactive users cannot create objects.
-
The @user_agreements/signatures@ endpoint returns the list of Link objects that represent signatures by the current user (created by @sign@).
+h3(#setup). User setup
+
+A user can be setup whether they are active or not. Setting up an inactive user enables self-activation. Setup does the following things:
+
+* @can_login@ @permission@ link going (email address → user uuid) which records @identity_url_prefix@
+* Adding membership to the "All users" group (can read all users, all users can see new user)
+* If @Users.AutoSetupNewUsersWithRepository@ is true, a new default git repo and @can_manage@ permission to that repo
+* if @Users.AutoSetupNewUsersWithVmUUID@ is set, @can_login@ permission to a shell node
+
+If the cluster configuration option @Users.AutoSetupNewUsers@ is true, new users are always setup immediately. When @Users.AutoSetupNewUsers@ is true, an user who has been set up but is not activated may still be able to do things, such as read things shared with "All users", clone and push to the git repository, or login to a VM.
+
h3. User profile
The user profile is checked by workbench after checking if user agreements need to be signed. The requirement to fill out the user profile is not enforced by the API server.
diff --git a/doc/admin/reassign-ownership.html.textile.liquid b/doc/admin/reassign-ownership.html.textile.liquid
new file mode 100644
index 000000000..90f554a4a
--- /dev/null
+++ b/doc/admin/reassign-ownership.html.textile.liquid
@@ -0,0 +1,47 @@
+---
+layout: default
+navsection: admin
+title: "Reassign ownership of a user's data to another user"
+...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+If a user leaves an organization and stops using their Arvados account, it may be desirable to reassign the data owned by that user to another user to maintain easy access.
+
+This is currently a command line based, admin-only feature.
+
+h3. Step 1: Determine user uuids
+
+User uuids can be determined by browsing workbench or using @arv user list@ at the command line.
+
+The "old user" is the user that is leaving the organization.
+
+The "new user" is the user that will gain ownership of the old user's data. This includes collections, projects, container requests, workflows, and git repositories owned by the old user. It also transfers any permissions granted to the old user, to the new user.
+
+In the example below, @x1u39-tpzed-3kz0nwtjehhl0u4@ is the old user and @x1u39-tpzed-fr97h9t4m5jffxs@ is the new user.
+
+h3. Step 2: Create a project
+
+Create a project owned by the new user that will hold the data from the old user.
+
+<pre>
+$ arv --format=uuid group create --group '{"group_class": "project", "name": "Data from old user", "owner_uuid": "x1u39-tpzed-fr97h9t4m5jffxs"}'
+x1u39-j7d0g-mczqiguhil13083
+</pre>
+
+h3. Step 3: Reassign data from the 'old user' to the new user and project
+
+The @user merge@ method reassigns data from the old user to the new user.
+
+<pre>
+$ arv user merge --old-user-uuid=x1u39-tpzed-3kz0nwtjehhl0u4 \
+ --new-user-uuid=x1u39-tpzed-fr97h9t4m5jffxs \
+ --new-owner-uuid=x1u39-j7d0g-mczqiguhil13083
+</pre>
+
+After reassigning data, use "unsetup to deactivate the old user's account.":activation.html#deactivating_users
+
+Note that authorization credentials (API tokens, ssh keys) are *not* transferred to the new user, as this would potentially give the old user access to the new user's account.
diff --git a/doc/api/methods/user_agreements.html.textile.liquid b/doc/api/methods/user_agreements.html.textile.liquid
new file mode 100644
index 000000000..96dfab7d0
--- /dev/null
+++ b/doc/api/methods/user_agreements.html.textile.liquid
@@ -0,0 +1,44 @@
+---
+layout: default
+navsection: api
+navmenu: API Methods
+title: "user agreements"
+
+...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/user_agreements@
+
+h2. Resource
+
+This provides an API for inactive users to sign clickthrough agreements prior to being activated.
+
+h2. Methods
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
+h3. list
+
+List user agreements. This is a list of collections which contain HTML files with the text of the clickthrough agreement(s) which can be rendered by Workbench.
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+
+h3. signatures
+
+List user agreements that have already been signed. These are recorded as link objects of @{"link_class": "signature", "name": "click"}@.
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+
+h3. sign
+
+Sign a user agreement.
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+{background:#ccffcc}.|uuid|string|The UUID of the user agreement collection.|path||
diff --git a/doc/install/cheat_sheet.html.textile.liquid b/doc/install/cheat_sheet.html.textile.liquid
index 562b76ddf..ef0c80e71 100644
--- a/doc/install/cheat_sheet.html.textile.liquid
+++ b/doc/install/cheat_sheet.html.textile.liquid
@@ -28,12 +28,32 @@ arv virtual_machine create --virtual-machine '{"hostname":"xxxxxxxchangeme.examp
h3. CLI: Activate user
+Note this bypasses user agreements checks, and does not set up the user with a default git repository or VM login.
+
<pre>
user_uuid=xxxxxxxchangeme
arv user update --uuid "$user_uuid" --user '{"is_active":true}'
</pre>
+h3. CLI: Setup a user
+
+This creates a default git repository and VM login.
+
+<pre>
+user_uuid=xxxxxxxchangeme
+
+arv user setup --uuid "$user_uuid"
+</pre>
+
+h3. CLI: Deactivate user
+
+<pre>
+user_uuid=xxxxxxxchangeme
+
+arv user unsetup --uuid "$user_uuid"
+</pre>
+
h3. User → VM
Give @$user_uuid@ permission to log in to @$vm_uuid@ as @$target_username@
-----------------------------------------------------------------------
hooks/post-receive
--
More information about the arvados-commits
mailing list