Quickstart: Protect an ASP.NET Core web API with the Microsoft identity platform

Article
10/23/2023

The following quickstart uses a ASP.NET Core web API code sample to demonstrate how to restrict resource access to authorized accounts. The sample supports authorization of personal Microsoft accounts and accounts in any Microsoft Entra organization.

Prerequisites

Azure account with an active subscription. Create an account for free.
Microsoft Entra tenant
.NET Core SDK 6.0+
Visual Studio 2022 or Visual Studio Code

Step 1: Register the application

Tip

Steps in this article may vary slightly based on the portal you start from.

First, register the web API in your Microsoft Entra tenant and add a scope by following these steps:

Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.
If you have access to multiple tenants, use the Settings icon in the top menu to switch to the tenant in which you want to register the application from the Directories + subscriptions menu.
Browse to Identity > Applications > App registrations and select New registration.
For Name, enter a name for the application. For example, enter AspNetCoreWebApi-Quickstart. Users of the app will see this name, and can be changed later.
Select Register.
Under Manage, select Expose an API > Add a scope. For Application ID URI, accept the default by selecting Save and continue, and then enter the following details:
- Scope name: access_as_user
- Who can consent?: Admins and users
- Admin consent display name: Access AspNetCoreWebApi-Quickstart
- Admin consent description: Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
- User consent display name: Access AspNetCoreWebApi-Quickstart
- User consent description: Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
- State: Enabled
Select Add scope to complete the scope addition.

Step 2: Download the ASP.NET Core project

Download the ASP.NET Core solution from GitHub.

Step 3: Configure the ASP.NET Core project

In this step, the sample code will be configured to work with the app registration that was created earlier.

Extract the .zip file to a local folder that's close to the root of the disk to avoid errors caused by path length limitations on Windows. For example, extract to C:\Azure-Samples.
Open the solution in the webapp folder in your code editor.
In appsettings.json, replace the values of ClientId, and TenantId. The value for the application (client) ID and the directory (tenant) ID, can be found in the app's Overview page on the Microsoft Entra admin center.
```
"ClientId": "Enter_the_Application_Id_here",
"TenantId": "Enter_the_Tenant_Info_Here"
```
- Enter_the_Application_Id_Here is the application (client) ID for the registered application.
- Replace Enter_the_Tenant_Info_Here with one of the following:
  - If the application supports Accounts in this organizational directory only, replace this value with the directory (tenant) ID (a GUID) or tenant name (for example, contoso.onmicrosoft.com). The directory (tenant) ID can be found on the app's Overview page.
  - If the application supports Accounts in any organizational directory, replace this value with organizations.
  - If the application supports All Microsoft account users, leave this value as common.

For this quickstart, don't change any other values in the appsettings.json file.

Step 4: Run the sample

Open a terminal and change directory to the project folder.
```
cd webapi
```
Run the following command to build the solution:
```
dotnet run
```

If the build has been successful, the following output is displayed:

Building...
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: https://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: http://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Application started. Press Ctrl+C to shut down.
...

How the sample works

The web API receives a token from a client application, and the code in the web API validates the token. This scenario is explained in more detail in Scenario: Protected web API.

Startup class

The Microsoft.AspNetCore.Authentication middleware uses a Startup class that's executed when the hosting process starts. In its ConfigureServices method, the AddMicrosoftIdentityWebApi extension method provided by Microsoft.Identity.Web is called.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, "AzureAd");
    }

The AddAuthentication() method configures the service to add JwtBearer-based authentication.

The line that contains .AddMicrosoftIdentityWebApi adds the Microsoft identity platform authorization to the web API. It's then configured to validate access tokens issued by the Microsoft identity platform based on the information in the AzureAD section of the appsettings.json configuration file:

appsettings.json key	Description
`ClientId`	Application (client) ID of the application registered in the Microsoft Entra admin center.
`Instance`	Security token service (STS) endpoint for the user to authenticate. This value is typically `https://login.microsoftonline.com/`, indicating the Azure public cloud.
`TenantId`	Name of the tenant or its tenant ID (a GUID), or `common` to sign in users with work or school accounts or Microsoft personal accounts.

The Configure() method contains two important methods, app.UseAuthentication() and app.UseAuthorization(), that enable their named functionality:

// The runtime calls this method. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // more code
    app.UseAuthentication();
    app.UseAuthorization();
    // more code
}

Protecting a controller, a controller's method, or a Razor page

A controller or controller methods can be protected by using the [Authorize] attribute. This attribute restricts access to the controller or methods by allowing only authenticated users. An authentication challenge can be started to access the controller if the user isn't authenticated.

namespace webapi.Controllers
{
    [Authorize]
    [RequiredScope("access_as_user")]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase

Validation of scope in the controller

The code in the API verifies that the required scopes are in the token by using [RequiredScope("access_as_user")] attribute:

namespace webapi.Controllers
{
    [Authorize]
    [RequiredScope("access_as_user")]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            // some code here
        }
    }
}

Help and support

If you need help, want to report an issue, or want to learn about your support options, see Help and support for developers.

Next steps

The following GitHub repository contains the ASP.NET Core web API code sample instructions and more samples that show how to achieve the following:

Add authentication to a new ASP.NET Core web API.
Call the web API from a desktop application.
Call downstream APIs like Microsoft Graph and other Microsoft APIs.

ASP.NET Core web API tutorials on GitHub