ASP.NET Core JWT Authentication and Authorization of Web API [Detailed]

What is JWT in .NET Core – JWT which stands for “JSON Web Tokens” is an open standard method for securely transmitting information between parties as a JSON object (commonly known as ‘Token’). The token is digitally signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA. Since the token is signed with a public/private key pairs, the signature certifies that only the party holding the private key is the one that signed it. So in this way authentication is done by JWT mechanism.

In the below image I have shown a JWT Token which looks like xxxxx.yyyyy.zzzzz.

A JWT Web Token consists of 3 parts separated with 2 dots. These parts are:

1. Header – the part of the token before the first dot is header. The Header consists of two parts, the first part contains the type of the token which is JWT. The second part contains the signing algorithm being used, such as HMAC SHA256 or RSA.
2. Payload – the part between the first and the second dot is Payload. It contains claims (which are statements about the data/user), these are iss (issuer), exp (expiration time), sub (subject), aud, etc. Claims are divided into public, private and registered types.
3. Signature – the part after the 2nd dot is Signature. The signature is created by taking the encoded header, the encoded payload, a secret, the algorithm specified in the header, and then signing them. This will create the Signature. The signature is used to verify that the message is not changed along the path and the token is signed with a private key. Signature can also verify the identity of the sender.

How do I know if my JWT Token is expired in .NET Core?

Copy the token and paste it on the token box given at https://jwt.io/. This will decode your JWT token and show the header, payload and signature in JSON. On the “payload” json, copy the value of “exp” key. This is the expiry time of the token expressed in Unix time. Now use C# function DateTimeOffset.FromUnixTimeSeconds("unix time") to convert the unix time to an understandable date and time value. I have shown this in the below image:

How is JWT implemented in .NET Core

The implementation is as follows.

1. Client authenticates itself with Username and Password to the Server.
2. On successful authentication, the Server creates JWT token and sends it to the client.
3. Client signs the Token with Private key, and sends it to the server in HTTP Authorization Header whenever it makes a request to secured resources.
4. Server receives a request, validates the JWT token, and sends secured data to the client.

Web API with JWT Authentication

There are 2 steps to use jwt authentication with web api. Step 1: Add configurations on the Startup class to use JWT authentication. Step 2: Add the [Authorize] attribute on the Web API controller. This will secure it with JWT authentication.

Let us create a JWT example to create Web API Security feature. This ensures that clients must send JWT token in the HTTP Authorization Header in order to access data from the API.

Firstly create the API Project called JWTAPI whose steps are outlined below.

Step #1: Create a New ASP.NET Core 5.0 API project in Visual Studio 2019

In your Visual Studio 19, create a new ASP.NET Core Web Application and name it ‘JWTAPI’.

Next, select ASP.NET Core 5.0 framework from the dropdown, and then select the Model-View-Controller template as shown by the below image.

Finally click the create button to create this project.

Step #2: Install JwtBearer package from Nuget and configure Startup.cs

You need to install the package called Microsoft.AspNetCore.Authentication.JwtBearer from NuGet. This package adds the middleware that enables an ASP.NET Core application to receive a Bearer Token in the Request Pipeline.

Next, configure JWT authentication in the project. To do this, register a JWT authentication schema by using AddAuthentication() method in the ConfigureServices() method of Startup.cs file. The code which you have to add is given below:

public void ConfigureServices(IServiceCollection services)
{
    services.AddCors();
    services.AddControllers();
    services.AddAuthentication(options =>
    {
        options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        options.DefaultScheme = JwtBearerDefaults.AuthenticationScheme;
    })
    .AddJwtBearer(options =>
    {
        options.SaveToken = true;
        options.RequireHttpsMetadata = false;
        options.TokenValidationParameters = new Microsoft.IdentityModel.Tokens.TokenValidationParameters()
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidAudience = "https://www.yogihosting.com",
            ValidIssuer = "https://www.yogihosting.com",
            ClockSkew = TimeSpan.Zero,// It forces tokens to expire exactly at token expiration time instead of 5 minutes later
            IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("MynameisJamesBond007"))
        };
    });
}

Explanation: The ‘AuthenticationOption’ has 3 properties:

• DefaultAuthenticateScheme
• DefaultChallengeScheme
• DefaultScheme

These 3 are set to the default value JwtBearerDefaults.AuthenticationScheme.

Next, I used the AddJwtBearer() method to configure the JwtBearerOptions as shown below. Also note I set the JWT SymmetricSecurityKey which is “MynameisJamesBond007”.

.AddJwtBearer(options =>
{
    options.SaveToken = true;
    options.RequireHttpsMetadata = false;
    options.TokenValidationParameters = new Microsoft.IdentityModel.Tokens.TokenValidationParameters()
    {
        ValidateIssuer = true,
        ValidateAudience = true,
        ValidAudience = "https://www.yogihosting.com",
        ValidIssuer = "https://www.yogihosting.com",
        ClockSkew = TimeSpan.Zero,// It forces tokens to expire exactly at token expiration time instead of 5 minutes later
        IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("MynameisJamesBond007"))
    };
});

I used the TokenValidationParameters property to specify how the token will be validated on the server. For this I set true for the Issuer and Audience.

The most important property here is the IssuerSigningKey that is used to set the security key with SymmetricSecurityKey class. The security key is the Private key. Through this key the token is signed by the client. The server validate the token which it get’s in the client request header. If the private key is in-correct then the token is faulty and so the request to the resource is not processed.

ValidAudience and ValidIssuer can have any values.

I am using ‘MynameisJamesBond007’ as my security key, you can use any key you want (min 16 characters in length).

Next, go to the Configure() method and tell your app to use authentication and authorization. You add the below 2 lines of code after the app.UseRouting().

app.UseAuthentication();
app.UseAuthorization();

Step #3: JWT Authentication and Authorization

Now I will create the API method to return data to the client in JSON. This data will be a list of ‘Flight Reservation’. The Web API will also have JWT Authentication added to it. So create a new class called Reservation.cs preferably inside the ‘Models’ folder, and add to it the code given below:

public class Reservation
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string StartLocation { get; set; }
    public string EndLocation { get; set; }
}

Next, create a new controller called ReservationController.cs. This controller will have the task to return reservations to the client whenever request to the API is made.

The full code of this controller is given below:

[Route("[controller]")]
[ApiController]
[Authorize]
public class ReservationController : ControllerBase
{
    [HttpGet]
    public IEnumerable<Reservation> Get() => CreateDummyReservations();

    public List<Reservation> CreateDummyReservations()
    {
        List<Reservation> rList = new List<Reservation> {
            new Reservation { Id=1, Name = "Ankit", StartLocation = "New York", EndLocation="Beijing" },
            new Reservation { Id=2, Name = "Bobby", StartLocation = "New Jersey", EndLocation="Boston" },
            new Reservation { Id=3, Name = "Jacky", StartLocation = "London", EndLocation="Paris" }
            };
        return rList;
    }
}

Explanation : I have marked this controller with [Authorize] attribute of the Microsoft.AspNetCore.Authorization namespace. This is done specifically in order to secure the API with JWT Authentication. This means if the token is missing or faulty then web api methods will not be initiated. While for proper tokens the Web API will be authorized to the request.

I have created some dummy reservations inside the CreateDummyReservations () function and these are returned by the API in JSON. The HttpGet method of the API does this work of returning these reservations in JSON.

[HttpGet]
public IEnumerable<Reservation> Get() => CreateDummyReservations();

You have successfully secured your API with JWT. Now request from the clients will be authenticated beforehand and only then the Web API will provide them with the reservation data. In technical terms – the Web API will authenticate the request from the clients and if these requests contain a correct JWT token then only the Web API will authorize the request to view the reservations.

Let us perform some testing. Comment out the [Authorize] attribute on the ‘ReservationController’ by applying ‘//’ before it. Next, run your application on visual studio. When the browser starts, open the URL of the ‘ReservationController’ which in my case is:

https://localhost:44360/Reservation

You will see the JSON containing the reservations as shown below:

Now remove the ‘//’ before the [Authorize] attribute (i.e. un-comment it) and refresh the same URL. This time you will see Http Error 401 which tells – you are unauthorized to access the reservation controller. Congratulations, JWT is implemented successfully on your JWTAPI project.

We have done the JWT Configuration on our project. Let’s now create the login feature.

Step #4: Install package – ‘IdentityModel.Tokens.Jwt’ from NuGet

We need to nstall the package called IdentityModel.Tokens.Jwt. This package is used to Create, Serialize and Validate JWT Tokens. Check the screenshot from NuGet:

Step #5: Create JWT Token and store it in a Cookie

We are ready to create JWT Token but we also need a place to store this token. Normally websites store the token in a database or in a cookie. Here we will store the token in a JWT Cookie. This cookie is just a normal cookie which will be storing the JWT Token. Whenever we need to call the web api, we will read this cookie to get the JWT Token and add this token on the authorization header of the request.

Now you are ready to make API Calls. So create a new controller called CallAPIController.cs.

We will also need to install Newtonsoft.json package which will convert the json returned by the web api to List<Reservation>. You can install it by running the command on the Package Manager Console window – Install-Package Newtonsoft.Json.

Import the following namespaces to the controller.

using JWTAPI.Models;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.IdentityModel.Tokens;
using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.IdentityModel.Tokens.Jwt;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Security.Claims;
using System.Text;
using System.Threading.Tasks;

Now add Index action methods which will validate for the username and password. Recall the JWT Token is created only when the user is successfully validated on the login screen. So when user is successfully logged in, a JWT Token is created and stored in a JWT Cookie. The code of this action method is given below:

public IActionResult Index(string message)
{
    ViewBag.Message = message;
    return View();
}

[HttpPost]
public IActionResult Index(string username, string password)
{
    if ((username != "secret") || (password != "secret"))
        return View((object)"Login Failed");

    var accessToken = GenerateJSONWebToken();
    SetJWTCookie(accessToken);

    return RedirectToAction("FlightReservation");
}

Explanation: To successfully login we need to enter “secret” for both username and password. You can replace this code with something that checks the username and password of the user from the database. Next See the lines 13 and 14. On line 13 a function is called which will create a new JWT Token. On line 14 I am calling another function which will set this JWT Token on a cookie. So add these 2 functions on the controller.

private string GenerateJSONWebToken()
{
    var securityKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("MynameisJamesBond007"));
    var credentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);

    var token = new JwtSecurityToken(
        issuer: "https://www.yogihosting.com",
        audience: "https://www.yogihosting.com",
        expires: DateTime.Now.AddHours(3),
        signingCredentials: credentials
        );

    return new JwtSecurityTokenHandler().WriteToken(token);
}

private void SetJWTCookie(string token)
{
    var cookieOptions = new CookieOptions
    {
        HttpOnly = true,
        Expires = DateTime.UtcNow.AddHours(3),
    };
    Response.Cookies.Append("jwtCookie", token, cookieOptions);
}

The GenerateJSONWebToken() function creates a JWT Token by assigned with the values of issuer, audience, expires and signingCredentials.

How to set JWT Token expiration time in .NET Core

We use JwtSecurityToken class “expires” property to set the expiry time of the JWT Token. Example: to set the expirty time of the token to be 3 hours after it is created, the C#.NET code for this will be expires: DateTime.Now.AddHours(3). I have shown this in highlighted way in the below code:

var securityKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(key));
var credentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);

var token = new JwtSecurityToken(
    issuer: "https://www.yogihosting.com",
    audience: "https://www.yogihosting.com",
    expires: DateTime.Now.AddHours(3),
    signingCredentials: credentials
    );

We can also use DateTime.Now.AddMinutes to set expiry time minutes or DateTime.Now.AddSeconds to set the time in seconds.

The JWT Token is returned by the GenerateJSONWebToken() function and the variable accessToken stores it. The function SetJWTCookie() creates a cookie by the name of “jwtCookie” and stores the JWT Token on it.

Notice the JWT token expires after 3 hours and the cookie also expires in 3 hours. We will talk about the expiry time in just a moment.

Next, I will adds the JWT Token to the HTTP authorization header.

Step #6: Call the Web API with JWT token added to HTTP authorization header

Add a new action method called “FlightReservation”. Here we will make the call to the Web API with JWT Token added to the HTTP authorization header. This action method code is given below.

public async Task<IActionResult> FlightReservation()
{
    var jwt = Request.Cookies["jwtCookie"];

    List<Reservation> reservationList = new List<Reservation>();

    using (var httpClient = new HttpClient())
    {
        httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", jwt);
        using (var response = await httpClient.GetAsync("https://localhost:44360/Reservation")) // change API URL to yours 
        {
            if (response.StatusCode == System.Net.HttpStatusCode.OK)
            {
                string apiResponse = await response.Content.ReadAsStringAsync();
                reservationList = JsonConvert.DeserializeObject<List<Reservation>>(apiResponse);
            }

            if (response.StatusCode == System.Net.HttpStatusCode.Unauthorized)
            {
                return RedirectToAction("Index", new { message = "Please Login again" });
            }
        }
    }

    return View(reservationList);
}

I first read the jwtCookie value which contains the JWT token.

var jwt = Request.Cookies["jwtCookie"];

Next, with HttpClient class, I am calling the Web API. Notice I am adding the JWT Token to the authorization header with the below code line.

httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", tokenString);

And finally make the call to the Web API at the URL – https://localhost:44360/Reservation by the below code.

using (var httpClient = new HttpClient())
{
    httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", jwt);
    using (var response = await httpClient.GetAsync("https://localhost:44360/Reservation")) // change API URL to yours 
    {
        if (response.StatusCode == System.Net.HttpStatusCode.OK)
        {
            string apiResponse = await response.Content.ReadAsStringAsync();
            reservationList = JsonConvert.DeserializeObject<List<Reservation>>(apiResponse);
        }

        if (response.StatusCode == System.Net.HttpStatusCode.Unauthorized)
        {
            return RedirectToAction("Index", new { message = "Please Login again" });
        }
    }
}

The API response can be of 2 types:

1. HttpStatusCode.OK – when the JWT token is validated successfully. Here we get the json containing all the reservations.
2. HttpStatusCode.Unauthorized – when the JWT token is validated “un-successfully”. This happens when JWT token has expired.

So for HttpStatusCode.OK case, I serialized the response to List<Reservation> which is send to the view to be displayed on a table. For the HttpStatusCode.Unauthorized case, the user is redirected to the login page with a message “Please Login again” on the route. This message will be displayed on the view.

Step #7: Create Login View

Create Index view inside the Views/CallAPI folder. This view will ask the user to enter his/her username and password.

@{ ViewBag.Title = "Login";}

@model string
<h2>Login</h2>

@if (Model != null)
{
    <div class="alert-danger">Login Failed</div>
}

@if (ViewBag.Message != null)
{
    <div class="alert-danger">@ViewBag.Message</div>
}

<form method="post">
    <table class="w-25 table table-striped table-bordered">
        <tbody>
            <tr>
                <td>Username</td>
                <td><input type="text" name="username" /></td>
            </tr>
            <tr>
                <td>Password</td>
                <td><input type="text" name="password" /></td>
            </tr>
            <tr>
                <td colspan="2">
                    <button>Submit</button>
                </td>
            </tr>
        </tbody>
    </table>
</form>

Next, add FlightReservation view inside the same Views/CallAPI folder. In this view we will be displaying the reservations which we get from the web api. It’s code is given below:

@model IEnumerable<Reservation>
@{ ViewBag.Title = "All Reservations";}

<h2>All Reservations</h2>
<table class="table table-sm table-striped table-bordered m-2">
    <thead><tr><th>ID</th><th>Name</th><th>Start Location</th><th>End Location</th></tr></thead>
    <tbody>
        @if (Model != null)
        {
            foreach (var r in Model)
            {
                <tr>
                    <td>@r.Id</td>
                    <td>@r.Name</td>
                    <td>@r.StartLocation</td>
                    <td>@r.EndLocation</td>
                </tr>
            }
        }
    </tbody>
</table>

Perfect, now it’s now time to test it.

Coming to the testing part, run your app in visual studio. Now open the url https://localhost:44361/CallAPI which will open the Login view. Enter “secret” for both username and password.

Click the Submit button, you will be redirected to FlightReservation action which will make the API call and show all the flight reservations. Check the below image:

Recall we set the JWT Token expiry time as 3 hours and also the cookie expiry time was set as 3 hours. So we can access the Secured Web API for 3 continuous hours without any need to login again. You can refresh the url – https://localhost:44360/CallAPI/FlightReservation by pressing f5 key for 3 hours and you will keep on seeing the reservations.

Now wait for 3 hours and refresh the page again. This time the JWT token has expired and so is the cookie, and now you will be redirected to the login page. The login page will also show you the message saying “Please Login again”. Check the below image where I have marked this message.

If you Don’t want to wait for 3 hours then change it to 1 minute for both jwt token and cookie and then test to see you being redirected to the login page.

expires: DateTime.Now.AddMinutes(1) // for jwt token
Expires = DateTime.UtcNow.AddMinutes(1) // for jwt cookie

The full JWT integration is completed and is working successfully. I hope you enjoyed reading this tutorial.

You can download the full codes of this tutorial from the below link:

Download

JWT Claims

JWT Claims are pieces of information added to the token. For example, a JWT token may contain a claim called “Roles” that asserts the Role of the user currently logged in.

First create a Users.cs class to the “Models” folder. This class will contain the Username, Password and Roles for the users that can be loggod in to the application.

public class Users
{
    public string Username { get; set; }
    public string Password { get; set; }
    public string Role { get; set; }
}

Now we will modify things we created before to include JWT Claims. First we will change the “CallAPIController” code to include JWT claims. So change the Index action method login code to as shown in highlighted code:

[HttpPost]
public IActionResult Index(string username, string password)
{
    Users loginUser = CreateDummyUsers().Where(a => a.Username == username && a.Password == password).FirstOrDefault();
    if (loginUser == null)
        return View((object)"Login Failed");

    var claims = new[] {
        new Claim(ClaimTypes.Role, loginUser.Role)
    };

    var accessToken = GenerateJSONWebToken(claims);
    SetJWTCookie(accessToken);

    return RedirectToAction("FlightReservation");
}

The changes include checking user’s credentials from a dummy repository which is called by CreateDummyUsers() method. If we find the user in the repository then we add “Role” claim.

var claims = new[] {
        new Claim(ClaimTypes.Role, loginUser.Role)
    };

The “Role” claim is passed to the function which creates the JWT token.

var accessToken = GenerateJSONWebToken(claims);

We now change the GenerateJSONWebToken() method code to add the claims to the JWT Token. See the change shown in highlighted color:

private string GenerateJSONWebToken(Claim[] claims)
{
    var securityKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("MynameisJamesBond007"));
    var credentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);

    var token = new JwtSecurityToken(
        issuer: "https://www.yogihosting.com",
        audience: "https://www.yogihosting.com",
        expires: DateTime.Now.AddHours(3),
        signingCredentials: credentials,
        claims: claims
        );

    return new JwtSecurityTokenHandler().WriteToken(token);
}

We also need to add CreateDummyUsers() method which holds 3 dummy users along with their roles.

public List<Users> CreateDummyUsers()
{
    List<Users> userList = new List<Users> {
        new Users { Username = "jack", Password = "jack", Role = "Admin" },
        new Users { Username = "donald", Password = "donald", Role = "Manager" },
        new Users { Username = "thomas", Password = "thomas", Role = "Developer" }
    };
    return userList;
}

Notice user jack has Admin role, donald has Manager role while thomas has Developer role.

JWT Authorization of Roles

We want our API to be accessed only by a specific role. We want the user to have “Manager” role, only then he can access the secured Web API. This process is know an Authorization of Roles through Claims.

We already have added the feature where the logged in users get their roles added to “Roles” claim on the token. Next we change the authorization attribute on web api to [Authorize(Roles = "Manager")] which specifies that only Manager roles claims can access the Web API. So make this change which is shown in the highlighted code given below.

[Route("[controller]")]
[ApiController]
[Authorize(Roles = "Manager")]
public class ReservationController : ControllerBase
{
    [HttpGet]
    public IEnumerable<Reservation> Get() => CreateDummyReservations();

    public List<Reservation> CreateDummyReservations()
    {
        ...
    }
}

With this change the Web API is only accessible by user “donald” since he has “Manager” role. In the below video I have shown the login by user “jack” which does not receives any reservation data from the api as he is not in the Manager role. While when I logged in with “donald”, I receive reservations from the api.

GET JWT Claims

The HttpContext.User.Claims provides all the claims added to the JWT Token. We can use it to create conditions on web api to dynamically return data based on the claims. Suppose we added a claim called “Name” to the JWT Token during the time of it’s creation.

var claims = new[] {
        new Claim("Name", person)
    };

Next, we want to filter the records that have the Name property value same as the value of the “Name” claim. This can be done as shown below:

[HttpGet]
public IEnumerable<Reservation> Get()
{
    var claims = HttpContext.User.Claims;
    return CreateDummyReservations().Where(t => t.Name == claims.FirstOrDefault(c => c.Type == "Name").Value);
}

JWT is a great way to secure your API without having to spend much time in integration process. I tried to show how easy the whole procedure is. I hope you like this tutorial so please share it on your reddit, facebook, twitter and other social accounts.