andrea-chiarelli

I have over 20 years of experience as a software engineer and technical author. Throughout my career, I've used several programming languages and technologies for the projects I was involved in, ranging from C# to JavaScript, ASP.NET to Node.js, Angular to React, SOAP to REST APIs, etc.

In the last few years, I've been focusing on simplifying the developer experience with Identity and related topics, especially in the .NET ecosystem.

Principal Developer Advocate

Andrea Chiarelli

What is the best way to apply Role-Based Access Control (RBAC) to your ASP.NET Web API? Let's find out together.

Role-Based Authorization for ASP.NET Web APIs

Learn how to build a CRUD Web API with ASP.NET through this practical tutorial.

Building ASP.NET CRUD Web APIs

Checking user permissions allows you to have more control over access to your ASP.NET Web API.

Protecting a Web API from unauthorized users is the first step to get control over who can access it. However, simply excluding anonymous users may be insufficient in some situations. You may need to control over who can do what on your application. This article will show you how to define and check permissions for users accessing your ASP.NET Web API secured with Auth0.

## The Need for Permissions

A previous article introduced [how to enable authorization for ASP.NET Web APIs](https://auth0.com/blog/aspnet-web-api-authorization/). The sample application accompanying that article is an ASP.NET Web API that implements the CRUD (*Create*, *Retrieve*, *Update*, *Delete*) operations over a glossary of terms. That article explains how to protect the Web API by using Auth0 so that only authorized users can create, modify, and delete glossary items. Everyone can still get the list of terms or a single glossary item.

That worked pretty well! However, you may need more granular control over the users who can do specific operations. For example, you may want to give some users the ability to add a new glossary term or modify an existing one, but you don't want them to delete items. Only specific users should be able also to delete items. To achieve this control level, you must deal with permissions.

In the security context, a **permission** is a property of a resource that indicates the operation a user can do on it, like, for example, read, write, print, send, etc. In the case of your sample application, you have the glossary and term resources. Regarding the former, you can get the list of terms and add new items. Regarding the latter, you can read, update, or delete it.

<details>
  <summary>Permissions vs. privileges</summary>
Usually, permissions and privileges are used interchangeably, but technically they have precise and different meanings in the context of computer security.


A **permission** is an action that can be performed on a resource. It is somehow bounded to the resource, and you can consider it as a resource property.

A **privilege** is a permission assigned to a user or an application. When you assign the writing permission to a user, you are granting them a privilege.
</details>

## Setting up the Web API Application

The goal of this article is to show you how to implement permission-based authorization in this sample application. 

> Make sure you have [the latest .NET SDK](https://dotnet.microsoft.com/download/dotnet/current) already installed on your machine to run the sample ASP.NET application.

So, let's start by downloading the source code with the following command:

```bash
git clone --branch add-authorization --single-branch https://github.com/auth0-blog/glossary-web-api-aspnet.git
```

Once you download the application, register it with Auth0 in order to enable support for the authorization service. If you haven't an Auth0 account, you can <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for a free one</a>. Follow the [instructions in this article to register the application with Auth0](https://auth0.com/blog/aspnet-web-api-authorization/#Registering-the-Web-API-with-Auth0).

After you completed the registration, move to the `glossary-web-api-aspnet` folder and open the `appsettings.json` configuration file. Its content looks as follows:

```json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "Auth0": {
    "Domain": "YOUR_AUTH0_DOMAIN",
    "Audience": "YOUR_UNIQUE_IDENTIFIER"
  }
}
```

Replace the `YOUR_AUTH0_DOMAIN` placeholder with your Auth0 domain and the `YOUR_UNIQUE_IDENTIFIER` placeholder with the value you provided as a unique identifier of your API (`https://glossary.com`, if you kept the value suggested in [the mentioned article](https://auth0.com/blog/aspnet-web-api-authorization/#Registering-the-Web-API-with-Auth0)).

> Note: Your Auth0 domain is a string in the form `YOUR-TENANT-NAME.auth0.com` where `YOUR-TENANT-NAME` is the name you provided when you created your account with Auth0. For more information, [check the documentation](https://auth0.com/docs/getting-started/the-basics#domains).

Now, launch the ASP.NET Web API application by typing `dotnet run` in a terminal window. By pointing your browser to `https://localhost:5001/swagger`, you should see the [Swagger UI](https://swagger.io/tools/swagger-ui/) shown below to test the API interactively:

![Protected Web APIs in Swagger UI](https://images.ctfassets.net/23aumh6u8s0i/1rNBChKdbCr9fKdpbbYcKR/014f6ace0411febc726959cd88ed8e6a/protected-swagger-ui-webapi.png)

To call the `POST`, `PUT`, and `DELETE` actions, [you need an access token, as explained in this section](https://auth0.com/blog/aspnet-web-api-authorization/#Testing-the-Secure-Web-API).

Now you are ready to set up permissions on your Web API.

## Defining Permissions for an API

The first step is to define the permissions for your application. These permissions can vary depending on the needs of your application. In the glossary Web API application, we are going to define the permissions identified by the following strings:

- `create:term`. This permission allows you to add a new term to the glossary.
- `update:term`. With this permission, you can update an existing term.
- `delete:term`. This permission allows you to delete a term from the glossary.

To associate these permissions with your API, go to the [API section](https://manage.auth0.com/#/apis) of your Auth0 Dashboard and select the API you defined for the glossary application. Then select the *Permissions* tab. Here you can add the permissions with their descriptions as defined above. At the end of this process, that page will look like the following:

![Defining permissions in the Auth0 Dashboard](https://images.ctfassets.net/23aumh6u8s0i/52FOUrB7EcV17WYLSjdbDS/19d1360d9def0ea77cc550ba664a7748/defining-permissions-auth0-dashboard.png.png)

This configuration informs Auth0 that the glossary Web API supports only these permissions.

Next, move to the *Settings* tab and scroll down to the *RBAC Settings* section. Here, click both the *Enable RBAC* and the *Add Permissions in the Access Token* toggle buttons, as in the following picture, and don't forget to click the *Save* button at the end:

![](https://images.ctfassets.net/23aumh6u8s0i/49AQnZIW5pP4wBIHA4sV9i/2c476e2508ff68fde80061b6973016ca/enabling-rbac.png)

These settings will enforce the evaluation  of roles and permissions assignments during the user login.

> Although we will not use roles in this article, you still need to enable RBAC (Role-Based Access Control) support.



<details>
  <summary>Permissions vs. scopes</summary>
When defining the API permissions in the Auth0 Dashboard, you find the term *scope* next to the term *permission*. You may think that they are synonymous, but they actually aren't. Both describe the actions that can be performed on a resource, but they are used in different authorization scenarios.

**Permissions** are used in a [first-party authorization scenario](https://auth0.com/docs/applications/first-party-and-third-party-applications#first-party-applications), i.e., when the same organization or person controls both the client and the server applications.

**Scopes** are used in a [third-party authorization scenario](https://auth0.com/docs/applications/first-party-and-third-party-applications#third-party-applications), i.e., when different organizations control the client and the server applications.

In the latter scenario, the client application asks for one or more permissions to operate on a specific resource on behalf of the user. This requested permission is a **scope**. Usually, scopes limit what an app can do on behalf of the user, and the user may grant them to the application or not.

Scopes have been [introduced by OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) in the context of delegated authorization.
</details>

## Checking Permissions in an API

As the next step, you need to check that the user calling your API has the proper permissions. You can accomplish this task by defining one or more authorization policies and applying them to the controller or the methods that implement your ASP.NET Web API.

An **authorization policy** is a set of requirements that users or applications must meet in order to be allowed to perform an action on a resource. Let's see how you can define and apply an authorization policy in practice.

### Registering an authorization policy

To define an authorization policy for the glossary Web API, open the `Startup.cs` file in the root folder of the project and append the following code to the body of the `ConfigureServices()` method:

```csharp
// Startup.cs

// ...existing code...

namespace Glossary
{
  public class Startup
  {
    // ...existing code...
    
    public void ConfigureServices(IServiceCollection services)
    {
      // ...existing code...
      
      //👇 new code
      services.AddAuthorization(options =>
      {
        options.AddPolicy("WriteAccess", policy => 
                          policy.RequireClaim("permissions", "create:term", "update:term"));
        options.AddPolicy("DeleteAccess", policy => 
                          policy.RequireClaim("permissions", "delete:term"));
      });
      //👆 new code
    }
    
    // ...existing code...
  }
}

```

You invoked the `AddAuthorization()` method to configure the ASP.NET authorization service. To this purpose, you defined two authorization policies via the `AddPolicy()` method of the `options` parameter. Each policy has a name and a lambda expression. For example, the `WriteAccess` authorization policy is defined by requiring the `permissions` [claim](https://auth0.com/docs/tokens/json-web-tokens/json-web-token-claims) in the access token whose value can be `create:term` or `update:term`. Similarly, for the `DeleteAccess` policy.

### Authorization policy approaches

You defined two authorization policies based on the permissions you defined for the API in the Auth0 Dashboard. Both policies are based on requiring the existence of claims with specific values. This is the simplest way to define an authorization policy in ASP.NET. It is usually referred to as [claim-based authorization](https://docs.microsoft.com/en-us/aspnet/core/security/authorization/claims).

If you have more complex criteria for defining your authorization policies, you need to use the [policy-based authorization](https://docs.microsoft.com/en-us/aspnet/core/security/authorization/policies) approach. For example, if you want to be sure that the issuer of the `permissions` claim is your [Auth0 tenant](https://auth0.com/docs/get-started/create-tenants), you can define your `WriteAccess` authorization policy as follows:

```csharp
options.AddPolicy("WriteAccess", policy => 
                    policy.RequireAssertion(context =>
                       context.User.HasClaim(claim =>
                         (claim.Type == "permissions" &&
                          (claim.Value == "create:term" ||
                           claim.Value == "update:term") &&
                          claim.Issuer == $"https://{Configuration["Auth0:Domain"]}/"
                         )
                       )
                    )
                  );
```

In this case, you used the `RequireAssertion()` method to build a boolean expression that evaluates your specific criteria. In particular, this criteria checks that the `Issuer` property of the claim matches the URL of your Auth0 tenant.

> Note that claim-based authorization is just a specialized case of policy-based authorization.

If you have more specific needs, you can even [customize the built-in ASP.NET authorization middleware](https://docs.microsoft.com/en-us/aspnet/core/security/authorization/customizingauthorizationmiddlewareresponse).

### Applying an authorization policy

Once you define and register your authorization policies, you can apply them in your Web API. Applying an authorization policy is just a matter of passing parameters to the `Authorize` attribute. So, open the `GlossaryController.cs` file under the `Controllers` folder and apply the changes outlined in the following:

```csharp
// Controllers/GlossaryController.cs

// ...existing code...

namespace Glossary.Controllers
{
  [ApiController]
  [Route("api/[controller]")]
  public class GlossaryController : ControllerBase
  {
    // ...existing code...

    [HttpPost]
    [Authorize(Policy = "WriteAccess")]    //👈 changed code
    public ActionResult Post(GlossaryItem glossaryItem)
    {
      // ...existing code...
    }

    [HttpPut]
    [Authorize(Policy = "WriteAccess")]    //👈 changed code
    public ActionResult Put(GlossaryItem glossaryItem)
    {
      // ...existing code...
    }

    [HttpDelete]
    [Route("{term}")]
    [Authorize(Policy = "DeleteAccess")]    //👈 changed code
    public ActionResult Delete(string term)
    {
      // ...existing code...
    }
  }
}
```

This way, you are requesting the ASP.NET authorization middleware to evaluate a specific policy to authorize the execution of the related controller's method.

Your Web API is ready to run and check permissions!

## Testing Permissions

To test the new glossary Web API, you are going to simulate users accessing the endpoints with different permissions. For this simulation, you will interact with the API through the Swagger UI by providing an access token. So, launch the Web API by typing `dotnet run` in a terminal window and point your browser to [https://localhost:5001/swagger](https://localhost:5001/swagger).

### Testing access without permissions

Let's try to access a protected endpoint with an access token not bound to any permissions. Go to the [API section](https://manage.auth0.com/#/apis) of your Auth0 Dashboard, select the API related to the glossary app, and select the *Test* tab. Here you can get a token to test your Web API by clicking the *Copy Token* icon as shown in the following picture:

![Copy access token](https://images.ctfassets.net/23aumh6u8s0i/1FENUfKNw5FrmexhvdWwv5/bb1c283a019dc0fd7322e357efd1bdb2/copy-token.png)

Now, head back to your browser and click the *Authorize* button. A window dialog opens, as shown in the following picture:

![Bearer token in Swagger UI](https://images.ctfassets.net/23aumh6u8s0i/18f9kh3tBXiOMbxjSA7j1k/c0ab1d1475b75ef51a50a1009ea3c5c1/access-token-swagger-ui.png)

Paste the token you copied from the Auth0 Dashboard into the text box and click *Authorize*.

> To learn a bit more about the Swagger UI, check out [this article about ASP.NET Web API authorization](https://auth0.com/blog/aspnet-web-api-authorization/).

Now, try to add a new glossary term through the `POST` action. You should get a negative response from the server similar to this one:

![Forbidden action on an endpoint](https://images.ctfassets.net/23aumh6u8s0i/2jJfEWsECwVKy9qwcy7Nyk/182e158601d78774ee3fd633028badea/forbidden-action-on-endpoint.png)

Notice that, this time, you didn't receive the `401 Unauthorized` HTTP status code. You received the `403 Forbidden` status code. This denotes that you are providing an access token, so you are authorized to access the application, but you don't have the required permissions to perform this specific action.

You can verify your current permissions by visiting [jwt.io](https://jwt.io/) and pasting your access token there. This tool allows you to decode your access token. You will discover that the `permissions` claim shown in the payload section is an empty array, as in the following picture:

![Empty permissions claim in JWT](https://images.ctfassets.net/23aumh6u8s0i/5bMNrF4vS9iYs3hQuxCMe2/d8bffd83f61373f5b9a6e2b0d69691b6/empty-permissions-claim-in-jwt.png)

### Testing access with writing permissions

Let's create an access token with the required permissions for adding a new term.

Back in your API configuration page on the Auth0 Dashboard, select the *Machine to Machine Applications* tab. You'll get a list of applications, some of them with the *(Test Application)* label in the name. These applications are automatically created by Auth0 when you create an API there. They are meant as test clients from your API. One of them should have the *Authorized* switch on. Click the dropdown next to it and check the `create:term` and `update:term` permissions in the section that will be shown:

![Writing permissions assignment](https://images.ctfassets.net/23aumh6u8s0i/1noHOvxBZaRERXAJ9SpPt2/849b32e5f54524cc3e6f3e58eb1f3578/assign-writing-permissions.png)

Then, click the *Update* button, move again to the *Test* tab, and copy the new token that has been generated for you. Now, in the Swagger UI of your Web API, click the *Authorize* button again. This time the following window should appear:

![Changing the access token](https://images.ctfassets.net/23aumh6u8s0i/1WKMrki5ZtwLPvBKmoQ1Gv/b276253e73ed5848f804ac69a37718d3/changing-access-token.png)

Click the *Logout* button and paste the new access token in the text box that appears.

At this point, try again to add a new term to the glossary through the `POST` action. Now you should get a successful response from the server.

If you decode your new access token in [jwt.io](https://jwt.io/), you should see that the `permissions` claim now contains the two permissions you assigned:

![Writing permissions in JWT](https://images.ctfassets.net/23aumh6u8s0i/WVVEcOwuIeuB73aYKu0Q0/e8a722919757b259befd52ddc09dfdf5/writing-permissions-in-jwt.png)

If you attempt to delete the newly created term with the same access token, you get the `403 Forbidden` status code as before. In fact, your access token doesn't contain the deleting permission.

### Testing access with deleting permissions

To be authorized to delete a glossary term, you need to grant the deleting permission to the test application. So, go back to the *Machine to Machine Application* tab of your API configuration on the Auth0 Dashboard and open the permissions section of the test application again. Check also the `delete:term` permission and click the *Update* button. Now, in the *Test* tab, copy the new access token and head back to your browser.

In the Swagger UI of your Web API, replace your current access token with the new one by using the *Authorize* button. Then, delete the glossary term you added earlier by using the `DELETE` action. This time your attempt should be successful!

## Recap

In summary, you learned that permissions give you more granular control over access to your Web API. You discovered how to define permissions associated with your API in Auth0 and how to define and register authorization policies in your ASP.NET application. You saw that checking permissions in your API controller is a matter of adding a parameter to the `Authorize` attribute. You used your test client application on the Auth0 Dashboard to generate access tokens with the required permissions. Finally, you used the Swagger UI to test your Web API with access tokens having different permissions.

You can download the final code of the sample application from [this GitHub repository](https://github.com/auth0-blog/glossary-web-api-aspnet/tree/add-permission).


Permission-Based Security for ASP.NET Web APIs

Learn how to secure an ASP.NET Core Web API by granting access only to authorized users through Auth0 authentication and authorization services.

Having control over who can access your API is a necessary requirement to make your application secure. This article will show you how to restrict access to your ASP.NET Core Web API to authorized users only.

## Setting up the Web API Application

Let's start by setting up the ASP.NET Core Web API application to be protected. You can download a glossary Web API from [this GitHub repository](https://github.com/auth0-blog/glossary-web-api-aspnet/tree/starter) by running the following command in a terminal window:

```bash
git clone --branch starter --single-branch https://github.com/auth0-blog/glossary-web-api-aspnet.git

```

This ASP.NET application provides you with a CRUD Web API to manage a glossary of terms. You can learn the details of its implementation by reading [this article](https://auth0.com/blog/building-aspnet-web-api).

Once you download the application, move to the `glossary-web-api-aspnet` folder and launch it by typing `dotnet run` in a terminal window. By pointing your browser to `https://localhost:5001/swagger`, you should see a page like the following to interactively test the APIs:

![Swagger UI for Web API](https://images.ctfassets.net/23aumh6u8s0i/39X3FZbdleAybhhvH5hCV7/b0276f9319a0a8110fcffc1dd583f602/webapi-swagger-ui.png)

The Web API application allows you to get a list of term definitions or a single term definition. It also lets you create a new definition and modify or delete an existing one.

The current implementation of this glossary Web API allows anyone to perform all the available operations on the glossary. Most probably, you want to allow everyone to get a single glossary item or the full glossary. Still, only authorized users should be enabled to create, update, and delete glossary items.

Let's go and see how to protect these three actions by integrating your ASP.NET Core Web API with [Auth0](https://auth0.com) services.

## Registering the Web API with Auth0

To start securing your API with Auth0, you need an Auth0 account. If you haven't got one, you can <a href="https://a0.to/blog_signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for a free one</a>. Now, you can register your Web API through the [Auth0 Dashboard](https://manage.auth0.com/).  Move to the [API section of the Dashboard](https://manage.auth0.com/#/apis) and follow these steps:

1. Click on *Create API*
2. Provide a friendly name for your API (for example, *Glossary API*) and a unique identifier in the URL format (for example, *https://glossary.com*)
3. Leave the signing algorithm as RS256 and click the *Create* button

These steps make Auth0 aware of your Web API and will allow you to control access.

> **Note**: While you are in the Auth0 Dashboard, take note of your Auth0 domain. You will need it soon. This is a string in the form `YOUR-TENANT-NAME.auth0.com` where `YOUR-TENANT-NAME` is the name you provided when you created your account with Auth0. For more information, [check the documentation](https://auth0.com/docs/getting-started/the-basics#domains).

<details>
  <summary>Using the Auth0 CLI</summary>
As an alternative to the Dashboard, you can use [the Auth0 CLI](https://auth0.com/blog/introducing-auth0-cli/) to register your API with Auth0.


In this case, [install the CLI on your machine](https://github.com/auth0/auth0-cli#installation) and [configure it to access your Auth0 tenant](https://github.com/auth0/auth0-cli#login). Then, run the following command in a terminal window:

```bash
auth0 apis create --name "Glossary API" --identifier https://glossary.com --scopes ""
```

This command creates an entry for your API with the name *Glossary API* and the unique identifier `https://glossary.com`. You are not specifying any [scope](https://auth0.com/docs/scopes) for this application right now.

Running this command has exactly the same effect as registering your API through the Auth0 Dashboard.

After the registration, you will get an output like the following:

```bash
=== <YOUR_AUTH0_DOMAIN> API created

  ID          60ac3b89f0cd4a003d42e850  
  NAME        Glossary API              
  IDENTIFIER  https://glossary.com   
  SCOPES  
```

Take note of the values for the `<YOUR_AUTH0_DOMAIN>` placeholder and the identifier.
</details>

## Enabling Authorization Support

The next step is to adapt the ASP.NET Core Web API application's code to use Auth0 authorization services.

### Configuring the Web API

Back in your ASP.NET application, open the `appsettings.json` configuration file and replace its content with the following:

```json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "Auth0": {
    "Domain": "YOUR_AUTH0_DOMAIN",
    "Audience": "YOUR_UNIQUE_IDENTIFIER"
  }
}
```

Replace the `YOUR_AUTH0_DOMAIN` placeholder with your Auth0 domain and the `YOUR_UNIQUE_IDENTIFIER` placeholder with the value you provided as a unique identifier of your API (`https://glossary.com`, if you kept the value suggested above).

### Integrating with Auth0

In order to interact with the Auth0 authorization services, your application needs to be able to handle tokens in the [JWT](https://jwt.io/) (*JSON Web Token*) format. You can accomplish this by installing the `Microsoft.AspNetCore.Authentication.JwtBearer` library. Move to your application folder and type the following command in a terminal window:

```bash
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
```

When the installation is complete, open the `Startup.cs` file and add the `JwtBearer` namespace. The `using` section of the file should look as shown below:

```c#
//Startup.cs
...existing code... 
using Microsoft.OpenApi.Models;
using Microsoft.AspNetCore.Authentication.JwtBearer; //👈 new code

namespace Glossary
{
  //...existing code...
}
```

In the same file, replace the `ConfigureServices()` method of the `Startup` class with the following code:

```c#
//Startup.cs

// ...existing code...
    public void ConfigureServices(IServiceCollection services)
    {
      //👇 new code
      services.AddAuthentication(options =>
      {
        options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
      }).AddJwtBearer(options =>
      {
        options.Authority = $"https://{Configuration["Auth0:Domain"]}/";
        options.TokenValidationParameters = 
          new Microsoft.IdentityModel.Tokens.TokenValidationParameters
          {
            ValidAudience = Configuration["Auth0:Audience"],
            ValidIssuer = $"{Configuration["Auth0:Domain"]}",
            ValidateLifetime = true,
          };
      });
      //👆 new code

      services.AddControllers();
      services.AddSwaggerGen(c =>
      {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "Glossary", Version = "v1" });
      });
    }
// ...existing code...
```

You added the authentication service by specifying the JWT bearer scheme. You also configured the JWT handler by using the domain and audience values from the `appsettings.json` configuration file. In particular, you built the authority URL based on the Auth0 domain and set the parameters that allow the access token to be validated. Specifically, a token is considered valid if it meets the following criteria:

- it has the expected audience,
- it was issued by the expected domain,
- it is not expired.

Finally, replace the `Configure()` method of the `Startup` class with the following code:

```c#
//Startup.cs

// ...existing code...
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseHttpsRedirection();
    app.UseRouting();
  
    app.UseAuthentication();  //👈 new code
    app.UseAuthorization();
  
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}
// ...existing code...
```

Compared to the previous version, you just added the `app.UseAuthentication()` statement to enable authentication for your application.

<details>
  <summary>Why do you need authentication?</summary>
You may wonder why you need to register the authentication middleware in your ASP.NET Web API. After all, you should only manage authorization. The authentication middleware is needed because it is responsible for creating the security context under which the code is running.


Also, the registration order is important: you need to register the authentication middleware before the authorization middleware.

For more details, check out the [ASP.NET Web API authentication and authorization documentation](https://docs.microsoft.com/en-us/aspnet/web-api/overview/security/authentication-and-authorization-in-aspnet-web-api).
</details>

<include src="Auth0TemplatesForDotnetCTA" />

## Securing the API Endpoints

Almost everything is ready to secure your application. You just need to protect the actions that allow clients to create, update, and delete glossary items. So, open the `GlossaryController.cs` file in the `Controllers` folder and add the `Microsoft.AspNetCore.Authorization` namespace. The `using` section of the file will look like the following:

```c#
//Controllers/GlossaryController.cs
using System;
using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;
using System.IO;
using Microsoft.AspNetCore.Authorization;  //👈 new code

namespace Glossary.Controllers
{
  // ...existing code...
}
```

Now, add the `Authorize` attribute to the `Post()`, `Put()`, and `Delete()` methods. As an example, your `Delete()` method should become like shown below:

```c#
//Controllers/GlossaryController.cs
// ...existing code...
        [HttpDelete]
        [Route("{term}")]
        [Authorize]  //👈 new code
        public ActionResult Delete(string term)
        {
            var glossaryItem = Glossary.Find(item =>
                   item.Term.Equals(term, StringComparison.InvariantCultureIgnoreCase));

            if (glossaryItem == null)
            {
                return NotFound();
            }
            else
            {
                Glossary.Remove(glossaryItem);
                return NoContent();
            }
        }
// ...existing code...
```

As you can see, the only difference is the `Authorize` attribute.

> **Note**: You may be wondering if the order of the attributes applied to a method or to a controller class matters. Their order is internally defined, and it depends on the stage of the HTTP pipeline they are bound to and on their scope (global, class, or method scope). So, from a syntactical point of view, it doesn't matter if you put, for example, the `Authorize` attribute before or after the `Route` one.
> For more information on this point, check the [official documentation](https://docs.microsoft.com/en-us/aspnet/core/mvc/controllers/filters?view=aspnetcore-3.0).

<include src="ebook-ads/dotnetIdentity" />

## Testing the Secure Web API

In order to ensure that all works as expected, run the application, point your browser to [https://localhost:5001/swagger](https://localhost:5001/swagger), and test the GET action on the `api/Glossary` endpoint. You should get the list of term definitions as before.

### Testing unauthorized accesses

Now, try to add a new item to the glossary by using the POST action on the `api/Glossary` endpoint as shown in the following picture:

![Calling HTTP POST on the Glossary Web API](https://images.ctfassets.net/23aumh6u8s0i/2Wj5qH5QGMcZC82KC47HVM/758a0589e4254ff6a013deb48808cba7/post-webapi-swagger-ui.png)

This time you should get a `401 Unauthorized` HTTP status code, as shown below:

![Unauthorized response from the Web API](https://images.ctfassets.net/23aumh6u8s0i/4GB1MoOEZ3VoKRddc5Vwxi/0510cf8164263b15d188fc5ab5751424/unauthorized-response.png)

This means that your endpoint is protected: only authorized users can add a new definition to the list. So, in order to add a new item to the glossary, you need to get an access token from Auth0 and make a request to the API endpoint using the [Bearer Authorization scheme](https://www.rfc-editor.org/rfc/rfc6750.html).

### Testing authorized accesses

However, before going ahead, you need a way to provide your access token to the interactive web API documentation. To achieve this goal, edit the `Startup.cs` file and apply the changes shown in the following code snippet to the `ConfigureServices()` method:

```csharp
//Startup.cs
// ...existing code...
    public void ConfigureServices(IServiceCollection services)
    {

      // ...existing code...
      services.AddControllers();

      services.AddSwaggerGen(c =>
      {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "MyProject", Version = "v1.0.0" });

        //👇 new code
        var securitySchema = new OpenApiSecurityScheme
        {
          Description = "Using the Authorization header with the Bearer scheme.",
          Name = "Authorization",
          In = ParameterLocation.Header,
          Type = SecuritySchemeType.Http,
          Scheme = "bearer",
          Reference = new OpenApiReference
          {
            Type = ReferenceType.SecurityScheme,
            Id = "Bearer"
          }
        };

        c.AddSecurityDefinition("Bearer", securitySchema);

        c.AddSecurityRequirement(new OpenApiSecurityRequirement
          {
              { securitySchema, new[] { "Bearer" } }
          });
        //👆 new code
      });
    }
// ...existing code...
```

You added a few additional configuration options to your API's Swagger instance. In particular, you defined a security schema and added it to the generated documentation as a security requirement.

Now, restart your ASP.NET Core Web API and take a look at the web page shown at the address [https://localhost:5001/swagger](https://localhost:5001/swagger):

![Protected Web APIs in Swagger UI](https://images.ctfassets.net/23aumh6u8s0i/1rNBChKdbCr9fKdpbbYcKR/014f6ace0411febc726959cd88ed8e6a/protected-swagger-ui-webapi.png)

You see the new *Authorize* button and the lock icon on each action. You can configure Swagger to get a more accurate UI, but this topic is out of the scope of this article. Please check out [the official documentation for more details](https://github.com/domaindrivendev/Swashbuckle.AspNetCore#add-security-definitions-and-requirements).

At this point, let's get the access token from Auth0. The simplest way is to access [the API section of your Auth0 Dashboard](https://manage.auth0.com/#/apis) again, select the API that you created before and select the *Test* tab. In this section, you can get a temporary token to test your Web API by clicking the *Copy Token* icon as shown in the following picture:

![Copying temporary token from the Auth0 Dashboard](https://images.ctfassets.net/23aumh6u8s0i/1FENUfKNw5FrmexhvdWwv5/bb1c283a019dc0fd7322e357efd1bdb2/copy-token.png)

Now, head back to your browser and click the *Authorize* button. A window dialog opens, as shown in the following picture:

![Configure access token for Swagger UI](https://images.ctfassets.net/23aumh6u8s0i/18f9kh3tBXiOMbxjSA7j1k/c0ab1d1475b75ef51a50a1009ea3c5c1/access-token-swagger-ui.png)

Paste the token you copied from the Auth0 Dashboard into the text box and click *Authorize*.

With this step, you have configured the interactive documentation to add the Authorization header to each HTTP request. That header's value will be the access token in the form of a bearer token.

If you try to add a new glossary term through the POST action, you should get a successful `201 Created` HTTP status code as before securing the API. The following picture shows an example of such a response:

![A successful response from the protected Web API](https://images.ctfassets.net/23aumh6u8s0i/2iY4mvFFAZGrDcpXKZiFPU/b0f0b3d576e9d0fc19e7fc7574e089a3/success-response-webapi-post.png)

Now your Web API is ready to be securely consumed by clients.

## Recap

This article showed you how to protect your ASP.NET Core Web API to prevent unauthorized users from accessing specific endpoints. You learned how to register your Web API application with Auth0, how to enable your ASP.NET application to support authorization, and how to use the autogenerated interactive documentation to test the endpoints.

You can download the full source code of the application from [GitHub](https://github.com/auth0-blog/glossary-web-api-aspnet/tree/add-authorization).


Authorization for ASP.NET Core Web APIs

f7144da08aeb41a93256f8ae88f507d2?s=64 avatar

f7144da08aeb41a93256f8ae88f507d2?s=64

Guest Author

Ajden Towfeek

This is a guest post by Ajden Towfeek. Ajden is a full-stack developer with focus on Microsoft technologies with 10+ years of experience in commercial software development.



_This is a guest post by Ajden Towfeek. Ajden has worked on everything from embedded devices to large scale enterprise systems during his 10+ years in commercial software development. Since 2007, Ajden has focused on Microsoft technologies and more lately on web technologies. Ajden is also a speaker at conferences and has a passion for teaching. He is a frequent blogger on [http://towfeek.se](http://www.towfeek.se), and you can follow him on twitter [@ajtowf](https://twitter.com/ajtowf). For screencasts on the latest web technology, make sure to check out his [youtube channel](https://www.youtube.com/c/AjdenTowfeek)._

-------------

# Pluralsight Course

I've created a [pluralsight course](http://www.pluralsight.com/courses/authenticating-angular-spa-aspnet-webapi-auth0) on how to implement Auth0 in an AngularJS application going against an ASP.NET WebAPI backend. Using Auth0 is a pluralsight first and so far it's performing well with good rating. Make sure to [check it out](http://www.pluralsight.com/courses/authenticating-angular-spa-aspnet-webapi-auth0) if you have a pluralsight subscription, otherwise I'm hoping the promotional video below can make you get one.  

-------------

<iframe width="640" height="480" src="https://www.youtube.com/embed/gPkhM1GwVYA?rel=0&vq=hd720" frameborder="0" allowfullscreen></iframe>

# Table of contents

The course is split into the following three modules:

* **An Introduction**: Course introduction with brief overview of Auth0, where we also register for a free developer account.
* **Building the Back-end API**: In this module we create the back-end and secure it with Auth0, we also test our API by making secure calls with postman.
* **Building the Front-end SPA**: In this module we create the front-end using AngularJS to communicate securely with our back-end. We use Auth0Lock to get a professional looking login dialog that displays well on any resolution and device.

# Why do a course on Auth0?

First of all, I'm new to using Auth0 as a service, I stumbled upon it when trying to find a quick to implement solution for a client I was working with a couple of months ago. I was amazed by how fast we were up and running and could move on to writing the business logic. Unfortunately, that particular client didn't end up using Auth0 in production for various reasons but I'm currently discussing the possibility of using Auth0 for user management with a new client.    

Aside from consulting I also teach and speak at conferences and to strengthen my brand I decided to try out for becoming a pluralsight author. The [audition](https://youtu.be/QjAfgfTZfho) went well, but angular 2 was off the table since it's still in alpha. When browsing the pluralsight library I noticed there was nothing on Auth0 there, so why not be the first one to contribute with an Auth0 course?

I've also added an Auth0 session to my ASP.NET classroom training after going through ASP.NET Identity to show how identity can be implemented even simpler, and the student reactions to how simple it is to use has been really positive.   

# Working with the Pluralsight team

From the initial contact with the audition to working close with my editor on the course, pluralsight was super professional. I really enjoyed the experience, and I definitely encourage other developers to go through the experience of creating a course. Even if I have some experience from creating [screencasts on youtube](https://www.youtube.com/c/AjdenTowfeek) this was something entirely different.

# Conclusion

After 30 hours of recording and editing the course was finished and it's now live, make sure to [check it out](http://www.pluralsight.com/courses/authenticating-angular-spa-aspnet-webapi-auth0). Auth0 is an awesome service and I'll definitely recommend it to future clients and keep teaching it in my class room training.

<include src="TweetQuote" quoteText="Auth0 is an awesome service and I'll definitely recommend it to future clients."/>


"webapi"