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 (
IAuthorizationServicelub sprawdzenie właściciela w handlerze). Jej pominięcie to najczęstsza luka BOLA/IDOR: zmieniasz w adresie/orders/5na/orders/6i 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
cnfz 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.pfxchroń 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
AuthorizationCSRF 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 zalg: noneoraz pomylenie RS256 z HS256). - Gdzie trzymać token w SPA:
localStoragejest podatny na XSS, a ciasteczkoHttpOnlyna CSRF (potrzebneSameSitei 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 potemUseAuthorization()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 walidacjaiss,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ż
- Refresh token: jak działa i kiedy go używać - rotacja, reuse detection i przykład.
- Multi-tenancy i bezpieczeństwo WebAPI: czym jest tenant - izolacja klientów w SaaS.
- Kryptografia: szyfrowanie symetryczne i asymetryczne, TLS - podstawy kryptografii.
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), alocalStoragejest podatny na XSS. - Co zrobić, gdy certyfikat wygaśnie? Klienci odrzucą połączenie, dlatego automatyzujemy odnowienia i monitorujemy daty ważności.