User management

This page describes how user accounts are created, set up and activated.

Authentication

Browser login and management of API tokens is described here.

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).

If a provider identifier is given, the API server searches for a matching user record.

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 and a pre-activated accounts.

If no user account is found, a new user account is created with the information from the identity provider.

If a user account has been linked or migrated the API server may follow internal redirects (redirect_to_user_uuid) to select the linked or migrated user account.

Federated Authentication

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.

User activation

This section describes the different user account states.

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 , the admin invokes setup on the user. The setup method adds the user to the “All users” group.
- If Users.AutoSetupNewUsers is true, this happens automatically during user creation, so in that case new users start at step (3).
- If Users.AutoSetupNewUsersWithRepository is true, a new git repo is created for the user.
- If Users.AutoSetupNewUsersWithVmUUID 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 (if any) and then invokes the user activate method on the user’s behalf.
The user activate method checks that all 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 .
Unsetup removes the user from the “All users” group and makes them inactive, preventing them from re-activating themselves.
Ownership reassignment moves any objects or permission from the old user to a new user and deletes any credentials for the old user.

User management can be performed through the web using Workbench or the command line. See user management at the CLI for specific examples.

User agreements and self-activation

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 through the user_agreements API . This returns a list of collection records.

The user agreements that users are required to sign should be added to the links table this way:

$ arv link create --link '{
  "link_class": "signature",
  "name": "require",
  "tail_uuid": "*system user uuid*",
  "head_uuid: "*collection uuid*"
}'

The collection should contain a single HTML file with the user agreement text.

Workbench displays the clickthrough agreements which the user can “sign”.

The user_agreements/sign endpoint creates a Link object:

{
  "link_class": "signature"
  "name": "click",
  "tail_uuid": "*user uuid*",
  "head_uuid: "*collection uuid*"
}

The user_agreements/signatures endpoint returns the list of Link objects that represent signatures by the current user (created by sign).

User profile

The fields making up the user profile are described in Workbench.UserProfileFormFields . See Configuration reference .

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.

User visibility

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 to create and add the user to the appropriate group(s).

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:

$ arv --format=uuid user create --user '{"email": "foo@example.com", "username": "foo"}'
clsr1-tpzed-1234567890abcdf
$ arv user setup --uuid clsr1-tpzed-1234567890abcdf

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.

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": "foo", "is_active": true}'

2. When the user logs in, they will be associated with the existing user object.

Auto-setup federated users from trusted clusters

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 .

Activation flows

Private instance

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 that developer/demo builds such as arvbox are configured with the “Open instance” policy described below.)

Users:
  AutoSetupNewUsers: 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 “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).

Federated instance

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
RemoteClusters:
  clsr2:
    ActivateUsers: true

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.

Open instance

Policy: anybody who shows up and signs the agreements is activated.

Users:
  AutoSetupNewUsers: true

Set up 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.

Previous: Upgrading to Containers API