Quickstart: Call a web API that is protected by the Microsoft identity platform

Applies to: Workforce tenants External tenants (learn more)

In this quickstart, you use a sample web app to show you how to protect an ASP.NET web API by using the Microsoft identity platform. The sample uses Microsoft Authentication Library (MSAL) to handle authentication.

Prerequisites

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

Register web API application

To complete registration, provide the application a name and specify the supported account types. Once registered, the application Overview page displays the identifiers needed in the application source code.

1. Sign in to the Microsoft Entra admin center as at least an Application Developer.

2. 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.

3. Browse to Identity > Applications > App registrations.

4. Select New registration.

5. Enter a Name for the application, such as NewWebAPI1.

6. For Supported account types, select Accounts in this organizational directory only. For information on different account types, select Help me choose option.

7. Select Register.

   

8. The application's Overview pane is displayed when registration is complete. Record the Directory (tenant) ID and the Application (client) ID to be used in your application source code.

   

Note

The Supported account types can be changed by referring to Modify the accounts supported by an application.

Expose an API

Once the API is registered, you can configure its permission by defining the scopes that the API exposes to client applications. Client applications request permission to perform operations by passing an access token along with its requests to the protected web API. The web API then performs the requested operation only if the access token it receives contains the required scopes.

ASP.NET

1. 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.

2. Select Add scope.

ASP.NET CORE

1. Under Manage, select Expose an API > Add a scope. Accept the proposed Application ID URI (api://{clientId}) by selecting Save and continue. The {clientId} is the value recorded from the Overview page. Then enter the following information:

   1. For Scope name, enter Forecast.Read.
   2. For Who can consent, ensure that the Admins and users option is selected.
   3. In the Admin consent display name box, enter Read forecast data.
   4. In the Admin consent description box, enter Allows the application to read weather forecast data.
   5. In the User consent display name box, enter Read forecast data.
   6. In the User consent description box, enter Allows the application to read weather forecast data.
   7. Ensure that the State is set to Enabled.

2. Select Add scope. If the scope has been entered correctly, it's listed in the Expose an API pane.

   

Clone or download the sample application

To obtain the sample application, you can either clone it from GitHub or download it as a .zip file.

ASP.NET

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.

ASP.NET CORE

git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git

• Download the .zip file. Extract it to a file path where the length of the name is fewer than 260 characters.

Configure the sample application

Configure the code sample to match the registered web API.

ASP.NET

1. Open the solution in Visual Studio, and then open the appsettings.json file under the root of the TodoListService project.

2. 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:

1. In the TodoListClient project root folder, open the app.config file.

2. 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:

1. Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.

2. Browse to Identity > Applications > App registrations and select New registration.

3. Select New registration.

4. 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.

5. 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.

6. 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.

1. In the App registrations portal, on the Overview page, copy the value of the Application (client) ID.

2. From the TodoListClient project root folder, open the app.config file, and then paste the Application ID value in the ida:ClientId parameter.

ASP.NET CORE

1. In your IDE, open the project folder, ms-identity-docs-code-dotnet/web-api, containing the sample.

2. Open appsettings.json file, which contains the following code snippet:

   {
     "AzureAd": {
       "Instance": "https://login.microsoftonline.com/", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter the tenant ID obtained from the Microsoft Entra admin center",
       "ClientId": "Enter the client ID obtained from the Microsoft Entra admin center",
       "Scopes": "Forecast.Read"
     },
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
     },
     "AllowedHosts": "*"
   }
   

   Find the following key:

   • ClientId - The identifier of the application, also referred to as the client. Replace the value text in quotes with Application (client) ID that was recorded earlier from the Overview page of the registered application.
   • TenantId - The identifier of the tenant where the application is registered. Replace the value text in quotes with Directory (tenant) ID value that was recorded earlier from the Overview page of the registered application.

Run the sample application

ASP.NET

Start both projects. For Visual Studio users;

1. Right click on the Visual Studio solution and select Properties

2. In the Common Properties select Startup Project and then Multiple startup projects.

3. For both projects choose Start as the action

4. Ensure the TodoListService service starts first by moving it to the first position in the list, using the up arrow.

Sign in to run your TodoListClient project.

1. Press F5 to start the projects. The service page opens, as well as the desktop application.

2. 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.

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

Run your project

1. Press F5 to run your project. Your TodoListClient app opens.
2. 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.

Optional: Limit sign-in access to certain users

By default, any personal accounts, such as outlook.com or live.com accounts, or work or school accounts from organizations that are integrated with Microsoft Entra ID 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.

ASP.NET CORE

1. Execute the following command to start the app:

   dotnet run
   

2. An output like the following sample appears:

   ...
   info: Microsoft.Hosting.Lifetime[14]
         Now listening on: http://localhost:{port}
   ...
   

   Record the port number in the http://localhost:{port} URL.

3. To verify the endpoint is protected, update the base URL in the following cURL command to match the one you received in the previous step, and then run the command:

   curl -X GET https://localhost:5001/weatherforecast -ki
   

   The expected response is 401 Unauthorized with output similar to:

   user@host:~$ curl -X GET https://localhost:5001/weatherforecast -ki
   HTTP/2 401
   date: Fri, 23 Sep 2023 23:34:24 GMT
   server: Kestrel
   www-authenticate: Bearer
   content-length: 0
   

Next steps

ASP.NET

Learn more by building a protected ASP.NET Core web api in the following tutorial series:

Protected web API tutorial

ASP.NET CORE

Proceed to the next article to learn how to call the protected web API using cURL.

How-to: Call an ASP.NET Core web API with cURL