X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/ec88f99b1eeb811159b3aea9a6f810dc06e9417b..c9bfa91e3c3ec90778795969fdd3787578a76ed4:/doc/admin/activation.html.textile.liquid

diff --git a/doc/admin/activation.html.textile.liquid b/doc/admin/activation.html.textile.liquid
index a38b877961..4a08e509c1 100644
--- a/doc/admin/activation.html.textile.liquid
+++ b/doc/admin/activation.html.textile.liquid
@@ -65,11 +65,33 @@ The @activate@ method of the users controller checks if the user @is_invited@ an
 
 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@ and @name: require@ and (system_user_uuid → uuid of collection containing user agreement text file)
+The available user agreements are represented in the Links table as
+
+<pre>
+{
+  "link_class": "signature",
+  "name": "require",
+  "tail_uuid": "*system user uuid*",
+  "head_uuid: "*collection uuid*"
+}
+</pre>
+
+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 with @link_class: signature@ and @name: click@ and (current user uuid &rarr; collection uuid). This is executed as a system user, so it bypasses the restriction that inactive users cannot create objects.
+The @user_agreements/sign@ endpoint creates a Link object:
+
+<pre>
+{
+  "link_class": "signature"
+  "name": "click",
+  "tail_uuid": "*user uuid*",
+  "head_uuid: "*collection uuid*"
+}
+</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@).
 
@@ -77,17 +99,54 @@ h3. 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.
 
-h3(#pre-activated). Pre-activated user accounts
+h3(#pre-activated). 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:
+
+<pre>
+{
+  "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>
 
-It is possible to create a user account for a user that has not yet logged in.
+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.
+
+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):
+
+<pre>
+{
+  "uuid": "home1-tpzed-000000000000000",
+  "email": "foo@example.com",
+  "username": "barney",
+  "is_active": true
+}
+</pre>
 
-# As an admin, create a user object.
-# Create a link with @link_class: permission@ and @name: can_login@ and (email address &rarr; user_uuid) and @properties[identity_url_prefix] = 'xxxxx-tpzed-'@ where 'xxxxx' is the @uuid_prefix@ of the SSO server.
-# When the user logs in the first time, the email address will be recognized and the user will be associated with the existing user uuid.
+2. When the user logs in, they will be associated with the existing user object.
 
-h3. Federated users
+h3. Auto-activate federated users from trusted clusters
 
-In the API server config, set @auto_activate_users_from@ with a list of cluster ids.  A federated users from one of the listed clusters which @is_active@ on the home cluster will be automatically set up and activated on this cluster.
+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
 
@@ -102,9 +161,9 @@ Setting @is_active@ is not sufficient to lock out a user.  The user can call @ac
 * Mark as inactive
 
 {% comment %}
-Does not revoke @is_admin@ though!  Maybe we need to fix that?
+Does not revoke @is_admin@, so you can't unsetup an admin unless you turn admin off first.
 
-Does not prevent user from reading things.
+"inactive" does not prevent user from reading things they previously had access to.
 
 Does not revoke API tokens.
 {% endcomment %}