doc/admin/merge-remote-account.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: admin
   4 title: "Migrating users to federated accounts"
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 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.
  13
  14 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.
  15
  16 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.
  17
  18 h2. arv-federation-migrate
  19
  20 The tool @arv-federation-migrate@ is part of the @arvados-python-client@ package.
  21
  22 This tool is designed to help an administrator who has access to all clusters in a federation to migrate users who have multiple accounts to a single federated account.
  23
  24 As part of migrating a user, any data or permissions associated with old user accounts will be reassigned to the federated account.
  25
  26 h2. Get user report
  27
  28 h3. With a LoginCluster
  29
  30 When using centralized user database as specified by "LoginCluster":federation.html#LoginCluster in the config file.
  31
  32 Set the @ARVADOS_API_HOST@ and @ARVADOS_API_TOKEN@ environment variables to be an admin user on cluster in @LoginCluster@ .  It will automatically determine the other clusters that are listed in the federation.
  33
  34 Next, run @arv-federation-migrate@ with the @--report@ flag:
  35
  36 <pre>
  37 $ arv-federation-migrate --report users.csv
  38 Getting user list from x6b1s
  39 Getting user list from x3982
  40 Wrote users.csv
  41 </pre>
  42
  43 h3. Without a LoginCluster
  44
  45 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:
  46
  47 _tokens.csv_
  48
  49 <pre>
  50 x3982.arvadosapi.com,v2/x3982-gj3su-sb6meh2jf145s7x/98d40d70d8862e33d7398213435d1a71a96cf870
  51 x6b1s.arvadosapi.com,v2/x6b1s-gj3su-dxc87btfv5kg91z/5575d980d3ff6231bb0c692281c42a7541c59417
  52 </pre>
  53
  54 Next, run @arv-federation-migrate@ with the @--tokens@ and @--report@ flags:
  55
  56 <pre>
  57 $ arv-federation-migrate --tokens tokens.csv --report users.csv
  58 Reading tokens.csv
  59 Getting user list from x6b1s
  60 Getting user list from x3982
  61 Wrote users.csv
  62 </pre>
  63
  64 h2. Update the user report
  65
  66 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.
  67
  68 _users.csv_
  69
  70 <pre>
  71 email,username,user uuid,primary cluster/user
  72 person_a@example.com,person_a,x6b1s-tpzed-hb5n7doogwhk6cf,x6b1s
  73 person_b@example.com,person_b,x3982-tpzed-1vl3k7knf7qihbe,
  74 person_b@example.com,person_b,x6b1s-tpzed-w4nhkx2rmrhlr54,
  75 </pre>
  76
  77 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, <code>person_b@example.com</code> is assigned the home cluster @x3982@.
  78
  79 _users.csv_
  80
  81 <pre>
  82 email,username,user uuid,primary cluster/user
  83 person_a@example.com,person_a,x6b1s-tpzed-hb5n7doogwhk6cf,x6b1s
  84 person_b@example.com,person_b,x3982-tpzed-1vl3k7knf7qihbe,x3982
  85 person_b@example.com,person_b,x6b1s-tpzed-w4nhkx2rmrhlr54,x3982
  86 </pre>
  87
  88 h2. Migrate users
  89
  90 To avoid disruption, advise users to log out and avoid running workflows while performing the migration.
  91
  92 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:
  93
  94 <pre>
  95 $ arv-federation-migrate --dry-run users.csv
  96 (person_b@example.com) Migrating x6b1s-tpzed-w4nhkx2rmrhlr54 to x3982-tpzed-1vl3k7knf7qihbe
  97 </pre>
  98
  99 Execute the migration using the @--migrate@ option (add @--tokens tokens.csv@ if not using LoginCluster):
 100
 101 <pre>
 102 $ arv-federation-migrate --migrate users.csv
 103 (person_b@example.com) Migrating x6b1s-tpzed-w4nhkx2rmrhlr54 to x3982-tpzed-1vl3k7knf7qihbe
 104 </pre>
 105
 106 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.