User activation

This page describes how new users are created and activated.

Browser login and management of API tokens is described here.

Authentication

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

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

Next, it searches by email address for a pre-activated account.

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, however it also results in a user object (representing the remote user) being created.

User setup

If auto_setup_new_users is true, as part of creating the new user object, the user is immediately set up with:

• 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

Otherwise, an admin must explicitly invoke “setup” on the user via workbench or the API.

User activation

A newly created user is inactive (is_active is false) by default unless new_users_are_active.

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.

At this point, there are two ways a user can be activated.

1. 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).
2. Self-activation using the activate method of the users controller.

User agreements

The activate method of the users controller checks if the user is_invited and whether the user has “signed” all the user agreements.

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.

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.

The available user agreements are represented in the Links table as

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

The collection contains the user agreement text file.

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.

The user_agreements/sign endpoint creates a Link object:

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

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

User profile

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.

Pre-activate 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:

{
  "email": "foo@example.com",
  "username": "barney",
  "is_active": true
}

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.

{
  "link_class": "permission",
  "name": "can_login",
  "tail_uuid": "email address",
  "head_uuid: "user uuid",
  "properties": {
    "identity_url_prefix": "xxxxx-tpzed-"
  }
}

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.

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

{
  "uuid": "home1-tpzed-000000000000000",
  "email": "foo@example.com",
  "username": "barney",
  "is_active": true
}

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

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.

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

Activation flows

Private instance

Policy: users must be manually approved.

auto_setup_new_users: false
new_users_are_active: false

1. User is created. Not set up. is_active is false.
2. Workbench checks is_invited and finds it is false. User gets “inactive user” page.
3. Admin goes to user page and clicks either “setup user” or manually is_active to true.
4. Clicking “setup user” sets up the user. This includes adding the user to “All users” which qualifies the user as is_invited.
5. On refreshing workbench, the user is still inactive, but is able to self-activate after signing clickthrough agreements (if any).
6. 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).

Federated instance

Policy: users from other clusters in the federation are activated, users from outside the federation must be manually approved

auto_setup_new_users: false
new_users_are_active: false
auto_activate_users_from: [home1]

1. Federated user arrives claiming to be from cluster ‘home1’
2. API server authenticates user as being from cluster ‘home1’
3. Because ‘home1’ is in auto_activate_users_from the user is set up and activated.
4. User can immediately start using workbench.

Open instance

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

auto_setup_new_users: true
new_users_are_active: false

1. User is created and auto-setup. At this point, is_active is false, but user has been added to “All users” group.
2. Workbench checks is_invited and finds it is true, because the user is a member of “All users” group.
3. Workbench presents user with list of user agreements, user reads and clicks “sign” for each one.
4. Workbench tries to activate user.
5. User is activated.

Developer instance

Policy: avoid wasting developer’s time during development/testing

auto_setup_new_users: true
new_users_are_active: true

1. User is created, immediately auto-setup, and auto-activated.
2. User can immediately start using workbench.

---

Previous: User management at the CLI Next: Migrating users to federated accounts