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

API dla firm: Client Credentials, klucze API i OpenIddict

Scenariusz

Budujesz API, które udostępnia cennik firmom (klientom biznesowym). Klient to serwer innej firmy, nie człowiek w przeglądarce. Dostaje długi sekret, po którym rozpoznajesz jego konto i uprawnienia (np. rola lub zakres: odczyt cennika, zapis). Wymagania: HTTPS, kontrola dostępu, wykrywanie nadużyć, a najlepiej także refresh token ze skrótem w bazie.

To jest komunikacja maszyna-maszyna. W OAuth2 odpowiada jej przepływ Client Credentials, w którym client_id + client_secret zastępują login i hasło człowieka.

Trzy drogi

Droga Kiedy Uwagi
A. Klucz API w nagłówku (bez JWT) mało klientów, prosty cennik Przy każdym żądaniu szukasz skrótu klucza w bazie (z cache), rola z bazy. Odwołanie klucza działa natychmiast. Najmniej ruchomych części.
B. Własny endpoint /token: klucz -> krótki JWT chcesz JWT i pełną kontrolę Rozsądne w małym, zamkniętym przypadku, ale nie jest to „OAuth2” i sam odpowiadasz za bezpieczeństwo.
C. Serwer zgodny z OAuth2: gotowy produkt (Keycloak, Entra ID, Auth0) albo framework do jego zbudowania (OpenIddict) klienci mają używać standardowych bibliotek, kilka rodzajów dostępu, rosnąca skala Prawdziwy OAuth2 client_credentials, klienci i sekrety w bazie, rotacja, audyt. Więcej konfiguracji na starcie.

Walidację JWT zawsze robisz biblioteką (JwtBearer), niezależnie od drogi. Własny serwer tokenów jest do nauki; w produkcji lepiej gotowy.

Jak działa Client Credentials

Klient                          Serwer autoryzacji              API z cennikiem
  | POST /connect/token  ----------> |                               |
  |  client_id + client_secret       | sprawdza sekret (hash w bazie)|
  |  scope=pricing:read              | sprawdza dozwolone zakresy    |
  | <---------- access_token (JWT, 10 min)                           |
  | GET /api/prices  (Authorization: Bearer ...) ------------------> |
  |                                                  sprawdza podpis, ważność, zakres
  | <---------------------------------------------------- 200 + dane |

Klient nie ma tu żadnego użytkownika, który się loguje. Token reprezentuje samego klienta, a to, co może, wynika z zakresów (scopes) przyznanych mu w bazie.

Co to daje klientowi (droga C)

  • Standardowe biblioteki w każdym języku. Klient konfiguruje gotowego klienta OAuth2 (adres tokenu, client_id, client_secret, zakres) i biblioteka sama pobiera oraz odnawia token. Nie pisze kodu pod Twój niestandardowy mechanizm.
  • Znany przepływ, więc krótszy onboarding i mniej własnej dokumentacji.
  • Zakresy: token mówi, do czego klient ma dostęp (pricing:read, pricing:write).
  • Przewidywalne błędy (invalid_client, invalid_scope) i pole expires_in w odpowiedzi.
  • Rozdzielenie identyfikatora i sekretu, łatwiejsza rotacja sekretu i wyłączenie jednego klienta bez wpływu na innych.
  • Dla Ciebie: nie utrzymujesz własnego kodu wydawania tokenów i rotacji kluczy podpisu, a przy rozwoju łatwo dodać inne przepływy (logowanie ludzi, SSO).

Czy refresh token ma tu sens?

W Client Credentials zwykle nie. Specyfikacja zaleca nie wydawać refresh tokenu w tym przepływie: klient trzyma długożyjący sekret i po prostu prosi o nowy access token, gdy poprzedni wygaśnie. Dlatego access token ma żyć krótko (5-15 minut). Rotacja i wykrywanie ponownego użycia chronią refresh tokeny, ale nie chronią sekretu klienta, który nadal pozwala wydać nowy token. Jeśli wymóg refresh tokenu jest nieodwołalny, wzorzec z tematu Refresh token (skrót w bazie, rotacja, rodzina tokenów, wykrywanie ponownego użycia) da się podpiąć pod endpoint wymiany klucza, ale nie zwiększa to ochrony klucza.

Co naprawdę zabezpiecza takie API

  • Sekret traktuj jak hasło: losowy (np. 32 bajty z RandomNumberGenerator), w bazie tylko skrót, pokazywany klientowi jeden raz, z jawnym prefiksem do identyfikacji (np. pk_ab12...). OpenIddict hashuje sekrety klientów sam.
  • Cykl życia: data ważności, odwołanie, rotacja (dwa aktywne sekrety na czas wymiany), LastUsedAt.
  • Sekret tylko w nagłówku lub ciele żądania, nigdy w URL (trafia do logów).
  • HTTPS wymuszone: HSTS i odrzucanie HTTP na brzegu. Sekret wysłany po HTTP już wyciekł, więc samo przekierowanie nie wystarcza.
  • Rola lub zakres w tokenie jest zamrożona do wygaśnięcia tokenu. Trzymaj access token krótko albo (w drodze A) sprawdzaj uprawnienia w bazie przy każdym żądaniu.
  • Limit żądań na klienta i monitoring: przy cenniku realnym ryzykiem jest masowe pobranie danych, nie tylko kradzież tokenu.
  • Opcjonalnie lista dozwolonych adresów IP klienta.

Klucz w każdym żądaniu (A) kontra token (C)

Droga A. Klient wysyła klucz w każdym żądaniu, a API za każdym razem go weryfikuje:

Klient: GET /api/prices
        X-Api-Key: pk_ab12...tajny-ciag

API (przy KAŻDYM żądaniu):
  1. handler uwierzytelniania czyta nagłówek X-Api-Key
  2. liczy skrót klucza (SHA-256) i szuka go w bazie (zwykle z krótkim cache)
  3. brak / wyłączony / wygasły  ->  401
  4. jest  ->  buduje ClaimsPrincipal z danych z bazy (id klienta, rola, zakresy)
  5. autoryzacja (polityki, [Authorize]) sprawdza claimy  ->  200 albo 403

Dwa etapy warto rozdzielić: uwierzytelnienie (kim jesteś?) robi handler klucza i tworzy tożsamość z claimami, a autoryzację (co ci wolno?) robi standardowy mechanizm ASP.NET Core na podstawie claimów, np. RequireAuthorization("pricing:read"). Endpoint nie wie, czy tożsamość przyszła z klucza, czy z tokenu. W bazie porównujesz skrót klucza, nigdy sam klucz.

Droga C. Sekret leci tylko do serwera tokenów, a dalej klient używa krótkiego tokenu:

Klient: POST /connect/token   (client_id + client_secret)    <- sekret tylko tutaj
Serwer: sprawdza sekret, wydaje access_token (JWT, 10 min) z claimami

Klient: GET /api/prices
        Authorization: Bearer <access_token>                   <- sekret już nie leci

API:    sprawdza podpis i ważność JWT (bez zapytania do bazy), claimy są w tokenie
A: klucz w każdym żądaniu C: token
Co leci po sieci tajny klucz za każdym razem sekret rzadko, token często
Zapytanie do bazy przy każdym żądaniu (lub cache) tylko przy wydawaniu tokenu
Odwołanie dostępu natychmiast po wygaśnięciu tokenu
Zmiana roli klienta od razu po wygaśnięciu tokenu
Skutki wycieku klucz działa do odwołania skradziony token działa kilka minut, ale sekret nadal pozwala wydać nowy

Droga A jest prostsza i daje natychmiastową kontrolę, kosztem częstszego wysyłania sekretu i obciążenia bazy. Droga C ogranicza ekspozycję sekretu i odciąża bazę, kosztem opóźnienia w odwołaniach.

B kontra C: dlaczego własnego endpointu nie nazywać OAuth2

W obu drogach klient wymienia sekret na krótki JWT. Różnica to zgodność ze standardem i to, kto odpowiada za szczegóły.

  • B (własny /token): sam decydujesz o wszystkim: klucz w nagłówku X-Api-Key, dowolny kształt odpowiedzi, własne błędy, własne podpisywanie i rotacja kluczy. Klienci muszą przeczytać Twoją dokumentację i napisać kod pod Ciebie.
  • C (serwer zgodny z OAuth2): zachowuje się tak, jak opisuje RFC 6749 (Client Credentials): żądanie POST w application/x-www-form-urlencoded z grant_type, client_id, client_secret, scope; odpowiedź JSON z access_token, token_type, expires_in; standardowe błędy (invalid_client, invalid_scope); discovery, JWKS, opcjonalnie unieważnianie i introspekcja.

Nazwa „OAuth2” jest obietnicą zgodności: klient zakłada, że zadziała standardowa biblioteka, że brzegowe przypadki są obsłużone i że protokół został przeanalizowany pod kątem bezpieczeństwa. Własny endpoint, który odbiega od standardu, zawiedzie w nieoczywisty sposób, a nazwa sugeruje gwarancje, których nie daje.

Gdybyś odwzorował endpoint z RFC dokładnie, technicznie miałbyś minimalny serwer OAuth2 dla jednego przepływu. Problem w tym, że „dokładnie” to dziesiątki szczegółów: kody błędów, nieujawnianie istnienia klienta, porównania odporne na ataki czasowe, przechowywanie sekretów, rotacja kluczy podpisu, discovery. Biblioteka taka jak OpenIddict robi właśnie to, więc C to w praktyce „B zrobione i utrzymywane przez kogoś, kto się na tym zna”. Droga B jest najsłabszym kompromisem: koszt własnego serwera tokenów bez korzyści ze standardu.

OAuth2, JWT i OpenID Connect: co jest czym

OAuth2 opisuje przepływ (kto, co i jak wymienia na token), ale nie określa formatu tokenu. JWT to format, który serwery najczęściej wybierają dla access tokenu (jest nawet profil, RFC 9068). Można mieć OAuth2 bez JWT (tokeny nieprzezroczyste) i JWT bez OAuth2 (własny endpoint z drogi B).

Token Format
Access token JWT (samodzielny, podpisany) albo token nieprzezroczysty (losowy ciąg, który API sprawdza w serwerze). Oba są zgodne z OAuth2.
ID token (OpenID Connect) zawsze JWT, bo tak wymaga specyfikacja OIDC
Refresh token zwykle nieprzezroczysty, trzymany w bazie
  • JWT (samodzielny): API weryfikuje podpis kluczem publicznym z JWKS i czyta claimy z tokenu, bez pytania serwera ani bazy. Szybkie i skalowalne, ale odwołanie działa dopiero po wygaśnięciu (stąd krótkie życie).
  • Nieprzezroczysty (referencyjny): API pyta serwera („introspekcja”) lub bazy, czy token jest ważny. Odwołanie działa natychmiast, kosztem zapytania przy każdym żądaniu.

OpenID Connect (OIDC) to nakładka na OAuth2 dodająca tożsamość użytkownika (ID token). Nie jest jednym „API produktu”, tylko zestawem standardowych endpointów HTTP:

Endpoint Do czego służy
/.well-known/openid-configuration discovery: JSON z adresami pozostałych endpointów, klient konfiguruje się jednym adresem
/connect/authorize początek logowania użytkownika (Authorization Code + PKCE)
/connect/token wymiana kodu, refresh tokenu lub sekretu klienta na tokeny
/connect/userinfo dane zalogowanego użytkownika, wywoływane access tokenem
JWKS klucze publiczne do weryfikacji podpisu tokenów
/connect/logout wylogowanie
/connect/introspect, /connect/revoke sprawdzenie i unieważnienie tokenu (RFC OAuth2)

Ścieżki zależą od serwera, dlatego klient czyta je z dokumentu discovery. W Client Credentials nie ma użytkownika, więc ID tokenu i userinfo nie używasz; przydają się discovery, token i JWKS. OIDC zaczyna się liczyć przy panelu z logowaniem ludzi lub SSO. Stary „OpenID 2.0” to inny, przestarzały protokół.

OpenIddict: framework, nie gotowy produkt

OpenIddict to zestaw bibliotek do zbudowania własnego serwera OAuth 2.0 / OIDC w ASP.NET Core, a nie program do uruchomienia i skonfigurowania w panelu.

  • Robi za Ciebie: protokół i endpointy, walidację żądań, sprawdzanie sekretów (hash), zakresów i uprawnień, podpisywanie tokenów, błędy zgodne ze specyfikacją, magazyn klientów i tokenów (EF Core), menedżery (IOpenIddictApplicationManager) i moduł walidacji tokenów w API.
  • Dokładasz sam: panel zarządzania klientami, ekran logowania i konta użytkowników (jeśli są), decyzję, co trafia do tokenu, hosting, bazę, klucze i certyfikaty, rotację, audyt i monitoring.
Rozwiązanie Typ
OpenIddict framework: budujesz serwer z klocków, pełna kontrola, najwięcej pracy
Duende IdentityServer framework (komercyjny), podobny model pracy
Keycloak gotowy produkt z panelem administracyjnym i Admin REST API
Entra ID, Auth0 usługa w chmurze, nic nie hostujesz

Refresh tokeny w OpenIddict. Są obsługiwane tylko w przepływach z użytkownikiem (Authorization Code); w Client Credentials ich nie ma. Biblioteka daje rotację, wykrywanie ponownego użycia (o ile wiem, unieważnia cały łańcuch autoryzacji), magazyn w bazie i opcjonalnie tokeny referencyjne (w bazie tylko skrót). To odpowiednik tego, co ręcznie zrobiono w Refresh token. Szkic (nazwy sprawdź w dokumentacji używanej wersji):

.AddServer(o =>
{{
    o.AllowAuthorizationCodeFlow().RequireProofKeyForCodeExchange();
    o.AllowRefreshTokenFlow();
    o.RegisterScopes(Scopes.OfflineAccess, "pricing:read"); // the client asks for offline_access to get a refresh token
    o.SetRefreshTokenLifetime(TimeSpan.FromDays(7));
    o.SetRefreshTokenReuseLeeway(TimeSpan.FromSeconds(30)); // tolerance for parallel refreshes
    o.UseReferenceRefreshTokens();                          // optional: only a hash lives in the database
}});

Dwa sposoby uwierzytelniania w jednym API

ASP.NET Core pozwala zarejestrować kilka schematów uwierzytelniania i wybierać je per endpoint albo połączyć w jeden. Sensowne np. przy migracji: stare klienty zostają na kluczach, nowe używają OAuth2, a klucze wygaszasz stopniowo. Szkic (nie kompilowany, nazwy sprawdź w dokumentacji o wielu schematach):

// Variant 1: separate schemes, chosen per endpoint
builder.Services.AddAuthentication()
    .AddScheme<AuthenticationSchemeOptions, ApiKeyHandler>("ApiKey", null)
    .AddJwtBearer("Bearer", o => {{ /* Authority = address of the OAuth2 server */ }});

app.MapGet("/api/prices", ...)
   .RequireAuthorization(new AuthorizeAttribute {{ AuthenticationSchemes = "ApiKey,Bearer" }});

// Variant 2: one "policy scheme" that picks the handler from the request
builder.Services.AddAuthentication("Smart")
    .AddPolicyScheme("Smart", null, o =>
        o.ForwardDefaultSelector = ctx => ctx.Request.Headers.ContainsKey("X-Api-Key") ? "ApiKey" : "Bearer")
    .AddScheme<AuthenticationSchemeOptions, ApiKeyHandler>("ApiKey", null)
    .AddJwtBearer("Bearer", o => {{ }});

Żeby to miało sens: oba schematy muszą dawać ten sam model uprawnień (handler klucza buduje ClaimsPrincipal z tymi samymi zakresami co token, wtedy polityki działają bez zmian), a limit żądań partycjonuj po tym samym identyfikatorze klienta, żeby nie dało się go obejść, używając na zmianę obu sposobów. Dla jednego klienta nie ma powodu trzymać dwóch ścieżek, bo rośnie powierzchnia ataku i kod do utrzymania.

Zarządzanie klientami z własnego panelu

Standardy OAuth2 i OIDC nie określają API do zarządzania klientami (poza rzadko wdrażanym Dynamic Client Registration, RFC 7591). Każdy serwer ma własne rozwiązanie:

Serwer Zarządzanie credentialami
OpenIddict brak gotowego REST API; używasz IOpenIddictApplicationManager we własnym kodzie i wystawiasz własne endpointy lub robisz to w panelu
Keycloak gotowe Admin REST API (klienci, regeneracja sekretu, role)
Microsoft Entra ID Microsoft Graph (aplikacje, dodawanie i usuwanie sekretów)
Auth0 Management API (klienci, granty, sekrety)
Duende IdentityServer konfiguracja w bazie (EF); API do rejestracji klientów zależy od edycji, sprawdź licencję

Szkic operacji w OpenIddict (nie kompilowany):

// POST /admin/clients -> creates a client, returns the secret ONCE
app.MapPost("/admin/clients", async (CreateClientRequest req, IOpenIddictApplicationManager apps) =>
{{
    var secret = Convert.ToBase64String(RandomNumberGenerator.GetBytes(32));
    var descriptor = new OpenIddictApplicationDescriptor
    {{
        ClientId = req.ClientId, ClientSecret = secret, DisplayName = req.Name,
        ClientType = ClientTypes.Confidential,
        Permissions = {{ Permissions.Endpoints.Token, Permissions.GrantTypes.ClientCredentials }}
    }};
    foreach (var s in req.Scopes) descriptor.Permissions.Add(Permissions.Prefixes.Scope + s);
    await apps.CreateAsync(descriptor);
    return Results.Ok(new {{ req.ClientId, clientSecret = secret }}); // the only time the secret is visible
}}).RequireAuthorization("panel-admin");

Analogicznie: lista klientów, zmiana zakresów, rotacja sekretu, wyłączenie i usunięcie. Na co uważać:

  • Endpointy administracyjne to najwrażliwsza część systemu: osobne uwierzytelnianie administratorów (najlepiej OIDC), rola panel-admin, a nie ten sam token co dla klientów API; najlepiej osobny host lub ścieżka niedostępna z internetu.
  • Audyt: kto, kiedy i co zmienił; sekretów nie loguj.
  • Rotacja bez przerwy: o ile wiem, OpenIddict trzyma jeden sekret na aplikację, więc płynna wymiana wymaga dwóch rejestracji klienta albo własnej logiki.
  • Unieważnienie klienta nie kasuje wydanych tokenów, które żyją do wygaśnięcia.

Dlaczego dostawcy API wybierają klucz API

Anthropic, OpenAI, Stripe czy SendGrid udostępniają API głównie przez klucz API (to moja interpretacja, nie ich uzasadnienie):

  • Prostota wejścia: jeden nagłówek i curl działa w minutę, bez pobierania i odnawiania tokenu.
  • Klient to serwer dewelopera: nie ma człowieka klikającego „zezwól”, więc przepływy z przeglądarką nie pasują.
  • Rozliczanie i limity per klucz: klucz jest naturalnym nośnikiem konta, budżetu i logów, a odwołanie działa natychmiast.
  • Dostęp do własnych zasobów: OAuth2 błyszczy przy delegowaniu dostępu do danych użytkownika (np. „zaloguj przez Google”), a tu tego nie ma.

Duzi dostawcy łączą oba modele: klucz API dla wywołań serwer-serwer, OAuth2 tam, gdzie jest delegowanie. Dlatego klucz API nie jest „gorszym” wyborem, tylko innym kompromisem. Wybór dla cennika: kilka zaufanych klientów i szybki start: klucz API (skrót w bazie, zakresy, limity, odwołanie, HTTPS); więcej klientów, standardowe biblioteki po ich stronie, plany rozbudowy: serwer OAuth2 (C).

Działający przykład - OpenIddictDemo

Jedna aplikacja .NET 8 jest jednocześnie serwerem autoryzacji (OpenIddict, klienci w SQLite) i API z cennikiem. Port 5004, tylko HTTPS (dotnet dev-certs https --trust). Dwóch klientów: acme-pricing (tylko odczyt) i partner-admin (odczyt i zapis). Pełny projekt jest w examples/OpenIddictDemo, scenariusz w requests.http.

using System.Collections.Concurrent;
using System.Security.Claims;
using System.Threading.RateLimiting;
using Microsoft.EntityFrameworkCore;
using Microsoft.IdentityModel.Tokens;
using OpenIddict.Abstractions;
using OpenIddict.Server.AspNetCore;
using OpenIddict.Validation.AspNetCore;
using static OpenIddict.Abstractions.OpenIddictConstants;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDb>(o =>
{
    o.UseSqlite("Data Source=openiddict.db");
    o.UseOpenIddict(); // adds the OpenIddict tables: applications (clients), scopes, tokens, authorizations
});

builder.Services.AddOpenIddict()
    .AddCore(o => o.UseEntityFrameworkCore().UseDbContext<AppDb>())
    .AddServer(o =>
    {
        o.SetTokenEndpointUris("connect/token");
        o.AllowClientCredentialsFlow();                       // machine-to-machine: client_id + client_secret -> access token
        o.RegisterScopes("pricing:read", "pricing:write");
        o.SetAccessTokenLifetime(TimeSpan.FromMinutes(10));   // short, because there is no refresh token in this flow

        // DEMO ONLY: keys are regenerated on every start. In production use real certificates or keys from a vault.
        o.AddEphemeralEncryptionKey().AddEphemeralSigningKey();
        o.DisableAccessTokenEncryption();                     // readable JWT (e.g. on jwt.io), good for learning

        o.UseAspNetCore().EnableTokenEndpointPassthrough();   // we build the token ourselves in /connect/token below
    })
    .AddValidation(o =>
    {
        o.UseLocalServer(); // the API is in the same app as the server, so it trusts it directly
        o.UseAspNetCore();
    });

builder.Services.AddAuthentication(OpenIddictValidationAspNetCoreDefaults.AuthenticationScheme);
builder.Services.AddAuthorizationBuilder()
    .AddPolicy("pricing:read", p => p.RequireAssertion(c => c.User.HasScope("pricing:read")))
    .AddPolicy("pricing:write", p => p.RequireAssertion(c => c.User.HasScope("pricing:write")));

// Rate limit PER CLIENT (partition by the token subject): the real risk of a price list is mass downloading.
builder.Services.AddRateLimiter(o =>
{
    o.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
    o.AddPolicy("per-client", ctx => RateLimitPartition.GetFixedWindowLimiter(
        ctx.User.FindFirstValue(Claims.Subject) ?? "anonymous",
        _ => new FixedWindowRateLimiterOptions { PermitLimit = 5, Window = TimeSpan.FromMinutes(1) }));
});

builder.Services.AddHostedService<Seeder>(); // creates the database and two demo clients

var app = builder.Build();

if (!app.Environment.IsDevelopment()) app.UseHsts();
app.UseHttpsRedirection(); // the demo runs on https only (OpenIddict itself refuses to work over plain http)
app.UseAuthentication();
app.UseRateLimiter();
app.UseAuthorization();

// Token endpoint. By the time we get here OpenIddict has ALREADY checked client_id, the client_secret
// (against its hash in the database), the grant type and whether the client may request the scopes.
app.MapPost("/connect/token", async (HttpContext http, IOpenIddictApplicationManager apps) =>
{
    var request = http.GetOpenIddictServerRequest()
        ?? throw new InvalidOperationException("The OpenID Connect request cannot be retrieved.");

    if (!request.IsClientCredentialsGrantType())
        return Results.BadRequest(new { error = Errors.UnsupportedGrantType });

    var application = await apps.FindByClientIdAsync(request.ClientId!)
        ?? throw new InvalidOperationException("The application cannot be found.");

    var identity = new ClaimsIdentity(TokenValidationParameters.DefaultAuthenticationType, Claims.Name, Claims.Role);
    identity.SetClaim(Claims.Subject, await apps.GetClientIdAsync(application));
    identity.SetClaim(Claims.Name, await apps.GetDisplayNameAsync(application));
    identity.SetScopes(request.GetScopes());                    // what the client asked for (and is allowed to get)
    identity.SetDestinations(_ => [Destinations.AccessToken]);  // put every claim into the access token

    return Results.SignIn(new ClaimsPrincipal(identity), properties: null, OpenIddictServerAspNetCoreDefaults.AuthenticationScheme);
});

// The business API: a price list. Access is decided by SCOPES from the token.
var prices = new ConcurrentDictionary<string, decimal>
{
    ["SKU-100"] = 19.99m,
    ["SKU-200"] = 49.90m,
    ["SKU-300"] = 129.00m
};

app.MapGet("/api/prices", (ClaimsPrincipal user) => new { client = user.FindFirstValue(Claims.Subject), prices })
    .RequireAuthorization("pricing:read")
    .RequireRateLimiting("per-client");

app.MapPut("/api/prices/{sku}", (string sku, PriceUpdate update) =>
{
    prices[sku] = update.Price;
    return Results.NoContent();
})
    .RequireAuthorization("pricing:write")
    .RequireRateLimiting("per-client");

app.Run();

record PriceUpdate(decimal Price);
using Microsoft.EntityFrameworkCore;
using OpenIddict.Abstractions;
using static OpenIddict.Abstractions.OpenIddictConstants;

public class AppDb(DbContextOptions<AppDb> options) : DbContext(options)
{
}

// Creates the database and two demo clients on startup (in production clients are added by an admin panel or a script).
public class Seeder(IServiceProvider services) : IHostedService
{
    public async Task StartAsync(CancellationToken ct)
    {
        await using var scope = services.CreateAsyncScope();
        await scope.ServiceProvider.GetRequiredService<AppDb>().Database.EnsureCreatedAsync(ct); // demo: no migrations
        var apps = scope.ServiceProvider.GetRequiredService<IOpenIddictApplicationManager>();

        await EnsureClientAsync(apps, "acme-pricing", "Acme Sp. z o.o.", "acme-secret-change-me",
            new[] { "pricing:read" }, ct);
        await EnsureClientAsync(apps, "partner-admin", "Partner Admin", "admin-secret-change-me",
            new[] { "pricing:read", "pricing:write" }, ct);
    }

    private static async Task EnsureClientAsync(IOpenIddictApplicationManager apps, string clientId, string displayName,
        string secret, string[] scopes, CancellationToken ct)
    {
        if (await apps.FindByClientIdAsync(clientId, ct) is not null) return;

        var descriptor = new OpenIddictApplicationDescriptor
        {
            ClientId = clientId,
            ClientSecret = secret,                 // OpenIddict stores only a HASH of the secret
            DisplayName = displayName,
            ClientType = ClientTypes.Confidential,
            Permissions =
            {
                Permissions.Endpoints.Token,
                Permissions.GrantTypes.ClientCredentials
            }
        };
        foreach (var scope in scopes) descriptor.Permissions.Add(Permissions.Prefixes.Scope + scope);

        await apps.CreateAsync(descriptor, ct);
    }

    public Task StopAsync(CancellationToken ct) => Task.CompletedTask;
}

Jak to wypróbować

dotnet dev-certs https --trust   # once
dotnet run

# token for the read-only client
curl -k -X POST https://localhost:5004/connect/token \
     -d "grant_type=client_credentials&client_id=acme-pricing&client_secret=acme-secret-change-me&scope=pricing:read"

# call the API with the access_token from the answer
curl -k https://localhost:5004/api/prices -H "Authorization: Bearer <access_token>"

# the same token cannot change prices -> 403
curl -k -X PUT https://localhost:5004/api/prices/SKU-100 -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" -d '{"price":17.5}'

Co ten przykład pokazuje

  • Sekret klienta jest w bazie jako skrót (zajmuje się tym OpenIddict). /connect/token dostaje żądanie dopiero po sprawdzeniu klienta, sekretu i zakresów.
  • Zakresy decydują o dostępie: odczyt dostaje pricing:read, zapis wymaga pricing:write. Zły sekret daje 401 invalid_client, niedozwolony zakres 400 invalid_scope, brak zakresu w tokenie 403.
  • Limit 5 żądań na minutę na klienta (partycja po sub z tokenu) kończy się odpowiedzią 429.
  • Brak refresh tokenu: expires_in to 600 s i klient po prostu pobiera nowy token.

Klient po stronie firmy: pobieranie i cache tokenu

using System.Net.Http.Json;
using System.Text.Json.Serialization;

// Fetches a token, keeps it until shortly before it expires, and reuses it for every API call.
public class PricingTokenProvider(HttpClient http, string clientId, string clientSecret)
{
    private string? _token;
    private DateTime _expiresAtUtc;

    public async Task<string> GetTokenAsync()
    {
        if (_token is not null && DateTime.UtcNow < _expiresAtUtc) return _token;

        var response = await http.PostAsync("connect/token", new FormUrlEncodedContent(new Dictionary<string, string>
        {
            ["grant_type"] = "client_credentials",
            ["client_id"] = clientId,
            ["client_secret"] = clientSecret,
            ["scope"] = "pricing:read"
        }));
        response.EnsureSuccessStatusCode();

        var body = await response.Content.ReadFromJsonAsync<TokenResponse>()!;
        _token = body!.AccessToken;
        _expiresAtUtc = DateTime.UtcNow.AddSeconds(body.ExpiresIn - 30); // refresh a bit early
        return _token;
    }
}

public record TokenResponse(
    [property: JsonPropertyName("access_token")] string AccessToken,
    [property: JsonPropertyName("expires_in")] int ExpiresIn);

W praktyce klient użyje gotowej biblioteki (np. zarządzania tokenami dostępu z Duende.AccessTokenManagement albo odpowiednika w swoim języku), która robi to samo i obsługuje równoległe wywołania.

Najczęstsze pułapki

  • Sekret klienta w repozytorium, logach lub URL.
  • Brak limitów żądań - jeden klient może pobrać cały cennik.
  • Długi access token bez możliwości odwołania - skradziony działa do końca ważności.
  • Zbyt szerokie zakresy dla wszystkich klientów zamiast minimalnych.
  • HTTP z przekierowaniem na HTTPS zamiast odrzucenia - sekret zdąży wyciec.
  • Własny serwer tokenów w produkcji bez audytu bezpieczeństwa.
  • Ta sama para kluczy podpisu na zawsze - brak rotacji i brak planu na wyciek klucza.

Pytania rekrutacyjne

  • Jaki przepływ OAuth2 dla komunikacji serwer-serwer? Client Credentials: klient uwierzytelnia się sekretem (lub certyfikatem) i dostaje access token, bez użytkownika.
  • Czy w Client Credentials używa się refresh tokenu? Zwykle nie. Klient trzyma sekret i pobiera nowy access token, więc access token jest krótki.
  • Klucz API czy OAuth2? Dla kilku zaufanych klientów klucz API jest prostszy; przy wielu klientach, zakresach i oczekiwaniu standardu lepszy jest OAuth2 (np. OpenIddict, Keycloak).
  • Jak ograniczasz uprawnienia klienta? Zakresami (scopes) przyznanymi w bazie i sprawdzanymi w politykach autoryzacji.
  • Jak chronisz sekret klienta w bazie? Zapisujesz tylko skrót, a sam sekret pokazujesz klientowi raz.
  • Jak zapobiegasz masowemu pobraniu danych? Limity żądań na klienta, monitoring i alerty.
  • Czy JWT jest częścią OAuth2? Nie. OAuth2 nie określa formatu tokenu; access token może być JWT albo nieprzezroczysty. ID token w OpenID Connect jest zawsze JWT.
  • Czym OIDC różni się od OAuth2? OAuth2 to autoryzacja (dostęp do zasobów), a OIDC dodaje uwierzytelnienie użytkownika: ID token, userinfo, discovery.
  • Czym jest OpenIddict? Frameworkiem do zbudowania własnego serwera OAuth2/OIDC w ASP.NET Core, nie gotowym produktem (w odróżnieniu od Keycloak).
  • Dlaczego własnego endpointu tokenów nie nazywać OAuth2? Bo nazwa obiecuje zgodność z RFC i działanie standardowych bibliotek; odstępstwa i własne błędy bezpieczeństwa łamią tę obietnicę.
  • Czy jedno API może obsługiwać klucz API i OAuth2? Tak, przez kilka schematów uwierzytelniania (lub policy scheme), pod warunkiem że oba budują ten sam model claimów i zakresów.
  • Czy OAuth2/OIDC mają API do zarządzania klientami? Nie ma standardu poza Dynamic Client Registration; każdy serwer ma własne (Keycloak Admin API, Graph, Management API) albo, jak OpenIddict, robisz to własnym kodem.
  • Dlaczego access token ma być krótki? Bo rola lub zakres są w nim zamrożone, a odwołanie pojedynczego tokenu jest trudne.

Zobacz też

Postaw mi kawę