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

Zabezpieczanie WebAPI: JWT, OAuth 2.0, OIDC, SSO i certyfikaty

Zabezpieczenie WebAPI to kilka niezależnych warstw. Trzeba odróżnić uwierzytelnianie (kim jesteś), autoryzację (co Ci wolno) oraz ochronę kanału (TLS, certyfikaty) i samej aplikacji (walidacja, limity). Podstawy kryptografii, na których to się opiera, są w temacie Kryptografia: szyfrowanie symetryczne i asymetryczne, hashowanie, TLS.

1. Uwierzytelnianie: skąd API wie, kto pyta

Mechanizm Jak działa Kiedy
Basic Auth Authorization: Basic base64(user:pass) przy każdym żądaniu tylko przez HTTPS, proste narzędzia wewnętrzne; w nowych systemach unikać
API Key stały klucz w nagłówku (X-Api-Key) integracje maszyna-maszyna, publiczne API z limitami; identyfikuje klienta, nie użytkownika
JWT Bearer klient wysyła podpisany token Authorization: Bearer <jwt>, API weryfikuje podpis, exp, iss, aud bez zaglądania do bazy SPA, aplikacje mobilne, mikroserwisy
OAuth 2.0 / OIDC tokeny wydaje serwer autoryzacji (patrz niżej) logowanie przez zewnętrznego dostawcę, SSO, dostęp delegowany
Cookie sesja w ciasteczku (HttpOnly, Secure, SameSite) MVC/Razor i Blazor Server w jednej domenie; w czystym API rzadziej
mTLS (certyfikat klienta) obie strony pokazują certyfikat komunikacja serwis-serwis, bankowość, IoT

2. JWT, OAuth 2.0, OpenID Connect i SSO to nie to samo

  • JWT to format tokenu: nagłówek, payload z claimami i podpis (xxxxx.yyyyy.zzzzz, części w Base64URL). Sam z siebie nie jest protokołem logowania.
  • OAuth 2.0 to protokół autoryzacji delegowanej: „aplikacja X może w moim imieniu czytać moje dane w usłudze Y”. Wydaje access token (często JWT) i refresh token. Nie jest protokołem logowania.
  • OpenID Connect (OIDC) to warstwa tożsamości nad OAuth 2.0: dodaje ID token mówiący, kim jest użytkownik. To właśnie OIDC realizuje „zaloguj się przez Google/Microsoft”.
  • SSO (Single Sign-On) to cel: zalogować się raz i mieć dostęp do wielu aplikacji. Realizuje się go przez OIDC lub SAML (starszy, popularny w korporacjach) z centralnym dostawcą tożsamości (Entra ID, Keycloak, Auth0, Okta, Duende IdentityServer).

W praktyce Identity Provider wydaje tokeny (OIDC/OAuth 2.0), a API (resource server) tylko je waliduje. API nie powinno samo obsługiwać haseł, jeśli można tego uniknąć.

Przepływy OAuth 2.0 (grant types)

  • Authorization Code + PKCE - standard dla SPA, aplikacji mobilnych i webowych z użytkownikiem. Przeglądarka dostaje jednorazowy code, wymienia go na token, a PKCE chroni przed jego przechwyceniem.
  • Client Credentials - komunikacja serwis-serwis, bez użytkownika (klient uwierzytelnia się sekretem lub certyfikatem).
  • Implicit i Password są przestarzałe - nie używaj ich w nowych systemach.

3. Autoryzacja: co wolno

W ASP.NET Core zwykle kilka poziomów:

  • Role - [Authorize(Roles = "Admin")],
  • Claims i policies - [Authorize(Policy = "CanEditOrders")], czyli elastyczniejsze reguły,
  • Scope'y w tokenie - np. orders.read, orders.write,
  • Autoryzacja zasobowa - czy ten użytkownik może edytować ten konkretny rekord (IAuthorizationService lub sprawdzenie właściciela w handlerze). Jej pominięcie to najczęstsza luka BOLA/IDOR: zmieniasz w adresie /orders/5 na /orders/6 i widzisz cudze dane.

Różnica kodów odpowiedzi: 401 Unauthorized = brak lub zły token (nie wiemy, kim jesteś), 403 Forbidden = wiemy, kim jesteś, ale nie wolno Ci.

4. Certyfikaty w zabezpieczaniu API

4.1 Certyfikat serwera (TLS / HTTPS) - podstawa

Certyfikat X.509 wiąże klucz publiczny z tożsamością (domena) i jest podpisany przez zaufane CA. Klient sprawdza łańcuch zaufania, ważność, zgodność nazwy (SAN) i unieważnienie (CRL/OCSP). Daje to trzy rzeczy: szyfrowanie, uwierzytelnienie serwera i integralność. Szczegóły uzgadniania klucza: Kryptografia.

  • Publiczne API używa certyfikatu publicznego CA (np. Let's Encrypt, odnawianego automatycznie co 90 dni).
  • TLS często kończy się na reverse proxy / load balancerze (nginx, OpenLiteSpeed, Azure Front Door, Cloudflare), a do Kestrela ruch idzie lokalnie.
  • Włącz HSTS (app.UseHsts()) i przekierowanie z HTTP (app.UseHttpsRedirection()).
  • Lokalnie: dotnet dev-certs https --trust (certyfikat deweloperski, nie na produkcję).

4.2 mTLS: uwierzytelnianie certyfikatem klienta

W mutual TLS certyfikat okazuje też klient, a serwer sprawdza, czy wystawiło go zaufane CA. Klucz prywatny nie jest nigdy wysyłany, więc nie da się go przechwycić ani zgadnąć.

  • Ma sens: komunikacja serwis-serwis (często automatycznie w service mesh: Istio, Linkerd), integracje B2B, bankowość (PSD2 wymaga certyfikatów kwalifikowanych), urządzenia IoT.
  • Nie ma sensu: publiczne SPA z użytkownikami końcowymi - instalowanie i rotowanie certyfikatów na każdym urządzeniu jest zbyt uciążliwe.

Kestrel wymagający certyfikatu klienta (pakiet Microsoft.AspNetCore.Authentication.Certificate):

builder.WebHost.ConfigureKestrel(k =>
{
    k.ConfigureHttpsDefaults(https =>
    {
        https.ClientCertificateMode = ClientCertificateMode.RequireCertificate;
    });
});

builder.Services
    .AddAuthentication(CertificateAuthenticationDefaults.AuthenticationScheme)
    .AddCertificate(options =>
    {
        options.AllowedCertificateTypes = CertificateTypes.Chained; // only certs chained to a trusted CA
        options.RevocationMode = X509RevocationMode.Online;         // check CRL/OCSP

        options.Events = new CertificateAuthenticationEvents
        {
            OnCertificateValidated = ctx =>
            {
                // extra check: allow only known thumbprints
                var allowed = new[] { "A1B2C3...THUMBPRINT" };
                if (!allowed.Contains(ctx.ClientCertificate.Thumbprint, StringComparer.OrdinalIgnoreCase))
                {
                    ctx.Fail("Unknown client certificate");
                    return Task.CompletedTask;
                }

                var claims = new[] { new Claim(ClaimTypes.Name, ctx.ClientCertificate.Subject) };
                ctx.Principal = new ClaimsPrincipal(new ClaimsIdentity(claims, ctx.Scheme.Name));
                ctx.Success();
                return Task.CompletedTask;
            }
        };
    });

Klient C# (HttpClient z certyfikatem):

var cert = new X509Certificate2("client.pfx", "pfx-password");
var handler = new HttpClientHandler();
handler.ClientCertificates.Add(cert);

using var client = new HttpClient(handler) { BaseAddress = new Uri("https://api.example.com") };
var response = await client.GetAsync("/api/orders");

Pułapka - reverse proxy: jeśli TLS kończy się na proxy, Kestrel nie zobaczy certyfikatu klienta. Proxy musi go przekazać w nagłówku (np. X-ARR-ClientCert), a aplikacja odczytać przez AddCertificateForwarding i app.UseCertificateForwarding(). Ufaj takiemu nagłówkowi tylko od własnego proxy, bo inaczej każdy może go sfałszować.

4.3 Certyfikaty i klucze w tokenach JWT

  • Podpis JWT: identity provider podpisuje token kluczem prywatnym (RS256/ES256), a API sprawdza podpis kluczem publicznym pobranym z endpointu JWKS (/.well-known/jwks.json). API nie zna żadnego sekretu, a klucze można rotować. Podpis symetryczny (HS256) wymaga, żeby sekret znały obie strony, więc przy wielu usługach jest ryzykowny.
  • Tokeny powiązane z certyfikatem (RFC 8705): token zawiera claim cnf z odciskiem certyfikatu klienta, więc skradziony token jest bezużyteczny bez klucza prywatnego (stosowane w bankowości, FAPI).
  • Uwierzytelnianie klienta w OAuth 2.0: klient potwierdza się wobec serwera autoryzacji certyfikatem (tls_client_auth) albo podpisanym JWT (private_key_jwt) zamiast współdzielonego sekretu.

4.4 Certificate pinning

Klient (zwykle aplikacja mobilna) zna z góry oczekiwany certyfikat lub klucz publiczny serwera i odrzuca każdy inny, nawet wystawiony przez zaufane CA. Chroni to przed sfałszowanym certyfikatem i MITM przy kompromitacji CA. Wada: ryzyko „zabicia” aplikacji przy wymianie certyfikatu, więc pinuje się raczej klucz publiczny lub certyfikat pośredni i ma plan awaryjny. W .NET robi się to przez ServerCertificateCustomValidationCallback.

4.5 Cykl życia certyfikatów - najczęstsze źródło awarii

  • Wygasanie: nieodnowiony certyfikat potrafi położyć produkcję. Automatyzuj odnowienia (ACME/certbot, Azure Key Vault) i monitoruj daty.
  • Rotacja: planuj wymianę bez przestoju (przez pewien czas ważne są stary i nowy certyfikat).
  • Klucz prywatny: nie w repozytorium ani w appsettings.json. Używaj Key Vault, HSM lub magazynu certyfikatów systemu, a plik .pfx chroń hasłem.
  • Unieważnianie: po wycieku klucza certyfikat trzeba odwołać (CRL/OCSP). Krótszy czas życia certyfikatów zmniejsza szkody.
  • Własne CA dla mikroserwisów wewnątrz firmy: step-ca, HashiCorp Vault PKI, Active Directory Certificate Services. Pamiętaj o dystrybucji certyfikatu root.

5. Pozostałe warstwy ochrony

  • HTTPS i HSTS - bez tego tokeny i hasła idą otwartym tekstem.
  • Walidacja wejścia - DTO zamiast encji (przeciw over-posting), FluentValidation, parametryzowane zapytania (EF) przeciw SQL injection.
  • CORS ograniczony do znanych originów (to ochrona przeglądarki, nie API jako takiego).
  • Rate limiting / throttling przeciw brute force i nadużyciom - zobacz Rate limiting.
  • Anty-CSRF - tylko gdy używasz ciasteczek. Przy tokenie w nagłówku Authorization CSRF nie dotyczy.
  • Hasła - hash z solą (PBKDF2/bcrypt/Argon2), nigdy szyfrowanie ani surowy hash.
  • Sekrety w Key Vault, zmiennych środowiskowych lub User Secrets.
  • Błędy - brak stack trace'ów dla klienta (ProblemDetails), logowanie i audyt zdarzeń bezpieczeństwa.
  • API Gateway / WAF (Azure API Management, Kong, YARP) jako centralny punkt uwierzytelniania, limitów i filtrowania.

6. JWT: najczęstsze pułapki

  • Token jest podpisany, nie zaszyfrowany - nie wkładaj do niego sekretów, każdy może odczytać payload.
  • Unieważnianie jest trudne (token jest samowystarczalny), więc stosuj krótki czas życia access tokenu (5-15 min) i refresh token (rotowany, przechowywany bezpiecznie), ewentualnie listę odwołanych tokenów.
  • Zawsze waliduj podpis, exp, iss, aud, a dozwolone algorytmy ustaw jawnie (atak z alg: none oraz pomylenie RS256 z HS256).
  • Gdzie trzymać token w SPA: localStorage jest podatny na XSS, a ciasteczko HttpOnly na CSRF (potrzebne SameSite i ochrona CSRF). Wzorzec BFF (Backend for Frontend) trzyma tokeny po stronie serwera.

7. Działający przykład - SecureApiDemo

Minimalne API (.NET 8, pakiet Microsoft.AspNetCore.Authentication.JwtBearer). Pokazuje: wystawienie tokenu, walidację JWT, politykę opartą na scope, rolę, oraz autoryzację zasobową (użytkownik widzi tylko swoje zamówienie). Token wystawia tu samo API wyłącznie na potrzeby demo - w produkcji robi to dostawca tożsamości, a API tylko waliduje.

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 the key lives in a secret store (Key Vault) and tokens are issued
// by an identity provider (Entra ID, Keycloak, Duende...). Here the API issues tokens itself.
const string Issuer = "https://demo.local";
const string Audience = "orders-api";
var signingKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("demo-key-change-me-at-least-32-bytes-long!!"));

// ---- AUTHENTICATION: who is calling? ----
builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(o =>
    {
        o.MapInboundClaims = false; // keep claim names as in the token ("sub", "role", "scope")
        o.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true, ValidIssuer = Issuer,
            ValidateAudience = true, ValidAudience = Audience,
            ValidateLifetime = true, ClockSkew = TimeSpan.FromSeconds(30),
            ValidateIssuerSigningKey = true, IssuerSigningKey = signingKey,
            ValidAlgorithms = new[] { SecurityAlgorithms.HmacSha256 }, // never accept "alg: none"
            NameClaimType = "name", RoleClaimType = "role"
        };
    });

// ---- AUTHORIZATION: what is the caller allowed to do? ----
builder.Services.AddAuthorization(o =>
{
    o.AddPolicy("CanReadOrders", p => p.RequireAssertion(ctx => HasScope(ctx.User, "orders.read")));
    o.AddPolicy("AdminOnly", p => p.RequireRole("admin"));
});

var app = builder.Build();

app.UseAuthentication(); // 1st: build the user from the token
app.UseAuthorization();  // 2nd: check policies

// demo users and data
var users = new Dictionary<string, (string Password, string Id, string Role)>
{
    ["alice"] = ("alice123", "1", "user"),
    ["bob"] = ("bob123", "2", "user"),
    ["admin"] = ("admin123", "99", "admin")
};
var orders = new List<Order>
{
    new(1, "1", "Laptop"), new(2, "1", "Mouse"), new(3, "2", "Keyboard")
};

// anonymous: issue a token (in real life: login + password check + rate limiting)
app.MapPost("/login", (LoginRequest request) =>
{
    if (!users.TryGetValue(request.Username, out var u) || u.Password != request.Password)
        return Results.Unauthorized();

    var claims = new[]
    {
        new Claim("sub", u.Id),
        new Claim("name", request.Username),
        new Claim("role", u.Role),
        new Claim("scope", "orders.read orders.write")
    };
    var token = new JwtSecurityToken(
        issuer: Issuer, audience: Audience, claims: claims,
        expires: DateTime.UtcNow.AddMinutes(10),           // short-lived access token
        signingCredentials: new SigningCredentials(signingKey, SecurityAlgorithms.HmacSha256));

    return Results.Ok(new { access_token = new JwtSecurityTokenHandler().WriteToken(token) });
});

app.MapGet("/api/public", () => "anyone can see this");

// policy based on scope: the token needs "orders.read"
app.MapGet("/api/orders", (ClaimsPrincipal user) =>
{
    var isAdmin = user.IsInRole("admin");
    var userId = user.FindFirstValue("sub");
    return orders.Where(o => isAdmin || o.OwnerId == userId);
}).RequireAuthorization("CanReadOrders");

// resource-based authorization: the user may read only HIS OWN order (protection against IDOR/BOLA)
app.MapGet("/api/orders/{id:int}", (int id, ClaimsPrincipal user) =>
{
    var order = orders.FirstOrDefault(o => o.Id == id);
    if (order is null) return Results.NotFound();

    var isOwner = order.OwnerId == user.FindFirstValue("sub");
    if (!isOwner && !user.IsInRole("admin")) return Results.Forbid(); // 403: authenticated, but not allowed
    return Results.Ok(order);
}).RequireAuthorization(); // 401 without a valid token

// role-based
app.MapDelete("/api/orders/{id:int}", (int id) =>
{
    var removed = orders.RemoveAll(o => o.Id == id);
    return removed > 0 ? Results.NoContent() : Results.NotFound();
}).RequireAuthorization("AdminOnly");

app.Run();

static bool HasScope(ClaimsPrincipal user, string scope) =>
    (user.FindFirstValue("scope") ?? string.Empty).Split(' ').Contains(scope);

record LoginRequest(string Username, string Password);
record Order(int Id, string OwnerId, string Item);

Projekt (SecureApiDemo.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>

Wypróbuj (dotnet run, potem curl lub plik requests.http):

# 1) without a token -> 401
curl -i http://localhost:5000/api/orders

# 2) log in as alice and copy the access_token
curl -X POST http://localhost:5000/login -H "Content-Type: application/json" \
     -d '{"username":"alice","password":"alice123"}'

# 3) alice's orders -> 200
curl http://localhost:5000/api/orders -H "Authorization: Bearer <access_token>"

# 4) someone else's order (id 3 belongs to bob) -> 403
curl -i http://localhost:5000/api/orders/3 -H "Authorization: Bearer <access_token>"

# 5) delete without the admin role -> 403 (log in as admin/admin123 to get 204)
curl -i -X DELETE http://localhost:5000/api/orders/1 -H "Authorization: Bearer <access_token>"

Co ten przykład pokazuje

  • Kolejność middleware: UseAuthentication() buduje użytkownika z tokenu, dopiero potem UseAuthorization() sprawdza polityki.
  • 401 vs 403: brak tokenu daje 401, a brak uprawnień przy poprawnym tokenie 403.
  • Policy na scope (CanReadOrders) oraz rola (AdminOnly).
  • Autoryzacja zasobowa: samo [Authorize] nie wystarczy, bo nie sprawdza, czyje jest zamówienie.
  • Jawna lista algorytmów (ValidAlgorithms) i walidacja iss, aud, exp.

8. Co wybrać w typowych sytuacjach

Scenariusz Rekomendacja
Własne SPA lub aplikacja mobilna plus API OIDC z Authorization Code + PKCE, JWT access token, API jako resource server
Wiele aplikacji w firmie, jedno logowanie (SSO) centralny IdP (Entra ID, Keycloak) z OIDC lub SAML
Serwis woła serwis OAuth 2.0 Client Credentials albo mTLS
Publiczne API dla partnerów API Key plus rate limiting, a przy dostępie do danych użytkownika OAuth 2.0
Integracja B2B, bankowość mTLS plus tokeny, często certyfikaty kwalifikowane
Proste wewnętrzne MVC w jednej domenie cookie authentication

Zwykle łączy się je warstwowo: TLS chroni kanał, certyfikat klienta tożsamość maszyny, a token użytkownika to, co wolno konkretnej osobie.

Zobacz też

Pytania rekrutacyjne

  • Czym różni się uwierzytelnianie od autoryzacji? Uwierzytelnianie ustala, kim jesteś, autoryzacja, co Ci wolno (401 vs 403).
  • JWT vs OAuth 2.0 vs OIDC vs SSO? JWT to format tokenu, OAuth 2.0 to protokół delegowanej autoryzacji, OIDC dodaje do niego tożsamość (logowanie), a SSO to cel realizowany przez OIDC lub SAML.
  • Jak API weryfikuje JWT? Sprawdza podpis kluczem publicznym z JWKS wystawcy (lub wspólnym kluczem przy HS256) oraz exp, iss, aud, bez zaglądania do bazy.
  • Jak unieważnić JWT? Krótki czas życia plus refresh token z rotacją, ewentualnie lista odwołanych tokenów.
  • Który flow OAuth dla SPA? Authorization Code z PKCE (nie Implicit).
  • Czym różni się TLS od mTLS? W TLS certyfikat okazuje tylko serwer, w mTLS obie strony.
  • Dlaczego mTLS nie nadaje się dla publicznego SPA? Zarządzanie certyfikatami na urządzeniach użytkowników końcowych jest niepraktyczne.
  • Co to IDOR/BOLA? Dostęp do cudzych zasobów przez podmianę identyfikatora, gdy API sprawdza tylko zalogowanie, a nie właściciela. Obrona: autoryzacja zasobowa.
  • Gdzie przechowywać token w SPA? Najbezpieczniej po stronie serwera (BFF z ciasteczkiem HttpOnly), a localStorage jest podatny na XSS.
  • Co zrobić, gdy certyfikat wygaśnie? Klienci odrzucą połączenie, dlatego automatyzujemy odnowienia i monitorujemy daty ważności.
Postaw mi kawę