Role-Based Authorization for ASP.NET Web APIs

Role-Based Access Control, also known as RBAC, is one of the most common strategies to restrict access to protected resources within an organization. It simplifies permission assignment by categorizing users in roles. However, many people making their first foray into RBAC have questions:

• How can you reflect this user categorization on your application to check users' privileges?
• How can you deal with roles in your code?
• Is role control appropriate for Web APIs?

In this article, you will learn the best way to implement RBAC in your ASP.NET Core Web API by using Auth0's capabilities.

What is RBAC?

Consider a payroll system in a company. Different people accessing this system have different rights to view and change data. Each employee can view their own data, while HR people can view all employees' data. Also, while an employee can just view their own data, HR people can change them. Roles may also not be assigned just by department. For example, the HR department may have just a few people who should have the ability to add new employees to the payroll system, with the remainder only having permission to update employees.

Assigning specific permissions individually to each employee can be challenging and lead to mistakes. To expand on the payroll system example, consider that we have at least 4 types of permissions. Each of these must be assigned with perfect accuracy to each employee in your company. With just a handful of employees and a few HR events a month, this would quickly spiral into a time-consuming and error-prone activity. This doesn't even consider needing to reassign permissions for a large group of people due to a security policy change.

Role-Based Access Control helps with the permission assignment by introducing the concept of role. A role is a collection of permissions. Basically, you build a predefined set of permissions, give it a name, such as Employee, HR Assistant, HR Manager, and assign that role to a user. If you need to add or remove a permission from all the users who have a specific role, you just need to add or remove that permission from the role they are assigned. That's a great improvement!

Want to take your Authorization to the next level? → fga.dev

Setting up the Sample Application

In order to best show how to use roles in an ASP.NET Web API application integrated with Auth0, you will build on a sample application. I've provided a starting point that you can download by running the following command in a terminal window:

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

Make sure you have the latest .NET SDK already installed on your machine to run the sample ASP.NET application.

The Web API implements a CRUD interface for a glossary of terms. It has some basic endpoints that allow you to create a definition, read a list of term definitions or a single one, and update or delete them. To learn more about the details of building and securing this application, check out this blog post.

Once you download the application on your machine, register it with Auth0 in order to enable support for authorization. If you don't yet have an Auth0 account, you can sign up for a free one. Follow the instructions in this article to register the application with Auth0.

After you have completed the registration, move to the glossary-rbac-web-api-aspnet folder and open the appsettings.json configuration file. Its content should look like this:

// appsettings.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).

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.

To test that everything works as expected, launch the ASP.NET Web API application by typing dotnet run in a terminal window. Now point your browser to https://localhost:5001/swagger, and you should see the Swagger UI shown below to test the API interactively:

To call the POST, PUT, and DELETE actions, you need an access token, as explained in this section. The related endpoints already require an access token, but they don't perform any check on the permissions granted to the users. This means that any user authorized to access the protected endpoints can do anything: create a new term, modify an existing term, and delete them.

In the following sections, you will implement RBAC to allow just specific users to perform specific actions.

Defining Permissions for Your API

As a first step to enable a more granular control on the access to your Web API, you have to define the permissions needed for your application. In the case of the glossary Web API application, define the permissions using 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 the API, go to the API section 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:

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

Next, move to the Settings tab and scroll down to the RBAC Settings section. Here, click the Enable RBAC and the Add Permissions in the Access Token toggle buttons, as in the following picture, and then click the Save button at the bottom:

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

Auth0 and RBAC

Auth0 lets you organize your RBAC easily through its Dashboard. If you have more complex or specific needs, you can also manage users and roles by using the Auth0 Management API. In this article, you will use the Dashboard to manage users and roles.

Your goal is to create roles so that only specific users can perform specific actions. In practice, you have to create:

• an Editor role, which includes the permission to create (create:term) and update (update:term) a glossary term,
• an Admin role, which includes the permission to delete (delete:term) a glossary term in addition to being able to create and modify it.

Creating roles

With this goal in mind, head to the Auth0 Dashboard and select Roles under the User Management section of the side menu. Click the Create Role button in the upper right corner and fill the form with the following data:

• glossary-admin as the name.
• Glossary administrator as the description.

Now click the Create button. In the screen you get, select the Permissions tab and associate the required permissions to define this role by clicking the Add Permissions button. You need to select the API you registered with Auth0 (Glossary, if you kept the suggested name) and select all its permissions, as shown in the following image:

Finally, click the Add Permissions button. You have just created the glossary-admin role as a collection of create:term, update:term, and delete:term permissions

Now, repeat the same process to create the Editor role with the following data:

• glossary-editor as the name.
• Glossary editor as the description.

This time, you will add only the create:term and update:term permissions to this role, as shown below:

Remember to click the Add Permissions button to finalize the creation of the glossary-editor role.

Creating users with roles

Ultimately, roles are meaningless without users. Now, you'll create two users and assign them the roles you've made to test the application.

The first user will have john@example.com as their email and username and will be assigned the glossary-editor role.

The second user will have jane@example.com as their email and username and will be assigned the glossary-admin role.

Open the Users section in your Auth0 Dashboard and click the Create User button. Then, fill the form with the required data for the first user:john@example.com as the email, a password of your choice, and Username-Password-Authentication as the connection. The following is an example of a filled form:

Click the Create button to create the user.

Now, on the user's page, select the Roles tab and click the Assign Roles button. In the popup window, select the glossary-editor role from the drop-down list and click the Assign button. The window should look as follows:

Repeat the same steps described so far to create the user jane@example.com and assign them the glossary-admin role.

Checking Permissions in Your API

At this point, you've configured your API and created users with their respective roles on Auth0. Now it's time to enable your app to have more granular control over the HTTP requests it receives.

Recall that roles are collections of permissions. When you enabled RBAC for your API in the Auth0 Dashboard, you ensured that tokens issued by Auth0 for the API will include permissions within the access token. As a result, when clients use that same token for HTTP requests, the API can parse the token's permissions.

To correctly authorize the incoming HTTP requests, your API needs to make sure the access token has the necessary permissions. You can accomplish this task by defining one or more authorization policies and applying them to 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:

// 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("CreateAccess", policy => 
                          policy.RequireClaim("permissions", "create:term"));
        options.AddPolicy("UpdateAccess", policy => 
                          policy.RequireClaim("permissions", "update:term"));
        options.AddPolicy("DeleteAccess", policy => 
                          policy.RequireClaim("permissions", "delete:term"));
      });
      //👆 new code
    }
    
    // ...existing code...
  }
}

Here, you've invoked the AddAuthorization() method to configure the ASP.NET authorization service. You've also defined three authorization policies via the AddPolicy() method of the options parameter. Each policy has a name and a lambda expression. For example, the CreateAccess authorization policy is defined by requiring the permissions claim in the access token whose value must be create:term. Similarly, for the UpdateAccess and the DeleteAccess policies.

Different approaches to creating authorization policies in ASP.NET exist. For example, you can use a claim-based authorization or a policy-based authorization approach. You can even create your own approach by customizing the built-in ASP.NET authorization middleware.

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 pointed out in the following:

// Controllers/GlossaryController.cs

// ...existing code...

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

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

    [HttpPut]
    [Authorize(Policy = "UpdateAccess")]    //👈 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 that the ASP.NET authorization middleware evaluates a specific policy to authorize the execution of the related controller's method.

Your Web API is ready to run and check permissions!

Testing the Web API

To test your glossary Web API, you need a client that allows your users to authenticate with Auth0 and get an access token with the proper permissions based on their role. Fortunately, the Swagger UI of the sample Web API is built to be very much an actual client of your API. You just need to enable OAuth support so that the user can authenticate and get their access token.

Configuring the client

To configure your Swagger UI, you need to register it with Auth0. Head to the Application section of your Auth0 Dashboard and click the Create Application button in the upper right corner. In the window that appears, provide a meaningful name, e.g., Glossary client, and select Regular Web Applications as the application type. That window should look like the following:

Now, click the Create button to confirm. After the client page is created, move to the Settings tab and take note of the Client ID and the Client Secret values.

Now, back in your project, open the appsettings.json configuration file and apply the changes highlighted below:

// appsettings.json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "Auth0": {
    "Domain": "YOUR_AUTH0_DOMAIN",
    "Audience": "YOUR_UNIQUE_IDENTIFIER",
    // 👇 new keys
    "ClientId": "YOUR_CLIENT_ID",
    "ClientSecret": "YOUR_CLIENT_SECRET"
    // 👆 new keys
  },
  "SwaggerUISecurityMode": "oauth2"        // 👈 new key
}

You added the ClientId and ClientSecret keys within the Auth0 section. Replace the YOUR_CLIENT_ID and YOUR_CLIENT_SECRET placeholders with the corresponding values you just annotated from the Auth0 Dashboard. The Domain and Audience keys keep the values you already assigned at the beginning of this article.

Also, you added the SwaggerUISecurityMode key with the oauth2 value. This key enables the Swagger UI to act as an OAuth client so that it asks Auth0 for an access token on behalf of a user. You will see how it works in a moment.

Keep in mind that the SwaggerUISecurityMode key is a custom key supported by this sample project. It is only required for demo purposes in order to test your API with the Swagger UI. In a real-world scenario, your API will be called by a real client.

Now, launch the Web API by typing dotnet run in a terminal window and point your browser to https://localhost:5001/swagger.

I suggest using your browser in incognito mode to switch between users easily. In fact, an unresolved issue in Swagger UI prevents you from logging out from the authorization server. See these issues for more information.

Testing access with the Editor role

In the Swagger UI of your Web API, click the Authorize button. You should see a window like the following:

This window asks to authorize the Swagger UI client to obtain an access token on behalf of the user. By clicking the Authorize button here, you will be redirected to the Auth0 Universal Login page. On that page, authenticate as a user having the Editor role by providing the credentials of john@example.com, as you created them before. After you authenticate, you will be redirected back to the following screen:

Your Swagger UI client has now received the access token for that user. Click the Close button and try to add a new term to the glossary through the POST action. In the Swagger UI, click the POST /api/Glossary row and then the Try it out button. Now, add a new term definition as in the following example:

By clicking the Execute button, you should get a successful response similar to the following:

If you copy the access token from the curl statement text box and decode it in jwt.io, you should see a payload similar to the following:

You can see the permissions claim containing the create:term and update:term permissions. These permissions are assigned to the current user thanks to their Editor role. Also, the create:term permission is the one required by the CreateAccess policy that controls the access to the Post() method in your API controller. So, everything works as expected.

If you try to modify a glossary term through the PUT action, you should get a successful response as well.

Testing the API with the Administrator Role

However, if you attempt to delete the newly created term, you should receive a 403 Forbidden status code. In fact, your access token doesn't contain the delete:term permission. Only users with the Admin role are allowed to delete terms.

So, clear the cookies in your browser (or close it and reopen it in incognito mode).

Click the Authorize button again and this time authenticate as the jane@example.com user. That user has the Admin role. Now, try to execute all the three protected actions: POST, PUT, and DELETE. You should be able to perform them successfully.

Roles and APIs

Applying RBAC to Web APIs shown above leverages the Auth0's ability to extract permissions from user roles at login time and add them to the permissions access token's claim. As the API developer, this approach lets you focus just on permissions and leave the role management to Auth0.

As an ASP.NET developer, you may know that you could use the Roles parameter with the Authorize attribute, as shown in the following example:

[HttpPost]
[Authorize(Roles = "glossary-editor, glossary-admin")]
public ActionResult Post(GlossaryItem glossaryItem)
{
  // ... existing code ...
}

So, you might ask yourself a couple of questions at this point:

• Is it possible to include user roles in the access token issued by Auth0?
• Why not check roles instead of permissions on the Web API side?

Let's try to answer both questions.

Including roles in the access token

Auth0 allows you to add user roles in the access token issued at login time. However, this is not a built-in feature, i.e., something that you got without any explicit intervention. To enrich the access token with the user's roles, you need to add an Auth0 Action to the login flow. An Action is a JavaScript function that allows you to customize the standard behavior of different Auth0 flows. Check out this blog post to get an overview of Auth0 Actions.

Showing how to use Auth0 Actions to add user roles in the access token is out of the scope of this article. However, you can take a look at this Action example to get an idea of how it works.

Checking permissions or roles?

One of the reasons you may want to check roles instead of permissions on the Web API side could be that they are easy to read and understand quickly. They lead to a direct mapping between user roles and your API. They are easy to read and understand. Looking at the following code, you know at a glance who is allowed to do a given action:

[HttpDelete]
[Route("{term}")]
[Authorize(Roles = "glossary-admin")]
public ActionResult Delete(string term)
{
  // ... existing code ...
}

It is immediately obvious that only the glossary administrator can delete a glossary term. Having the permission instead of the role requires you to think about who the users having the delete:term permission may be. It implies you have an extra layer of mapping between roles and permissions in mind.

However, there are some drawbacks in checking roles on the Web API side in return for this benefit.

Imagine you implemented your glossary Web API with role checking instead of permission checking. After your Web API is published, you need a new role for your glossary application: the Assistant role. Say you name this role glossary-assistant. Users in this role can only update existing terms, and so they will only have the update:term permission.

To enable this role on your Web API, you now need to change its code in the controller. You need to add the glossary-assistant role to the list of the allowed roles of the Put() method. Not complicated... But now, you need to redeploy your API with the new code!

If you check permissions instead of roles, you don't need any updates on the Web API side. The role management and the permission unpacking is an Auth0 responsibility.

Once again: roles are just collections of permissions. While, in general, permissions are quite static, roles are more dynamic. The need to group permissions for new roles or combine multiple roles for the same user makes permission checking more convenient and lower-maintenance.

Think of the simple glossary Web API. It relies on only three permissions. However, it can lead to the creation of seven roles (eight, if we also consider the empty role). This should make you think about the opportunity to deal with roles on the Web API side.

Finally, consider that Auth0 allows you to directly assign permissions to a user. In that case, if you only check roles, you miss any directly assigned permissions causing a security flaw in your Web API.

Summary

Throughout this article, you learned how to use Auth0 Role-Based Access Control in your ASP.NET Web API.

You started by defining and assigning roles to your users. Then, you registered a glossary Web API with Auth0 and enabled RBAC support. Next, you implemented an authorization policy in your Web API to check user permissions.

Finally, you learned why checking permissions on the API side is better than directly checking roles.

You can find the final version of the glossary Web API implemented throughout the article in this GitHub repository.