Introduction to Refresh Tokens

Welcome to the first lesson of our course on securing your REST API application with C# in ASP.NET Core. In this module, we will move beyond basic JWT authentication and focus on implementing, managing, and rotating refresh tokens. This mechanism is the industry standard for balancing high security with a seamless user experience.

In a stateless authentication system, refresh tokens act as long-lived credentials that allow clients to obtain new access tokens without forcing the user to re-enter their password.

To understand their necessity, we must look at the limitations of a standalone access token:

1. Access tokens are short-lived (typically 5–15 minutes) to minimize risk if stolen.
2. Once an access token expires, the user is effectively logged out.
3. Asking the user to log in every 15 minutes creates a terrible user experience.

Refresh tokens solve this by having a lifespan of days or weeks. They are used strictly to negotiate new access tokens. This separation of concerns allows us to keep access tokens short-lived and secure, while maintaining long-running user sessions.

The two token types have different storage strategies on the client and server sides:

• Access tokens are stateless JWTs. They are stored only on the client (typically in memory or local storage) and are never persisted on the server. The server validates them purely by checking their cryptographic signature. This makes them fast to verify but impossible to revoke before they expire.
• Refresh tokens are stored on both sides. The server persists them in a database, which enables validation, revocation, and rotation. The client stores them locally (e.g., in an HTTP-only cookie or secure storage) so it can present them when requesting a new access token.

This dual-storage design is critical: because refresh tokens exist in the server's database, the server can revoke them at any time — something it cannot do with a stateless JWT. This is what gives the refresh token architecture its security advantage.

Implementing this dual-token architecture introduces new dynamics to your application.

Advantages:

• Enhanced Security: Since access tokens expire quickly, the window of opportunity for an attacker using a stolen access token is very small.
• Revocation Capabilities: Unlike JWTs, which cannot be easily revoked before expiry, refresh tokens are stored in a database. You can instantly revoke a user's access by marking their refresh token as revoked.
• Seamless Experience: Users remain authenticated for long periods without repeated login prompts.

Disadvantages:

• Increased Complexity: The client must handle token expiration and perform background refreshes.
• Storage Requirements: Unlike stateless JWTs, refresh tokens require server-side storage and state management.
• Attack Surface: If a refresh token is stolen, an attacker could potentially generate new access tokens until the refresh token expires.

To mitigate the risk of theft, we employ a technique called token rotation.

Refresh token rotation is a security protocol where every time a refresh token is used, it is invalidated and replaced.

1. Single Use: A refresh token is valid for exactly one exchange.
2. The Exchange: When the client requests a new access token, the server issues a new access token AND a new refresh token.
3. Invalidation: The old refresh token is immediately marked as revoked.

Why is this secure? If an attacker manages to steal a refresh token, they race the legitimate user to use it.

• If the attacker uses it first, the legitimate user's next attempt will fail (because the token is revoked), forcing them to log in again. This "sudden logout" alerts the user (and potentially the system) that something is wrong.
• If the user uses it first, the attacker's stolen token becomes useless immediately.

Token Reuse Detection: By keeping revoked tokens in the database (marked with IsRevoked = true) rather than deleting them, the server can detect when someone attempts to reuse an already-rotated token. If a revoked token is presented, the server knows a theft has likely occurred and can take defensive action, such as revoking all tokens for that user. We will implement this detection in our rotation endpoint.

This rotation creates a moving target, significantly limiting the damage a compromised token can cause.

The following diagram illustrates the lifecycle of a token refresh request.

The Process Steps:

1. Request: The client sends the expired access token (optional, depending on implementation) and the valid refreshToken₀ to the /refresh endpoint.
2. Verification: The API checks the database. If the token exists and hasn't been revoked or expired, it proceeds.
3. Rotation (Critical Step): The API marks refreshToken₀ as revoked. It is no longer valid.
4. Issuance: The API generates accessToken₁ and refreshToken₁.
5. Persistence: refreshToken₁ is saved to the database.
6. Response: The client receives the new pair and updates its local storage.

This flow ensures that the database always reflects the single most recent valid token for that session.

To implement this, we first need a model to represent the token in our database. We use Entity Framework Core to define the schema.

namespace YourNamespace.Models;

public sealed class RefreshToken
{
    public Guid Id { get; set; } = Guid.NewGuid();

    // Store as a random opaque string, not a JWT.
    public string Token { get; set; } = string.Empty;

    public int UserId { get; set; }
    public User? User { get; set; }

    public DateTime ExpiresAtUtc { get; set; }

    // Track whether this token has been used or revoked.
    // Keeping revoked tokens (instead of deleting them)
    // enables token reuse detection.
    public bool IsRevoked { get; set; } = false;

    // Helps with auditing, debugging, and cleanup jobs.
    public DateTime CreatedAtUtc { get; set; } = DateTime.UtcNow;
}

We use a separate Guid Id as the primary key, following Entity Framework Core conventions (EF Core automatically treats a property named Id as the primary key). The Token string is stored as a separate unique-indexed column that we query against. This separation keeps the primary key stable and predictable while allowing the token value itself to be any format we choose.

The IsRevoked flag is central to our rotation strategy: instead of deleting used tokens, we mark them as revoked. This lets us detect token reuse — if someone presents a token that is already revoked, we know a theft may have occurred. The CreatedAtUtc field records when the token was issued, which is useful for auditing and for background cleanup jobs that periodically remove old revoked tokens.

Next, we register the model in our AppDbContext. This allows us to perform CRUD operations on the tokens. We use the Fluent API in OnModelCreating to configure indexes and relationships.

using Microsoft.EntityFrameworkCore;
using YourNamespace.Models;

namespace YourNamespace.Data;

public sealed class AppDbContext : DbContext
{
    public AppDbContext(DbContextOptions<AppDbContext> options)
        : base(options) { }

    public DbSet<User> Users => Set<User>();
    public DbSet<RefreshToken> RefreshTokens => Set<RefreshToken>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);

        modelBuilder.Entity<RefreshToken>()
            .HasIndex(x => x.Token)
            .IsUnique();

        modelBuilder.Entity<RefreshToken>()
            .HasOne(x => x.User)
            .WithMany()
            .HasForeignKey(x => x.UserId)
            .OnDelete(DeleteBehavior.Cascade);
    }
}

The unique index on Token ensures fast lookups when a client presents a refresh token, and prevents duplicate token values from being stored.

The OnDelete(DeleteBehavior.Cascade) configuration tells the database to automatically delete all of a user's refresh tokens when that user's row is removed from the Users table. This is triggered by the database engine itself when a DELETE statement hits the parent row. Without it, you would be left with "orphan" tokens — refresh tokens pointing to a UserId that no longer exists. Cascade delete is appropriate here because a refresh token has no meaning without its associated user. In scenarios where you need to preserve historical records (e.g., audit logs), you would choose DeleteBehavior.Restrict or DeleteBehavior.SetNull instead.

We need a dedicated service to handle the creation of token values. This service separates the concern of generating cryptography from the concern of handling HTTP requests and database operations.

First, we define a configuration class to hold our token lifetimes. Centralizing these values makes them easy to find and update.

namespace YourNamespace.Infrastructure.Auth;

public static class TokenOptions
{
    public static readonly TimeSpan AccessTokenLifetime = TimeSpan.FromMinutes(15);
    public static readonly TimeSpan RefreshTokenLifetime = TimeSpan.FromDays(7);
}

Next, we implement the TokenService class. It provides two methods: one to generate a signed JWT access token, and one to generate a cryptographically secure refresh token string.

using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Security.Cryptography;
using System.Text;
using Microsoft.IdentityModel.Tokens;
using YourNamespace.Models;

namespace YourNamespace.Infrastructure.Auth;

public sealed class TokenService
{
    private readonly SymmetricSecurityKey _key;

    public TokenService(string jwtSecretKey)
    {
        _key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(jwtSecretKey));
    }

    // Generates a stateless JWT (Access Token) from a User entity
    public string GenerateAccessToken(User user)
    {
        var claims = new List<Claim>
        {
            new(ClaimTypes.NameIdentifier, user.Id.ToString()),
            new(ClaimTypes.Name, user.Username),
            new(ClaimTypes.Role, user.Role),
            new(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString())
        };

        var creds = new SigningCredentials(_key, SecurityAlgorithms.HmacSha256);

        var token = new JwtSecurityToken(
            claims: claims,
            expires: DateTime.UtcNow.Add(TokenOptions.AccessTokenLifetime),
            signingCredentials: creds);

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

    // Generates a 256-bit random, URL-safe opaque string
    public static string GenerateRefreshToken()
    {
        var bytes = RandomNumberGenerator.GetBytes(32);
        return Base64UrlEncoder.Encode(bytes);
    }
}

Notice that GenerateAccessToken is an instance method because it requires the signing key (stored in _key). In contrast, GenerateRefreshToken is static because it does not depend on any instance state — it simply produces a random string. This distinction keeps the API honest about what each method needs to function.

GenerateRefreshToken produces a cryptographically secure, opaque token in two steps. First, RandomNumberGenerator.GetBytes(32) fills a 32-byte array with random data from the operating system's cryptographic RNG. This is important — System.Random is not suitable for security purposes because its output is predictable. The 32 bytes give us 256 bits of entropy, which makes brute-forcing the token computationally infeasible. Second, Base64UrlEncoder.Encode converts those bytes to a URL-safe string with no padding characters, making it safe to transmit in HTTP headers or query parameters without additional escaping.

The resulting token is opaque: unlike a JWT, it carries no claims or user data of its own. Its only job is to serve as a random lookup key into the RefreshTokens database table, where the server can find the associated user and expiration.

The GenerateAccessToken method accepts a User entity directly, which allows it to embed the user's identity, name, and role as claims in the JWT. This ensures the access token carries enough information for the server to authorize requests without additional database lookups.

To make the service functional, we must register it and the database context in our application container in Program.cs. We use SQLite as our database and register TokenService as a singleton — since it only holds a signing key and has no mutable state, a single instance is safe to share across all requests.

// Program.cs
const string JwtSecretKey = "0123456789abcdef0123456789abcdef";

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlite("Data Source=pastebin.db"));

builder.Services.AddSingleton(new TokenService(JwtSecretKey));

Note: In the examples for this course, we hardcode the JWT secret directly in Program.cs for simplicity. In a production application, you should store secrets in environment variables, Azure Key Vault, or the ASP.NET Core Secret Manager — never in source code.

We also need a simple DTO record for the response that our endpoints will return:

public record AuthTokensResponse(string AccessToken, string RefreshToken);

Now that our infrastructure is in place, we can build the logic that clients will interact with.

Before implementing endpoints, we define a reusable helper function that orchestrates the full process of issuing a new token pair. This function is called during both login and token refresh, ensuring consistent behavior throughout the application.

The function performs several operations in sequence: look up the user, generate both tokens, revoke any existing tokens for that user, persist the new token, and return the pair.

static async Task<AuthTokensResponse> CreateAuthTokensAsync(
    int userId,
    AppDbContext db,
    TokenService tokens,
    CancellationToken ct)
{
    // 1. Find the user (needed for JWT claims)
    var user = await db.Users.FindAsync([userId], ct);
    if (user is null)
    {
        throw new InvalidOperationException("User not found");
    }

    // 2. Generate tokens
    var accessToken = tokens.GenerateAccessToken(user);
    var refreshToken = TokenService.GenerateRefreshToken();
    var expiresAtUtc = DateTime.UtcNow.Add(TokenOptions.RefreshTokenLifetime);

    // 3. Revoke any existing refresh tokens for this user
    var existing = await db.RefreshTokens
        .Where(rt => rt.UserId == userId)
        .ToListAsync(ct);

    foreach (var token in existing)
    {
        token.IsRevoked = true;
    }

    // 4. Store the new refresh token
    db.RefreshTokens.Add(new RefreshToken
    {
        Token = refreshToken,
        UserId = userId,
        ExpiresAtUtc = expiresAtUtc
    });

    await db.SaveChangesAsync(ct);
    return new AuthTokensResponse(accessToken, refreshToken);
}

By marking all existing tokens as revoked before adding a new one (step 3), we enforce a strict policy where a user is only allowed one valid session at a time. This is a design choice; some applications allow multiple concurrent sessions (e.g., one on mobile, one on desktop), but for this course, we prioritize strict security control.

This helper function is defined as a static local function in Program.cs, which is idiomatic for Minimal API applications. It keeps the token-creation logic in one place rather than duplicating it across every endpoint that needs to issue tokens.

Using Minimal APIs, we define the /api/auth/refresh endpoint directly in Program.cs. This endpoint validates the incoming refresh token, checks for reuse attacks, performs rotation, and issues a new token pair.

app.MapPost("/api/auth/refresh", async (
    RefreshRequest request,
    AppDbContext db,
    TokenService tokens,
    CancellationToken ct) =>
{
    // 1. Basic Validation
    var incoming = request.RefreshToken ?? string.Empty;
    if (string.IsNullOrWhiteSpace(incoming))
    {
        return Results.BadRequest(new { error = "Missing refresh token" });
    }

    // 2. Database Lookup
    var stored = await db.RefreshTokens
        .FirstOrDefaultAsync(rt => rt.Token == incoming, ct);

    if (stored is null)
    {
        return Results.Unauthorized();
    }

    // 3. Token Reuse Detection (CRITICAL)
    // If someone presents a token that is already revoked,
    // a theft has likely occurred. Revoke ALL tokens for this user.
    if (stored.IsRevoked)
    {
        var userTokens = db.RefreshTokens
            .Where(rt => rt.UserId == stored.UserId);

        foreach (var token in userTokens)
        {
            token.IsRevoked = true;
        }

        await db.SaveChangesAsync(ct);
        return Results.Unauthorized();
    }

    // 4. Expiration Check
    if (stored.ExpiresAtUtc <= DateTime.UtcNow)
    {
        stored.IsRevoked = true;
        await db.SaveChangesAsync(ct);
        return Results.Unauthorized();
    }

    // 5. Token Rotation — mark old token as revoked
    var userId = stored.UserId;
    stored.IsRevoked = true;
    await db.SaveChangesAsync(ct);

    // 6. Issue new token pair
    var auth = await CreateAuthTokensAsync(userId, db, tokens, ct);
    return Results.Json(auth);
});

record RefreshRequest(string? RefreshToken);

This endpoint implements two critical security mechanisms:

• Token Rotation (Step 5): The old token is marked as revoked (IsRevoked = true) before the new one is issued. If the process fails halfway, the user loses their session — this is a "fail-safe" design. It is better to accidentally log a user out than to leave a compromised token active.
• Token Reuse Detection (Step 3): Because we keep revoked tokens in the database instead of deleting them, we can detect when a previously-used token is presented again. This is a strong signal that the token was stolen — either the attacker or the legitimate user is replaying an old token. In response, we revoke all tokens for that user, forcing everyone (including the attacker) to re-authenticate.

Notice that the endpoint delegates token creation to CreateAuthTokensAsync (step 6), keeping the endpoint focused on validation and rotation logic.

When a client successfully calls this endpoint, they will receive a JSON payload containing the new credentials:

{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "dGhpcyBpcyBhIHJhbmRvbSB0b2tlbiBzdHJpbmc"
}

The client must now discard their old tokens and replace them with these new values for all subsequent requests.

In this lesson, we established the foundation for a robust authentication system using refresh token rotation. You learned how to model the token in C#, configure the database context, and implement the logic to swap an old token for a new one securely.

The key takeaways are:

• Refresh tokens live in the database (with IsRevoked and CreatedAtUtc tracking), while access tokens are stateless JWTs.
• Rotation marks the old token as revoked immediately upon use, rather than deleting it.
• Token reuse detection leverages revoked tokens to identify potential theft and revoke all sessions for the affected user.
• The CreateAuthTokensAsync helper encapsulates token generation and database operations for consistent use across login, registration, and refresh flows.

In the upcoming practice exercises, you will write the code to integrate this service into a functional API and handle edge cases where token rotation fails. Prepare to get your hands dirty with Entity Framework Core and JWT logic!