C# / .NET Kompendium PLEN
.NET / C# / Bezpieczeństwo

Refresh token: jak działa i kiedy go używać

Problem, który rozwiązuje

Access token (zwykle JWT) jest samowystarczalny: API sprawdza jego podpis i nie pyta nikogo o zdanie, więc nie da się go łatwo unieważnić. Dlatego powinien żyć krótko (5-15 minut). Krótki token ogranicza szkody po kradzieży, ale użytkownik nie chce się logować co kilka minut. Rozwiązaniem jest drugi token: refresh token. Szerszy kontekst (JWT, OAuth 2.0, OIDC) jest w temacie Zabezpieczanie WebAPI.

Czym jest refresh token

  • Długo żyjący (dni lub tygodnie) sekret, którego jedynym zadaniem jest uzyskanie nowego access tokenu bez ponownego podawania hasła.
  • Zwykle nieprzezroczysty (opaque): losowy ciąg, a nie JWT. Nic w nim nie ma, a serwer zna jego znaczenie z bazy.
  • Wysyłany wyłącznie do endpointu tokenów (serwera autoryzacji), nigdy do API z zasobami. Dzięki temu rzadko jest narażony na przechwycenie.
  • W OAuth 2.0 uzyskuje się go przez scope offline_access (w OIDC) i wymienia przez grant_type=refresh_token.
Access token Refresh token
Do czego dostęp do API zdobycie nowego access tokenu
Czas życia krótki (minuty) długi (dni, tygodnie)
Dokąd wysyłany do każdego API z zasobami tylko do serwera tokenów
Format zwykle JWT (samowystarczalny) zwykle losowy, nieprzezroczysty
Unieważnianie trudne (czeka do wygaśnięcia) łatwe (serwer trzyma jego stan)
Ryzyko kradzieży ograniczone czasem większe, więc wymaga ochrony i rotacji

Przepływ krok po kroku

1. Klient --- login + hasło ----------------------------> Serwer tokenów
   Klient <-- access token (60 s) + refresh token (7 dni) --

2. Klient --- access token -----------------------------> API  --> 200 OK

3. (po 60 s) Klient --- access token ------------------> API  --> 401 (wygasł)

4. Klient --- refresh token ----------------------------> Serwer tokenów
   Klient <-- NOWY access token + NOWY refresh token ----   (stary refresh token przestaje działać)

5. Klient --- nowy access token ------------------------> API  --> 200 OK

Zapytanie OAuth 2.0 o odświeżenie wygląda tak:

POST /token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<token>&client_id=my-spa

Rotacja i wykrywanie ponownego użycia (najważniejszy mechanizm bezpieczeństwa)

Samo długie życie refresh tokenu to ryzyko: kto go ukradnie, może wiecznie generować nowe access tokeny. Dlatego stosuje się rotację:

  1. Każdy refresh token jest jednorazowy. Po użyciu serwer wydaje nowy i unieważnia stary.
  2. Tokeny jednego logowania tworzą rodzinę (family), czyli łańcuch kolejnych rotacji.
  3. Jeśli użyty już refresh token wróci do serwera (reuse detection), to znaczy, że ktoś go skopiował: legalny użytkownik i złodziej mają ten sam token. Serwer unieważnia całą rodzinę, co wymusza ponowne logowanie i wyrzuca złodzieja.

To zalecenie z OAuth 2.0 Security Best Current Practice dla klientów publicznych (SPA, aplikacje mobilne).

Gdzie i jak przechowywać

Po stronie klienta:

  • SPA: najlepiej w ciasteczku HttpOnly; Secure; SameSite ustawianym przez własny backend (wzorzec BFF), tak aby skrypt JavaScript nie miał do niego dostępu. localStorage jest podatny na kradzież przez XSS.
  • Aplikacja mobilna: w bezpiecznym magazynie systemu (iOS Keychain, Android Keystore).
  • Aplikacja serwerowa lub desktopowa: zaszyfrowany magazyn (DPAPI, Key Vault).

Po stronie serwera:

  • Zapisuj tylko skrót tokenu (SHA-256 wystarczy, bo token jest losowy i długi, w przeciwieństwie do haseł, które wymagają wolnego hasha z solą), a nie sam token.
  • Przechowuj: identyfikator użytkownika, rodzinę, termin ważności, flagi „użyty” i „unieważniony”, a w razie potrzeby urządzenie lub adres IP.
  • Unikalny indeks na skrócie i operacja rotacji w jednej transakcji, żeby dwa równoległe żądania nie użyły tego samego tokenu.
  • Termin ważności: bezwzględny (np. 30 dni od logowania) lub przesuwany (sliding), często oba naraz.
  • Wylogowanie to unieważnienie rodziny. Możesz też pozwalać „wyloguj ze wszystkich urządzeń”.

Kiedy używać

  • Tak: SPA i aplikacje mobilne, gdzie użytkownik ma pozostać zalogowany przez dni (access token krótki, sesja długa).
  • Tak: gdy potrzebujesz możliwości odwołania dostępu użytkownika bez czekania na wygaśnięcie JWT.
  • Nie potrzeba: komunikacja serwis-serwis (OAuth 2.0 Client Credentials) - klient po prostu pobiera nowy access token, używając swojego sekretu lub certyfikatu.
  • Nie potrzeba: krótkie sesje, po których ponowne logowanie nie przeszkadza, oraz sesje cookie w klasycznym MVC.
  • Nie próbuj pisać tego sam, jeśli masz dostawcę tożsamości: Entra ID, Keycloak, Auth0 i Duende IdentityServer mają rotację i reuse detection. W ASP.NET Core 8 MapIdentityApi wystawia też endpoint /refresh.

Działający przykład - RefreshTokenDemo

Minimalne API (.NET 8, pakiet Microsoft.AspNetCore.Authentication.JwtBearer): logowanie wydaje access token ważny 60 sekund oraz refresh token, /refresh robi rotację, a ponowne użycie starego tokenu unieważnia całą rodzinę.

using System.Security.Cryptography;
using System.Text;

public enum RotateStatus { Ok, Invalid, ReuseDetected }

public class RefreshTokenRecord
{
    public string Hash { get; init; } = string.Empty;      // only the HASH is stored, never the token itself
    public string UserId { get; init; } = string.Empty;
    public string FamilyId { get; init; } = string.Empty;  // all tokens of one login (one chain of rotations)
    public DateTime ExpiresAt { get; init; }
    public bool Used { get; set; }
    public bool Revoked { get; set; }
}

// In-memory store for the demo. In production: a database table with a unique index on Hash,
// and Rotate() as one transaction (so two parallel requests cannot both use the same token).
public class RefreshTokenStore
{
    private static readonly TimeSpan Lifetime = TimeSpan.FromDays(7); // absolute lifetime of one token
    private readonly Dictionary<string, RefreshTokenRecord> _tokens = new();
    private readonly object _lock = new();

    public string Create(string userId, string familyId)
    {
        // opaque, random, high-entropy value (NOT a JWT)
        var raw = Convert.ToBase64String(RandomNumberGenerator.GetBytes(64))
            .Replace('+', '-').Replace('/', '_').TrimEnd('=');

        var record = new RefreshTokenRecord
        {
            Hash = Hash(raw),
            UserId = userId,
            FamilyId = familyId,
            ExpiresAt = DateTime.UtcNow.Add(Lifetime)
        };

        lock (_lock) _tokens[record.Hash] = record;
        return raw;
    }

    // Rotation: a refresh token can be used ONCE; the answer contains a brand new refresh token.
    public (RotateStatus Status, string? UserId, string? NewToken) Rotate(string raw)
    {
        lock (_lock)
        {
            if (!_tokens.TryGetValue(Hash(raw), out var record)
                || record.Revoked
                || record.ExpiresAt < DateTime.UtcNow)
                return (RotateStatus.Invalid, null, null);

            if (record.Used)
            {
                // An already used token came back: either the client is buggy or the token was STOLEN
                // (the thief and the owner both hold it). Safest reaction: kill the whole family.
                RevokeFamily(record.FamilyId);
                return (RotateStatus.ReuseDetected, null, null);
            }

            record.Used = true;
            var next = Create(record.UserId, record.FamilyId); // same family, new token
            return (RotateStatus.Ok, record.UserId, next);
        }
    }

    // Logout: revoke the whole chain, so no refresh token of this login works any more.
    public void Revoke(string raw)
    {
        lock (_lock)
        {
            if (_tokens.TryGetValue(Hash(raw), out var record)) RevokeFamily(record.FamilyId);
        }
    }

    private void RevokeFamily(string familyId)
    {
        foreach (var t in _tokens.Values.Where(t => t.FamilyId == familyId)) t.Revoked = true;
    }

    // SHA-256 is enough here: the token is random and long, so it cannot be guessed or brute-forced
    // (unlike passwords, which need a slow hash with a salt).
    private static string Hash(string raw) => Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(raw)));
}
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;

var builder = WebApplication.CreateBuilder(args);

// DEMO ONLY: in production tokens come from an identity provider and the key is not stored in code.
const string Issuer = "https://demo.local";
const string Audience = "demo-api";
var signingKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("demo-key-change-me-at-least-32-bytes-long!!"));
var accessLifetime = TimeSpan.FromSeconds(60); // SHORT on purpose, so you can watch it expire

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(o =>
    {
        o.MapInboundClaims = false;
        o.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true, ValidIssuer = Issuer,
            ValidateAudience = true, ValidAudience = Audience,
            ValidateLifetime = true,
            ClockSkew = TimeSpan.Zero, // no tolerance, so expiry is visible exactly after 60 s
            ValidateIssuerSigningKey = true, IssuerSigningKey = signingKey,
            ValidAlgorithms = new[] { SecurityAlgorithms.HmacSha256 }
        };
    });
builder.Services.AddAuthorization();
builder.Services.AddSingleton<RefreshTokenStore>();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();

string CreateAccessToken(string userId)
{
    var token = new JwtSecurityToken(Issuer, Audience,
        claims: new[] { new Claim("sub", userId) },
        expires: DateTime.UtcNow.Add(accessLifetime),
        signingCredentials: new SigningCredentials(signingKey, SecurityAlgorithms.HmacSha256));
    return new JwtSecurityTokenHandler().WriteToken(token);
}

var users = new Dictionary<string, string> { ["alice"] = "alice123", ["bob"] = "bob123" };

// 1) Login: the user proves who they are ONCE and gets a pair of tokens.
app.MapPost("/login", (LoginRequest request, RefreshTokenStore store) =>
{
    if (!users.TryGetValue(request.Username, out var password) || password != request.Password)
        return Results.Unauthorized();

    var refresh = store.Create(request.Username, familyId: Guid.NewGuid().ToString("N"));
    return Results.Ok(new TokenResponse(CreateAccessToken(request.Username), (int)accessLifetime.TotalSeconds, refresh));
});

// 2) Refresh: exchange a refresh token for a NEW pair (no password needed, the old refresh token dies).
app.MapPost("/refresh", (RefreshRequest request, RefreshTokenStore store) =>
{
    var (status, userId, newRefresh) = store.Rotate(request.RefreshToken);
    return status switch
    {
        RotateStatus.Ok => Results.Ok(new TokenResponse(CreateAccessToken(userId!), (int)accessLifetime.TotalSeconds, newRefresh!)),
        RotateStatus.ReuseDetected => Results.Json(
            new { error = "refresh token reuse detected - the whole session was revoked, log in again" },
            statusCode: StatusCodes.Status401Unauthorized),
        _ => Results.Unauthorized()
    };
});

// 3) Logout: the refresh token chain is revoked (the access token still lives until it expires).
app.MapPost("/logout", (RefreshRequest request, RefreshTokenStore store) =>
{
    store.Revoke(request.RefreshToken);
    return Results.NoContent();
});

// A protected resource: only the ACCESS token is sent here, never the refresh token.
app.MapGet("/api/me", (ClaimsPrincipal user) => new
{
    user = user.FindFirstValue("sub"),
    accessTokenExpiresAtUtc = DateTimeOffset.FromUnixTimeSeconds(long.Parse(user.FindFirstValue("exp")!))
}).RequireAuthorization();

app.Run();

record LoginRequest(string Username, string Password);
record RefreshRequest(string RefreshToken);
record TokenResponse(string AccessToken, int ExpiresIn, string RefreshToken);

Projekt (RefreshTokenDemo.csproj):

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="8.0.10" />
  </ItemGroup>

</Project>

Jak to wypróbować

dotnet run (adres http://localhost:5002), potem plik requests.http lub curl:

# 1) log in: access token (60 s) + refresh token
curl -X POST http://localhost:5002/login -H "Content-Type: application/json" \
     -d '{"username":"alice","password":"alice123"}'

# 2) call the API with the access token -> 200 (after 60 s -> 401)
curl http://localhost:5002/api/me -H "Authorization: Bearer <accessToken>"

# 3) refresh: new pair of tokens, the old refresh token dies
curl -X POST http://localhost:5002/refresh -H "Content-Type: application/json" \
     -d '{"refreshToken":"<refreshToken>"}'

# 4) reuse the OLD refresh token -> 401 "reuse detected", and now even the newest one is dead
curl -i -X POST http://localhost:5002/refresh -H "Content-Type: application/json" \
     -d '{"refreshToken":"<old refreshToken>"}'

Co ten przykład pokazuje

  • Krótki access token (ClockSkew = Zero, 60 s), więc wygaśnięcie widać gołym okiem.
  • Refresh token to losowy ciąg, a w magazynie jest tylko jego skrót SHA-256.
  • Rotacja: po /refresh stary token jest oznaczony jako użyty, a odpowiedź zawiera nowy.
  • Reuse detection: ponowne użycie starego tokenu unieważnia całą rodzinę (RevokeFamily).
  • Atomowość: Rotate działa pod blokadą. W bazie to musi być jedna transakcja z unikalnym indeksem.
  • Wylogowanie unieważnia łańcuch tokenów, ale access token żyje do wygaśnięcia (dlatego ma być krótki).

Wariant z bazą danych (EF Core) - RefreshTokenDbDemo

W produkcji magazyn refresh tokenów to tabela w bazie, nie Dictionary. Pełny projekt (SQLite, port 5003, ten sam scenariusz w requests.http) jest w examples/RefreshTokenDbDemo. Poniżej najważniejsze fragmenty.

Co się zmienia względem wersji w pamięci:

  • Przy generowaniu tokenu nie sprawdzasz, czy już istnieje. Token ma 512 bitów entropii, więc kolizja jest praktycznie niemożliwa. Ręczne „sprawdź i wstaw” i tak byłoby wyścigiem, więc zamiast tego: unikalny indeks na TokenHash i ponowienie losowania, gdy baza odrzuci zapis.
  • Przy odświeżaniu szukasz tokenu po skrócie. Nie ma wpisu, jest wygasły lub unieważniony: 401. Jest już użyty: unieważnij rodzinę i 401. Jest ważny: oznacz jako użyty i wydaj nowy.
  • Oznaczenie jako użyty musi być atomowe. Zwykłe „odczytaj, sprawdź flagę, zapisz” ma ten sam wyścig co Dictionary bez lock. Rozwiązanie: jedno warunkowe UPDATE (ExecuteUpdateAsync), które zmienia UsedAt tylko wtedy, gdy token wciąż jest nieużyty, i zwraca liczbę zmienionych wierszy. Dokładnie jedno z równoległych żądań dostanie 1, reszta 0. Działa też przy wielu instancjach aplikacji, czego lock w pamięci nie zapewni.
  • Raw token nigdy nie trafia do bazy ani do logów, tylko jego skrót.
using Microsoft.EntityFrameworkCore;

public class RefreshToken
{
    public Guid Id { get; set; }
    public string TokenHash { get; set; } = string.Empty;  // only the HASH is stored (unique index)
    public string UserId { get; set; } = string.Empty;
    public Guid FamilyId { get; set; }                     // all tokens of one login (index)
    public DateTime ExpiresAt { get; set; }
    public DateTime? UsedAt { get; set; }                  // set exactly once, atomically
    public DateTime? RevokedAt { get; set; }
}

public class AppDb(DbContextOptions<AppDb> options) : DbContext(options)
{
    public DbSet<RefreshToken> RefreshTokens => Set<RefreshToken>();

    protected override void OnModelCreating(ModelBuilder b)
    {
        b.Entity<RefreshToken>().HasIndex(t => t.TokenHash).IsUnique(); // guards against collisions and speeds up lookups
        b.Entity<RefreshToken>().HasIndex(t => t.FamilyId);             // revoking a whole family filters by it
    }
}
using System.Security.Cryptography;
using System.Text;
using Microsoft.EntityFrameworkCore;

public enum RotateStatus { Ok, Invalid, ReuseDetected }

// Database-backed refresh token store. It works with several app instances because the database,
// not an in-process lock, decides which request "wins" (a conditional UPDATE is atomic).
public class DbRefreshTokenStore(AppDb db)
{
    private static readonly TimeSpan Lifetime = TimeSpan.FromDays(7);

    // Creates and stores a new token. No "does it exist already?" check: the token has 512 bits of entropy,
    // and the unique index would reject a (practically impossible) duplicate, so we just retry.
    public async Task<string> CreateAsync(string userId, Guid familyId, CancellationToken ct = default)
    {
        for (var attempt = 0; attempt < 3; attempt++)
        {
            var raw = GenerateRaw();
            db.RefreshTokens.Add(new RefreshToken
            {
                Id = Guid.NewGuid(),
                TokenHash = Hash(raw),
                UserId = userId,
                FamilyId = familyId,
                ExpiresAt = DateTime.UtcNow.Add(Lifetime)
            });
            try
            {
                await db.SaveChangesAsync(ct);
                return raw;
            }
            catch (DbUpdateException) when (attempt < 2)
            {
                db.ChangeTracker.Clear(); // unique index violation: forget the entity and draw a new token
            }
        }
        throw new InvalidOperationException("Could not generate a unique refresh token.");
    }

    public async Task<(RotateStatus Status, string? UserId, string? NewToken)> RotateAsync(string raw, CancellationToken ct = default)
    {
        var hash = Hash(raw);
        var now = DateTime.UtcNow;
        await using var tx = await db.Database.BeginTransactionAsync(ct);

        // Atomic "claim": the condition and the change are ONE statement, so when two requests bring
        // the same token, exactly one gets 1 affected row and the other gets 0.
        var claimed = await db.RefreshTokens
            .Where(t => t.TokenHash == hash && t.UsedAt == null && t.RevokedAt == null && t.ExpiresAt > now)
            .ExecuteUpdateAsync(s => s.SetProperty(t => t.UsedAt, now), ct);

        if (claimed == 0)
        {
            var existing = await db.RefreshTokens.AsNoTracking().FirstOrDefaultAsync(t => t.TokenHash == hash, ct);
            if (existing is { UsedAt: not null, RevokedAt: null })
            {
                // An already used token came back: possible theft, so kill the whole family.
                await RevokeFamilyAsync(existing.FamilyId, ct);
                await tx.CommitAsync(ct);
                return (RotateStatus.ReuseDetected, null, null);
            }
            return (RotateStatus.Invalid, null, null); // unknown, expired or already revoked
        }

        var current = await db.RefreshTokens.AsNoTracking().FirstAsync(t => t.TokenHash == hash, ct);
        var next = await CreateAsync(current.UserId, current.FamilyId, ct); // same family, new token
        await tx.CommitAsync(ct);
        return (RotateStatus.Ok, current.UserId, next);
    }

    // Logout: revoke the whole chain.
    public async Task RevokeAsync(string raw, CancellationToken ct = default)
    {
        var hash = Hash(raw);
        var familyId = await db.RefreshTokens.Where(t => t.TokenHash == hash)
            .Select(t => (Guid?)t.FamilyId).FirstOrDefaultAsync(ct);
        if (familyId is not null) await RevokeFamilyAsync(familyId.Value, ct);
    }

    private Task<int> RevokeFamilyAsync(Guid familyId, CancellationToken ct)
    {
        var now = DateTime.UtcNow;
        return db.RefreshTokens
            .Where(t => t.FamilyId == familyId && t.RevokedAt == null)
            .ExecuteUpdateAsync(s => s.SetProperty(t => t.RevokedAt, now), ct);
    }

    private static string GenerateRaw() =>
        Convert.ToBase64String(RandomNumberGenerator.GetBytes(64)).Replace('+', '-').Replace('/', '_').TrimEnd('=');

    // SHA-256 is enough: the token is random and long (unlike a password, it cannot be brute-forced).
    private static string Hash(string raw) => Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(raw)));
}

Co jeszcze potrzeba w produkcji

  • Zadanie sprzątające usuwające wygasłe tokeny (użyte trzymaj do wygaśnięcia, bo dzięki nim wykrywasz ponowne użycie).
  • Migracje zamiast EnsureCreated() i prawdziwa baza (PostgreSQL, SQL Server). Do przykładu wybrano SQLite, bo provider InMemory nie obsługuje ExecuteUpdate.
  • Indeks na FamilyId (jest w przykładzie), bo unieważnianie rodziny filtruje po nim.

Gotowe rozwiązania w ASP.NET Core 8

Pisanie własnego serwera tokenów (jak w przykładach powyżej) służy nauce. W prawdziwym projekcie zwykle sięgasz po gotowe narzędzie:

  • Identity API endpoints (.NET 8) - AddIdentityApiEndpoints<TUser>() i MapIdentityApi<TUser>() dodają gotowe endpointy /register, /login, /refresh, /manage/info i inne, a pod spodem działa AddBearerToken. Dostajesz access token i refresh token bez pisania kodu. Ograniczenia: tokeny nie są JWT, tylko zabezpieczonymi przez Data Protection biletami (nieprzezroczystymi dla klienta); refresh token jest bezstanowy (nie ma tabeli, więc nie ma rotacji, wykrywania ponownego użycia ani unieważniania pojedynczej sesji, a unieważnienie wszystkich sesji użytkownika to zmiana jego SecurityStamp); to rozwiązanie dla aplikacji własnych (first-party), bez OpenID Connect.
  • OpenIddict (zobacz API dla firm: Client Credentials i OpenIddict) - darmowy, otwarty framework do zbudowania własnego serwera OAuth 2.0 / OpenID Connect w ASP.NET Core (nie gotowy produkt). Przechowuje tokeny w bazie (EF Core), obsługuje rotację refresh tokenów i pełne przepływy (Authorization Code + PKCE, Client Credentials).
  • Duende IdentityServer - dojrzały, komercyjny (licencja dla większych firm) serwer OIDC.
  • Zewnętrzny dostawca (Microsoft Entra ID, Auth0, Keycloak) - najmniej własnego kodu, serwer tokenów i przechowywanie refresh tokenów są po ich stronie, a Twoje API tylko waliduje JWT.

Reguła: nie pisz serwera tokenów samodzielnie w produkcji. Własna implementacja ma sens, gdy rozumiesz mechanizm (rozmowa rekrutacyjna) albo masz bardzo proste, zamknięte wymagania.

Po stronie klienta: jedno odświeżenie naraz

Częsty błąd w SPA lub aplikacji mobilnej: kilka równoległych żądań dostaje 401 i każde próbuje odświeżyć token. Przy rotacji drugie odświeżenie używa już zużytego tokenu, więc serwer uznaje to za kradzież i unieważnia sesję. Rozwiązanie: tylko jedno odświeżenie w danym momencie, a pozostałe żądania czekają na jego wynik:

private static readonly SemaphoreSlim Gate = new(1, 1); // only ONE refresh at a time

private async Task<string> GetFreshAccessTokenAsync(string staleToken, CancellationToken ct)
{
    await Gate.WaitAsync(ct);
    try
    {
        // another request may have already refreshed while we were waiting
        if (_tokens.AccessToken != staleToken) return _tokens.AccessToken;

        var pair = await _auth.RefreshAsync(_tokens.RefreshToken, ct); // POST /refresh
        _tokens.Save(pair);                                            // the old refresh token is now useless
        return pair.AccessToken;
    }
    finally { Gate.Release(); }
}

Dobrą praktyką jest też odświeżanie zawczasu (np. na minutę przed wygaśnięciem, zgodnie z expires_in) oraz krótka tolerancja po stronie serwera dla odpowiedzi, która zgubiła się w sieci (klient nie dostał nowego tokenu i ponawia żądanie).

Najczęstsze pułapki

  • Refresh token w localStorage - kradzież przez XSS. Użyj ciasteczka HttpOnly (BFF).
  • Refresh token jako JWT bez możliwości unieważnienia - traci się główną zaletę, czyli kontrolę po stronie serwera.
  • Brak rotacji - skradziony token działa do końca terminu ważności.
  • Zapis tokenu w bazie w postaci jawnej - wyciek bazy to wyciek wszystkich sesji.
  • Wysyłanie refresh tokenu do API z zasobami - powinien trafiać tylko do serwera tokenów.
  • Wyścig równoległych odświeżeń - opisany wyżej.
  • Brak limitu sesji i brak „wyloguj ze wszystkich urządzeń”.

Pytania rekrutacyjne

  • Po co refresh token, skoro jest access token? Pozwala trzymać access token krótko (mała szkoda po kradzieży), a użytkownika zostawić zalogowanego na długo.
  • Czym różni się od access tokenu? Jest długożyjący, zwykle nieprzezroczysty, trafia tylko do serwera tokenów i serwer może go łatwo unieważnić.
  • Co to rotacja refresh tokenów i reuse detection? Każdy token jest jednorazowy. Ponowne użycie zużytego tokenu oznacza kradzież i unieważnia całą rodzinę tokenów.
  • Gdzie przechowywać refresh token w SPA? W ciasteczku HttpOnly ustawianym przez backend (BFF), nie w localStorage.
  • Czy trzeba go używać w Client Credentials? Nie, klient po prostu pobiera nowy access token swoim sekretem lub certyfikatem.
  • Jak unieważnić dostęp użytkownika? Unieważnić jego rodziny refresh tokenów. Access token wygaśnie sam, dlatego ma żyć krótko.
  • Czy przed wygenerowaniem refresh tokenu sprawdzasz w bazie, czy już istnieje? Nie, token ma 512 bitów entropii, a kolizję wyłapie unikalny indeks. Sprawdzenie jest potrzebne przy odbiorze tokenu od klienta, a oznaczenie go jako użytego musi być atomowym UPDATE.
  • Czy ASP.NET Core 8 ma gotowe endpointy z refresh tokenem? Tak, MapIdentityApi z AddBearerToken, ale tokeny są bezstanowe (bez rotacji i reuse detection) i bez OIDC. Do pełnych scenariuszy służy OpenIddict, Duende lub zewnętrzny dostawca.
  • Dlaczego w bazie trzymamy skrót, a nie token? Żeby wyciek bazy nie ujawnił działających tokenów. SHA-256 wystarcza, bo token jest losowy i długi.
Postaw mi kawę