doc/admin/activation.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: admin
   4 title: User activation
   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 After completing the authentication process with the SSO server and receiving a new @identity_url@, a new user object is always created.
  14
  15 h3. Auto setup
  16
  17 If @auto_setup_new_users@ is true, as part of creating the new user object, the user is immediately setup with:
  18
  19 * @can_login@ @permission@ link going (email address &rarr; user uuid) which records @identity_url_prefix@ (??? wtf does this mean)
  20 * Membership in the "All users" group (can read all users, all users can see new user)
  21 * A new git repo and @can_manage@ permission if @auto_setup_new_users_with_repository@ is true
  22 * @can_login@ permission to a shell node if @auto_setup_new_users_with_vm_uuid@ is set to the uuid of a vm
  23
  24 h3. is_active
  25
  26 A newly created user is inactive (@is_active@ is false) by default unless @new_users_are_active@.
  27
  28 An inactive user cannot create or update any object, but can read Arvados objects that the user account has permission to read.  This implies that if @auto_setup_new_users@ is true, an "inactive" user who has been set up 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.  (unless these services check is_active)
  29
  30 (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).
  31
  32 At this point, there are two ways a user can become active:
  33
  34 # 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 @auto_setup_new_users_with_repository@ and/or @auto_setup_new_users_with_vm_uuid@ are set).
  35 # Calling to the @activate@ method of the users controller.   (see below).
  36
  37 h3. User agreements
  38
  39 The @activate@ method of the users controller.  This checks if the user @is_invited@ and whether the user has signed all the clickthrough agreements.
  40
  41 @is_invited@ is true if any of these are true:
  42 * @is_active@ is true
  43 * @new_users_are_active@ is true
  44 * the user account has a permission link to read the system "all users" group.
  45
  46 Clickthrough 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.
  47
  48 The available user agreements are represented in the links table as @link_class: signature@ and @name: require@ and (system_user_uuid &rarr; uuid of collection containing user agreement text file)
  49
  50 On workbench, it checks @is_invited@.  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.
  51
  52 The @user_agreements/sign@ endpoint creates a Link with @link_class: signature@ and @name: click@ and (current user uuid &rarr; collection uuid). This is executed as a system user, so it bypasses the restriction that inactive users cannot create objects.
  53
  54 The @user_agreements/signatures@ endpoint returns the list of Link objects that represent signatures by the current user (created by @sign@).
  55
  56 h3. Typical flows
  57
  58 h4. Open instance
  59
  60 Policy: anybody who shows up and signs the agreements is activated.
  61
  62 <pre>
  63 auto_setup_new_users: true
  64 new_users_are_active: false
  65 </pre>
  66
  67 # User is created and auto-setup.  At this point, @is_active@ is false, but user has been added to "All users" group.
  68 # Workbench checks @is_invited@ and finds it is true, because the user is a member of "All users" group.
  69 # Workbench presents user with list of user agreements, user reads and clicks "sign" for each one.
  70 # Workbench tries to activate user.
  71 # User is activated.
  72
  73 h4. Private instance
  74
  75 Policy: users must be manually approved.
  76
  77 <pre>
  78 auto_setup_new_users: false
  79 new_users_are_active: false
  80 </pre>
  81
  82 # User is created.  Not set up.  @is_active@ is false.
  83 # Workbench checks @is_invited@ and finds it is false.  User gets "inactive user" page.
  84 # Admin goes to user page and clicks either "setup user" or manually @is_active@ to true.
  85 # Clicking "setup user" sets up the user.  This includes adding the user to "All users" which qualifies the user as @is_invited@.
  86 # On refreshing workbench, the user is still inactive, but is able to self-activate after signing clickthrough agreements (if any).
  87 # Alternately, directly setting @is_active@ to true also sets up the user, but workbench won't display clickthrough agreements (because the user is already active).
  88
  89 h4. Developer instance
  90
  91 Policy: avoid wasting developer's time clicking through extra pages.
  92
  93 <pre>
  94 auto_setup_new_users: true
  95 new_users_are_active: true
  96 </pre>
  97
  98 # User is created and auto-setup.  Also sets @is_active@ to true.
  99 # User can immediately start using workbench.
 100
 101 h3. User profile
 102
 103 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.
 104
 105 h3. Deactivating users
 106
 107 Setting @is_active@ is not sufficient to lock out a user.  The user can call @activate@ to become active again.  Instead, use @unsetup@:
 108
 109 * Delete oid_login_perms
 110 * Delete git repository permission links
 111 * Delete VM login permission links
 112 * Remove from "All users" group
 113 * Delete any "signatures"
 114 * Clear preferences / profile
 115 * Mark as inactive
 116
 117 Does not revoke @is_admin@ though!  Maybe we need to fix that?
 118
 119 Does not prevent user from reading things?