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 This page describes how new users are created and activated.
  14
  15 h3. Authentication
  16
  17 "Browser login and management of API tokens is described here.":{{site.baseurl}}/api/tokens.html
  18
  19 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@.
  20
  21 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).
  22
  23 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
  24
  25 If no existing user record is found, a new user object will be created.
  26
  27 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.
  28
  29 h3. User activation
  30
  31 A newly created user is inactive (@is_active@ is false) by default.
  32
  33 An inactive user cannot create or update any object, but can read Arvados objects that the user account has permission to read.
  34
  35 There are three ways a user can be activated:
  36
  37 # Self-activation.  When a user logs in to Workbench, checks for "user agreements":#user_agreements and Workbench automatically attempts to self-activate.
  38 # An admin can invoke the @activate@ method of the users controller using @arv user activate --uuid=...@ (this also checks for user agreements)
  39 # An admin can set the @is_active@ field directly (bypassing user agreements)
  40
  41 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.
  42
  43 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.
  44
  45 When a user is activated, some basic setup is done, but does not perform full "user setup":#setup .
  46
  47 * @can_login@ @permission@ link going (email address &rarr; user uuid) which records @identity_url_prefix@
  48 * Adding membership to the "All users" group (can read all users, all users can see new user)
  49
  50 h3(#deactivating_users). Deactivate a user
  51
  52 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@.
  53
  54 Note: also make sure that @is_admin: false@.  If the user still has @is_admin: true@ the user may be able to re-activate themself.
  55
  56 <pre>
  57 $ arv user unsetup --uuid=x1u39-tpzed-3kz0nwtjehhl0u4
  58 </pre>
  59
  60 * Delete oid_login_perms
  61 * Delete git repository permission links
  62 * Delete VM login permission links
  63 * Remove access to "All users" group
  64 * Delete any user agreement signatures
  65 * Clear preferences / profile
  66 * Mark as inactive
  67
  68 Unsetup does not revoke API tokens.
  69
  70 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
  71
  72 h3(#user_agreements). User agreements and self-activation
  73
  74 The @activate@ method of the users controller checks if the user @is_invited@ and whether the user has "signed" all the user agreements.
  75
  76 @is_invited@ is true if any of these are true:
  77 * @is_active@ is true
  78 * @Users.NewUsersAreActive@ is true
  79 * The user account has permission to view the membership of the "All Users" group.
  80
  81 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.
  82
  83 The user agreements that users are required to sign should be added to the @links@ table this way:
  84
  85 <pre>
  86 $ arv link create --link '{
  87   "link_class": "signature",
  88   "name": "require",
  89   "tail_uuid": "*system user uuid*",
  90   "head_uuid: "*collection uuid*"
  91 }'
  92 </pre>
  93
  94 The collection contains a single HTML file with the user agreement text.
  95
  96 Workbench 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.
  97
  98 The @user_agreements/sign@ endpoint creates a Link object:
  99
 100 <pre>
 101 {
 102   "link_class": "signature"
 103   "name": "click",
 104   "tail_uuid": "*user uuid*",
 105   "head_uuid: "*collection uuid*"
 106 }
 107 </pre>
 108
 109 The @user_agreements/signatures@ endpoint returns the list of Link objects that represent signatures by the current user (created by @sign@).
 110
 111 h3(#setup). User setup
 112
 113 A user can be setup whether they are active or not.  Setting up an inactive user enables self-activation.  Setup does the following things:
 114
 115 * @can_login@ @permission@ link going (email address &rarr; user uuid) which records @identity_url_prefix@
 116 * Adding membership to the "All users" group (can read all users, all users can see new user)
 117 * If @Users.AutoSetupNewUsersWithRepository@ is true, a new default git repo and @can_manage@ permission to that repo
 118 * if @Users.AutoSetupNewUsersWithVmUUID@ is set, @can_login@ permission to a shell node
 119
 120 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.
 121
 122 h3. User profile
 123
 124 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.
 125
 126 h3(#pre-activated). Pre-activate user by email address
 127
 128 You may create a user account for a user that has not yet logged in, and identify the user by email address.
 129
 130 1. As an admin, create a user object:
 131
 132 <pre>
 133 $ arv user create --user '{"email": "foo@example.com", "username": "barney", "is_active": true}'
 134 </pre>
 135
 136 2. When the user logs in the first time, the email address will be recognized and the user will be associated with the existing user object.
 137
 138 h3. Pre-activate federated user
 139
 140 1. As admin, create a user object with the @uuid@ of the federated user (this is the user's uuid on their home cluster, called @clsr2@ in this example):
 141
 142 <pre>
 143 $ arv user create --user '{"uuid": "clsr2-tpzed-1234567890abcdf", "email": "foo@example.com", "username": "barney", "is_active": true}'
 144 </pre>
 145
 146 2. When the user logs in, they will be associated with the existing user object.
 147
 148 h3. Auto-activate federated users from trusted clusters
 149
 150 In the API server config, set @ActivateUsers: true@ for each federated cluster in @RemoteClusters@ .  A federated user from one of the listed clusters which @is_active@ on the home cluster will be automatically set up and activated on this cluster.
 151
 152 h3. Activation flows
 153
 154 h4. Private instance
 155
 156 Policy: users must be manually activated by the admin.
 157
 158 Here is the configuration for this policy.  This is also the default if not provided.
 159 (However, be aware this is not how developer/demo builds such as "arvbox":{{site.baseurl}}/install/arvbox.html are configured.)
 160
 161 <pre>
 162 Users:
 163   AutoSetupNewUsers: false
 164   NewUsersAreActive: false
 165 </pre>
 166
 167 # User is created.  Not set up.  @is_active@ is false.
 168 # Workbench checks @is_invited@ and finds it is false.  User gets "inactive user" page.
 169 # Admin goes to user page and clicks either "setup user" or manually @is_active@ to true.
 170 # Clicking "setup user" sets up the user.  This includes adding the user to "All users" which qualifies the user as @is_invited@.
 171 # On refreshing workbench, the user is still inactive, but is able to self-activate after signing clickthrough agreements (if any).
 172 # 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).
 173
 174 h4. Federated instance
 175
 176 Policy: users other clusters in the federation are activated, users from outside the federation must be manually approved.
 177
 178 Here is the configuration for this policy and an example remote cluster @clsr2@.
 179
 180 <pre>
 181 Users:
 182   AutoSetupNewUsers: false
 183   NewUsersAreActive: false
 184 RemoteClusters:
 185   clsr2:
 186     ActivateUsers: true
 187 </pre>
 188
 189 # Federated user arrives claiming to be from cluster 'clsr2'
 190 # API server authenticates user as being from cluster 'clsr2'
 191 # Because 'clsr2' has @ActivateUsers@ the user is set up and activated.
 192 # User can immediately start using Workbench.
 193
 194 h4. Open instance
 195
 196 Policy: anybody who shows up and signs the agreements is activated.
 197
 198 <pre>
 199 Users:
 200   AutoSetupNewUsers: true
 201   NewUsersAreActive: false
 202 </pre>
 203
 204 "Set up user agreements":#user_agreements by creating "signature" "require" links as described earlier.
 205
 206 # User is created and auto-setup.  At this point, @is_active@ is false, but user has been added to "All users" group.
 207 # Workbench checks @is_invited@ and finds it is true, because the user is a member of "All users" group.
 208 # Workbench presents user with list of user agreements, user reads and clicks "sign" for each one.
 209 # Workbench tries to activate user.
 210 # User is activated.
 211
 212 h4. Developer instance
 213
 214 Policy: avoid wasting developer's time during development/testing.  Insecure.
 215
 216 <pre>
 217 Users:
 218   AutoSetupNewUsers: true
 219   NewUsersAreActive: true
 220 </pre>
 221
 222 # User is created, immediately auto-setup, and auto-activated.
 223 # User can immediately start using workbench.