Call Protected APIs in ASP.NET Core

Original post written by Andrea Chiarelli for Auth0 blog.

Learn the right way to call a protected API using an access token in ASP.NET Core applications.

Calling an API protected with an access token is pretty easy. It’s a matter of adding a bearer token to the HTTP request. You can do this in different ways in .NET. But what is the best way to do it in an ASP.NET Core application? Let's find out together with a practical example.

Call a Protected API: The Basics

In the OAuth 2.0 context, an application can call a protected API by including an access token in its HTTP request (RFC6750). The most common and recommended way to include the access token into the HTTP request is to use the Bearer authentication scheme. In short, this means that the request should include an Authorization header with the Bearer prefix, as shown in the following example:

GET /resource HTTP/1.1
Host: server.example.com
Authorization: Bearer mF_9.B5f-4.1JqM

The string following the Bearer prefix is the value of the access token.

Bear in mind two things:

• The Bearer prefix indicates that any application in possession of the token can use it to call the protected API. No further proof of identity is requested by the API. This implies that you must send the request over a secure channel (such as HTTPS) and take extreme care to prevent any risk of token theft.
• The value of the token is not relevant to the client application. It can be a JWT or use some other format. From the calling application's point of view, it's just a sequence of characters.

Basically, this is all you need to know to call a protected API:

1. How to get an access token.

2. How to attach the token to the HTTP request.

You will learn how to do this in practice in the next sections.

The Sample Application

To show how to call a protected API from ASP.NET Core, you will explore the code of a sample application and progressively modify it until you get the best approach.

To run the sample app you need the .NET 6.0 SDK installed on your machine.

If this is the first time you run an ASP.NET Core application on your machine, make sure to trust its HTTPS development certificate.

Let's download the sample application from GitHub by running the following command in a terminal window:

git clone --branch starting-point --single-branch https://github.com/auth0-blog/call-protected-api-aspnet-core.git

You will get a reward-points-redemption-app folder with two subfolders: catalog and redemption-api. The catalog folder contains the code of an ASP.NET Core MVC application that shows a reward catalog to authenticated users. The redemption-api folder contains the code of an ASP.NET Core Web API that allows users to redeem their points to get a reward.

The following diagram shows the overall interaction of the system components:

Following the diagram:

1. The user authenticates with Auth0.
2. After authentication, the user explores the reward catalog.
3. When the user wants to redeem their points to get a catalog item, the catalog app makes a request to the redemption API.

The projects you downloaded from GitHub already implement most of those interactions. Getting the access token and calling the API are missing. You will implement this functionality in a moment.

While the application calling the protected API is an ASP.NET Core MVC application, all you learn in this article applies to other ASP.NET Core application frameworks, such as Razor Pages and Blazor Server.

If you want to learn how to add authentication to an ASP.NET Core MVC application, check out this article.

Configure the catalog application

Before proceeding with the needed changes, you must configure the two applications to work with Auth0. Let's start with the catalog application. You need an Auth0 account. If you don't have it yet, you can sign up for a free one.

In the Auth0 dashboard, move to the Applications section and follow these steps:

1. Click on Create Application.
2. Provide a friendly name for your application (for example, Catalog Web App) and choose Regular Web Applications as the application type.
3. Finally, click the Create button.

These steps make Auth0 aware of your ASP.NET Core MVC application and will allow you to control access.

After creating the application, you land on the Quick Start tab of the application page. Ignore it and move to the Settings tab. Here take note of your Auth0 domain and client id. Then, in the same form, assign the value https://localhost:7095/callback to the Allowed Callback URLs field and the value https://localhost:7095/ to the Allowed Logout URLs field.

The first value tells Auth0 which URL to call back after the user authentication. The second value tells Auth0 which URL a user should be redirected to after their logout.

Click the Save Changes button to apply them.

Now, go to the catalog folder and open the appsettings.json configuration file. Its content is as shown below:

// catalog/appsettings.json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Auth0": {
    "Domain": "YOUR_AUTH0_DOMAIN",
    "ClientId": "YOUR_CLIENT_ID"
  }
}

Replace the placeholders YOUR_AUTH0_DOMAIN and YOUR_CLIENT_ID with the respective values taken from the Application settings under the Basic Information section.

Read more...