The Refresh JWT in ASP.NET Core

In this article, we will discuss the use of refresh tokens in ASP.NET Core to provide a way for users to remain authenticated even after their initial access token has expired.

What is a Refresh Token?

A refresh token is a token that is used to obtain a new access token. Access tokens have a limited lifespan and once they expire, the user needs to re-authenticate in order to get a new one. A refresh token allows the user to get a new access token without re-entering their credentials.

Implementing Refresh Tokens in ASP.NET Core

To implement refresh tokens in ASP.NET Core, you will need to use the Microsoft.AspNetCore.Authentication.JwtBearer package. This package provides an JwtBearerOptions class that allows you to configure various options for the JWT bearer authentication middleware.

To start, you will need to add the JwtBearer middleware to your pipeline in the Startup.cs file.

public void ConfigureServices(IServiceCollection services)
{
    services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
        .AddJwtBearer(options =>
        {
            options.RequireHttpsMetadata = false;
            options.SaveToken = true;
            options.TokenValidationParameters = new TokenValidationParameters
            {
                ValidateIssuerSigningKey = true,
                IssuerSigningKey = new SymmetricSecurityKey(Encoding.ASCII.GetBytes("secret key")),
                ValidateIssuer = false,
                ValidateAudience = false
            };
        });
    services.AddControllers();
}

In the above example, we are configuring the JWT bearer middleware to not require HTTPS, save the token, and use the provided symmetric key for validation.

Generating a Refresh Token

Once the JWT bearer middleware is set up, you can generate a refresh token when a user successfully logs in. Here is an example of how you might generate a refresh token in a login action:

[HttpPost("login")]
public async Task<IActionResult> Login([FromBody] LoginDto loginDto)
{
    var user = await _userService.Authenticate(loginDto.Username, loginDto.Password);

    if (user == null)
        return BadRequest(new { message = "Username or password is incorrect" });

    var tokenHandler = new JwtSecurityTokenHandler();
    var key = Encoding.ASCII.GetBytes("secret key");
    var tokenDescriptor = new SecurityTokenDescriptor
    {
        Subject = new ClaimsIdentity(new Claim[] 
        {
            new Claim(ClaimTypes.Name, user.Id.ToString())
        }),
        Expires = DateTime.UtcNow.AddDays(7),
        SigningCredentials = new SigningCredentials(new SymmetricSecurityKey(key), SecurityAlgorithms.HmacSha256Signature)
    };
    var token = tokenHandler.CreateToken(tokenDescriptor);
    var refreshToken = _userService.GenerateRefreshToken();
    _userService.SaveRefreshToken(user.Id, refreshToken);

    return Ok(new
    {
        access_token = tokenHandler.WriteToken(token),
        refresh_token = refreshToken
    });
}

In this example, we are calling a GenerateRefreshToken method on the _userService object, which is responsible for generating a new refresh token. We also calling a SaveRefreshToken method on the _userService object, which is responsible for storing the refresh token in a secure manner, associate it with the userId and expiration date.

Using the Refresh Token

Once a user has a refresh token, they can use it to obtain a new access token. Here is an example of how you might implement a refresh token action in a controller:

[HttpPost("refresh")]
public IActionResult Refresh([FromBody] RefreshTokenDto refreshTokenDto)
{
    var userId = _userService.GetUserIdFromRefreshToken(refreshTokenDto.RefreshToken);
    if (userId == null)
        return Unauthorized();

    var tokenHandler = new JwtSecurityTokenHandler();
    var key = Encoding.ASCII.GetBytes("secret key");
    var tokenDescriptor = new SecurityTokenDescriptor
    {
        Subject = new ClaimsIdentity(new Claim[] 
        {
            new Claim(ClaimTypes.Name, userId)
        }),
        Expires = DateTime.UtcNow.AddDays(7),
        SigningCredentials = new SigningCredentials(new SymmetricSecurityKey(key), SecurityAlgorithms.HmacSha256Signature)
    };
    var token = tokenHandler.CreateToken(tokenDescriptor);
    var newRefreshToken = _userService.GenerateRefreshToken();
    _userService.SaveRefreshToken(userId, newRefreshToken);

    return Ok(new
    {
        access_token = tokenHandler.WriteToken(token),
        refresh_token = newRefreshToken
    });
}

In this example, we are calling a GetUserIdFromRefreshToken method on the _userService object which is responsible for checking that the refresh token is valid and belongs to the user, and returns the userId associated with it. If the token is not valid, the method returns null. If the token is valid, the method generates a new access token and refresh token, and returns them in the response.

In this way, you can use refresh tokens to provide a way for users to remain authenticated even after their initial access token has expired.

Note: This is a basic example and in the production environment, you should use a more secure way to store refresh tokens, like using the database or a dedicated token store, and also you should handle the expiration of the refresh tokens and invalidate them after a certain period.

Best Practices

Here are some best practices for dealing with refresh tokens:

1. Use a secure storage: Refresh tokens should be stored in a secure manner, such as in a database or a dedicated token store.

2. Use a unique and cryptographically-random token value: Refresh tokens should be generated using a cryptographically-secure random number generator to ensure that they cannot be guessed.

3. Use short-lived access tokens: Access tokens should have a short lifespan, typically on the order of minutes or hours. This helps to limit the amount of time that an attacker has to use a compromised token.

4. Rotate and revoke tokens: Refresh tokens should be rotated periodically, so that if one is compromised, it can be quickly revoked and a new one issued.

5. Use a secure communication channel: Refresh tokens should be transmitted over a secure communication channel, such as HTTPS, to prevent eavesdropping.

6. Limit the number of refresh tokens per user: Limit the number of refresh tokens that can be issued to a user to prevent an attacker from obtaining too many tokens.

7. Limit the scope of refresh tokens: Limit the scope of refresh tokens to only the necessary permissions.

8. Use token binding: Token binding is a mechanism that associates a token with a particular client and helps to prevent token replay attacks.

9. Logging & Auditing: Keep a log of the refresh token usage and revoke them as soon as you detect any suspicious activity.

10. Handle the expiration of the refresh tokens: Have a mechanism to handle the expiration of the refresh tokens and invalidate them after a certain period.