Quickstart: Protect a web API with the Microsoft identity platform

Article
12/14/2022

The following quickstart uses, uses a code sample that demonstrates how to protect an ASP.NET web API by restricting access to its resources to authorized accounts only. The sample supports authorization of personal Microsoft accounts and accounts in any Azure Active Directory (Azure AD) organization.

The article also uses a Windows Presentation Foundation (WPF) app to demonstrate how to request an access token to access a web API.

Prerequisites

An Azure account with an active subscription. Create an account for free.
Visual Studio 2022. Download Visual Studio for free.

Clone or download the sample

The code sample can be obtained in two ways:

Clone it from your shell or command line:

git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git

Download it as a ZIP file.

Tip

To avoid errors caused by path length limitations in Windows, we recommend extracting the archive or cloning the repository into a directory near the root of your drive.

Register the web API (TodoListService)

Sign in to the Azure portal.
If you have access to multiple tenants, use the Directory + subscription filter in the top menu to select the tenant in which you want to register an application.
Find and select Azure Active Directory.
Under Manage, select App registrations > New registration.
Enter a Name for your application, for example AppModelv2-NativeClient-DotNet-TodoListService. Users of your app might see this name, and you can change it later.
For Supported account types, select Accounts in any organizational directory.
Select Register to create the application.
On the app Overview page, look for the Application (client) ID value, and then record it for later use. You'll need it to configure the Visual Studio configuration file for this project (that is, ClientId in the TodoListService\appsettings.json file).
Under Manage, select Expose an API > Add a scope. Accept the proposed Application ID URI (api://{clientId}) by selecting Save and continue, and then enter the following information:
1. For Scope name, enter access_as_user.
2. For Who can consent, ensure that the Admins and users option is selected.
3. In the Admin consent display name box, enter Access TodoListService as a user.
4. In the Admin consent description box, enter Accesses the TodoListService web API as a user.
5. In the User consent display name box, enter Access TodoListService as a user.
6. In the User consent description box, enter Accesses the TodoListService web API as a user.
7. For State, keep Enabled.
Select Add scope.

Configure the service project

Configure the service project to match the registered web API.

Open the solution in Visual Studio, and then open the appsettings.json file under the root of the TodoListService project.
Replace the value of the Enter_the_Application_Id_here by the Client ID (Application ID) value from the application you registered in the App registrations portal both in the ClientID and the Audience properties.

Add the new scope to the app.config file

To add the new scope to the TodoListClient app.config file, follow these steps:

In the TodoListClient project root folder, open the app.config file.
Paste the Application ID from the application that you registered for your TodoListService project in the TodoListServiceScope parameter, replacing the {Enter the Application ID of your TodoListService from the app registration portal} string.

Note

Make sure that the Application ID uses the following format: api://{TodoListService-Application-ID}/access_as_user (where {TodoListService-Application-ID} is the GUID representing the Application ID for your TodoListService app).

Register the web app (TodoListClient)

Register your TodoListClient app in App registrations in the Azure portal, and then configure the code in the TodoListClient project. If the client and server are considered the same application, you can reuse the application that's registered in step 2. Use the same application if you want users to sign in with a personal Microsoft account.

Register the app

To register the TodoListClient app, follow these steps:

Go to the Microsoft identity platform for developers App registrations portal.
Select New registration.
When the Register an application page opens, enter your application's registration information:
1. In the Name section, enter a meaningful application name that will be displayed to users of the app (for example, NativeClient-DotNet-TodoListClient).
2. For Supported account types, select Accounts in any organizational directory.
3. Select Register to create the application.
Note

In the TodoListClient project app.config file, the default value of ida:Tenant is set to common. The possible values are:
- common: You can sign in by using a work or school account or a personal Microsoft account (because you selected Accounts in any organizational directory in a previous step).
- organizations: You can sign in by using a work or school account.
- consumers: You can sign in only by using a Microsoft personal account.
On the app Overview page, select Authentication, and then complete these steps to add a platform:
1. Under Platform configurations, select the Add a platform button.
2. For Mobile and desktop applications, select Mobile and desktop applications.
3. For Redirect URIs, select the https://login.microsoftonline.com/common/oauth2/nativeclient check box.
4. Select Configure.
Select API permissions, and then complete these steps to add permissions:
1. Select the Add a permission button.
2. Select the My APIs tab.
3. In the list of APIs, select AppModelv2-NativeClient-DotNet-TodoListService API or the name you entered for the web API.
4. Select the access_as_user permission check box if it's not already selected. Use the Search box if necessary.
5. Select the Add permissions button.

Configure your project

Configure your TodoListClient project by adding the Application ID to the app.config file.

In the App registrations portal, on the Overview page, copy the value of the Application (client) ID.
From the TodoListClient project root folder, open the app.config file, and then paste the Application ID value in the ida:ClientId parameter.

Run your projects

Start both projects. For Visual Studio users;

Right click on the Visual Studio solution and select Properties
In the Common Properties select Startup Project and then Multiple startup projects.
For both projects choose Start as the action
Ensure the TodoListService service starts first by moving it to the fist position in the list, using the up arrow.

Press F5 to start the projects. The service page opens, as well as the desktop application.
In the TodoListClient, at the upper right, select Sign in, and then sign in with the same credentials you used to register your application, or sign in as a user in the same directory.

If you're signing in for the first time, you might be prompted to consent to the TodoListService web API.

To help you access the TodoListService web API and manipulate the To-Do list, the sign-in also requests an access token to the access_as_user scope.

Pre-authorize your client application

You can allow users from other directories to access your web API by pre-authorizing the client application to access your web API. You do this by adding the Application ID from the client app to the list of pre-authorized applications for your web API. By adding a pre-authorized client, you're allowing users to access your web API without having to provide consent.

In the App registrations portal, open the properties of your TodoListService app.
In the Expose an API section, under Authorized client applications, select Add a client application.
In the Client ID box, paste the Application ID of the TodoListClient app.
In the Authorized scopes section, select the scope for the api://<Application ID>/access_as_user web API.
Select Add application.

Run your project

Press F5 to run your project. Your TodoListClient app opens.
At the upper right, select Sign in, and then sign in by using a personal Microsoft account, such as a live.com or hotmail.com account, or a work or school account.

By default, any personal accounts, such as outlook.com or live.com accounts, or work or school accounts from organizations that are integrated with Azure AD can request tokens and access your web API.

To specify who can sign in to your application, by changing the TenantId property in the appsettings.json file.

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

Learn more about the protected web API scenario that the Microsoft identity platform supports.

Protected web API scenario

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 Azure Active Directory (Azure AD) organization.

Prerequisites

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

Step 1: Register the application

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

Sign in to the Azure portal.
If access to multiple tenants is available, use the Directories + subscriptions filter in the top menu to switch to the tenant in which to register the application.
Search for and select Azure Active Directory.
Under Manage, select App registrations > 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 Azure portal.
```
"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 Azure portal.
`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

Quickstart: Protect a web API with the Microsoft identity platform

Prerequisites

Clone or download the sample

Register the web API (TodoListService)

Configure the service project

Add the new scope to the app.config file

Register the web app (TodoListClient)

Register the app

Configure your project

Run your projects

Pre-authorize your client application

Run your project

Help and support

Next steps

Prerequisites

Step 1: Register the application

Step 2: Download the ASP.NET Core project

Step 3: Configure the ASP.NET Core project

Step 4: Run the sample

How the sample works

Startup class

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

Validation of scope in the controller

Help and support

Next steps

Feedback

Additional resources

Additional resources

Quickstart: Protect a web API with the Microsoft identity platform

Prerequisites

Clone or download the sample

Register the web API (TodoListService)

Configure the service project

Add the new scope to the app.config file

Register the web app (TodoListClient)

Register the app

Configure your project

Run your projects

Pre-authorize your client application

Run your project

Optional: Limit sign-in access to certain users

Help and support

Next steps

Prerequisites

Step 1: Register the application

Step 2: Download the ASP.NET Core project

Step 3: Configure the ASP.NET Core project

Step 4: Run the sample

How the sample works

Startup class

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

Validation of scope in the controller

Help and support

Next steps

Feedback

Additional resources

Additional resources