h3. User setup
-If @auto_setup_new_users@ is true, as part of creating the new user object, the user is immediately set up with:
+If @Users.AutoSetupNewUsers@ 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
+* A new git repo and @can_manage@ permission to that repo if @Users.AutoSetupNewUsersWithRepository@ is true
+* @can_login@ permission to a shell node if @Users.AutoSetupNewUsersWithVmUUID@ is set to the uuid of a vm
Otherwise, an admin must explicitly invoke "setup" on the user via workbench or the API.
h3. User activation
-A newly created user is inactive (@is_active@ is false) by default unless @new_users_are_active@.
+A newly created user is inactive (@is_active@ is false) unless explicitly set by the admin.
-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.
+An inactive user cannot create or update any object, but can read Arvados objects that the user account has permission to read. As a result, when @Users.AutoSetupNewUsers@ is true, an user who has been set up but is not activate 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.
{% comment %}
Maybe these services should check is_active.
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 %}
-At this point, there are two ways a user can be activated.
+There are three ways a user can be activated.
-# 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.
+# Self-activation by Workbench. When an inactive user logs, Workbench attempts to self-activate. Successful activation creates the git repo and vm login for the user.
+# An admin can invoke the @activate@ method of the users controller using @arv user activate --uuid=...@
+# 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 @Users.AutoSetupNewUsersWithRepository@ and/or @Users.AutoSetupNewUsersWithVmUUID@ are set). The admin can invoke "setup" separately (or use the "Setup" button on Workbench).
-h3. User agreements
+h3(#deactivating_users). Deactivate a user
+
+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@.
+
+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.
+
+<pre>
+$ arv user unsetup --uuid=x1u39-tpzed-3kz0nwtjehhl0u4
+</pre>
+
+* 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
+
+Unsetup does not revoke API tokens.
+
+An "inactive" user with a valid API token can still read the database, but is barred from creating or modifying records. User deactivation with "unsetup" should be done together with "ownership reassignment.":reassign-ownership.html
+
+h3(#user_agreements). 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.
+* @Users.NewUsersAreActive@ is true
+* The user account has permission to view the membership of the "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.
1. As an admin, create a user object:
<pre>
-{
- "email": "foo@example.com",
- "username": "barney",
- "is_active": true
-}
+$ arv user create --user '{"email": "foo@example.com", "username": "barney", "is_active": true}'
</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>
-
-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.
+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.
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": "barney", "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.
-
-"inactive" does not prevent user from reading things they previously had access to.
-
-Does not revoke API tokens.
-{% endcomment %}
+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.
h3. Activation flows
h4. Private instance
-Policy: users must be manually approved.
+Policy: users must be manually activated 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.)
<pre>
-auto_setup_new_users: false
-new_users_are_active: false
+Users:
+ AutoSetupNewUsers: false
+ NewUsersAreActive: false
</pre>
# User is created. Not set up. @is_active@ is false.
h4. Federated instance
-Policy: users from other clusters in the federation are activated, users from outside the federation must be manually approved
+Policy: users 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
+ NewUsersAreActive: 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
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
+ NewUsersAreActive: false
</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.
h4. Developer instance
-Policy: avoid wasting developer's time during development/testing
+Policy: avoid wasting developer's time during development/testing. Insecure.
<pre>
-auto_setup_new_users: true
-new_users_are_active: true
+Users:
+ AutoSetupNewUsers: true
+ NewUsersAreActive: true
</pre>
# User is created, immediately auto-setup, and auto-activated.
projects / arvados.git / commitdiff