Konfigurieren der JWT-Bearer-Authentifizierung in ASP.NET Core

2025-01-30

Die JWT (JSON Web Token) Bearer-Authentifizierung wird häufig für APIs verwendet. Sie funktioniert ähnlich wie die cookie-Authentifizierung, wobei der Identitätsanbieter nach erfolgreicher Authentifizierung ein JWT oder Token ausstellt. Diese Token können dann zur Authentifizierung an andere Server gesendet werden, im Gegensatz zu Cookies, die nur an die ausstellende Domäne zurückgesendet werden. Ein JWT ist ein unabhängiges Token, das Informationen für eine API-Ressource oder einen Client enthält. Der Client, der das JWT angefordert hat, kann mit Hilfe des Authorization Headers und eines Bearer Tokens Daten von einer API-Ressource anfragen.

JWT Bearer Authentication bietet folgende Funktionen:

Authentifizierung: Bei Verwendung von JwtBearerHandler sind Bearer-Token für die Authentifizierung unerlässlich. JwtBearerHandler validiert das Token und extrahiert die Identität des Benutzers aus seinen Ansprüchen.
Autorisierung: Bearer-Token ermöglichen die Autorisierung, indem sie eine Sammlung von Ansprüchen bereitstellen, die die Berechtigungen des Benutzers oder der Anwendung darstellen, ähnlich wie ein cookie.
Delegierte Autorisierung: Wenn ein benutzerspezifisches Zugriffstoken anstelle eines anwendungsweiten Tokens zur Authentifizierung zwischen APIs verwendet wird, bezeichnet man diesen Prozess als delegierte Autorisierung.

Eine Einführung in die JWT-Bearer-Authentifizierung finden Sie unter JSON-Web-Token.Beispielcode anzeigen oder herunterladen

In diesem Artikel werden die folgenden Themenbereiche behandelt:

Tokentypen
Verwendung von JWT-Tokens zur Sicherung von APIs
Wie passt OIDC/OAuth hier hinein?
Implementierung der JWT-Token-Authentifizierung
Empfohlene Ansätze zum Erstellen eines JWT

Tokentypen

Es gibt zahlreiche Arten von Token und Formaten. Vom Generieren Ihrer eigenen Zugriffstoken oder ID-Token wird, außer zu Testzwecken, abgeraten. Selbst erstellte Token, die sich nicht an etablierte Standards halten:

Können zu Sicherheitsschwachstellen führen.
Sind nur für geschlossene Systeme geeignet.

Wir empfehlen, OpenID Connect 1.0 oder einen OAuth-Standard zu verwenden, um Zugriffstoken für den API-Zugang zu erstellen.

Zugriffstoken

Zugriffstoken:

Sind Zeichenfolgen, die von einer Client App verwendet werden, um Anfragen an den Server zur Implementierung einer API zu stellen.
Sie können im Format variieren. Verschiedene APIs können unterschiedliche Formate für die Token verwenden.
Können verschlüsselt sein.
Sollten niemals von einem Web Client oder einer UI App, die das Zugriffstoken besitzt, gelesen oder interpretiert werden.
Sind ausschließlich für Anfragen an eine API bestimmt.
Werden in der Regel als Bearer-Token im Header der Autorisierungsanforderung an die API gesendet.

Siehe OAuth 2.0-Autorisierungsframework

Anwendungszugriffstoken und delegierte Zugriffstoken

Bei Zugriffstoken kann es sich um Anwendungszugriffstoken oder delegierte Zugriffstoken handeln. Die Token haben unterschiedliche Ansprüche und werden unterschiedlich verwaltet und gespeichert. Ein Zugriffstoken für die Anwendung wird in der Regel einmal in der App gespeichert, bis er abläuft, während ein delegierter Zugriffstoken pro Benutzer entweder in einem cookie oder in einem sicheren Server-Cache gespeichert wird.

Wir empfehlen, delegierte Zugriffstoken für Benutzer zu verwenden, wenn ein Benutzer beteiligt ist. Nachgeschaltete APIs können im Namen des authentifizierten Benutzers ein delegiertes Token für den Zugriff anfordern.

Eingeschränkte Zugriffstoken des Absenders

Zugriffstoken können als Bearer-Token oder eingeschränkte Token des Absenders für den Zugriff auf Ressourcen verwendet werden. Absenderbeschränkte Token erfordern, dass der anfordernde Client den Besitz eines privaten Schlüssels nachweist, um das Token zu verwenden. Der Nachweis des Besitzes eines privaten Schlüssels garantiert, dass das Token nicht unabhängig verwendet werden kann. Token mit Senderbeschränkung können auf zwei Arten implementiert werden:

ID-Token

ID-Tokens sind Sicherheits-Tokens, die die erfolgreiche Authentifizierung eines Benutzers bestätigen. Mit den Token kann der Client die Identität des Benutzers überprüfen. Der JWT-Tokenserver gibt ID-Token aus, die Ansprüche mit Benutzerinformationen enthalten. ID-Tokens sind immer im JWT--Format.

ID-Token sollten niemals für den Zugriff auf APIs verwendet werden.

Andere Tokens

Es gibt viele Arten von Token, einschließlich Zugriffs- und ID-Tokens, wie sie in den OpenID Connect- und OAuth-Standards festgelegt sind. Aktualisierungstoken können verwendet werden, um eine UI App zu aktualisieren, ohne den Benutzer erneut zu authentifizieren. OAuth JAR-Token können Autorisierungsanforderungen auf sichere Weise senden. Prüfbare Anmeldeinformationsflüsse verwenden JWT-Typen zum Ausstellen oder Überprüfen von Anmeldeinformationen. Es ist wichtig, dass Sie Token gemäß den Spezifikationen verwenden. Weitere Informationen finden Sie in den in diesem Artikel später bereitgestellten Standard-Links.

Verwendung von JWT-Tokens zur Sicherung einer API

Wenn Sie JWT-Zugriffstoken für die API-Autorisierung verwenden, gewährt oder verweigert die API den Zugriff auf der Grundlage des bereitgestellten Tokens. Wenn die Anfrage nicht autorisiert ist, wird eine 401 oder 403 Antwort zurückgegeben. Die API sollte den Benutzer nicht an den Identitätsanbieter umleiten, um ein neues Token abzurufen oder zusätzliche Berechtigungen anzufordern. Die App, die die API nutzt, ist für die Beschaffung eines geeigneten Tokens verantwortlich. Dadurch wird eine klare Trennung der Zuständigkeiten zwischen der API - Autorisierung - und der nutzenden Client-App - Authentifizierung - sichergestellt.

Hinweis

HTTP ermöglicht auch eine 404-Antwort bei fehlender Autorisierung sodass keine Informationen über das Vorhandensein von Ressourcen an nicht autorisierte Clients übergeben werden.

401 – Nicht autorisiert

Eine 401 Unauthorized-Antwort zeigt an, dass das bereitgestellte Zugriffstoken nicht die erforderlichen Standards erfüllt. Dafür kann es mehrere Gründe geben, darunter:

Ungültige Signatur: Die Signatur des Tokens stimmt nicht überein, was auf potenzielle Manipulationen hinweist.
Ablauf: Das Token ist abgelaufen und nicht mehr gültig.
Falsche Behauptungen: Wesentliche Behauptungen innerhalb des Tokens, wie etwa die Zielgruppe (aud) oder des Ausstellers (iss), fehlen oder sind ungültig.

Hinweis

Aus der HTTP-Semantik RFC 9110: Der Server, der eine 401-Antwort generiert, MUSS das Headerfeld „WWW-Authenticate“ (Abschnitt 11.6.1) senden, das mindestens eine für die Zielressource geltende Abfrage enthält.

Die OAuth-Spezifikationen stellen detaillierte Richtlinien zu den erforderlichen Ansprüchen und deren Validierung bereit.

403 Verboten

Eine 403 Forbidden Antwort weist in der Regel darauf hin, dass der authentifizierte Benutzer nicht über die erforderlichen Berechtigungen für den Zugriff auf die angeforderte Ressource verfügt. Dies unterscheidet sich von Authentifizierungsproblemen, z. B. einem ungültigen Token, und hat nichts mit den Standardansprüchen innerhalb des Zugriffstokens zu tun.

In ASP.NET Core können Sie die Autorisierung erzwingen durch:

Anforderungen und Richtlinien: Definieren Sie benutzerdefinierte Anforderungen, z. B. „Muss ein Administrator sein“, und ordnen Sie sie Richtlinien zu. Rollenbasierte Autorisierung: Weisen Sie Benutzern Rollen zu, z. B. „Admin“, „Editor“, und beschränken Sie den Zugriff auf der Grundlage dieser Rollen.

Welche Rolle spielt OIDC und/oder OAuth bei der Verwendung von Bearer Token?

Wenn eine API JWT-Zugriffstoken für die Autorisierung verwendet, überprüft die API nur das Zugriffstoken, aber nicht, wie das Token erlangt wurde.

OpenID Connect (OIDC) und OAuth 2.0 bieten standardisierte, sichere Frameworks für den Token-Erwerb. Die Anforderung von Token variiert je nach Art der App. Aufgrund der Komplexität der sicheren Vergabe von Token ist es sehr empfehlenswert, sich auf diese Standards zu verlassen:

Für Apps, die im Namen eines Benutzers und einer Anwendung handeln: OIDC ist die bevorzugte Wahl, da es den delegierten Zugriff des Benutzers ermöglicht. In Web-Apps wird der vertrauliche Codefluss mit Proof Key für Code Exchange (PKCE) für erhöhte Sicherheit empfohlen.
- Wenn die aufrufende App eine ASP.NET Core App mit serverseitiger OIDC-Authentifizierung ist, können Sie die Option SaveTokens verwenden, um Zugriffstoken in einem cookie für die spätere Verwendung über HttpContext.GetTokenAsync("access_token") zu speichern.
Wenn die App keinen Benutzer hat: Der OAuth 2.0 Client-Credentials-Flow ist geeignet für das Abrufen von Anwendungszugriffstoken.

Implementierung der JWT-Token-Authentifizierung

Das NuGet-Paket Microsoft.AspNetCore.Authentication.JwtBearer kann zum Validieren der JWT-Bearer-Token verwendet werden.

JWT-Bearer-Token sollten in einer API vollständig validiert werden. Folgendes sollte validiert werden:

Die Signatur für Vertrauen und Integrität. Dadurch wird sichergestellt, dass das Token von dem vorgesehenen sicheren Token-Dienst erstellt wurde und nicht manipuliert wurde.
Ausstelleranspruch mit dem erwarteten Wert.
Zielgruppenanspruch mit dem erwarteten Wert.
Tokenablauf.

Die folgenden Ansprüche sind für OAuth 2.0-Zugriffstoken erforderlich: iss, exp, aud, sub, client_id, iat und jti.

Wenn einer dieser Ansprüche oder Werte nicht korrekt ist, sollte die API eine 401-Antwort zurückgeben.

Grundlegende Validierung des JWT-Bearer-Tokens

Eine Standardimplementierung von AddJwtBearer kann nur die Zielgruppe und den Aussteller validieren. Die Signatur muss validiert werden, um sicherzustellen, dass das Token vertrauenswürdig ist und nicht manipuliert wurde.

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

Explizite Validierung des JWT-Bearer-Tokens

Die AddJwtBearer-Methode bietet mehrere Konfigurationen. Einige Anbieter sicherer Token verwenden eine nicht standardisierte Metadatenadresse und der Parameter kann explizit eingerichtet werden. Die API kann mehrere Aussteller oder Zielgruppen akzeptieren.

Eine explizite Definition der Parameter ist nicht erforderlich. Die Definitionen hängen von den Zugriffstoken-Anspruchswerten und dem Secure Token Server ab, der zur Validierung des Zugriffstokens verwendet wird. Sie sollten nach Möglichkeit die Standardwerte verwenden.

Siehe MapInboundClaims-Details von Mapping-Ansprüchen.

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 mit mehreren Schemata

APIs müssen oft Zugriffstoken von verschiedenen Ausstellern unterstützen. Die Unterstützung mehrerer Token-Aussteller in einer API kann durch folgende Maßnahmen erreicht werden:

Getrennte APIs: Erstellen Sie unterschiedliche APIs mit dedizierten Authentifizierungsschemata für jeden Aussteller.
AddPolicyScheme Diese Methode kann mehrere Authentifizierungsschemata definieren und eine Logik implementieren, um das geeignete Schema anhand der Token-Eigenschaften (z. B. Aussteller, Ansprüche) auszuwählen. Dieser Ansatz lässt eine größere Flexibilität innerhalb einer einzigen API zu.

Erzwingen der Bearer-Authentifizierung

SetDefaultPolicy kann verwendet werden, um eine Authentifizierung für alle Anfragen zu verlangen, selbst für Endpunkte ohne ein [Authorize]-Attribut. SetDefaultPolicy konfiguriert die Richtlinie, die für Endpunkte mit dem Attribut [Authorize] verwendet wird und standardmäßig authentifizierte Benutzer erfordert. Weitere Details finden Sie in der Dokumentation Anfordern authentifizierter Benutzer*innen.

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

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

Das Attribut Authorize kann auch verwendet werden, um die Authentifizierung zu erzwingen. Wenn mehrere Schemata verwendet werden, muss das Inhaberschema allgemein als Standard-Authentifizierungsschema festgelegt oder über [Authorize(AuthenticationSchemes = JwtBearerDefaults.AuthenticationScheme]) angegeben werden.

Autorisierung in Controllern:

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

Autorisierung in Minimal-APIs:

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

Empfohlene Ansätze zum Erstellen eines JWT

Ein unsicherer Umgang mit Zugriffstoken, wie z. B. eine schwache Authentifizierung oder das Speichern von Token in einem anfälligen Client-seitigen Storage, kann zu erheblichen Sicherheitsschwachstellen führen. Beispielsweise können Zugriffstoken mithilfe von lokalem Speicher, Sitzungsspeicher oder Webworkern direkt im Browser gespeichert werden. Der folgende Abschnitt enthält bewährte Verfahren für Apps, die Zugriffstoken verwenden und erstellen.

Standards verwenden

Beim Erstellen von Zugriffstoken müssen immer Standards wie OpenID Connect oder OAuth verwendet werden. Zugriffstoken dürfen nicht in Produktions-Apps erstellt werden, ohne die in diesem Artikel beschriebenen Sicherheitsvorkehrungen zu beachten. Das Erstellen von Zugriffstoken sollte auf Testszenarien beschränkt sein.

Asymmetrische Schlüssel verwenden

Beim Erstellen von Zugriffstoken müssen immer asymmetrische Schlüssel verwendet werden. Der öffentliche Schlüssel ist in den bekannten Endpunkten verfügbar und die API Clients können die Signatur des Zugriffstokens anhand des öffentlichen Schlüssels validieren.

Niemals ein Zugriffstoken aus einer Anfrage nach Benutzernamen/Kennwort erstellen

Ein Zugriffstoken darf NICHT aus einer Benutzername-/Kennwortanforderung erstellt werden. Benutzernamen-/Kennwortanforderungen werden nicht authentifiziert und sind durch Identitätswechsel und Phishing angreifbar. Zugriffstoken sollten nur mit einem OpenID Connect Flow oder einem OAuth Standard Flow erstellt werden. Ein Abweichen von diesen Standards kann zu einer unsicheren App führen.

Cookies verwenden

Für sichere Web-Apps ist ein Backend erforderlich, um Zugriffstoken auf einem vertrauenswürdigen Server zu speichern. Nur ein sicheres Nur-HTTP-cookie wird im Clientbrowser freigegeben. Um zu erfahren, wie Sie dies in einer ASP.NET Core Web App tun können, lesen Sie die OIDC-Authentifizierungsdokumentation.

Downstream-APIs

APIs müssen gelegentlich im Namen des authentifizierten Benutzers in der aufrufenden App auf Benutzerdaten von nachgeschalteten APIs zugreifen. Die Implementierung eines Flusses für OAuth-Clientanmeldeinformationen ist zwar eine Option, erfordert jedoch volles Vertrauen zwischen den beiden API-Apps. Ein sicherer Ansatz ist die Verwendung einer Zero-Trust-Strategie mit einem delegierten Zugriffstoken für Benutzer. Dieser Ansatz:

Erhöht die Sicherheit, indem der API nur die für den jeweiligen Benutzer erforderlichen Berechtigungen erteilt werden.
Erfordert, dass die API das neue Zugriffstoken für den Benutzer erstellt, der die App und die API aufruft.

Es gibt mehrere Möglichkeiten, eine Zero-Trust-Strategie mit einem delegierten Zugriffstoken für Benutzer zu implementieren:

Verwenden Sie OAuth 2.0 Token Exchange, um ein neues delegiertes Zugriffstoken anzufordern.

Dies ist eine gute Möglichkeit, diese Anforderung zu implementieren, aber es ist kompliziert, wenn Sie den OAuth Flow implementieren müssen.

Siehe OAuth 2.0-Tokenaustausch

Verwenden des On-Behalf-Of-Flusses von Microsoft Identity Web, um ein neues Token für den delegierten Zugriff anzufordern

Die Verwendung der Microsoft Identity Web-Authentifizierungsbibliothek ist der einfachste und sicherste Ansatz. Sie funktioniert nur mit Microsoft Entra ID und Microsoft Entra External ID.

Weitere Informationen finden Sie unter Microsoft Identity Platform und On-Behalf-Of-Fluss von OAuth 2.0.

Verwenden Sie das gleiche delegierte Zugriffstoken, das an die API gesendet wird.

Dieser Ansatz ist nicht schwer zu implementieren, aber das Zugriffstoken hat Zugriff auf alle Downstream-APIs. YARP Reverse Proxy kann verwendet werden, um dies zu implementieren.

Verwenden des Flusses für OAuth-Clientanmeldeinformationen und eines Anwendungszugriffstokens

Dies ist einfach zu implementieren, aber die Client-Anwendung hat vollen Zugriff auf die Anwendung und nicht auf ein delegiertes Zugriffstoken. Das Token sollte in der Client-API-Anwendung zwischengespeichert werden.

Hinweis

Jede App-zu-App-Sicherheit funktioniert ebenfalls. Es kann eine Zertifikatsauthentifizierung oder, in Azure, eine verwaltete Identität verwendet werden.

Behandeln von Zugriffstoken

Wenn Zugriffstoken in einer Clientanwendung verwendet werden, müssen die Zugriffstoken rotiert, beibehalten und irgendwo auf dem Server gespeichert werden. In einer Web-Anwendung werden Cookies verwendet, um die Sitzung zu sichern und können über die Option SaveTokens zum Speichern von Token verwendet werden.

SaveTokens wird Zugriffstoken aktuell nicht automatisch aktualisieren, aber diese Funktionalität ist für .NET 10 geplant. Folgen Sie https://github.com/dotnet/aspnetcore/issues/8175 für Updates. In der Zwischenzeit können Sie das Zugriffstoken manuell aktualisieren, wie in der Dokumentation zu Blazor Web App mit OIDC gezeigt, oder ein NuGet-Paket eines Drittanbieters wie Duende.AccessTokenManagement.OpenIdConnect für die Handhabung und Verwaltung von Zugriffstoken in der Client-App verwenden. Weitere Informationen finden Sie unter „Token Management“ bei Duende.

Hinweis

Wenn Sie den Cache in der Produktion bereitstellen, sollte er in einer Bereitstellung mit mehreren Instanzen funktionieren. Normalerweise ist ein persistenter Cache erforderlich.

Einige sichere Token-Server verschlüsseln die Zugriffstoken. Für Zugriffstoken ist kein Format erforderlich. Bei Verwendung der OAuth-Introspektion wird ein Referenz-Token anstelle eines Zugriffstokens verwendet. Eine Client-Anwendung (UI) sollte niemals ein Zugriffstoken öffnen, da das Zugriffstoken dafür nicht vorgesehen ist. Nur eine API, für die das Zugriffstoken erstellt wurde, darf das Zugriffstoken öffnen.

Öffnen Sie keine Zugriffstoken in einer UI-Anwendung.
Senden Sie das ID-Token nicht an die APIs
Zugriffstoken können ein beliebiges Format haben
Zugriffstoken können verschlüsselt sein
Zugriffstoken laufen ab und müssen erneuert werden
Zugriffstoken werden auf einem sicheren Backend-Server aufbewahrt

YARP (noch ein weiterer Reverse-Proxy)

YARP (Yet Another Reverse Proxy) ist eine nützliche Technologie zum Behandeln von HTTP-Anforderungen und zum Weiterleiten der Anforderungen an andere APIs. YARP kann Sicherheitslogik zum Abrufen neuer Zugangsdaten implementieren. YARP wird häufig im Zusammenhang mit der BFF-Sicherheitsarchitektur (Backend für Frontend) verwendet.

Blazor Beispiele, in denen YARP zum Implementieren des BFF-Musters verwendet wird, finden Sie in den folgenden Artikeln:

Ein Beispiel, in dem YARP zum Implementieren des BFF-Musters verwendet wird, finden Sie unter Blazor.

Weitere Informationen finden Sie unter auth0: Das Back-End für Frontend-Muster.

Testen von APIs

Integrationstests und Container mit Zugriffstoken können verwendet werden, um sichere APIs zu testen. Zugriffstoken können mit dem Tool „dotnet user-jwts“ erstellt werden.

Warnung

Stellen Sie sicher, dass Sicherheitsprobleme nicht zu Testzwecken in die API eingeführt werden Das Testen wird schwieriger, wenn delegierte Zugriffstoken verwendet werden, da diese Token nur über eine Benutzeroberfläche und einen OpenID Connect Flow erstellt werden können. Wenn ein Test Tool verwendet wird, um delegierte Zugriffstoken zu erstellen, müssen die Sicherheitsfunktionen für das Testen deaktiviert werden. Es ist wichtig, dass diese Funktionen nur in der Testumgebung deaktiviert sind.

Erstellen Sie dedizierte und isolierte Testumgebungen, in denen die Sicherheitsfunktionen sicher deaktiviert oder geändert werden können. Stellen Sie sicher, dass diese Änderungen strikt auf die Testumgebung beschränkt sind.

Verwenden Sie Swagger UI, Curl und andere UI-Tools für APIs

Swagger UI und Curl sind großartige UI Tools zum Testen von APIs. Damit die Tools funktionieren, kann die API ein OpenAPI-Dokument erstellen und dieses in das Client-Testing Tool geladen werden. Der OpenAPI-Datei der API kann ein Sicherheitsfluss zum Abrufen eines neuen Zugriffstokens hinzugefügt werden.

Warnung

Stellen Sie keine unsicheren Testprozesse in der Produktionsumgebung bereit.

Wenn Sie eine Swagger UI für eine API implementieren, sollten Sie die UI normalerweise nicht in der Produktion bereitstellen, da die Sicherheit geschwächt werden muss, um die Möglichkeit zu bieten, dass dies funktioniert.