---
layout: default
navsection: admin
-title: User activation
+title: User management
...
{% comment %}
SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}
-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
+{% comment %}
+TODO: Link to relevant workbench documentation when it gets written
+{% endcomment %}
-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).
+This page describes how user accounts are created, set up and activated.
-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).
+h2. Authentication
-Next, it searches by email address for a "pre-activated account.":#pre-activated
+"Browser login and management of API tokens is described here.":{{site.baseurl}}/api/tokens.html
-If no existing user record is found, a new user object will be created.
+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@).
-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 a provider identifier is given, the API server searches for a matching user record.
-h3. User setup
+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 a "pre-activated accounts.":#pre-activated
-If @auto_setup_new_users@ is true, as part of creating the new user object, the user is immediately set up with:
+If no user account is found, a new user account is created with the information from the identity provider.
-* @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 if @auto_setup_new_users_with_repository@ is true
-* @can_login@ permission to a shell node if @auto_setup_new_users_with_vm_uuid@ is set to the uuid of a vm
+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.
-Otherwise, an admin must explicitly invoke "setup" on the user via workbench or the API.
+h3. Federated Authentication
-h3. User activation
+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.
-A newly created user is inactive (@is_active@ is false) by default unless @new_users_are_active@.
+h2. User activation
-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.
+This section describes the different user account states.
-{% comment %}
-Maybe these services should check is_active.
+!(full-width){{site.baseurl}}/images/user-account-states.svg!
-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 %}
+notextile. <div class="spaced-out">
-At this point, there are two ways a user can be activated.
+# 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).
+# Using Workbench or the "command line":{{site.baseurl}}/install/cheat_sheet.html , the admin invokes @setup@ on the user.
+If "Users.AutoSetupNewUsers":config.html is true, this happens automatically during user creation, so in that case new users start at step (3).
+The setup method adds the user to the "All users" group.
+If "Users.AutoSetupNewUsersWithRepository":config.html is true, a new git repo is created for the user.
+If "Users.AutoSetupNewUsersWithVmUUID":config.html is set, the user is given login permission to the specified shell node
+# 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.
+# 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.
+# The user is active. User has normal access to the system.
+# From steps (1) and (3), an admin user can directly update the @is_active@ flag. This bypasses enforcement that user agreements are signed.
+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.
+# An existing user can have their access revoked using @unsetup@ and "ownership reassigned.":reassign-ownership.html .
+Unsetup removes the user from the "All users" group and makes them inactive, preventing them from re-activating themselves.
+"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.
-# 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).
-# Self-activation using the @activate@ method of the users controller.
+notextile. </div>
-h3. User agreements
+User management can be performed through the web using Workbench or the command line. See "user management at the CLI":{{site.baseurl}}/install/cheat_sheet.html for specific examples.
-The @activate@ method of the users controller checks if the user @is_invited@ and whether the user has "signed" all the user agreements.
+h2(#user_agreements). User agreements and self-activation
-@is_invited@ is true if any of these are true:
-* @is_active@ is true
-* @new_users_are_active@ is true
-* the user account has a permission link to read the system "all users" group.
+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.
-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.
-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 should contain a single HTML file with the user agreement text.
-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.
+Workbench displays the clickthrough agreements which the user can "sign".
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. User profile
+h2. User profile
+
+The fields making up the user profile are described in @Workbench.UserProfileFormFields@ . See "Configuration reference":config.html .
-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.
+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.
-h3(#pre-activated). Pre-activate user by email address
+h2(#pre-activated). Pre-setup user by email address
You may create a user account for a user that has not yet logged in, and identify the user by email address.
1. As an admin, create a user object:
<pre>
-{
- "email": "foo@example.com",
- "username": "barney",
- "is_active": true
-}
+$ arv --format=uuid user create --user '{"email": "foo@example.com", "username": "foo"}'
+clsr1-tpzed-1234567890abcdf
+$ arv user setup --uuid clsr1-tpzed-1234567890abcdf
</pre>
-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.
-
-<pre>
-{
- "link_class": "permission",
- "name": "can_login",
- "tail_uuid": "email address",
- "head_uuid: "user uuid",
- "properties": {
- "identity_url_prefix": "xxxxx-tpzed-"
- }
-}
-</pre>
+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.
-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.
+h2. Pre-activate federated user
-h3. Pre-activate federated user
-
-1. As admin, create a user object with the @uuid@ of the federated user (this is the user's uuid on their home cluster):
+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):
<pre>
-{
- "uuid": "home1-tpzed-000000000000000",
- "email": "foo@example.com",
- "username": "barney",
- "is_active": true
-}
+$ arv user create --user '{"uuid": "clsr2-tpzed-1234567890abcdf", "email": "foo@example.com", "username": "foo", "is_active": true}'
</pre>
2. When the user logs in, they will be associated with the existing user object.
-h3. Auto-activate federated users from trusted clusters
-
-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.
-
-h3(#deactivating_users). Deactivating users
-
-Setting @is_active@ is not sufficient to lock out a user. The user can call @activate@ to become active again. Instead, use @unsetup@:
-
-* Delete oid_login_perms
-* Delete git repository permission links
-* Delete VM login permission links
-* Remove from "All users" group
-* Delete any "signatures"
-* Clear preferences / profile
-* Mark as inactive
-
-{% comment %}
-Does not revoke @is_admin@, so you can't unsetup an admin unless you turn admin off first.
+h2. Auto-setup federated users from trusted clusters
-"inactive" does not prevent user from reading things they previously had access to.
+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 .
-Does not revoke API tokens.
-{% endcomment %}
+h2. Activation flows
-h3. Activation flows
+h3. Private instance
-h4. Private instance
+Policy: users must be manually set up by the admin.
-Policy: users must be manually approved.
+Here is the configuration for this policy. This is also the default if not provided.
+(However, be aware that developer/demo builds such as "arvbox":{{site.baseurl}}/install/arvbox.html are configured with the "Open instance" policy described below.)
<pre>
-auto_setup_new_users: false
-new_users_are_active: false
+Users:
+ AutoSetupNewUsers: false
</pre>
# User is created. Not set up. @is_active@ is false.
# Workbench checks @is_invited@ and finds it is false. User gets "inactive user" page.
-# Admin goes to user page and clicks either "setup user" or manually @is_active@ to true.
-# Clicking "setup user" sets up the user. This includes adding the user to "All users" which qualifies the user as @is_invited@.
-# On refreshing workbench, the user is still inactive, but is able to self-activate after signing clickthrough agreements (if any).
-# 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).
+# Admin goes to user page and clicks "setup user" or sets @is_active@ to true.
+# On refreshing workbench, the user is able to self-activate after signing clickthrough agreements (if any).
+# Alternately, directly setting @is_active@ to true also sets up the user, but skips clickthrough agreements (because the user is already active).
+
+h3(#federated). Federated instance
-h4. Federated instance
+Policy: users from other clusters in the federation are activated, users from outside the federation must be manually approved.
-Policy: users from other clusters in the federation are activated, users from outside the federation must be manually approved
+Here is the configuration for this policy and an example remote cluster @clsr2@.
<pre>
-auto_setup_new_users: false
-new_users_are_active: false
-auto_activate_users_from: [home1]
+Users:
+ AutoSetupNewUsers: false
+RemoteClusters:
+ clsr2:
+ ActivateUsers: true
</pre>
-# Federated user arrives claiming to be from cluster 'home1'
-# API server authenticates user as being from cluster 'home1'
-# Because 'home1' is in @auto_activate_users_from@ the user is set up and activated.
-# User can immediately start using workbench.
+# Federated user arrives claiming to be from cluster 'clsr2'
+# API server authenticates user as being from cluster 'clsr2'
+# Because 'clsr2' has @ActivateUsers@ the user is set up and activated.
+# User can immediately start using Workbench.
-h4. Open instance
+h3. Open instance
Policy: anybody who shows up and signs the agreements is activated.
<pre>
-auto_setup_new_users: true
-new_users_are_active: false
+Users:
+ AutoSetupNewUsers: true
</pre>
+"Set up user agreements":#user_agreements by creating "signature" "require" links as described earlier.
+
# User is created and auto-setup. At this point, @is_active@ is false, but user has been added to "All users" group.
# Workbench checks @is_invited@ and finds it is true, because the user is a member of "All users" group.
# Workbench presents user with list of user agreements, user reads and clicks "sign" for each one.
# Workbench tries to activate user.
# User is activated.
-
-h4. Developer instance
-
-Policy: avoid wasting developer's time during development/testing
-
-<pre>
-auto_setup_new_users: true
-new_users_are_active: true
-</pre>
-
-# User is created, immediately auto-setup, and auto-activated.
-# User can immediately start using workbench.
projects / arvados.git / blobdiff