Migrate an organization
If you are responsible for migrating an organization, follow the steps in this topic. This procedure assumes that you have planned the migration as described in Plan your migration.
Before you begin:
- Notify all the users of your existing Azure Sphere tenant of the planned migration.
- If your organization has only a few Azure Sphere users, one person can perform the migration and additional users can be responsible for adding themselves to the new environment after the migration.
- If your organization has a large number of Azure Sphere users, gather the desired login identity for each user in the new environment, and determine the role appropriate for each user.
Step 1. Install the SDK
The first step in migration is to install the 19.10 SDK on your local machine.
Step 2. Establish your Azure Sphere login identity
After you've installed the 19.10 SDK, you can use azsphere to register a Microsoft account with the new environment. You can use any Microsoft account, including the work or school account you used with the old environment.
Log in to Azure Sphere with a Microsoft account.
azsphere login --newuser <email>
The email address you specify will be your new Azure Sphere login. You can use the same account you used previously with Azure Sphere, or you can use a different account. The login command registers your identity with Azure Sphere and then prompts you to log in. Complete the login dialog and click Accept to enable Azure Sphere to sign you in to use the service and resources.
In the following command, the azsphere login command registers email@example.com as an Azure Sphere user in the new environment.
C:\Users\test> azsphere login --newuser firstname.lastname@example.org Registration successful. Press any key to login with your new account.
After you log in, the command output shows that you have no tenants available in the new environment because you have not yet migrated your existing tenant.
warn: You don't have access to any Azure Sphere tenants. warn: Type 'azsphere tenant create --name <name>' or, if you have used Azure Sphere before, type 'azsphere tenant migrate'.
Step 3. Migrate your tenant
You've now established your identity in the new authentication and device management environment. You still have a user identity in the old, legacy environment. Use the identity from the old environment to migrate the tenant itself.
To migrate a tenant:
azsphere tenant migrate
If you are prompted, log in again using your old Azure Sphere login—that is, the work or school account you used with the 19.09 (or earlier) release. After this login, you will see information about your old environment. The user identity that the command output shows might be different from the identity with which you logged in to the new environment.
If you have access to an existing tenant, the command suggests that you migrate it.
azsphere tenant migrate Discovered legacy Azure Sphere user 'email@example.com'. Use 'azsphere tenant migrate --force-legacy-login' to look for tenants with a different legacy user. Looking for tenants that can be migrated by legacy Azure Sphere user 'firstname.lastname@example.org'. Legacy Azure Sphere user 'email@example.com' can migrate the following Azure Sphere tenants: <list of tenants> warn: See https://aka.ms/AzureSphereMigration for further details. Install the 19.09 SDK from https://aka.ms/AzureSphereSDK1909 if you are not ready to proceed. warn: Enter 'yes' to continue. Enter anything else to exit.
When migration starts, azsphere displays a verification message. Depending on the number of users and devices in the tenant, migration may take as long as 20 minutes. Until migration is complete, attempts to use cloud-dependent commands will return the following error:
Migration of your Azure Sphere tenant (<tenant ID>) is currently in progress. Please try again later.
You should now be able to see devices in your tenant in the new environment:
azsphere device list
Step 4. Add users
The new authentication model requires all users to have a role that defines the actions they perform on the devices and deployments in the tenant. Possible roles are Administrator, Contributor, and Reader. As the first user to sign in to the new environment, you are by default assigned an Administrator role in the tenant.
After migration completes, other users can still log into the legacy environment, but they cannot log into the new tenant until they install the 19.10 SDK and establish an identity.
Other users can add themselves to the new environment by using the azsphere login --newuser command, and become additional Administrators of the tenant by using the azsphere tenant migrate command, just as you did above.
Alternatively, you can register more users in the new environment yourself, and manage their access:
azsphere register-user --newuser <email>
The register-user command adds a user identity to the Azure Sphere Security Service. The email address must be a Microsoft account. After you register the email as a new user, the user can sign in to Azure Sphere using the registered email address. You can also assign a role to the user:
azsphere role add --user <email> --role <user-role>
Possible roles are Administrator, Contributor, and Reader. By default, users are not assigned a role.
An administrator can change any user's role at any time by using the azsphere role command.
Step 5. Restrict access
In the previous environment, anyone who had an account in your directory could access the Azure Sphere tenant. As the final step in migration, you should remove access to prevent such individuals from migrating themselves to become an additional Administrators in the tenant:
azsphere role remove-legacy-access
This command removes access for all users in the directory who have not been explicitly added and assigned a role.