Share via

Access Azure Sphere Public API with AAD application service principal

  • Article

Important

This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.

Automated tools require restricted access and non-interactive authentication instead of authenticating as a fully privileged user. This can be achieved by using service principals that allow applications to sign in with specific permissions. Simply put, an Azure service principal works as an identity which gets created in Azure when an application is registered in Azure Active Directory.

In this mode, access permission for the application in the Azure Active Directory (AAD) tenant is defined by the service principal, which enables authentication and authorization when accessing resources.

There are two types of authentication methods available for service principals, client certificates and client secrets.

Prerequisites

Step 1: Register a service principal

  1. In the Azure portal, on the left navigation pane, click Azure Active Directory.
  2. Register an application with Azure AD and create a service principal. Note the Client ID.
  3. Select authentication type. There are two types of authentication available for service principals:
    • Client secret
    • Client certificate

Step 2: Add the service principal to the Azure Sphere tenant and assign a role

Note

Ensure that you have the following before beginning this step:

Azure Sphere treats the service principal as another user. To acquire a token using the service principal, first add the service principal user to the Azure Sphere tenant, and then assign a role to the user in an Azure Sphere tenant using the Azure Sphere CLI.

The user identity can be generated as <ObjectID>@<TenantID>.onmicrosoft.com.

In the following example we create a user using a combination of object ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx and Azure AD tenant ID zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz in the Azure Sphere tenant ID tttttttt-tttt-tttt-tttt-tttttttttttt, and then add the Contributor role for this user.

  1. Sign in with your Azure Sphere login using the Azure Sphere CLI:

    azsphere login

  2. Select the required tenant:

    azsphere tenant select --tenant tttttttt-tttt-tttt-tttt-tttttttttttt

  3. To add the user to a required role:

    azsphere role add --role Contributor --user xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx@zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz.onmicrosoft.com

Step 3: Register client secrets or client certificates using the application registration portal

Client secrets and client certificates enable applications to identify themselves to the authentication service when receiving tokens at a web addressable location (using an HTTPS scheme). We recommend using a certificate instead of a client secret for client credential scenarios when authenticating with Azure Active Directory.

The client secret or client certificate for the application registration can be used to obtain an access token for the Azure Sphere Public API (PAPI).

Configure application with client secret

To register your application with a client secret:

  1. In the Azure portal, on the left navigation pane, click Azure Active Directory.

  2. Go to App registrations, and select the application you created in Step 1: Register a service principal.

  3. From the left pane, select Certificates & secrets > Client secrets section > New client secret.

  4. Enter a description, select the validity duration, and select Add. The client secret is generated and the client secret value is displayed.

  5. Copy the client secret value because you won't be able to retrieve the key later.

  6. Provide the client secret value with the Azure Sphere Public API Application ID to sign in as the application. Store the key value where your application can retrieve it.

    Important

    The client secret value is an important security credential. Do not share the client secret with anyone or distribute it within a client application. We recommend using the Azure Key Vault service that provides centralized secrets management, with full control over access policies and audit history.

Use the following sample code:

 IConfidentialClientApplication app =

 ConfidentialClientApplicationBuilder.Create("<<App registration Client ID>>")

                 .WithClientSecret("<<App registration Client Secret Value>>")

                 .WithAuthority(AzureCloudInstance.AzurePublic, "<<3rd Party Tenant Id>>")

                 .Build();

 string[] scopes = new[] { "https://firstparty.sphere.azure.net/api/.default" };

 AuthenticationResult result =  await app.AcquireTokenForClient(scopes).ExecuteAsync();
 string accessToken=result.AccessToken;

Configure application with client certificate

To set up the client certificate:

  1. In the Azure portal, on the left navigation pane, click Azure Active Directory.
  2. Go to App registrations, and select the application you created in Step 1: Register a service principal.
  3. From the left pane, select Certificates & secrets > Certificates > Upload certificate. Select the certificate (an existing certificate or the self-signed certificate you exported).
  4. After registering the certificate with your application in the application registration portal, enable the client application code to use the certificate.

To register your application with a client certificate use the following sample code:

 IConfidentialClientApplication app =

 ConfidentialClientApplicationBuilder.Create("<<App registration Client ID>>")

                 .WithCertificate("<<App registration Certificate>>")

                 .WithAuthority(AzureCloudInstance.AzurePublic, "<<3rd Party Tenant Id>>")

                 .Build();

 string[] scopes = new[] { "https://firstparty.sphere.azure.net/api/.default" };

 AuthenticationResult result =  await app.AcquireTokenForClient(scopes).ExecuteAsync();
 string accessToken=result.AccessToken;

Note

You will need to add MSAL.Net library to use IConfidentialClient.