Authenticate to Azure resources from .NET apps hosted on-premises

Apps hosted outside of Azure (for example, on-premises or at a third-party data center) should use an application service principal to authenticate to Azure when accessing Azure resources. Application service principal objects are created using the app registration process in Azure. When an application service principal is created, a client ID and client secret will be generated for your app. The client ID, client secret, and your tenant ID are then stored in environment variables so they can be used by the Azure Identity library to authenticate your app to Azure at runtime.

A different app registration should be created for each environment the app is hosted in. This allows environment specific resource permissions to be configured for each service principal and make sure an app deployed to one environment doesn't talk to Azure resources that are part of another environment.

1 - Register the application in Azure

An app can be registered with Azure using either the Azure portal or the Azure CLI.

Azure portal

Sign in to the Azure portal and follow these steps.

Instructions	Screenshot
In the Azure portal: Enter app registrations in the search bar at the top of the Azure portal. Select the item labeled App registrations under the under Services heading on the menu that appears below the search bar.
On the App registrations page, select + New registration.
On the Register an application page, fill out the form as follows: Name → Enter a name for the app registration in Azure. It's recommended this name include the app name and environment (test, prod) the app registration is for. Supported account types → Accounts in this organizational directory only. Select Register to register your app and create the application service principal.
On the App registration page for your app: Application (client) ID → This is the app id the app will use to access Azure during local development. Copy this value to a temporary location in a text editor as you will need it in a future step. Directory (tenant) id → This value will also be needed by your app when it authenticates to Azure. Copy this value to a temporary location in a text editor it will also be needed it in a future step. Client credentials → You must set the client credentials for the app before your app can authenticate to Azure and use Azure services. Select Add a certificate or secret to add credentials for your app.
On the Certificates & secrets page, select + New client secret.
The Add a client secret dialog will pop out from the right-hand side of the page. In this dialog: Description → Enter a value of Current. Expires → Select a value of 24 months. Select Add to add the secret. IMPORTANT: Set a reminder in your calendar prior to the expiration date of the secret. This way, you can add a new secret prior and update your apps prior to the expiration of this secret and avoid a service interruption in your app.
On the Certificates & secrets page, you will be shown the value of the client secret. Copy this value to a temporary location in a text editor, as you'll need it in a future step. IMPORTANT: This is the only time you will see this value. Once you leave or refresh this page, you won't be able to see this value again. You may add an additional client secret without invalidating this client secret, but you won't see this value again.

Azure CLI

az ad sp create-for-rbac --name <app-name>

The output of the command will be similar to the following. Make note of these values or keep this window open as you will need these values in the next step and will not be able to view the password (client secret) value again.

{
  "appId": "00000000-1111-2222-3333-444444444444",
  "displayName": "msdocs-dotnet-sdk-auth-prod",
  "password": "abcdefghijklmnopqrstuvwxyz",
  "tenant": "00000000-0000-0000-0000-000000000000"
}

2 - Assign roles to the application service principal

Next, you need to determine what roles (permissions) your app needs on what resources and assign those roles to your app. Roles can be assigned a role at a resource, resource group, or subscription scope. This example shows how to assign roles for the service principal at the resource group scope, since most apps group all their Azure resources into a single resource group.

Azure portal

Instructions	Screenshot
Locate the resource group for your app by searching for the resource group name using the search box at the top of the Azure portal. Navigate to your resource group by selecting the resource group name under the Resource Groups heading in the dialog box.
On the page for the resource group, select Access control (IAM) from the left-hand menu.
On the Access control (IAM) page: Select the Role assignments tab. Select + Add from the top menu and then Add role assignment from the resulting drop-down menu.
The Add role assignment page lists all of the roles that can be assigned for the resource group. Use the search box to filter the list to a more manageable size. This example shows how to filter for Storage Blob roles. Select the role that you want to assign. Select Next to go to the next screen.
The next Add role assignment page allows you to specify what user to assign the role to. Select User, group, or service principal under Assign access to. Select + Select members under Members. A dialog box will open on the right-hand side of the Azure portal.
In the Select members dialog: The Select text box can be used to filter the list of users and groups in your subscription. If needed, type the first few characters of the service principal you created for the app to filter the list. Select the service principal associated with your application. Select Select at the bottom of the dialog to continue.
The service principal will now show as selected on the Add role assignment screen. Select Review + assign to go to the final page and then Review + assign again to complete the process.

Azure CLI

A service principal is assigned a role in Azure using the az role assignment create command:

az role assignment create --assignee "{appId}" \
    --role "{roleName}" \
    --resource-group "{resourceGroupName}"

To get the role names to which a service principal can be assigned, use the az role definition list command:

az role definition list \
    --query "sort_by([].{roleName:roleName, description:description}, &roleName)" \
    --output table

For example, to allow the service principal with the appId of 00000000-0000-0000-0000-000000000000 read, write, and delete access to Azure Storage blob containers and data to all storage accounts in the msdocs-dotnet-sdk-auth-example resource group, assign the application service principal to the Storage Blob Data Contributor role using the following command:

az role assignment create --assignee "00000000-0000-0000-0000-000000000000" \
    --role "Storage Blob Data Contributor" \
    --resource-group "msdocs-dotnet-sdk-auth-example"

For information on assigning permissions at the resource or subscription level using the Azure CLI, see Assign Azure roles using the Azure CLI.

3 - Configure environment variables for application

The DefaultAzureCredential object will look for service principal credentials in a set of environment variables at runtime. There are multiple ways to configure environment variables when working with .NET depending on your tooling and environment.

Regardless of which approach you choose, configure the following environment variables when working with a service principal:

• AZURE_CLIENT_ID → The app ID value.
• AZURE_TENANT_ID → The tenant ID value.
• AZURE_CLIENT_SECRET → The password/credential generated for the app.

IIS

If your app is hosted in IIS, it's recommended that you set environment variables per app pool to isolate settings between apps.

appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='ASPNETCORE_ENVIRONMENT',value='Production']" /commit:apphost
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='AZURE_CLIENT_ID',value='00000000-0000-0000-0000-000000000000']" /commit:apphost
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='AZURE_TENANT_ID',value='11111111-1111-1111-1111-111111111111']" /commit:apphost
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='AZURE_CLIENT_SECRET',value='=abcdefghijklmnopqrstuvwxyz']" /commit:apphost

You can also configure these settings directly using the applicationPools element inside of the applicationHost.config file:

<applicationPools>
   <add name="CorePool" managedRuntimeVersion="v4.0" managedPipelineMode="Classic">
      <environmentVariables>
         <add name="ASPNETCORE_ENVIRONMENT" value="Development" />
         <add name="AZURE_CLIENT_ID" value="00000000-0000-0000-0000-000000000000" />
         <add name="AZURE_TENANT_ID" value="11111111-1111-1111-1111-111111111111" />
         <add name="AZURE_CLIENT_SECRET" value="=abcdefghijklmnopqrstuvwxyz" />
      </environmentVariables>
   </add>
</applicationPools>

Windows

You can set environment variables for Windows from the command line. However, when using this approach the values are accessible to all apps running on that operating system and may cause conflicts if you aren't careful. Environment variables can be set at either the user or system level.

# Set user environment variables
setx ASPNETCORE_ENVIRONMENT "Development"
setx AZURE_CLIENT_ID "00000000-0000-0000-0000-000000000000"
setx AZURE_TENANT_ID "11111111-1111-1111-1111-111111111111"
setx AZURE_CLIENT_SECRET "=abcdefghijklmnopqrstuvwxyz"

# Set system environment variables - requires running as admin
setx ASPNETCORE_ENVIRONMENT "Development"
setx AZURE_CLIENT_ID "00000000-0000-0000-0000-000000000000" /m
setx AZURE_TENANT_ID "11111111-1111-1111-1111-111111111111" /m
setx AZURE_CLIENT_SECRET "=abcdefghijklmnopqrstuvwxyz" /m

You can also use PowerShell to set environment variables at either the user or machine level:

# Set user environment variables
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "00000000-0000-0000-0000-000000000000", "User")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "11111111-1111-1111-1111-111111111111", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "=abcdefghijklmnopqrstuvwxyz", "User")

# Set system environment variables - requires running as admin
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "00000000-0000-0000-0000-000000000000", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "11111111-1111-1111-1111-111111111111", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "=abcdefghijklmnopqrstuvwxyz", "Machine")

4 - Implement DefaultAzureCredential in your application

DefaultAzureCredential is an opinionated, ordered sequence of mechanisms for authenticating to Microsoft Entra ID. Each authentication mechanism is a class derived from the TokenCredential class and is known as a credential. At runtime, DefaultAzureCredential attempts to authenticate using the first credential. If that credential fails to acquire an access token, the next credential in the sequence is attempted, and so on, until an access token is successfully obtained. In this way, your app can use different credentials in different environments without writing environment-specific code.

To use DefaultAzureCredential, add the Azure.Identity and optionally the Microsoft.Extensions.Azure packages to your application:

Command Line

In a terminal of your choice, navigate to the application project directory and run the following commands:

dotnet add package Azure.Identity
dotnet add package Microsoft.Extensions.Azure

NuGet Package Manager

Right-click your project in Visual Studio's Solution Explorer window and select Manage NuGet Packages. Search for Azure.Identity, and install the matching package. Repeat this process for the Microsoft.Extensions.Azure package.

Azure services are accessed using specialized client classes from the various Azure SDK client libraries. These classes and your own custom services should be registered so they can be accessed via dependency injection throughout your app. In Program.cs, complete the following steps to register a client class and DefaultAzureCredential:

1. Include the Azure.Identity and Microsoft.Extensions.Azure namespaces via using directives.
2. Register the Azure service client using the corresponding Add-prefixed extension method.
3. Pass an instance of DefaultAzureCredential to the UseCredential method.

For example:

using Microsoft.Extensions.Azure;
using Azure.Identity;

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"));
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

An alternative to UseCredential is to instantiate DefaultAzureCredential directly:

using Azure.Identity;

builder.Services.AddSingleton<BlobServiceClient>(_ =>
    new BlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"),
        new DefaultAzureCredential()));

When the preceding code runs on your local development workstation, it looks in the environment variables for an application service principal or at locally installed developer tools, such as Visual Studio, for a set of developer credentials. Either approach can be used to authenticate the app to Azure resources during local development.

When deployed to Azure, this same code can also authenticate your app to other Azure resources. DefaultAzureCredential can retrieve environment settings and managed identity configurations to authenticate to other services automatically.