Migrating users to federated accounts

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.

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.

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.


The tool arv-federation-migrate is part of the arvados-python-client package.

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.

As part of migrating a user, any data or permissions associated with old user accounts will be reassigned to the federated account.

Get user report

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:



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

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.


email,user uuid,primary cluster/user

The third 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. In this example, person_b@example.com is assigned the home cluster x3982.


email,user uuid,primary cluster/user

Migrate users

To avoid disruption, advise users to log out and avoid running workflows while performing the migration.

After updating users.csv, use the --migrate option:

$ arv-federation-migrate --tokens tokens.csv --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.

Previous: User activation Next: Migrating account providers

The content of this documentation is licensed under the Creative Commons Attribution-Share Alike 3.0 United States licence.
Code samples in this documentation are licensed under the Apache License, Version 2.0.