Test Authorization in ASP.NET Core Web APIs With the `user-jwts` Tool

Original post written by Andrea Chiarelli for Auth0 Blog.

How to use the new user-jwts tool to test a protected ASP.NET Core Web API without involving an authorization server.

Testing a protected Web API is not an easy task. At the very least, you need to configure an authorization server, such as your Auth0 tenant, configure your app, and get specific access tokens for your authorization scenarios. This implies several back and forths between your development environment and the Auth0 dashboard (or any other authorization server backend), which may be time-consuming, error-prone, and require an Internet connection, of course. The user-jwts tool, included with the .NET CLI version 7.0, simplifies this Web API testing approach.

Meet the user-jwts Tool

The user-jwts tool allows you to generate tokens customized for your needs and test your ASP.NET Core Web API without the need for a real authorization server. It's a CLI tool integrated with the .NET CLI starting from version 7.0 of the .NET SDK, so make sure you have this version installed on your machine.

The tool simplifies the interactive testing process of your protected API. Its general syntax is as follows:

dotnet user-jwts [options] [command]

You can pass commands to the tool to specify how to manage your JWT tokens and options to work with projects or solutions. In the following sections, you will learn the main commands you may need for testing your ASP.NET Core Web API. For a complete reference to the commands and options available, check out the official documentation.

Set Up Your Project

You will learn how to use the user-jwts tool with a practical approach by testing a ready-to-use ASP.NET Core Web API. Download it by running the following command in a terminal window:

git clone https://github.com/auth0-blog/glossary-aspnet-core-webapi

You will find the project in the glossary-aspnet-core-webapi folder. Go to that folder and run the application with the following command:

dotnet run

Then, point your browser to the https://localhost:5001/swagger URL. You should get the following page:

The Web API provides a few endpoints that allow you to manage a glossary of terms. This is a slightly modified application coming from this article about using permissions with ASP.NET Core Web APIs.

You can perform the typical CRUD (Create, Retrieve, Update, Delete) operations on a list of term definitions. The endpoints are protected, and each operation requires an access token with different permissions:

• The GET method on the /api/Glossary and the /api/Glossary/{term} endpoints requires an access token, but it doesn't care about specific permissions.
• The POST and PUT methods on the /api/Glossary endpoint require an access token with create:term and update:term permissions.
• The DELETE method on the /api/Glossary/{term} endpoint requires an access token with delete:term permission.

The ASP.NET Core Web API application provides a Web UI for interacting with it, but in this article, we will use curl to make HTTP requests just to be consistent with the CLI nature of the user-jwts tool. Feel free to use the tool you prefer to make your HTTP requests.

If you try to call these endpoints without an access token, you will get an "unauthorized" response message. For example, assume you call the /api/Glossary endpoint as follows:

curl -i https://localhost:5001/api/glossary

You will get the following error message as a response:

HTTP/1.1 401 Unauthorized
Content-Length: 0
Date: Mon, 05 Dec 2022 09:28:37 GMT
Server: Kestrel
WWW-Authenticate: Bearer

This message tells you that you are not authorized to call that endpoint, and you must pass a bearer token as a credential (WWW-Authenticate: Bearer).

You can read this article to learn more about the different HTTP response messages you can receive from a protected web API.

Read more...