Add Authorization to Your ASP.NET Core Web API Application

Auth0 allows you to add authentication and access user profile information in almost any application type quickly. This guide demonstrates how to integrate Auth0 with any new or existing ASP.NET Web API application using the Microsoft.AspNetCore.Authentication.JwtBearer package.

If you haven’t created an API in your Auth0 dashboard yet, you can use the interactive selector to create a new Auth0 API or select an existing API that represents the project you want to integrate with.

Alternatively, you can read our getting started guide, which will help you set up your first API through the Auth0 Dashboard.

Note that every API in Auth0 is configured using an API Identifier; your application code will use the API Identifier as the Audience to validate the access token.

New to Auth0? Learn how Auth0 works and read about implementing API authentication and authorization using the OAuth 2.0 framework.

Define permissions

Permissions let you define how resources can be accessed on behalf of the user with a given access token. For example, you might choose to grant read access to the messages resource if users have the manager access level, and grant write access to that resource if they have the administrator access level.

You can define allowed permissions in the Permissions view of the Auth0 Dashboard’s APIs section. The following example uses the read:messages scope.

Install dependencies

To allow your application to validate access tokens, add a reference to the Microsoft.AspNetCore.Authentication.JwtBearer NuGet package:

Install-Package Microsoft.AspNetCore.Authentication.JwtBearer

Configure the middleware

Set up the authentication middleware by configuring it in your application’s Program.cs file:

1. Register the authentication services by making a call to the AddAuthentication method. Configure JwtBearerDefaults.AuthenticationScheme as the default scheme.

2. Register the JWT Bearer authentication scheme by making a call to the AddJwtBearer method. Configure your Auth0 domain as the authority and your Auth0 API Identifier as the audience, and be sure that your Auth0 domain and API Identifier are set in your application’s appsettings.json file.

   In some cases, the access token will not have a sub claim; in this case, the User.Identity.Name will be null. If you want to map a different claim to User.Identity.Name, add it to options.TokenValidationParameters within the AddJwtBearer() call.

3. Add the authentication and authorization middleware to the middleware pipeline by adding calls to the UseAuthenticationand UseAuthorizationmethods under the var app = builder.Build();method.

Validate scopes

To ensure that an access token contains the correct scopes, use Policy-Based Authorization in the ASP.NET Core:

1. Create a new authorization requirement called HasScopeRequirement, which will check whether the scopeclaim issued by your Auth0 tenant is present, and if so, will check that the claim contains the requested scope.
2. Under your Program.csfile’s var builder = WebApplication.CreateBuilder(args);method, add a call to the app.AddAuthorizationmethod.
3. Add policies for scopes by calling AddPolicyfor each scope.
4. Register a singleton for the HasScopeHandlerclass.

Protect API endpoints

The JWT middleware integrates with the standard ASP.NET Core Authentication and Authorization mechanisms.

To secure an endpoint, add the [Authorize] attribute to your controller action (or the entire controller if you want to protect all of its actions).

When securing endpoints that require specific scopes, make sure that the correct scope is present in the access_token. To do so, add the Authorize attribute to the Scoped action and pass read:messages as the policy parameter.

Call your API

The way in which you call your API depends on the type of application you are developing and the framework you are using. To learn more, read the relevant application Quickstart:

• Single-Page Applications
• Mobile / Native Application

Get an access token

Regardless of the type of application you are developing or the framework you are using, to call your API, you need an access token.

If you call your API from a Single-Page Application (SPA) or Native application, you will receive an access token after the authorization flow completes.

If you call the API from a command-line tool or other service where a user entering credentials does not exist, use the OAuth Client Credentials Flow. To do so, register a Machine-to-Machine Application and pass the following values in your request:

• Client ID as the client_id parameter.
• Client Secret as the client_secret parameter.
• API Identifier (the same value used to configure the middleware earlier in this quickstart) as the audience parameter.

To learn more about getting the Client ID and Client Secret for your machine-to-machine application, read Application Settings.

Example request

cURL

curl --request post \
--url 'https://dev-gja8kxz4ndtex3rq.us.auth0.com/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded'

Call a secure endpoint

Now that you have an access token, you can use it to call secure API endpoints. When calling a secure endpoint, you must include the access token as a Bearer token in the Authorization header of the request. For example, you can make a request to the /api/private endpoint:

cURL

curl --request get \
--url http://localhost:3010/api/private \
--header 'authorization: Bearer YOUR_ACCESS_TOKEN'

Call the /api/private-scoped endpoint in a similar way, but ensure that the API permissions are configured correctly and that the access token includes the read:messages scope.

Checkpoint

You should now be able to call the /api/private and /api/private-scoped endpoints.

Run your application and verify that:

• GET /api/privateis available for authenticated requests.
• GET /api/private-scopedis available for authenticated requests containing an access token with the read:messagesscope.

Next Steps

Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

• Auth0 Dashboard - Learn how to configure and manage your Auth0 tenant and applications
• Auth0 Marketplace - Discover integrations you can enable to extend Auth0’s functionality