X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/d30db61ea4bdcd686c418cef01ba00e89c4bc338..ea42eaf1e8776704de1ef75d01259d33dcabaef3:/doc/admin/activation.html.textile.liquid diff --git a/doc/admin/activation.html.textile.liquid b/doc/admin/activation.html.textile.liquid index 4f9d2b2c0a..cce83c70bc 100644 --- a/doc/admin/activation.html.textile.liquid +++ b/doc/admin/activation.html.textile.liquid @@ -1,7 +1,7 @@ --- layout: default navsection: admin -title: User activation +title: User management ... {% comment %} @@ -10,75 +10,62 @@ Copyright (C) The Arvados Authors. All rights reserved. SPDX-License-Identifier: CC-BY-SA-3.0 {% endcomment %} -This page describes how new users are created and activated. - -h3. Authentication - -"Browser login and management of API tokens is described here.":{{site.baseurl}}/api/tokens.html - -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@. - -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). - -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 - -If no existing user record is found, a new user object will be created. - -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. +{% comment %} +TODO: Link to relevant workbench documentation when it gets written +{% endcomment %} -h3. User activation +This page describes how user accounts are created, set up and activated. -A newly created user is inactive (@is_active@ is false) by default. +h2. Authentication -An inactive user cannot create or update any object, but can read Arvados objects that the user account has permission to read. +"Browser login and management of API tokens is described here.":{{site.baseurl}}/api/tokens.html -There are three ways a user can be activated: +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@). -# Self-activation. When a user logs in to Workbench, checks for "user agreements":#user_agreements and Workbench automatically attempts to self-activate. -# An admin can invoke the @activate@ method of the users controller using @arv user activate --uuid=...@ (this also checks for user agreements) -# An admin can set the @is_active@ field directly (bypassing user agreements) +If a provider identifier is given, the API server searches for a matching user record. -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. +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 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. +If no user account is found, a new user account is created with the information from the identity provider. -When a user is activated, some basic setup is done, but does not perform full "user setup":#setup . +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. -* @can_login@ @permission@ link going (email address → user uuid) which records @identity_url_prefix@ -* Adding membership to the "All users" group (can read all users, all users can see new user) +h3. Federated Authentication -h3(#deactivating_users). Deactivate a user +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. -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@. +h2. User activation -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. +This section describes the different user account states. -
-$ arv user unsetup --uuid=x1u39-tpzed-3kz0nwtjehhl0u4 -+!(full-width){{site.baseurl}}/images/user-account-states.svg! -* Delete oid_login_perms -* Delete git repository permission links -* Delete VM login permission links -* Remove access to "All users" group -* Delete any user agreement signatures -* Clear preferences / profile -* Mark as inactive +notextile.
-$ arv user create --user '{"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-1234567890abcdf2. 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. -h3. Pre-activate federated user +h2. 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, called @clsr2@ in this example):
-$ arv user create --user '{"uuid": "clsr2-tpzed-1234567890abcdf", "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}'2. When the user logs in, they will be associated with the existing user object. -h3. Auto-activate federated users from trusted clusters +h2. Auto-setup federated users from trusted clusters -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. +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 . -h3. Activation flows +h2. Activation flows -h4. Private instance +h3. Private instance -Policy: users must be manually activated by the admin. +Policy: users must be manually set up by the admin. Here is the configuration for this policy. This is also the default if not provided. -(However, be aware this is not how developer/demo builds such as "arvbox":{{site.baseurl}}/install/arvbox.html are configured.) +(However, be aware that developer/demo builds such as "arvbox":{{site.baseurl}}/install/arvbox.html are configured with the "Open instance" policy described below.)
Users: AutoSetupNewUsers: false - NewUsersAreActive: false# 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). -h4. Federated instance +h3(#federated). Federated instance -Policy: users 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@.
Users: AutoSetupNewUsers: false - NewUsersAreActive: false RemoteClusters: clsr2: ActivateUsers: true @@ -191,14 +168,13 @@ RemoteClusters: # 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.Users: AutoSetupNewUsers: true - NewUsersAreActive: false"Set up user agreements":#user_agreements by creating "signature" "require" links as described earlier. @@ -208,16 +184,3 @@ Users: # 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. Insecure. - --Users: - AutoSetupNewUsers: true - NewUsersAreActive: true -- -# User is created, immediately auto-setup, and auto-activated. -# User can immediately start using workbench.