X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/932e3d6e9a899cc662ea3934b79057d39cd88fed..75fbb4eabf0da2fceebf8196bec769e4cbc6547b:/doc/admin/merge-remote-account.html.textile.liquid?ds=sidebyside
diff --git a/doc/admin/merge-remote-account.html.textile.liquid b/doc/admin/merge-remote-account.html.textile.liquid
index b69730c930..2fa7a6e41c 100644
--- a/doc/admin/merge-remote-account.html.textile.liquid
+++ b/doc/admin/merge-remote-account.html.textile.liquid
@@ -1,7 +1,7 @@
---
layout: default
navsection: admin
-title: "Migrating a user to a federated account"
+title: "Migrating users to federated accounts"
...
{% comment %}
Copyright (C) The Arvados Authors. All rights reserved.
@@ -9,39 +9,98 @@ Copyright (C) The Arvados Authors. All rights reserved.
SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}
-When you use federation capabilities to connect two or more clusters that were already operating, some users might already have accounts on multiple clusters. Typically, they will want to choose a single account on one of the clusters and abandon the rest, transferring all data or permissions from their old âremoteâ accounts to a single âhomeâ account.
+When using multiple Arvados clusters, prior to federation capabilities described here, a user would have to create a separate account on each cluster. Unfortunately, because each account represents a separate "identity", in this system permissions granted to a user on one cluster do not transfer to another cluster, even if the accounts are associated with the same user.
-This effect can be achieved by changing the UUIDs of the user records on the remote clusters. This should be done before the user has ever used federation features to access cluster B with cluster A credentials. Otherwise, see "managing conflicting accounts" below.
+To address this, Arvados supports "federated user accounts". A federated user account is associated with a specific "home" cluster, and can be used to access other clusters in the federation that trust the home cluster. When a user arrives at another cluster's Workbench, they select and log in to their home cluster, and then are returned to the starting cluster logged in with the federated user account.
-For example, a user might have:
-* an account A on cluster A with uuid @aaaaa-tpzed-abcdefghijklmno@, and
-* an account B on cluster B with uuid @bbbbb-tpzed-lmnopqrstuvwxyz@
+When setting up federation capabilities on existing clusters, some users might already have accounts on multiple clusters. In order to have a single federated identity, users should be assigned a "home" cluster, and accounts associated with that user on the other (non-home) clusters should be migrated to the new federated user account. The @arv-federation-migrate@ tool assists with this.
-An administrator at cluster B can merge the two accounts by renaming account B to account A.
+h2. arv-federation-migrate
-#!/usr/bin/env python
-import arvados
-arvados.api('v1').users().update_uuid(
- uuid="bbbbb-tpzed-lmnopqrstuvwxyz",
- new_uuid="aaaaa-tpzed-abcdefghijklmno").execute()
-
#!/usr/bin/env python
-import arvados
-import random
-import string
-random_chars = ''.join(random.SystemRandom().choice(string.ascii_lowercase + string.digits) for _ in range(15))
-arvados.api('v1').users().update_uuid(
- uuid="aaaaa-tpzed-abcdefghijklmno",
- new_uuid="bbbbb-tpzed-"+random_chars).execute()
-
+$ arv-federation-migrate --report users.csv +Getting user list from x6b1s +Getting user list from x3982 +Wrote users.csv ++ +h3. Without a LoginCluster + +The first step is to create @tokens.csv@ and list each cluster and API token to access the cluster. API tokens must be trusted tokens with administrator access. This is a simple comma separated value file and can be created in a text editor. Example: + +_tokens.csv_ + +
+x3982.arvadosapi.com,v2/x3982-gj3su-sb6meh2jf145s7x/98d40d70d8862e33d7398213435d1a71a96cf870 +x6b1s.arvadosapi.com,v2/x6b1s-gj3su-dxc87btfv5kg91z/5575d980d3ff6231bb0c692281c42a7541c59417 ++ +Next, run @arv-federation-migrate@ with the @--tokens@ and @--report@ flags: + +
+$ arv-federation-migrate --tokens tokens.csv --report users.csv +Reading tokens.csv +Getting user list from x6b1s +Getting user list from x3982 +Wrote users.csv ++ +h2. Update the user report + +This will produce a report of users across all clusters listed in @tokens.csv@, sorted by email address. This file can be loaded into a text editor or spreadsheet program for ease of viewing and editing. + +_users.csv_ + +
+email,username,user uuid,primary cluster/user +person_a@example.com,person_a,x6b1s-tpzed-hb5n7doogwhk6cf,x6b1s +person_b@example.com,person_b,x3982-tpzed-1vl3k7knf7qihbe, +person_b@example.com,person_b,x6b1s-tpzed-w4nhkx2rmrhlr54, ++ +The fourth column describes that user's home cluster. If a user only has one account (identified by email address), the column will be filled in and there is nothing to do. If the column is blank, that means there is more than one Arvados account associated with the user. Edit the file and provide the desired home cluster for each user as necessary (note: if there is a LoginCluster, all users will be migrated to the LoginCluster). It is also possible to change the desired username for a user. In this example,
person_b@example.com
is assigned the home cluster @x3982@.
+
+_users.csv_
+
++email,username,user uuid,primary cluster/user +person_a@example.com,person_a,x6b1s-tpzed-hb5n7doogwhk6cf,x6b1s +person_b@example.com,person_b,x3982-tpzed-1vl3k7knf7qihbe,x3982 +person_b@example.com,person_b,x6b1s-tpzed-w4nhkx2rmrhlr54,x3982 ++ +h2. Migrate users + +To avoid disruption, advise users to log out and avoid running workflows while performing the migration. + +After updating @users.csv@, you can preview the migration using the @--dry-run@ option (add @--tokens tokens.csv@ if not using LoginCluster). This will print out what actions the migration will take (as if it were happening) and report possible problems, but not make any actual changes on any cluster: + +
+$ arv-federation-migrate --dry-run users.csv +(person_b@example.com) Migrating x6b1s-tpzed-w4nhkx2rmrhlr54 to x3982-tpzed-1vl3k7knf7qihbe ++ +Execute the migration using the @--migrate@ option (add @--tokens tokens.csv@ if not using LoginCluster): + +
+$ arv-federation-migrate --migrate users.csv +(person_b@example.com) Migrating x6b1s-tpzed-w4nhkx2rmrhlr54 to x3982-tpzed-1vl3k7knf7qihbe ++ +After migration, users should select their home cluster when logging into Arvados Workbench. If a user attempts to log into a migrated user account, they will be redirected to log in with their home cluster.