Migrate to Azure Sphere (Integrated) ahead of Sept 2027 retirement of Legacy service interface

September 27, 2027Azure Sphere deprecates the legacy service interfaces, the Azure Sphere (Legacy) API (also known as PAPI) and the Azure Sphere CLI (also known as PAPI). Azsphere) If you have not yet migrated, you must migrate to Azure Sphere (Integrated) before this date by following the instructions below.

Azure (Integrated) is a new service interface for Azure Sphere. It has many advantages over Azure Sphere (Legacy).The legacy interface is being deprecated because the unified interface provides a similar replacement, as well as significant improvements in security (Azure RBAC integration), usability (Azure Portal integration), and observability/alerts (Azure Monitor integration).

This blog is designed to help Azure Sphere administrators and engineering teams understand and plan their migration. We designed the migration process to allow you to manage Azure Sphere devices on both Azure Sphere (Unified) and Azure Sphere (Legacy) as needed throughout the migration project.

The migration process can be divided into the following work areas:

• Integrate legacy tenants into the Azure Sphere catalog in the Azure Portal
• Migrating interactive user workflows
• Automated Processes and Interface Migration

Integrating Azure Sphere (Legacy) Tenants into the Azure Sphere Catalog

The first step of the migration process must be completed before any other tasks can begin. Integrate features into the Azure Portal Prepares an Azure Sphere (Legacy) tenant to be managed in your Azure environment, becoming the Azure Sphere catalog. The tenant and its resources remain the same, except that they can be accessed and managed through Azure’s user interfaces, including the Azure Portal, the Azure Sphere extension for Azure CLI, and Azure Sphere for PowerShell.

The integration process involves two steps:

• Assign an Azure resource ID to each resource in your tenant so that Azure Resource Manager can manage the resource.
• Map legacy tenant user access roles to user access roles managed by Azure Role-Based Access Control (RBAC). When you see the suggested access role mappings during the integration process, you can accept, modify, or reject them. You can modify user access at any time after the integration step is complete.

The integration phase typically takes only a few minutes, and once complete, all users who were granted access during integration can immediately manage the new Azure Sphere catalog from any user interface in Azure. Because the integration process does not break any existing workflows, we recommend that you integrate as soon as possible so that you can explore the new Azure Sphere (integrated) interface and its benefits. Once complete, you can begin the rest of your migration efforts.

Migrating interactive user workflows

Interactive workflows are workflows where an individual uses the “azsphere” CLI (or a script that uses the “azsphere” CLI) to perform a task. These interactive workflows can occur as part of manufacturing (e.g., billing a tenant for a new device), operations (e.g., managing certificates associated with a tenant), or developer use cases (e.g., disabling a developer device from receiving over-the-air updates).

When planning a workflow migration, you should consider user training, updating internal documentation, and updating scripts if they are used interactively. You may also want to consider leveraging two key improvements in Azure Sphere (integration): a simplified interface for Azure Sphere in the Azure Portal, and powerful user access management in Azure role-based access control (RBAC).

It is important to consider whether certain user workflows are better performed in a web interface rather than a CLI. Azure Sphere (integrated) allows you to manage your catalog in the Azure Portal, and for many interactive user workflows, the Portal provides a richer and simpler user experience. For example, you can simultaneously upload and deploy images in a single step in the Azure Portal, as shown below.

Second, consider how you can more effectively restrict user access. Azure Sphere (Integrated) supports Azure Role-Based Access Control (RBAC), which enables much more powerful and granular user access than Azure Sphere (Legacy).

This is a least privilege model designed to grant individual users access to only the resources they need for their jobs, and to grant them only the user actions they need for their jobs. For example, you might allow a user to view a production device group in the Azure Sphere catalog and create a new deployment for that device group, but specifically prohibit them from moving devices out of the device group or viewing other device groups in the catalog.

If you have not used Azure RBAC before, it is a good idea to learn more about basic Azure RBAC concepts, such as scope and resource hierarchy, because these concepts are important for understanding the impact of applying specific RBAC role permissions to catalogs and their child resources, such as device groups.

To help, we have provided the following: Example of RBAC configuration for multiple business users Demonstrates some best practices for RBAC for Azure Sphere. This sample emphasizes permissions tailored to common business user needs, including software engineers who create applications for Azure Sphere devices, OT technicians who manage a fleet of production Azure Sphere devices, and manufacturers who build Azure Sphere devices.

Remove user access to an Azure Sphere (Legacy) tenant

Once your workflows are migrated and your users are using Azure Sphere (Integration) full-time, we recommend that you remove permissions for each user in the legacy tenant to eliminate unintended access. Otherwise, users may continue to use legacy and bypass the fine-grained access controls you configure in Azure RBAC. Removing legacy user access also helps ensure that those users can successfully perform all required tasks in Azure Sphere (Integration) and are not impacted by legacy deprecation.

Users who are converting or testing automated processes may need to maintain legacy tenant access for a longer period of time.

Automated Processes and Interface Migration

In addition to migrating interactive workflows, if your organization has built automated processes that use Azure Sphere (Legacy) scripts or user interfaces based on the Azure Sphere (Legacy) API, you will need to rework those processes to use Azure Sphere (Integration). To make the migration process as easy as possible, you can actively develop and test your updated automation while your production legacy-based automation is running without interruption. Be careful when testing irreversible commands, such as claiming devices to a catalog that you do not intend to retain long-term.

For each interface you build in the Azure Sphere (Unified) API, you must create a Microsoft Entra access token that allows the interface to access the API endpoints. For more information about access tokens and calling Azure REST APIs, see: Azure REST API Reference Documentation.

After you deploy the updated automation processes and interfaces to production, you must remove Azure Sphere (Legacy) access to the service principals used to authenticate the old legacy-based automation and interfaces. Removing all service principal access ensures that all automation processes are fully migrated and are not affected by the legacy retirement.

Terminate remaining access to legacy tenants

The final step in the migration process is to remove any remaining Azure Sphere (Legacy) access. Currently, an Azure Sphere (Legacy) tenant requires at least one active legacy administrator account, even if the tenant is integrated with the Azure Portal. We are working on a feature that allows you to delete the last legacy tenant administrator account, but it is not currently available. We will announce its availability in an Azure Update when we release this feature.

Leverage features available in Azure Sphere (Integrated)

While not required to use Azure Sphere (Integration), we strongly encourage you to explore and leverage other powerful Azure services that are available today on Azure Sphere as part of your migration planning.

One of the most powerful features is Azure Monitor, which provides a variety of fleet monitoring capabilities, such as collecting performance metrics and diagnostic data, and querying events in the activity log from both Azure Sphere devices and the Azure Sphere Security Service.

Using Azure Monitor data, you can correlate device fleet status with events that occur in the Azure Sphere Security Service, such as the release of a new app update. You can also configure notifications for important events, such as the impending expiration of an Azure Sphere tenant certificate. For more information, see: Azure Sphere fleet and device health monitoring.

Getting started and finding help

It’s easy to just get started Integrate Azure Sphere (Legacy) tenants into the Azure Sphere (Unified) catalog You’re starting to explore how to use Azure Sphere with the Azure CLI or the Azure Portal.

Azure Sphere (Legacy) is fully supported until the next version. September 27, 2027 Retirement date. All migration activities must be completed by this date. If you have questions about the migration or need technical assistance, you can find answers from community experts. Microsoft Q&AOr you can contact us AZSPPGSUP@microsoft.com.