Konfigurace ověřování pomocí nositele JWT v ASP.NET Core

2025-01-19

JWT (JSON Web Token) ověřování nosných tokenů se běžně využívá pro API. I když funguje podobně jako ověřování cookie, zprostředkovatel identity vydá při úspěšném ověření JWT nebo tokeny. Tyto tokeny je pak možné odeslat na jiné servery k ověření, na rozdíl od souborů cookie, které se odesílají pouze do vydávající domény. JWT je samostatný token, který zapouzdřuje informace pro prostředek rozhraní API nebo klienta. Klient, který požadoval JWT, může požadovat data z prostředku rozhraní API pomocí autorizační hlavičky a nosného tokenu.

JWT Bearer Authentication poskytuje:

ověřování: Při použití JwtBearerHandlerjsou nosné tokeny nezbytné pro ověřování. JwtBearerHandler ověří token a extrahuje identitu uživatele z jeho atributů.
Autorizace: Nosné tokeny umožňují autorizaci poskytnutím kolekce deklarací představujících oprávnění uživatele nebo aplikace, podobně jako cookie.
delegovaná autorizace: Pokud se přístupový token specifický pro uživatele používá k ověřování mezi rozhraními API místo přístupového tokenu pro celou aplikaci, tento proces se označuje jako delegovaná autorizace.

Pro úvod do ověřování protokolem JWT Bearer viz téma JSON Web Tokeny.Zobrazit nebo stáhnout ukázkový kód

Tento článek se zabývá následujícími oblastmi:

Typy tokenů
Použití tokenů JWT k zabezpečení rozhraní API
Jak do toho zapadá OIDC/OAuth?
Implementace ověřování pomocí nosného tokenu JWT
Doporučené přístupy k vytvoření JWT

Typy tokenů

Existuje mnoho typů tokenů a formátů. Generování vlastních přístupových tokenů nebo tokenů ID se nedoporučuje, s výjimkou testovacích účelů. Tokeny vytvořené vlastním systémem, které neodpovídají zavedeným standardům:

Může vést k ohrožením zabezpečení.
Jsou vhodné pouze pro uzavřené systémy.

Pro vytváření přístupových tokenů určených pro přístup k rozhraní API doporučujeme použít OpenID Connect 1.0 nebo standard OAuth.

Přístupové tokeny

Přístupové tokeny:

Jsou řetězce používané klientskou aplikací k odesílání požadavků na server, který implementuje rozhraní API.
Může se lišit ve formátu. Různá rozhraní API můžou pro tokeny používat různé formáty.
Je možné šifrovat.
Přístupový token by nikdy neměl být čten nebo interpretován webovým klientem nebo aplikací uživatelského rozhraní.
Jsou určeny výhradně pro provádění požadavků na rozhraní API.
Obvykle se odesílají do rozhraní API v autorizační hlavičce požadavku jako nosný token.

Viz Rámec autorizace OAuth 2.0

Přístupové tokeny aplikace a delegovaná přístupová tokeny

Přístupové tokeny mohou být buď aplikační přístupové tokeny, nebo delegované přístupové tokeny. Tokeny mají různé deklarace identity a spravují se a ukládají odlišně. Přístupový token aplikace se obvykle ukládá jednou v aplikaci, dokud nevyprší platnost, zatímco delegovaný přístupový token se ukládá na uživatele, a to buď v cookie, nebo v zabezpečené mezipaměti serveru.

Doporučujeme používat delegovaná přístupová tokeny uživatelů, kdykoli je uživatel zapojen. Podřízená rozhraní API můžou požadovat delegovaný přístupový token uživatele jménem ověřeného uživatele.

Přístupové tokeny s omezeným přístupem odesílatele

Přístupové tokeny lze použít jako nosné tokeny nebo tokeny s omezením odesílatele pro přístup k prostředkům. Tokeny s omezenými odesílateli vyžadují, aby žádající klient prokázal vlastnictví privátního klíče, aby token používal. Ověření vlastnictví privátního klíče zaručuje, že token nelze používat nezávisle. Tokeny s omezením odesílatele je možné implementovat dvěma způsoby:

Identifikační tokeny

Tokeny ID jsou tokeny zabezpečení, které ověřují úspěšné ověření uživatele. Tokeny umožňují klientovi ověřit identitu uživatele. Server tokenů JWT vydává tokeny ID obsahující deklarace identity s informacemi o uživateli. Tokeny ID jsou vždy ve formátu JWT.

Tokeny ID by nikdy neměly používat pro přístup k rozhraním API.

Další tokeny

Existuje mnoho typů tokenů, včetně přístupových tokenů a tokenů ID určených standardy OpenID Connect a OAuth. Obnovovací tokeny je možné použít k aktualizaci aplikace uživatelského rozhraní bez opětovného ověření uživatele. tokeny JAR OAuth můžou bezpečně odesílat žádosti o autorizaci. Ověřitelné toky přihlašovacích údajů využívají typy JWT k vystavování nebo ověřování přihlašovacích údajů. Je důležité používat tokeny podle specifikací. Další informace najdete v odkazech na standardy uvedené dále v tomto článku.

Použití tokenů JWT k zabezpečení rozhraní API

Při použití přístupových tokenů JWT pro autorizaci rozhraní API rozhraní API udělí nebo odmítne přístup na základě poskytnutého tokenu. Pokud požadavek není autorizovaný, vrátí se odpověď 401 nebo 403. Rozhraní API by nemělo uživatele přesměrovat na zprostředkovatele identity, aby získal nový token nebo požádal o další oprávnění. Aplikace, která rozhraní API využívá, zodpovídá za získání příslušného tokenu. Tím se zajistí jasné oddělení obav mezi rozhraním API (autorizací) a používáním klientské aplikace (ověřování).

Poznámka

HTTP také umožňuje vrátit kód 404, aby neautorizovaným klientům neprozradil informace o existenci zdrojů.

401 Neautorizováno

Odpověď 401 Neautorizováno značí, že zadaný přístupový token nesplňuje požadované standardy. Příčinou může být několik důvodů, mezi které patří:

neplatný podpis: Podpis tokenu se neshoduje, což naznačuje potenciální manipulaci.
vypršení platnosti: Platnost tokenu vypršela a už není platná.
Nesprávná tvrzení: Kritická tvrzení v rámci tokenu, jako je publikum (aud) nebo vystavovatel (iss), chybí nebo jsou neplatná.

Poznámka

Ze sémantiky HTTP RFC 9110: Server, který generuje odpověď 401, musí odeslat pole hlavičky WWW-Authenticate (oddíl 11.6.1) obsahující alespoň jeden úkol použitelný pro cílový prostředek.

Specifikace OAuth poskytují podrobné pokyny k požadovaným deklaracím identity a jejich ověřování.

403 Zakázáno

Odpověď 403 Zakázáno obvykle značí, že ověřený uživatel nemá potřebná oprávnění pro přístup k požadovanému prostředku. To se liší od problémů s ověřováním, například neplatný token a nesouvisí se standardními deklaracemi identity v rámci přístupového tokenu.

V ASP.NET Core můžete vynutit autorizaci pomocí:

Požadavky a zásady: Definujte vlastní požadavky, například "Musí být správcem" a přidružte je k zásadám. autorizaci na základě role: Přiřaďte uživatele k rolím, například Správce, Editor a omezte přístup na základě těchto rolí.

Jakou roli má OIDC nebo OAuth při použití nosných tokenů?

Pokud rozhraní API k autorizaci používá přístupové tokeny JWT, rozhraní API ověří pouze přístupový token, nikoli způsob získání tokenu.

OpenID Connect (OIDC) a OAuth 2.0 poskytují standardizované zabezpečené architektury pro získání tokenu. Získání tokenů se liší v závislosti na typu aplikace. Vzhledem ke složitosti získávání zabezpečených tokenů se důrazně doporučuje spoléhat na tyto standardy:

Pro aplikace, které fungují jménem uživatele a aplikace: Upřednostňovanou volbou je OIDC, což umožňuje delegovaný přístup uživatelů. V webových aplikacích se doporučuje použití tajného toku kódu s důkazovým klíčem pro výměnu kódů (PKCE) pro zvýšenou bezpečnost.
- Pokud je volající aplikace ASP.NET Core s ověřováním OIDC na straně serveru , můžete použít možnost SaveTokens k uložení přístupového tokenu do cookie pro pozdější použití prostřednictvím HttpContext.GetTokenAsync("access_token").
Pokud aplikace nemá žádného uživatele: Tok přihlašovacích údajů klienta OAuth 2.0 je vhodný pro získání přístupových tokenů aplikace.

Implementace ověřování pomocí nosného tokenu JWT

Balíček NuGet Microsoft.AspNetCore.Authentication.JwtBearer lze použít k ověření nosných tokenů JWT.

Nosné tokeny JWT by měly být plně ověřeny v rozhraní API. Měli byste ověřit následující:

Podpis pro důvěryhodnost a integritu. Tím se zajistí, že token byl vytvořen určenou službou zabezpečených tokenů a nebyl manipulován.
Tvrzení vydavatele s očekávanou hodnotou
Nárok cílové skupiny s očekávanou hodnotou
Vypršení platnosti tokenu

Pro přístupové tokeny OAuth 2.0 jsou vyžadovány následující deklarace identity: iss, exp, aud, sub, client_id, iata jti.

Pokud některé z těchto deklarací identity nebo hodnot nejsou správné, rozhraní API by mělo vrátit odpověď 401.

Základní ověření předkládacího tokenu JWT

Základní implementace AddJwtBearer může ověřit pouze cílovou skupinu a vystavitele. Podpis se musí ověřit, aby token mohl být důvěryhodný a že s ním nedošlo k manipulaci.

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
.AddJwtBearer(jwtOptions =>
{
	jwtOptions.Authority = "https://{--your-authority--}";
	jwtOptions.Audience = "https://{--your-audience--}";
});

Explicitní ověření tokenu nositele JWT

Metoda AddJwtBearer poskytuje více konfigurací. Někteří poskytovatelé zabezpečených tokenů používají nestandardní adresu metadat a parametr je možné nastavit explicitně. Rozhraní API může přijímat více vystavitelů nebo cílových skupin.

Explicitní definování parametrů není povinné. Definice závisí na hodnotách deklarací přístupového tokenu a na serveru zabezpečeného tokenu použitém k ověření přístupového tokenu. Pokud je to možné, měli byste použít výchozí hodnoty.

Viz Mapování nároků podrobnosti o MapInboundClaims.

builder.Services.AddAuthentication()
.AddJwtBearer("some-scheme", jwtOptions =>
{
	jwtOptions.MetadataAddress = builder.Configuration["Api:MetadataAddress"];
	// Optional if the MetadataAddress is specified
	jwtOptions.Authority = builder.Configuration["Api:Authority"];
	jwtOptions.Audience = builder.Configuration["Api:Audience"];
	jwtOptions.TokenValidationParameters = new TokenValidationParameters
	{
		ValidateIssuer = true,
		ValidateAudience = true,
		ValidateIssuerSigningKey = true,
		ValidAudiences = builder.Configuration.GetSection("Api:ValidAudiences").Get<string[]>(),
		ValidIssuers = builder.Configuration.GetSection("Api:ValidIssuers").Get<string[]>()
	};

	jwtOptions.MapInboundClaims = false;
});

JWT s několika schématy

Rozhraní API často potřebují přijmout přístupové tokeny od různých vystavitelů. Podporu více vystavitelů tokenů v rozhraní API lze provést pomocí:

samostatná rozhraní API: Vytvořte samostatná rozhraní API s vyhrazenými schématy ověřování pro jednotlivé vystavitele.
AddPolicyScheme Tato metoda může definovat více schémat ověřování a implementovat logiku pro výběr vhodného schématu na základě vlastností tokenu (např. vystavitel, deklarace identity). Tento přístup umožňuje větší flexibilitu v rámci jednoho rozhraní API.

Vynucení ověřování nositele

SetDefaultPolicy lze použít k vyžadování ověřování pro všechny požadavky i na koncové body bez atributu [Authorize]. SetDefaultPolicy nakonfiguruje zásadu použitou pro koncové body s atributem [Authorize] a výchozí nastavení vyžaduje ověřené uživatele. Další podrobnosti najdete v dokumentaci vyžadující ověřené uživatele .

var requireAuthPolicy = new AuthorizationPolicyBuilder()
	.RequireAuthenticatedUser()
	.Build();

builder.Services.AddAuthorizationBuilder()
	.SetDefaultPolicy(requireAuthPolicy);

Atribut Authorize lze také použít k vynucení ověřování. Pokud se používá více schémat, nosné schéma obecně musí být nastaveno jako výchozí schéma ověřování nebo specifikováno prostřednictvím [Authorize(AuthenticationSchemes = JwtBearerDefaults.AuthenticationScheme]).

Autorizace v kontrolerech

[Authorize]
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{

Autorizace v minimálních rozhraních API:

app.MapGet("/hello", [Authorize] () => "Hi");

Doporučené přístupy k vytvoření JWT

Nezabezpečené zpracování přístupových tokenů, jako je slabé ověřování nebo ukládání tokenů do ohroženého úložiště na straně klienta, může vést k významným ohrožením zabezpečení. Například ukládání přístupových tokenů přímo v prohlížeči pomocí místního úložiště, úložiště relací nebo webových pracovních procesů. Následující část obsahuje osvědčené postupy pro aplikace používající a vytváření přístupových tokenů.

Použití standardů

Standardy, jako je OpenID Connect nebo OAuth, by se měly při vytváření přístupových tokenů vždy používat. Přístupové tokeny by neměly být vytvářeny v produkčních aplikacích bez dodržení bezpečnostních opatření popsaných v tomto článku. Vytváření přístupových tokenů by mělo být omezené na testovací scénáře.

Použití asymetrických klíčů

Asymetrické klíče by měly při vytváření přístupových tokenů vždy používat. Veřejný klíč je k dispozici ve známých koncových bodech a klienti rozhraní API můžou ověřit podpis přístupového tokenu pomocí veřejného klíče.

Nikdy nevytvořte přístupový token z požadavku na uživatelské jméno nebo heslo.

Neměli byste NEVYTVÁŘET přístupový token z požadavku na uživatelské jméno nebo heslo. Požadavky na uživatelské jméno a heslo se neověřují a jsou zranitelné vůči útokům zosobnění a útokům phishing. Přístupové tokeny by se měly vytvářet jenom pomocí toku OpenID Connect nebo standardního toku OAuth. Odchylka od těchto standardů může mít za následek nezabezpečenou aplikaci.

Použití souborů cookie

V případě zabezpečených webových aplikací se k ukládání přístupových tokenů na důvěryhodném serveru vyžaduje back-end. V klientském prohlížeči se sdílí pouze bezpečný soubor cookie s atributem HttpOnly cookie. Podívejte se na dokumentaci k ověřování OIDC pro informace o tom, jak to udělat ve webové aplikaci ASP.NET Core.

Následná rozhraní API

Rozhraní API občas potřebují přístup k uživatelským datům z podřízených rozhraní API jménem ověřeného uživatele ve volající aplikaci. I když je implementace toku přihlašovacích údajů klienta OAuth možností, vyžaduje úplnou důvěru mezi oběma API aplikacemi. Bezpečnější přístup zahrnuje použití strategie nulové důvěryhodnosti s delegovaným přístupovým tokenem uživatele. Tento přístup:

Vylepšuje zabezpečení tím, že rozhraní API uděluje pouze potřebná oprávnění pro daného konkrétního uživatele.
Vyžaduje rozhraní API k vytvoření nového přístupového tokenu pro uživatele, který volá aplikaci a rozhraní API.

Existuje několik způsobů implementace strategie nulové důvěryhodnosti s delegovaným přístupovým tokenem uživatele:

Použití výměny tokenů OAuth 2.0 k vyžádání nového delegovaného přístupového tokenu

Toto je dobrý způsob, jak tento požadavek implementovat, ale je to složité, pokud musíte implementovat tok OAuth.

Viz OAuth 2.0 Token Exchange

Použijte web Microsoft Identity jménem služby Flow k vyžádání nového delegovaného přístupového tokenu.

Použití knihovny ověřování webu Microsoft Identity web je nejjednodušší a bezpečný přístup. Funguje jenom s MICROSOFT Entra ID, Microsoft Entra External ID.

Další informace najdete v tématu Microsoft Identity Platform a on-Behalf-Of tok OAuth 2.0.

Použití stejného delegovaného přístupového tokenu odeslaného do rozhraní API

Tento přístup není obtížné implementovat, ale přístupový token má přístup ke všem podřízeným rozhraním API. K implementaci je možné použít reverzní proxy yarp.

Použití toku přihlašovacích údajů klienta OAuth a použití přístupového tokenu aplikace

To se dá snadno implementovat, ale klientská aplikace má úplný přístup k aplikacím a ne delegovaný přístupový token. Token by se měl ukládat do mezipaměti v aplikaci klientského rozhraní API.

Poznámka

Funguje také zabezpečení mezi aplikacemi. Ověřování certifikátů nebo v Azure se dá použít spravovaná identita.

Zpracování přístupových tokenů

Pokud používáte přístupové tokeny v klientské aplikaci, musí se přístupové tokeny obměňovat, uchovávat a ukládat někde na serveru. Ve webové aplikaci se soubory cookie používají k zabezpečení relace a lze je použít k ukládání tokenů prostřednictvím možnosti SaveTokens.

SaveTokens aktuálně neaktualizuje přístupové tokeny automaticky, ale tato funkce se plánuje pro .NET 10. Sledujte https://github.com/dotnet/aspnetcore/issues/8175 pro aktualizace. Do té doby můžete přístupový token ručně aktualizovat, jak je demonstrováno v Blazor Web App dokumentaci OIDC, nebo použít balíček NuGet od třetí strany, jako je Duende.AccessTokenManagement.OpenIdConnect, ke zpracování a správě přístupových tokenů v klientské aplikaci. Další informace najdete v tématu správa tokenů Duende.

Poznámka

Pokud se nasazuje do produkčního prostředí, mezipaměť by měla fungovat v nasazení multi-instance. Obvykle se vyžaduje trvalá mezipaměť.

Některé servery zabezpečených tokenů šifrují přístupové tokeny. Přístupové tokeny nevyžadují žádný formát. Při použití introspekce OAuth se místo přístupového tokenu použije referenční token. Aplikace klienta (UI) by nikdy neměla otevřít přístupový token, protože přístupový token není určený k tomuto účelu. Přístupový token by měl otevřít pouze rozhraní API, pro které byl přístupový token vytvořen.

Neotevírejte přístupové tokeny v aplikaci uživatelského rozhraní.
Neodesílejte token ID do rozhraní API.
Přístupové tokeny můžou mít libovolný formát.
Přístupové tokeny je možné zašifrovat.
Platnost přístupových tokenů vyprší a je potřeba je otočit.
Přístupové tokeny se uchovávají na zabezpečeném back-endovém serveru.

YARP (ještě další reverzní proxy server)

YARP (další reverzní proxy server) je užitečná technologie pro zpracování požadavků HTTP a předávání požadavků jiným rozhraním API. YARP může implementovat logiku zabezpečení pro získání nových přihlašovacích údajů pro přístup. YARP se často používá při přijímání back-endu pro architekturu zabezpečení BFF (Front-end).

Příklady Blazor , které k implementaci modelu BFF používají YARP, najdete v následujících článcích:

Blazor Příklad, který k implementaci vzoru BFF používá YARP, najdete v tématu Zabezpečení ASP.NET Core Blazor Web App s OpenID Connect (OIDC).

Další informace naleznete v části auth0: Vzorec backendu pro frontend.

Testování rozhraní API

Testy integrace a kontejnery s přístupovými tokeny je možné použít k testování zabezpečených rozhraní API. Přístupové tokeny lze vytvořit pomocí nástroje dotnet user-jwts.

Varování

Ujistěte se, že nejsou problémy se zabezpečením zavedeny do rozhraní API pro účely testování. Testování je při použití delegovaných přístupových tokenů náročnější, protože tyto tokeny je možné vytvářet pouze prostřednictvím uživatelského rozhraní a toku OpenID Connect. Pokud se k vytváření delegovaných přístupových tokenů používá testovací nástroj, musí být pro testování zakázané funkce zabezpečení. Je nezbytné, aby tyto funkce byly zakázány pouze v testovacím prostředí.

Vytvořte vyhrazená a izolovaná testovací prostředí, kde je možné bezpečně zakázat nebo upravit funkce zabezpečení. Ujistěte se, že tyto změny jsou výhradně omezené na testovací prostředí.

Použití uživatelského rozhraní Swagger, Curl a dalších nástrojů uživatelského rozhraní API

Swagger UI a Curl jsou skvělé nástroje uživatelského rozhraní pro testování rozhraní API. Aby nástroje fungovaly, může rozhraní API vytvořit dokument OpenAPI a tento dokument lze načíst do klientského testovacího nástroje. Do souboru API OpenAPI je možné přidat tok zabezpečení pro získání nového přístupového tokenu.

Varování

Nenasazujte nezabezpečené toky testů zabezpečení do produkčního prostředí.

Při implementaci uživatelského rozhraní Swagger pro rozhraní API byste normálně neměli nasazovat uživatelské rozhraní do produkčního prostředí, protože zabezpečení musí být oslabené, aby to fungovalo.