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 "Browser login and management of API tokens is described here.":{{site.baseurl}}/api/tokens.html
  16
  17 h3. Authentication
  18
  19 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).
  20
  21 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).
  22
  23 Next, it searches by email address for a "pre-activated account.":#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, however it also results in a user object (representing the remote user) being created.
  28
  29 h3. User setup
  30
  31 If @auto_setup_new_users@ is true, as part of creating the new user object, the user is immediately set up with:
  32
  33 * @can_login@ @permission@ link going (email address &rarr; user uuid) which records @identity_url_prefix@
  34 * Membership in the "All users" group (can read all users, all users can see new user)
  35 * A new git repo and @can_manage@ permission if @auto_setup_new_users_with_repository@ is true
  36 * @can_login@ permission to a shell node if @auto_setup_new_users_with_vm_uuid@ is set to the uuid of a vm
  37
  38 Otherwise, an admin must explicitly invoke "setup" on the user via workbench or the API.
  39
  40 h3. User activation
  41
  42 A newly created user is inactive (@is_active@ is false) by default unless @new_users_are_active@.
  43
  44 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.
  45
  46 {% comment %}
  47 Maybe these services should check is_active.
  48
  49 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.
  50 {% endcomment %}
  51
  52 At this point, there are two ways a user can be activated.
  53
  54 # 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).
  55 # Self-activation using the @activate@ method of the users controller.
  56
  57 h3. User agreements
  58
  59 The @activate@ method of the users controller checks if the user @is_invited@ and whether the user has "signed" all the user agreements.
  60
  61 @is_invited@ is true if any of these are true:
  62 * @is_active@ is true
  63 * @new_users_are_active@ is true
  64 * the user account has a permission link to read the system "all users" group.
  65
  66 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.
  67
  68 The available user agreements are represented in the Links table as
  69
  70 <pre>
  71 {
  72   "link_class": "signature",
  73   "name": "require",
  74   "tail_uuid": "*system user uuid*",
  75   "head_uuid: "*collection uuid*"
  76 }
  77 </pre>
  78
  79 The collection contains the user agreement text file.
  80
  81 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.
  82
  83 The @user_agreements/sign@ endpoint creates a Link object:
  84
  85 <pre>
  86 {
  87   "link_class": "signature"
  88   "name": "click",
  89   "tail_uuid": "*user uuid*",
  90   "head_uuid: "*collection uuid*"
  91 }
  92 </pre>
  93
  94 This is executed as a system user, so it bypasses the restriction that inactive users cannot create objects.
  95
  96 The @user_agreements/signatures@ endpoint returns the list of Link objects that represent signatures by the current user (created by @sign@).
  97
  98 h3. User profile
  99
 100 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.
 101
 102 h3(#pre-activated). Pre-activate user by email address
 103
 104 You may create a user account for a user that has not yet logged in, and identify the user by email address.
 105
 106 1. As an admin, create a user object:
 107
 108 <pre>
 109 {
 110   "email": "foo@example.com",
 111   "username": "barney",
 112   "is_active": true
 113 }
 114 </pre>
 115
 116 2. Create a link object, where @tail_uuid@ is the user's email address, @head_uuid@ is the user object created in the previous step, and @xxxxx@ is the value of @uuid_prefix@ of the SSO server.
 117
 118 <pre>
 119 {
 120   "link_class": "permission",
 121   "name": "can_login",
 122   "tail_uuid": "email address",
 123   "head_uuid: "user uuid",
 124   "properties": {
 125     "identity_url_prefix": "xxxxx-tpzed-"
 126   }
 127 }
 128 </pre>
 129
 130 3. When the user logs in the first time, the email address will be recognized and the user will be associated with the linked user object.
 131
 132 h3. Pre-activate federated user
 133
 134 1. As admin, create a user object with the @uuid@ of the federated user (this is the user's uuid on their home cluster):
 135
 136 <pre>
 137 {
 138   "uuid": "home1-tpzed-000000000000000",
 139   "email": "foo@example.com",
 140   "username": "barney",
 141   "is_active": true
 142 }
 143 </pre>
 144
 145 2. When the user logs in, they will be associated with the existing user object.
 146
 147 h3. Auto-activate federated users from trusted clusters
 148
 149 In the API server config, configure @auto_activate_users_from@ with a list of one or more five-character cluster ids.  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.
 150
 151 h3(#deactivating_users). Deactivating users
 152
 153 Setting @is_active@ is not sufficient to lock out a user.  The user can call @activate@ to become active again.  Instead, use @unsetup@:
 154
 155 * Delete oid_login_perms
 156 * Delete git repository permission links
 157 * Delete VM login permission links
 158 * Remove from "All users" group
 159 * Delete any "signatures"
 160 * Clear preferences / profile
 161 * Mark as inactive
 162
 163 {% comment %}
 164 Does not revoke @is_admin@, so you can't unsetup an admin unless you turn admin off first.
 165
 166 "inactive" does not prevent user from reading things they previously had access to.
 167
 168 Does not revoke API tokens.
 169 {% endcomment %}
 170
 171 h3. Activation flows
 172
 173 h4. Private instance
 174
 175 Policy: users must be manually approved.
 176
 177 <pre>
 178 auto_setup_new_users: false
 179 new_users_are_active: false
 180 </pre>
 181
 182 # User is created.  Not set up.  @is_active@ is false.
 183 # Workbench checks @is_invited@ and finds it is false.  User gets "inactive user" page.
 184 # Admin goes to user page and clicks either "setup user" or manually @is_active@ to true.
 185 # Clicking "setup user" sets up the user.  This includes adding the user to "All users" which qualifies the user as @is_invited@.
 186 # On refreshing workbench, the user is still inactive, but is able to self-activate after signing clickthrough agreements (if any).
 187 # 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).
 188
 189 h4. Federated instance
 190
 191 Policy: users from other clusters in the federation are activated, users from outside the federation must be manually approved
 192
 193 <pre>
 194 auto_setup_new_users: false
 195 new_users_are_active: false
 196 auto_activate_users_from: [home1]
 197 </pre>
 198
 199 # Federated user arrives claiming to be from cluster 'home1'
 200 # API server authenticates user as being from cluster 'home1'
 201 # Because 'home1' is in @auto_activate_users_from@ the user is set up and activated.
 202 # User can immediately start using workbench.
 203
 204 h4. Open instance
 205
 206 Policy: anybody who shows up and signs the agreements is activated.
 207
 208 <pre>
 209 auto_setup_new_users: true
 210 new_users_are_active: false
 211 </pre>
 212
 213 # User is created and auto-setup.  At this point, @is_active@ is false, but user has been added to "All users" group.
 214 # Workbench checks @is_invited@ and finds it is true, because the user is a member of "All users" group.
 215 # Workbench presents user with list of user agreements, user reads and clicks "sign" for each one.
 216 # Workbench tries to activate user.
 217 # User is activated.
 218
 219 h4. Developer instance
 220
 221 Policy: avoid wasting developer's time during development/testing
 222
 223 <pre>
 224 auto_setup_new_users: true
 225 new_users_are_active: true
 226 </pre>
 227
 228 # User is created, immediately auto-setup, and auto-activated.
 229 # User can immediately start using workbench.