About migration

The Azure Sphere 19.10 SDK introduces two important changes to user authentication and cloud management.

Starting with this release, Azure Sphere supports role-based user authentication. This authentication method supports login with any Microsoft or work/school account and enables you to assign specific roles to individual users.

Changes to cloud management make it easier to group your devices and to deploy applications.

As a result of these changes, you'll be required to migrate your Azure Sphere tenant and users to a new authentication and cloud management environment. Migration is a one-time, irreversible action. This topic describes the changes to authentication and cloud management and provides guidance on how to plan your migration.

Changes to authentication

The change to role-based authentication provides several benefits:

  • Users can sign in to Azure Sphere with any Microsoft account. You can still use a work/school account, as with previous releases, but such an account is no longer required.

  • Each Azure Sphere tenant has one or more local administrators, who manage user access and roles. Previously, all users had complete access to the tenant. A local administrator, such as a deployment or operations manager for Azure Sphere, could not limit the activities of individual users.

In the new authentication model, users can have any of several roles.

  • An Administrator has full access to all devices and operations within the tenant, including the permission to add or delete other users. The Administrator role is assigned by default to the user who performs the migration.
  • A Contributor can add devices and create and change deployments. Software and hardware developers who create applications, manage connected devices, and update deployments, but are not responsible for managing tenant access, should have the Contributor role.
  • A Reader has access to information about the tenant, including the claimed devices, the current deployments, and, when available, any error reporting data from the devices. This role is appropriate for maintenance and operations personnel who are responsible for tracking connected device performance at end-user installations.

If you are an individual user, migration is straightforward. If you are part of a wider organization using Azure Sphere, then you'll need to plan ahead. As part of migration, each individual Azure Sphere user must be added to the new environment. Their existing identity will not migrate from the previous environment. Depending on how you choose to manage your Azure Sphere tenant, an administrator can add the users or the users can add themselves. See Plan your migration for details.

Changes to the cloud management model

Changes to the cloud management model make it easier to create deployments and organize devices. In the new model:

  • Every tenant has products. The products are your device types, such as coffee makers or dishwashers.
  • Every product has one or more device groups. All the devices in a device group are the same type of product. By default, Azure Sphere creates three default device groups for every product: “Development”, “Field Test”, and “Production”. For example, most of the devices of a certain product might be in the Production group, while a few are in the Field Test group.
  • Every device group has a deployment, which consists of the set of images that run on its devices.

You no longer have to set up feeds for your applications. You create a device group for a product and assign a deployment to the device group.

After migration

After migration to the new environment:

  • Users who log in to the old environment can no longer see the tenant.
  • Users must be assigned a role in the tenant. A user who lacks a role can log in, but cannot see any details or perform any actions. The user who migrates the tenant is by default assigned an Administrator role. No other users receive default roles; an Administrator must explicitly assign a role to each user.

What doesn't change

Although the user authentication and cloud management model changes are significant, most of the infrastructure you've already set up will not change with the 19.10 SDK release.

  • Your Azure Sphere tenants remain unchanged; only the authentication required to access a tenant changes.
  • The devices that have been claimed to a tenant remain claimed to that tenant.
  • The applications that are currently running on your devices will not change.
  • Your existing deployments will not change. The same images will be delivered to the same devices.
  • All product SKU/device-group pairs that you set up under the old model will continue to exist. However, if you previously set up a device group that contains multiple product SKUs, it will be split into multiple device groups, each of which is associated with a different product.

Plan your migration

Before you install the 19.10 SDK, decide how and when you will migrate. If you are an individual user, you can migrate immediately. If you are part of a wider organization using Azure Sphere, then the first person to log in to the new environment with the 19.10 SDK will be required to migrate the tenant, after which any other users in that tenant will not be able to use any cloud-dependent azsphere commands until they too upgrade to the 19.10 SDK. The azsphere CLI reference contains a list of the cloud-dependent commands.


Continue using the 19.09 SDK until you are ready to perform the migration. If you have already installed the 19.10 SDK but are not ready to migrate, uninstall it, then download the 19.09 SDK and reinstall it.

The 19.10 Azure Sphere SDK supports only the new user authentication and cloud management environment. After you install the 19.10 SDK, the only cloud-dependent azsphere command that you can use starts the migration process for a tenant. All other cloud-dependent commands will fail.

Migrating an individual

If you are the only Azure Sphere user, Migrate an individual describes how to migrate to the new environment.

Migrating an organization

For an organization, you should carefully plan the migration. The migration will require all users to install the new SDK immediately. Any build scripts must also be updated. The 19.09 SDK will fail if you use it after migration.

For a small group of Azure Sphere users, we recommend the following approach:

  1. The first person to install the 19.10 SDK can migrate the tenant and become its first administrator. After migration, the 19.09 SDK will no longer work for existing users.
  2. When additional users try to log in after migration, they must install the 19.10 SDK and migrate themselves as additional administrators of the tenant.
  3. After all users have migrated, an administrator can remove legacy access.

For a large group of Azure Sphere users, we recommend the following approach:

  1. Choose a person in your organization as the initial administrator for your Azure Sphere tenant. This person will be responsible for performing the initial migration and adding other users to the tenant. The initial administrator must already have a login account for the existing Azure Sphere tenant. You can always add additional administrators after migration.
  2. Compile a list of users who require access to the Azure Sphere tenant, along with the role that is appropriate for each user.
  3. Choose a time and date for the migration and notify all current Azure Sphere users. Although the migration process is not time-consuming or complicated, existing users will be unable to log in to Azure Sphere or perform any cloud-dependent actions until they upgrade.
  4. At migration time, notify users that migration is starting and that their access to Azure Sphere will be temporarily unavailable.
  5. Remove legacy access as soon as the migration is started.
  6. When migration is complete, add the user identities and roles from your compiled list.
  7. Notify users when migration is complete, so that they can download the 19.10 SDK and continue using Azure Sphere.

This procedure ensures predictable results for the entire organization and enables administrators to assign the appropriate roles to users. By designating an administrator and publicizing the migration strategy well ahead of time, you can ensure that a single user doesn't install the 19.10 SDK, perform the migration, and thus cut off access to remaining users without warning.

Migrate an organization describes how to migrate a multi-user organization to the new environment.


You cannot reverse a migration; it's a one-time, one-way process. Tenant migration enables role-based access control, and after migration you cannot go back to using the 19.09 SDK or login. If you try to log in but instead see the error You do not have any tenant associated with this account, it is possible that someone in your organization migrated your tenant. If this happens, contact the others in your organization who are working with Azure Sphere. The person who migrated the tenant can add your login to the new tenant and you'll be ready to use the 19.10 SDK.

What happens if I don't migrate?

If you don't migrate to the new environment, you can continue to use the 19.09 SDK for now. Your existing deployments and development scenarios will continue to work. However, you will not be able to use the 19.09 SDK to create new tenants, product SKUs, SKUs, components, and device groups. None of the new features in the 19.10 SDK will be available to you.

Support for the 19.09 SDK will be removed in the future. At that point it will be necessary to migrate. You cannot use the 19.10 SDK or any later SDK unless you migrate.