doc/admin/user-management.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: admin
   4 title: User management
   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 # "Authentication":#authentication
  14 ## "Federated Authentication":#federated_auth
  15 # "User activation":#user_activation
  16 # "User agreements and self-activation":#user_agreements
  17 # "User profile":#user_profile
  18 # "User visibility":#user_visibility
  19 # "Pre-setup user by email address":#pre-activated
  20 # "Pre-activate federated user":#pre-activated-fed
  21 # "Auto-setup federated users from trusted clusters":#auto_setup_federated
  22 # "Activation flows":#activation_flows
  23 ## "Private instance":#activation_flow_private
  24 ## "Federated instance":#federated
  25 ## "Open instance":#activation_flow_open
  26 # "Service Accounts":#service_accounts
  27
  28 {% comment %}
  29 TODO: Link to relevant workbench documentation when it gets written
  30 {% endcomment %}
  31
  32 This page describes how user accounts are created, set up and activated.
  33
  34 h2(#authentication). Authentication
  35
  36 "Browser login and management of API tokens is described here.":{{site.baseurl}}/api/tokens.html
  37
  38 After completing the log in and authentication process, the API server receives a user record from the upstream identity provider (Google, LDAP, etc) consisting of the user's name, primary email address, alternate email addresses, and optional unique provider identifier (@identity_url@).
  39
  40 If a provider identifier is given, the API server searches for a matching user record.
  41
  42 If a provider identifier is not given, no match is found, it next searches by primary email and then alternate email address.  This enables "provider migration":migrating-providers.html and "pre-activated accounts.":#pre-activated
  43
  44 If no user account is found, a new user account is created with the information from the identity provider.
  45
  46 If a user account has been "linked":{{site.baseurl}}/user/topics/link-accounts.html or "migrated":merge-remote-account.html the API server may follow internal redirects (@redirect_to_user_uuid@) to select the linked or migrated user account.
  47
  48 h3(#federated_auth). Federated Authentication
  49
  50 A federated user follows a slightly different flow.  The client presents a token issued by the remote cluster.  The local API server contacts the remote cluster to verify the user's identity.  This results in a user object (representing the remote user) being created on the local cluster.  If the user cannot be verified, the token will be rejected.  If the user is inactive on the remote cluster, a user record will be created, but it will also be inactive.
  51
  52 h2(#user_activation). User activation
  53
  54 This section describes the different user account states.
  55
  56 !(side){{site.baseurl}}/images/user-account-states.svg!
  57
  58 notextile. <div class="spaced-out">
  59
  60 # A new user record is not set up, and not active.  An inactive user cannot create or update any object, but can read Arvados objects that the user account has permission to read (such as publicly available items readable by the "anonymous" user).
  61 # Using Workbench or the "command line":{{site.baseurl}}/admin/user-management-cli.html , the admin invokes @setup@ on the user.  The setup method adds the user to the "All users" group.
  62 - If "Users.AutoSetupNewUsers":config.html is true, this happens automatically during user creation, so in that case new users start at step (3).
  63 - If "Users.AutoSetupNewUsersWithRepository":config.html is true, a new git repo is created for the user.
  64 - If "Users.AutoSetupNewUsersWithVmUUID":config.html is set, the user is given login permission to the specified shell node
  65 # User is set up, but still not yet active.  The browser presents "user agreements":#user_agreements (if any) and then invokes the user @activate@ method on the user's behalf.
  66 # The user @activate@ method checks that all "user agreements":#user_agreements are signed.  If so, or there are no user agreements, the user is activated.
  67 # The user is active.  User has normal access to the system.
  68 # From steps (1) and (3), an admin user can directly update the @is_active@ flag.  This bypasses enforcement that user agreements are signed.
  69 If the user was not yet set up (still in step (1)), it adds the user to the "All users", but bypasses creating default git repository and assigning default VM access.
  70 # An existing user can have their access revoked using @unsetup@ and "ownership reassigned":reassign-ownership.html .
  71 Unsetup removes the user from the "All users" group and makes them inactive, preventing them from re-activating themselves.
  72 "Ownership reassignment":reassign-ownership.html moves any objects or permission from the old user to a new user and deletes any credentials for the old user.
  73
  74 notextile. </div>
  75
  76 User management can be performed through the web using Workbench or the command line.  See "user management at the CLI":{{site.baseurl}}/admin/user-management-cli.html for specific examples.
  77
  78 h2(#user_agreements). User agreements and self-activation
  79
  80 The @activate@ method of the users controller checks if the user account is part of the "All Users" group and whether the user has "signed" all the user agreements.
  81
  82 User agreements are accessed through the "user_agreements API":{{site.baseurl}}/api/methods/user_agreements.html .  This returns a list of collection records.
  83
  84 The user agreements that users are required to sign should be added to the @links@ table this way:
  85
  86 <pre>
  87 $ arv link create --link '{
  88   "link_class": "signature",
  89   "name": "require",
  90   "tail_uuid": "*system user uuid*",
  91   "head_uuid: "*collection uuid*"
  92 }'
  93 </pre>
  94
  95 The collection should contain a single HTML file with the user agreement text.
  96
  97 Workbench displays the clickthrough agreements which the user can "sign".
  98
  99 The @user_agreements/sign@ endpoint creates a Link object:
 100
 101 <pre>
 102 {
 103   "link_class": "signature"
 104   "name": "click",
 105   "tail_uuid": "*user uuid*",
 106   "head_uuid: "*collection uuid*"
 107 }
 108 </pre>
 109
 110 The @user_agreements/signatures@ endpoint returns the list of Link objects that represent signatures by the current user (created by @sign@).
 111
 112 h2(#user_profile). User profile
 113
 114 The fields making up the user profile are described in @Workbench.UserProfileFormFields@ .  See "Configuration reference":config.html .
 115
 116 The user profile is checked by workbench after checking if user agreements need to be signed.  The values entered are stored in the @properties@ field on the user object.  Unlike user agreements, the requirement to fill out the user profile is not enforced by the API server.
 117
 118 h2(#user_visibility). User visibility
 119
 120 Initially, a user is not part of any groups and will not be able to interact with other users on the system.  The admin should determine who the user is permited to interact with and use Workbench or the "command line":group-management.html#add to create and add the user to the appropriate group(s).
 121
 122 h2(#pre-activated). Pre-setup user by email address
 123
 124 You may create a user account for a user that has not yet logged in, and identify the user by email address.
 125
 126 1. As an admin, create a user object:
 127
 128 <pre>
 129 $ arv --format=uuid user create --user '{"email": "foo@example.com", "username": "foo"}'
 130 clsr1-tpzed-1234567890abcdf
 131 $ arv user setup --uuid clsr1-tpzed-1234567890abcdf
 132 </pre>
 133
 134 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.
 135
 136 h2(#pre-activated-fed). Pre-activate federated user
 137
 138 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):
 139
 140 <pre>
 141 $ arv user create --user '{"uuid": "clsr2-tpzed-1234567890abcdf", "email": "foo@example.com", "username": "foo", "is_active": true}'
 142 </pre>
 143
 144 2. When the user logs in, they will be associated with the existing user object.
 145
 146 h2(#auto_setup_federated). Auto-setup federated users from trusted clusters
 147
 148 By setting @ActivateUsers: true@ for each federated cluster in @RemoteClusters@, a federated user from one of the listed clusters will be automatically set up and activated on this cluster.  See configuration example in "Federated instance":#federated .
 149
 150 h2(#activation_flows). Activation flows
 151
 152 h3(#activation_flow_private). Private instance
 153
 154 Policy: users must be manually set up by the admin.
 155
 156 Here is the configuration for this policy.  This is also the default if not provided.
 157 (However, be aware that developer/demo builds such as "arvbox":{{site.baseurl}}/install/arvbox.html are configured with the "Open instance" policy described below.)
 158
 159 <pre>
 160 Users:
 161   AutoSetupNewUsers: false
 162 </pre>
 163
 164 # User is created.  Not set up.  @is_active@ is false.
 165 # Workbench checks @is_invited@ and finds it is false.  User gets "inactive user" page.
 166 # Admin goes to user page and clicks "setup user" or sets @is_active@ to true.
 167 # On refreshing workbench, the user is able to self-activate after signing clickthrough agreements (if any).
 168 # Alternately, directly setting @is_active@ to true also sets up the user, but skips clickthrough agreements (because the user is already active).
 169
 170 h3(#federated). Federated instance
 171
 172 Policy: users from other clusters in the federation are activated, users from outside the federation must be manually approved.
 173
 174 Here is the configuration for this policy and an example remote cluster @clsr2@.
 175
 176 <pre>
 177 Users:
 178   AutoSetupNewUsers: false
 179 RemoteClusters:
 180   clsr2:
 181     ActivateUsers: true
 182 </pre>
 183
 184 # Federated user arrives claiming to be from cluster 'clsr2'
 185 # API server authenticates user as being from cluster 'clsr2'
 186 # Because 'clsr2' has @ActivateUsers@ the user is set up and activated.
 187 # User can immediately start using Workbench.
 188
 189 h3(#activation_flow_open). Open instance
 190
 191 Policy: anybody who shows up and signs the agreements is activated.
 192
 193 <pre>
 194 Users:
 195   AutoSetupNewUsers: true
 196 </pre>
 197
 198 "Set up user agreements":#user_agreements by creating "signature" "require" links as described earlier.
 199
 200 # User is created and auto-setup.  At this point, @is_active@ is false, but user has been added to "All users" group.
 201 # Workbench checks @is_invited@ and finds it is true, because the user is a member of "All users" group.
 202 # Workbench presents user with list of user agreements, user reads and clicks "sign" for each one.
 203 # Workbench tries to activate user.
 204 # User is activated.
 205
 206 h2(#service_accounts). Service Accounts
 207
 208 For automation purposes, you can create service accounts that aren't tied to an external authorization system. These kind of accounts don't really differ much from standard user accounts, they just cannot be accessed through a normal login mechanism.
 209
 210 As an admin, you can create accounts like described in the "user pre-setup section above":#pre-activated and then "activate them by updating its @is_active@ field":{{site.baseurl}}/admin/user-management-cli.html#activate-user.
 211
 212 Once a service account is created you can "use an admin account to set up a token":{{site.baseurl}}/admin/user-management-cli.html#create-token for it, so that the required automations can authenticate. Note that these tokens support having a limited lifetime by using the @expires_at@ field and also "limited scope":{{site.baseurl}}/admin/scoped-tokens.html, if required by your security policies. You can read more about them at "the API reference page":{{site.baseurl}}/api/methods/api_client_authorizations.html.