Freigeben über

Schützen einer ASP.NET Core Blazor Web App mit Microsoft Entra ID

Dieser Artikel beschreibt, wie Sie ein Blazor Web App mit der Microsoft Identity Platform und den Microsoft Identity Webpaketen für Microsoft Entra ID mithilfe einer Beispielanwendung sichern können.

Diese Version des Artikels behandelt die Implementierung von Entra, ohne das Back-End für Frontend (BFF)-Muster zu übernehmen. Das BFF-Muster ist nützlich, um authentifizierte Anforderungen an externe Dienste zu senden. Ändern Sie die Artikelversionsauswahl in BFF-Muster , wenn die Spezifikation der App aufruft, das BFF-Muster zu übernehmen.

Die folgende Spezifikation wird behandelt:

  • Der Blazor Web App verwendet den Auto-Render-Modus mit globaler Interaktivität (InteractiveAuto).
  • Das Serverprojekt ruft AddAuthenticationStateSerialization auf, um einen serverseitigen Authentifizierungsstatusanbieter hinzuzufügen, der PersistentComponentState verwendet, um den Authentifizierungsstatus an den Client weiterzuleiten. Der Client ruft AddAuthenticationStateDeserialization auf, um den vom Server übergebenen Authentifizierungszustand zu deserialisieren und zu nutzen. Der Authentifizierungsstatus wird für die Lebensdauer der WebAssembly-Anwendung festgelegt.
  • Die App verwendet Microsoft Entra ID, basierend auf Microsoft Identity Web Paketen.
  • Automatische nicht-interaktive Tokenaktualisierung wird vom Framework verwaltet.
  • Die App nutzt serverseitige und clientseitige Dienst-Exposées, um generierte Wetterdaten anzuzeigen.
    • Beim Rendern der Weather-Komponente auf dem Server zum Anzeigen von Wetterdaten verwendet die Komponente die ServerWeatherForecaster. Microsoft Identity Webpakete stellen API bereit, um einen benannten nachgelagerten Webdienst für Web-API-Aufrufe zu erstellen. IDownstreamApi wird in ServerWeatherForecaster eingefügt, welches verwendet wird, um CallApiForUserAsync zum Abrufen von Wetterdaten aus einer externen Web-API (MinimalApiJwt Projekt) aufzurufen.
    • Wenn die Weather-Komponente auf dem Client gerendert wird, verwendet die Komponente die ClientWeatherForecaster-Dienstimplementierung, die eine vorkonfigurierte HttpClient (in der Client-Projektdatei Program) nutzt, um einen Web-API-Aufruf an die Minimal-API des Serverprojekts (/weather-forecast) für Wetterdaten zu machen. Der Minimal-API-Endpunkt erhält die Wetterdaten von der „ServerWeatherForecaster“-Klasse und gibt sie an den Client zur Darstellung durch die Komponente zurück.

Beispiellösung

Die Beispiellösung besteht aus den folgenden Projekten:

  • BlazorWebAppEntra: Serverseitiges Projekt des Blazor Web App, das einen Beispiel-Minimal-API-Endpunkt für Wetterdaten enthält.
  • BlazorWebAppEntra.Client: Clientseitiges Projekt der Blazor Web App.
  • MinimalApiJwt: Back-End-Web-API mit einem Beispiel für einen minimalen API-Endpunkt für Wetterdaten.

Greifen Sie auf das Beispiel über den neuesten Versionsordner im Repository für Blazor Beispiele mit dem folgenden Link zu. Das Beispiel befindet sich im BlazorWebAppEntra Ordner für .NET 9 oder höher.

Starten Sie die Lösung vom Aspire/Aspire.AppHost Projekt.

Anzeigen oder Herunterladen von Beispielcode (Anleitung zum Herunterladen)

Microsoft Entra ID-App-Registrierungen

Es wird empfohlen, separate Registrierungen für Apps und Web-APIs zu verwenden, auch wenn sich die Apps und Web-APIs in derselben Lösung befinden. Der folgende Leitfaden richtet sich an die BlazorWebAppEntra App- und MinimalApiJwt Web-API der Beispiellösung, gilt jedoch im Allgemeinen für alle Entra-basierten Registrierungen für Apps und Web-APIs.

Registrieren Sie zuerst die Web-API (MinimalApiJwt), damit Sie beim Registrieren der App Zugriff auf die Web-API gewähren können. Die Mandanten-ID und Client-ID der Web-API werden verwendet, um die Web-API in ihrer Program Datei zu konfigurieren. Nachdem Sie die Web-API registriert haben, exponieren Sie die Web-API in App-Registrierungen>API exponieren mit einem Bereichsnamen von Weather.Get. Notieren Sie den App-ID-URI für die Verwendung in der App-Konfiguration.

Registrieren Sie als Nächstes die App (BlazorWebAppEntra) mit einer Webplattformkonfiguration mit zwei Einträgen unter Umleitungs-URI: https://localhost/signin-oidc und https://localhost/signout-callback-oidc (Ports sind für diese URIs nicht erforderlich). Legen Sie die Anmelde-URL des Frontkanals auf https://localhost/signout-callback-oidc (ein Port ist nicht erforderlich). Die Mandanten-ID, die Mandantendomäne und die Client-ID der App werden zusammen mit der Basisadresse, dem App-ID-URI und dem Wetterbereichsnamen der Web-API verwendet, um die App in der appsettings.json Datei zu konfigurieren. Erteilen Sie API-Berechtigungen zum Zugriff auf die Web-API unter App-Registrierungen>API-Berechtigungen. Wenn die Sicherheitsspezifikation der App dies aufruft, können Sie der Organisation die Zustimmung des Administrators für den Zugriff auf die Web-API erteilen. Autorisierte Benutzer und Gruppen werden der Registrierung der App in App-Registrierungen>Enterprise-Anwendungen zugewiesen.

Konfigurieren Sie in der Entra- oder Azure-Portal-Konfiguration der impliziten Genehmigung und hybriden Bewegungsarten der App-Registrierung, dass Sie kein Kontrollkästchen aktivieren, damit der Autorisierungsendpunkt keine Zugriffstoken oder ID-Token zurückgibt. Der OpenID Connect-Anforderungshandler fordert automatisch die entsprechenden Token an, indem er den vom Autorisierungsendpunkt zurückgegebenen Code verwendet.

Erstellen Sie ein Client-Geheimnis in der App-Registrierung im Entra- oder Azure-Portal (Verwalten>Zertifikate und Geheimnisse>neues Client-Geheimnis). Warten Sie auf den geheimen Clientschlüssel Wert zur Nutzung im nächsten Abschnitt.

Weitere Anleitungen zur Entra-Konfiguration für bestimmte Einstellungen finden Sie weiter unten in diesem Artikel.

Serverseitiges Blazor Web App Projekt (BlazorWebAppEntra)

Das BlazorWebAppEntra-Projekt ist das serverseitige Projekt des Blazor Web App.

Clientseitiges Blazor Web App Projekt (BlazorWebAppEntra.Client)

Das BlazorWebAppEntra.Client-Projekt ist das clientseitige Projekt des Blazor Web App.

Wenn der Benutzer sich während des clientseitigen Renderings an- oder abmelden muss, wird ein vollständiges Neuladen der Seite initiiert.

Back-End-Web-API-Projekt (MinimalApiJwt)

Das Projekt MinimalApiJwt ist eine Back-End-Web-API für mehrere Front-End-Projekte. Das Projekt konfiguriert einen minimalen API-Endpunkt für Wetterdaten.

Die Datei MinimalApiJwt.http kann zum Testen der Wetterdatenanforderung verwendet werden. Beachten Sie, dass das MinimalApiJwt-Projekt ausgeführt werden muss, um den Endpunkt zu testen, wobei der Endpunkt in der Datei hartcodiert ist. Weitere Informationen finden Sie unter Verwenden von HTTP-Dateien in Visual Studio 2022.

Das Projekt enthält Pakete und Konfigurationen zum Erstellen von OpenAPI-Dokumenten.

Ein sicherer Wettervorhersagedatenendpunkt befindet sich in der Datei des Program Projekts:

app.MapGet("/weather-forecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
}).RequireAuthorization();

Für die RequireAuthorization-Erweiterungsmethode ist eine Autorisierung für die Routendefinition erforderlich. Fügen Sie für alle Controller, die Sie dem Projekt hinzufügen, das [Authorize] Attribut dem Controller oder der Aktion hinzu.

Konfigurieren des Back-End-Web-API-Projekts (MinimalApiJwt)

Konfigurieren Sie das Projekt im JwtBearerOptions des AddJwtBearer-Aufrufs in der Datei MinimalApiJwt des Program-Projekts.

Für die Registrierung der Web-API-App wird der Weather.Get Bereich im Entra- oder Azure-Portal in "Verfügbarmachen einer API" konfiguriert.

Authority legt die autoritative Stelle für OIDC-Aufrufe fest.

jwtOptions.Authority = "{AUTHORITY}";

** In den folgenden Beispielen werden eine Mandanten-ID von aaaabbbb-0000-cccc-1111-dddd2222eeee und ein Verzeichnisname von contoso verwendet.

Wenn die App in einem ME-ID-Mandanten registriert wurde, sollte die Autorität dem Aussteller (iss) in dem vom Identitätsanbieter zurückgegebenen JWT entsprechen:

jwtOptions.Authority = "https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee";

Wenn die App in einem externen Microsoft Entra-ID-Mandanten registriert ist:

jwtOptions.Authority = "https://contoso.ciamlogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0";

Wenn die App in einem AAD B2C-Mandanten registriert ist:

jwtOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0";

Note

Azure Active Directory B2C ist ab dem 1. Mai 2025 nicht mehr als Dienst für neue Kunden verfügbar. AAD B2C-Mandanten werden für Kunden mit Konten unterstützt, die vor dem 1. Mai 2025 bis 2030 eingerichtet wurden. Weitere Informationen finden Sie unter Azure AD B2C: Häufig gestellte Fragen (FAQ)

Audience legt die Zielgruppe für alle empfangenen JWT-Zugriffstoken fest.

jwtOptions.Audience = "{AUDIENCE}";

Stimmen Sie den Wert nur auf den Pfad des Anwendungs-ID-URI ab, der beim Hinzufügen des Weather.Get-Bereichs unter API bereitstellen im Entra- oder Azure-Portal konfiguriert wurde. Fügen Sie den Bereichsnamen "Weather.Get," nicht in den Wert ein.

Die folgenden Beispiele verwenden eine Anwendungs-ID (Client-ID) von 11112222-bbbb-3333-cccc-4444dddd5555. Im dritten Beispiel wird eine Mandantendomäne von contoso.onmicrosoft.com.

ME-ID Mieterbeispiel:

jwtOptions.Audience = "api://11112222-bbbb-3333-cccc-4444dddd5555";

Externer Microsoft Entra-ID-Mandant:

jwtOptions.Audience = "11112222-bbbb-3333-cccc-4444dddd5555";

AAD B2C-Mandant Beispiel:

jwtOptions.Audience = "https://contoso.onmicrosoft.com/11112222-bbbb-3333-cccc-4444dddd5555";

Konfigurieren des Serverprojekts (BlazorWebAppEntra)

AddMicrosoftIdentityWebApp aus Microsoft Identity Web (Microsoft.Identity.Web NuGet-Paket, API-Dokumentation) wird in der Datei des BlazorWebAppEntraProgram Projekts konfiguriert.

Rufen Sie die Anwendungs-ID (Client-ID), die Mandantendomäne (Herausgeber) und die Verzeichnis-ID (Mandant) aus der Registrierung der App im Entra- oder Azure-Portal ab. Der App-ID-URI wird für den Weather.Get Bereich aus der Registrierung der Web-API abgerufen. Schließen Sie den Bereichsnamen aus, wenn Sie die App-ID-URI aus dem Portal entnehmen.

Die Authentifizierungskonfiguration hängt vom Mandantentyp ab:

ME-ID Mandantenkonfiguration

Dieser Abschnitt gilt für eine App, die in einer Microsoft Entra-ID oder einem Azure AAD B2C-Mandanten registriert ist.

In der BlazorWebAppEntra-Projektdatei Program geben Sie die Werte für die folgenden Platzhalter in der Microsoft-Identity-Webkonfiguration an:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(msIdentityOptions =>
    {
        msIdentityOptions.CallbackPath = "/signin-oidc";
        msIdentityOptions.ClientId = "{CLIENT ID (BLAZOR APP)}";
        msIdentityOptions.Domain = "{DIRECTORY NAME}.onmicrosoft.com";
        msIdentityOptions.Instance = "https://login.microsoftonline.com/";
        msIdentityOptions.ResponseType = "code";
        msIdentityOptions.TenantId = "{TENANT ID}";
    })
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("DownstreamApi", configOptions =>
    {
        configOptions.BaseUrl = "{BASE ADDRESS}";
        configOptions.Scopes = ["{APP ID URI}/Weather.Get"];
    })
    .AddDistributedTokenCaches();

Platzhalter in der vorherigen Konfiguration:

  • {CLIENT ID (BLAZOR APP)}: Die Client-ID der Anwendung.
  • {DIRECTORY NAME}: Der Verzeichnisname der Mandantendomäne.
  • {TENANT ID}: Die Registrierungs-ID (Mandant).
  • {BASE ADDRESS}: Die Basisadresse der Web-API.
  • {APP ID URI}: Die App-ID-URI für Web-API-Bereiche. Eines der folgenden Formate wird verwendet, wobei der {CLIENT ID (WEB API)} Platzhalter die Client-ID der Entra-Registrierung der Web-API ist, und der {DIRECTORY NAME} Platzhalter ist der Verzeichnisname der Domäne des Mandanten (Herausgeber) (Beispiel: contoso).
    • ME-ID Mandant Format: api://{CLIENT ID (WEB API)}
    • B2C-Mandant-Format https://{DIRECTORY NAME}.onmicrosoft.com/{CLIENT ID (WEB API)}

Example:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(msIdentityOptions =>
    {
        msIdentityOptions.CallbackPath = "/signin-oidc";
        msIdentityOptions.ClientId = "00001111-aaaa-2222-bbbb-3333cccc4444";
        msIdentityOptions.Domain = "contoso.onmicrosoft.com";
        msIdentityOptions.Instance = "https://login.microsoftonline.com/";
        msIdentityOptions.ResponseType = "code";
        msIdentityOptions.TenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee";
    })
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("DownstreamApi", configOptions =>
    {
        configOptions.BaseUrl = "https://localhost:7277";
        configOptions.Scopes = ["api://11112222-bbbb-3333-cccc-4444dddd5555/Weather.Get"];
    })
    .AddDistributedTokenCaches();

Konfiguration der externen Microsoft Entra-ID

Dieser Abschnitt bezieht sich auf eine App, die in einem externen Microsoft Entra-ID-Mandanten registriert ist.

In der BlazorWebAppEntra-Projektdatei Program geben Sie die Werte für die folgenden Platzhalter in der Microsoft-Identity-Webkonfiguration an:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(msIdentityOptions =>
    {
        msIdentityOptions.CallbackPath = "/signin-oidc";
        msIdentityOptions.Authority = "https://{DIRECTORY NAME}.ciamlogin.com/{TENANT ID}/v2.0";
        msIdentityOptions.ClientId = "{CLIENT ID (BLAZOR APP)}";
        msIdentityOptions.ResponseType = "code";
    })
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("DownstreamApi", configOptions =>
    {
        configOptions.BaseUrl = "{BASE ADDRESS}";
        configOptions.Scopes = ["{APP ID URI}/Weather.Get"];
    })
    .AddDistributedTokenCaches();

Platzhalter in der vorherigen Konfiguration:

  • {DIRECTORY NAME}: Der Verzeichnisname der Mandantendomäne.
  • {CLIENT ID (BLAZOR APP)}: Die Client-ID der Anwendung.
  • {BASE ADDRESS}: Die Basisadresse der Web-API.
  • {APP ID URI}: Die App-ID-URI für Web-API-Bereiche. Eines der folgenden Formate wird verwendet, wobei der {CLIENT ID (WEB API)} Platzhalter die Client-ID der Entra-Registrierung der Web-API ist und der {DIRECTORY NAME} Platzhalter der Verzeichnisname der Mandantendomäne (Herausgeber) ist (Beispiel: contoso).
    • ME-ID- oder Microsoft Entra External ID-Mandantenformat: api://{CLIENT ID (WEB API)}
    • B2C-Mandant-Format https://{DIRECTORY NAME}.onmicrosoft.com/{CLIENT ID (WEB API)}

Example:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(msIdentityOptions =>
    {
        msIdentityOptions.CallbackPath = "/signin-oidc";
        msIdentityOptions.Authority = "https://contoso.ciamlogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0";
        msIdentityOptions.ClientId = "00001111-aaaa-2222-bbbb-3333cccc4444";
        msIdentityOptions.ResponseType = "code";
    })
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("DownstreamApi", configOptions =>
    {
        configOptions.BaseUrl = "https://localhost:7277";
        configOptions.Scopes = ["api://11112222-bbbb-3333-cccc-4444dddd5555/Weather.Get"];
    })
    .AddDistributedTokenCaches();

Der Rückrufpfad („CallbackPath“) muss mit dem Umleitungs-URI (Login-Rückrufpfad) übereinstimmen, der bei der Registrierung der Anwendung im Entra- oder Azure-Portal konfiguriert wurde. Pfade werden auf dem Blatt "Authentifizierung " der App-Registrierung konfiguriert. Der Standardwert von CallbackPath ist /signin-oidc für eine registrierte Umleitungs-URI von https://localhost/signin-oidc (ein Anschluss ist nicht erforderlich).

Der SignedOutCallbackPath ist der Anforderungspfad innerhalb des Basis-Pfads der App, der vom OpenID-Verbinden-Handler abgefangen wird, wo der Benutzer-Agent zuerst zurückgegeben wird, nachdem er sich von Entra abgemeldet hat. Die Beispiel-App legt keinen Wert für den Pfad fest, da der Standardwert von "/signout-callback-oidc" verwendet wird. Nach dem Abfangen der Anfrage leitet der OpenID Connect Handler auf den SignedOutRedirectUri oder RedirectUri um, falls angegeben.

Warning

Speichern Sie keine geheimen App-Schlüssel, Verbindungszeichenfolgen, Anmeldeinformationen, Kennwörter, persönliche Identifikationsnummern (PINs), privaten C#/.NET-Code oder private Schlüssel/Token im clientseitigen Code, der immer unsicher ist. In Test- oder Stagingumgebungen und Produktionsumgebungen sollten serverseitiger Blazor-Code und Web-APIs sichere Authentifizierungsflows verwenden, die die Verwaltung von Anmeldeinformationen innerhalb von Projektcode oder Konfigurationsdateien vermeiden. Außerhalb der lokalen Entwicklungstests wird empfohlen, die Verwendung von Umgebungsvariablen zum Speichern vertraulicher Daten zu vermeiden, da Umgebungsvariablen nicht der sicherste Ansatz sind. Für lokale Entwicklungstests wird das Tool "Geheimer Manager " zum Sichern vertraulicher Daten empfohlen. Weitere Informationen finden Sie unter "Sichere Verwaltung vertraulicher Daten und Anmeldeinformationen".

Diese Version des Artikels behandelt die Implementierung von Entra mit dem Backend für Frontend (BFF)-Muster. Ändern Sie die Artikelversionsauswahl in ein Nicht-BFF-Muster , wenn die Spezifikation der App nicht zum Übernehmen des BFF-Musters aufruft.

Die folgende Spezifikation wird behandelt:

  • Der Blazor Web App verwendet den Auto-Render-Modus mit globaler Interaktivität (InteractiveAuto).
  • Das Serverprojekt ruft AddAuthenticationStateSerialization auf, um einen serverseitigen Authentifizierungsstatusanbieter hinzuzufügen, der PersistentComponentState verwendet, um den Authentifizierungsstatus an den Client weiterzuleiten. Der Client ruft AddAuthenticationStateDeserialization auf, um den vom Server übergebenen Authentifizierungszustand zu deserialisieren und zu nutzen. Der Authentifizierungsstatus wird für die Lebensdauer der WebAssembly-Anwendung festgelegt.
  • Die App verwendet Microsoft Entra ID, basierend auf Microsoft Identity Web Paketen.
  • Automatische nicht-interaktive Tokenaktualisierung wird vom Framework verwaltet.
  • Das Backend for Frontend (BFF) Muster wird mit Aspire für die Service-Erkennung und YARP für die Weiterleitung von Anfragen an einen Wettervorhersage-Endpunkt in der Backend-App übernommen.
    • Eine Backend-Web-API verwendet die JWT-Träger-Authentifizierung, um JWT-Tokens zu validieren, die von Blazor Web App in der Anmeldung cookie gespeichert wurden.
    • Aspire verbessert die Erfahrung beim Erstellen von .NET Cloud-nativen Apps. Es bietet einen konsistenten, festgelegten Satz von Tools und Mustern zum Entwickeln und Betreiben verteilter Apps.
    • YARP (Yet Another Reverse Proxy) ist eine Bibliothek, die zum Erstellen eines Reverseproxyservers verwendet wird.
  • Die App verwendet serverseitige und clientseitige Dienstabstraktionen, um generierte Wetterdaten anzuzeigen.
    • Beim Rendern der Weather-Komponente auf dem Server zum Anzeigen von Wetterdaten verwendet die Komponente die ServerWeatherForecaster. Microsoft Identity Webpakete stellen API bereit, um einen benannten nachgelagerten Webdienst für Web-API-Aufrufe zu erstellen. IDownstreamApi wird in ServerWeatherForecaster eingefügt, welches verwendet wird, um CallApiForUserAsync zum Abrufen von Wetterdaten aus einer externen Web-API (MinimalApiJwt Projekt) aufzurufen.
    • Wenn die Weather-Komponente auf dem Client gerendert wird, verwendet die Komponente die ClientWeatherForecaster-Dienstimplementierung, die eine vorkonfigurierte HttpClient (in der Client-Projektdatei Program) nutzt, um einen Web-API-Aufruf an die Minimal-API des Serverprojekts (/weather-forecast) für Wetterdaten zu machen. Der Minimal-API-Endpunkt ruft ein Zugriffstoken für den Benutzer ab, indem er GetAccessTokenForUserAsync aufruft. Zusammen mit den korrekten Bereichen wird ein Reverseproxy-Aufruf an die externe Web-API („MinimalApiJwt-Projekt“) durchgeführt, um Wetterdaten zu erhalten und an den Client zur Darstellung durch die Komponente zurückzugeben.

Prerequisites

Aspire erfordert Visual Studio , Version 17.10 oder höher.

Weitere Informationen finden Sie im Abschnitt "Voraussetzungen" der Schnellstartanleitung: Erstellen Ihrer ersten Aspire Lösung.

Beispiellösung

Die Beispiellösung besteht aus den folgenden Projekten:

  • Aspire:
    • Aspire.AppHost: Wird verwendet, um die übergeordneten Orchestrierungsaufgaben der App zu verwalten.
    • Aspire.ServiceDefaults: Enthält Standardkonfigurationen für Aspire Apps, die nach Bedarf erweitert und angepasst werden können.
  • MinimalApiJwt: Back-End-Web-API mit einem Beispiel für einen minimalen API-Endpunkt für Wetterdaten.
  • BlazorWebAppEntra: Server-seitiges Projekt der Blazor Web App.
  • BlazorWebAppEntra.Client: Clientseitiges Projekt der Blazor Web App.

Greifen Sie auf das Beispiel über den neuesten Versionsordner im Repository für Blazor Beispiele mit dem folgenden Link zu. Das Beispiel befindet sich im BlazorWebAppEntraBff Ordner für .NET 9 oder höher.

Anzeigen oder Herunterladen von Beispielcode (Anleitung zum Herunterladen)

Microsoft Entra ID-App-Registrierungen

Es wird empfohlen, separate Registrierungen für Apps und Web-APIs zu verwenden, auch wenn sich die Apps und Web-APIs in derselben Lösung befinden. Der folgende Leitfaden richtet sich an die BlazorWebAppEntra App- und MinimalApiJwt Web-API der Beispiellösung, gilt jedoch im Allgemeinen für alle Entra-basierten Registrierungen für Apps und Web-APIs.

Registrieren Sie zuerst die Web-API (MinimalApiJwt), damit Sie beim Registrieren der App Zugriff auf die Web-API gewähren können. Die Mandanten-ID und Client-ID der Web-API werden verwendet, um die Web-API in ihrer Program Datei zu konfigurieren. Nachdem Sie die Web-API registriert haben, exponieren Sie die Web-API in App-Registrierungen>API exponieren mit einem Bereichsnamen von Weather.Get. Notieren Sie den App-ID-URI für die Verwendung in der App-Konfiguration.

Registrieren Sie als Nächstes die App (BlazorWebAppEntra) mit einer Webplattformkonfiguration mit zwei Einträgen unter Umleitungs-URI: https://localhost/signin-oidc und https://localhost/signout-callback-oidc (Ports sind für diese URIs nicht erforderlich). Die Mandanten-ID, die Mandantendomäne und die Client-ID der App werden zusammen mit der Basisadresse, dem App-ID-URI und dem Wetterbereichsnamen der Web-API verwendet, um die App in der appsettings.json Datei zu konfigurieren. Erteilen Sie API-Berechtigungen zum Zugriff auf die Web-API unter App-Registrierungen>API-Berechtigungen. Wenn die Sicherheitsspezifikation der App dies aufruft, können Sie der Organisation die Zustimmung des Administrators für den Zugriff auf die Web-API erteilen. Autorisierte Benutzer und Gruppen werden der Registrierung der App in App-Registrierungen>Enterprise-Anwendungen zugewiesen.

Konfigurieren Sie in der Entra- oder Azure-Portal-Konfiguration der impliziten Genehmigung und hybriden Bewegungsarten der App-Registrierung, dass Sie kein Kontrollkästchen aktivieren, damit der Autorisierungsendpunkt keine Zugriffstoken oder ID-Token zurückgibt. Der OpenID Connect-Anforderungshandler fordert automatisch die entsprechenden Token an, indem er den vom Autorisierungsendpunkt zurückgegebenen Code verwendet.

Erstellen Sie ein Client-Geheimnis in der App-Registrierung im Entra- oder Azure-Portal (Verwalten>Zertifikate und Geheimnisse>neues Client-Geheimnis). Warten Sie auf den geheimen Clientschlüssel Wert zur Nutzung im nächsten Abschnitt.

Weitere Anleitungen zur Entra-Konfiguration für bestimmte Einstellungen finden Sie weiter unten in diesem Artikel.

Aspire Projekte

Weitere Informationen zur Verwendung von und Details zu den Projekten und der Beispiel-App finden Sie in der -Dokumentation.

Bestätigen Sie, dass Sie die Voraussetzungen für Aspire erfüllt haben. Weitere Informationen finden Sie im Abschnitt "Voraussetzungen" der Schnellstartanleitung: Erstellen Ihrer ersten Aspire Lösung.

Die Beispiel-App konfiguriert nur ein unsicheres HTTP-Startprofil (http) für die Verwendung während der Entwicklungstests. Für weitere Informationen, einschließlich eines Beispiels für unsichere und sichere Starteinstellungen-Profile, siehe Zulassen unsicherer Datentransport in Aspire (Aspire Dokumentation).

Serverseitiges Blazor Web App Projekt (BlazorWebAppEntra)

Das BlazorWebAppEntra-Projekt ist das serverseitige Projekt des Blazor Web App.

Clientseitiges Blazor Web App Projekt (BlazorWebAppEntra.Client)

Das BlazorWebAppEntra.Client-Projekt ist das clientseitige Projekt des Blazor Web App.

Wenn der Benutzer sich während des clientseitigen Renderings an- oder abmelden muss, wird ein vollständiges Neuladen der Seite initiiert.

Back-End-Web-API-Projekt (MinimalApiJwt)

Das Projekt MinimalApiJwt ist eine Back-End-Web-API für mehrere Front-End-Projekte. Das Projekt konfiguriert einen minimalen API-Endpunkt für Wetterdaten. Anfragen aus dem Blazor Web App server-seitigen Projekt (BlazorWebAppEntra) werden an das MinimalApiJwt-Projekt weitergeleitet.

Die Datei MinimalApiJwt.http kann zum Testen der Wetterdatenanforderung verwendet werden. Beachten Sie, dass das MinimalApiJwt-Projekt ausgeführt werden muss, um den Endpunkt zu testen, wobei der Endpunkt in der Datei hartcodiert ist. Weitere Informationen finden Sie unter Verwenden von HTTP-Dateien in Visual Studio 2022.

Das Projekt enthält Pakete und Konfigurationen zum Erstellen von OpenAPI-Dokumenten.

Ein sicherer Wettervorhersagedatenendpunkt befindet sich in der Datei des Program Projekts:

app.MapGet("/weather-forecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
}).RequireAuthorization();

Für die RequireAuthorization-Erweiterungsmethode ist eine Autorisierung für die Routendefinition erforderlich. Fügen Sie für alle Controller, die Sie dem Projekt hinzufügen, das [Authorize] Attribut dem Controller oder der Aktion hinzu.

Konfigurieren des Back-End-Web-API-Projekts (MinimalApiJwt)

Konfigurieren Sie das MinimalApiJwt-Projekt im JwtBearerOptions des AddJwtBearer-Aufrufs in der Projektdatei Program.

Für die Registrierung der Web-API-App wird der Weather.Get Bereich im Entra- oder Azure-Portal in "Verfügbarmachen einer API" konfiguriert.

Authority legt die autoritative Stelle für OIDC-Aufrufe fest.

jwtOptions.Authority = "{AUTHORITY}";

In den folgenden Beispielen wird eine Mandanten-ID von aaaabbbb-0000-cccc-1111-dddd2222eeee und ein Verzeichnisname von contoso verwendet.

Wenn die App in einem ME-ID-Mandanten registriert wurde, sollte die Autorität dem Aussteller (iss) in dem vom Identitätsanbieter zurückgegebenen JWT entsprechen:

jwtOptions.Authority = "https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee";

Wenn die App in einem externen Microsoft Entra-ID-Mandanten registriert ist:

jwtOptions.Authority = "https://contoso.ciamlogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0";

Wenn die App in einem AAD B2C-Mandanten registriert ist:

jwtOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0";

Note

Azure Active Directory B2C ist ab dem 1. Mai 2025 nicht mehr als Dienst für neue Kunden verfügbar. AAD B2C-Mandanten werden für Kunden mit Konten unterstützt, die vor dem 1. Mai 2025 bis 2030 eingerichtet wurden. Weitere Informationen finden Sie unter Azure AD B2C: Häufig gestellte Fragen (FAQ)

Audience legt die Zielgruppe für alle empfangenen JWT-Zugriffstoken fest.

jwtOptions.Audience = "{AUDIENCE}";

Stimmen Sie den Wert nur auf den Pfad des Anwendungs-ID-URI ab, der beim Hinzufügen des Weather.Get-Bereichs unter API bereitstellen im Entra- oder Azure-Portal konfiguriert wurde. Fügen Sie den Bereichsnamen "Weather.Get," nicht in den Wert ein.

Die folgenden Beispiele verwenden eine Anwendungs-ID (Client-ID) von 11112222-bbbb-3333-cccc-4444dddd5555. Im dritten Beispiel wird eine Mandantendomäne von contoso.onmicrosoft.com verwendet.

ME-ID Mieterbeispiel:

jwtOptions.Audience = "api://11112222-bbbb-3333-cccc-4444dddd5555";

Externer Microsoft Entra-ID-Mandant:

jwtOptions.Audience = "11112222-bbbb-3333-cccc-4444dddd5555";

AAD B2C-Mandant Beispiel:

jwtOptions.Audience = "https://contoso.onmicrosoft.com/11112222-bbbb-3333-cccc-4444dddd5555";

Konfigurieren des Serverprojekts (BlazorWebAppEntra)

AddMicrosoftIdentityWebApp aus Microsoft Identity Web (Microsoft.Identity.Web NuGet-Paket, API-Dokumentation) wird in der Datei des BlazorWebAppEntraProgram Projekts konfiguriert.

Rufen Sie die Anwendungs-ID (Client-ID), die Mandantendomäne (Herausgeber) und die Verzeichnis-ID (Mandant) aus der Registrierung der App im Entra- oder Azure-Portal ab. Der App-ID-URI wird für den Weather.Get Bereich aus der Registrierung der Web-API abgerufen. Schließen Sie den Bereichsnamen aus, wenn Sie die App-ID-URI aus dem Portal entnehmen.

Die Authentifizierungskonfiguration hängt vom Mandantentyp ab:

ME-ID Mandantenkonfiguration

Dieser Abschnitt gilt für eine App, die in einer Microsoft Entra-ID oder einem Azure AAD B2C-Mandanten registriert ist.

In der BlazorWebAppEntra-Projektdatei Program geben Sie die Werte für die folgenden Platzhalter in der Microsoft-Identity-Webkonfiguration an:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(msIdentityOptions =>
    {
        msIdentityOptions.CallbackPath = "/signin-oidc";
        msIdentityOptions.ClientId = "{CLIENT ID (BLAZOR APP)}";
        msIdentityOptions.Domain = "{DIRECTORY NAME}.onmicrosoft.com";
        msIdentityOptions.Instance = "https://login.microsoftonline.com/";
        msIdentityOptions.ResponseType = "code";
        msIdentityOptions.TenantId = "{TENANT ID}";
    })
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("DownstreamApi", configOptions =>
    {
        configOptions.BaseUrl = "{BASE ADDRESS}";
        configOptions.Scopes = ["{APP ID URI}/Weather.Get"];
    })
    .AddDistributedTokenCaches();

Stellen Sie dem Anforderungstransformator denselben nachgeschalteten API-Bereich bereit:

List<string> scopes = ["{APP ID URI}/Weather.Get"];

Platzhalter in der vorherigen Konfiguration:

  • {CLIENT ID (BLAZOR APP)}: Die Client-ID der Anwendung.
  • {DIRECTORY NAME}: Der Verzeichnisname der Mandantendomäne.
  • {TENANT ID}: Die Registrierungs-ID (Mandant).
  • {BASE ADDRESS}: Die Basisadresse der Web-API.
  • {APP ID URI}: Die App-ID-URI für Web-API-Bereiche. Eines der folgenden Formate wird verwendet, wobei der {CLIENT ID (WEB API)} Platzhalter die Client-ID der Entra-Registrierung der Web-API ist, und der {DIRECTORY NAME} Platzhalter ist der Verzeichnisname der Domäne des Mandanten (Herausgeber) (Beispiel: contoso).
    • ME-ID Mandant Format: api://{CLIENT ID (WEB API)}
    • B2C-Mandant-Format https://{DIRECTORY NAME}.onmicrosoft.com/{CLIENT ID (WEB API)}

Example:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(msIdentityOptions =>
    {
        msIdentityOptions.CallbackPath = "/signin-oidc";
        msIdentityOptions.ClientId = "00001111-aaaa-2222-bbbb-3333cccc4444";
        msIdentityOptions.Domain = "contoso.onmicrosoft.com";
        msIdentityOptions.Instance = "https://login.microsoftonline.com/";
        msIdentityOptions.ResponseType = "code";
        msIdentityOptions.TenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee";
    })
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("DownstreamApi", configOptions =>
    {
        configOptions.BaseUrl = "https://localhost:7277";
        configOptions.Scopes = 
            ["api://11112222-bbbb-3333-cccc-4444dddd5555/Weather.Get"];
    })
    .AddDistributedTokenCaches();

Example:

List<string> scopes = ["api://11112222-bbbb-3333-cccc-4444dddd5555/Weather.Get"];

Konfiguration der externen Microsoft Entra-ID

Dieser Abschnitt bezieht sich auf eine App, die in einem externen Microsoft Entra-ID-Mandanten registriert ist.

In der BlazorWebAppEntra-Projektdatei Program geben Sie die Werte für die folgenden Platzhalter in der Microsoft-Identity-Webkonfiguration an:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(msIdentityOptions =>
    {
        msIdentityOptions.CallbackPath = "/signin-oidc";
        msIdentityOptions.Authority = "https://{DIRECTORY NAME}.ciamlogin.com/{TENANT ID}/v2.0";
        msIdentityOptions.ClientId = "{CLIENT ID (BLAZOR APP)}";
        msIdentityOptions.ResponseType = "code";
    })
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("DownstreamApi", configOptions =>
    {
        configOptions.BaseUrl = "{BASE ADDRESS}";
        configOptions.Scopes = ["{APP ID URI}/Weather.Get"];
    })
    .AddDistributedTokenCaches();

Stellen Sie dem Anforderungstransformator denselben nachgeschalteten API-Bereich bereit:

List<string> scopes = ["{APP ID URI}/Weather.Get"];

Platzhalter in der vorherigen Konfiguration:

  • {DIRECTORY NAME}: Der Verzeichnisname der Mandantendomäne.
  • {CLIENT ID (BLAZOR APP)}: Die Client-ID der Anwendung.
  • {BASE ADDRESS}: Die Basisadresse der Web-API.
  • {APP ID URI}: Die App-ID-URI für Web-API-Bereiche. Eines der folgenden Formate wird verwendet, wobei der {CLIENT ID (WEB API)} Platzhalter die Client-ID der Entra-Registrierung der Web-API ist, und der {DIRECTORY NAME} Platzhalter ist der Verzeichnisname der Domäne des Mandanten (Herausgeber) (Beispiel: contoso).
    • ME-ID- oder Microsoft Entra External ID-Mandantenformat: api://{CLIENT ID (WEB API)}
    • B2C-Mandant-Format https://{DIRECTORY NAME}.onmicrosoft.com/{CLIENT ID (WEB API)}

Example:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(msIdentityOptions =>
    {
        msIdentityOptions.CallbackPath = "/signin-oidc";
        msIdentityOptions.Authority = "https://contoso.ciamlogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0";
        msIdentityOptions.ClientId = "00001111-aaaa-2222-bbbb-3333cccc4444";
        msIdentityOptions.ResponseType = "code";
    })
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("DownstreamApi", configOptions =>
    {
        configOptions.BaseUrl = "https://localhost:7277";
        configOptions.Scopes = ["api://11112222-bbbb-3333-cccc-4444dddd5555/Weather.Get"];
    })
    .AddDistributedTokenCaches();

Example:

List<string> scopes = ["api://11112222-bbbb-3333-cccc-4444dddd5555/Weather.Get"];

Warning

Produktions-Apps sollten einen anbieter für verteilte Produktionstokencache verwenden. Andernfalls kann die App in einigen Szenarien eine schlechte Leistung aufweisen. Weitere Informationen finden Sie im Abschnitt "Verwenden eines verteilten Cacheanbieters für verteilte Produktionstoken ".

Der Rückrufpfad („CallbackPath“) muss mit dem Umleitungs-URI (Login-Rückrufpfad) übereinstimmen, der bei der Registrierung der Anwendung im Entra- oder Azure-Portal konfiguriert wurde. Pfade werden auf dem Blatt "Authentifizierung " der App-Registrierung konfiguriert. Der Standardwert von CallbackPath ist /signin-oidc für eine registrierte Umleitungs-URI von https://localhost/signin-oidc (ein Anschluss ist nicht erforderlich).

Der SignedOutCallbackPath ist der Anforderungspfad innerhalb des Basis-Pfads der App, der vom OpenID-Verbinden-Handler abgefangen wird, wo der Benutzer-Agent zuerst zurückgegeben wird, nachdem er sich von Entra abgemeldet hat. Die Beispiel-App legt keinen Wert für den Pfad fest, da der Standardwert von "/signout-callback-oidc" verwendet wird. Nach dem Abfangen der Anfrage leitet der OpenID Connect Handler auf den SignedOutRedirectUri oder RedirectUri um, falls angegeben.

Warning

Speichern Sie keine geheimen App-Schlüssel, Verbindungszeichenfolgen, Anmeldeinformationen, Kennwörter, persönliche Identifikationsnummern (PINs), privaten C#/.NET-Code oder private Schlüssel/Token im clientseitigen Code, der immer unsicher ist. In Test- oder Stagingumgebungen und Produktionsumgebungen sollten serverseitiger Blazor-Code und Web-APIs sichere Authentifizierungsflows verwenden, die die Verwaltung von Anmeldeinformationen innerhalb von Projektcode oder Konfigurationsdateien vermeiden. Außerhalb der lokalen Entwicklungstests wird empfohlen, die Verwendung von Umgebungsvariablen zum Speichern vertraulicher Daten zu vermeiden, da Umgebungsvariablen nicht der sicherste Ansatz sind. Für lokale Entwicklungstests wird das Tool "Geheimer Manager " zum Sichern vertraulicher Daten empfohlen. Weitere Informationen finden Sie unter "Sichere Verwaltung vertraulicher Daten und Anmeldeinformationen".

Einrichten des geheimen Clientschlüssels

Dieser Abschnitt gilt nur für das Serverprojekt des Blazor Web App.

Verwenden Sie eine oder beide der folgenden Vorgehensweisen, um den geheimen Clientschlüssel der App bereitzustellen:

  • Secret Manager-Tool: Das Tool "Geheimer Manager" speichert private Daten auf dem lokalen Computer und wird nur während der lokalen Entwicklung verwendet.
  • Azure Key Vault: Sie können den geheimen Clientschlüssel in einem Schlüsseltresor für die Verwendung in einer beliebigen Umgebung speichern, einschließlich der Entwicklungsumgebung, wenn Sie lokal arbeiten. Einige Entwickler*innen ziehen es vor, für Staging- und Produktionsbereitstellungen Schlüsseltresore und für die lokale Entwicklung den Geheimnis-Manager zu verwenden.

Wir empfehlen dringend, dass Sie vermeiden, geheime Clientschlüssel im Projektcode oder in Konfigurationsdateien zu speichern. Verwenden Sie sichere Authentifizierungsflows, wie z. B. einen der in diesem Abschnitt beschriebenen Ansätze oder beide davon.

Geheimnis-Manager-Tool

Das Tool "Geheimer Manager" kann den geheimen Clientschlüssel der Server-App unter dem Konfigurationsschlüssel AzureAd:ClientSecretspeichern.

Die Blazor Server-App wurde für das Tool "Geheimer Manager" nicht initialisiert. Verwenden Sie eine Befehlsshell, wie die Developer PowerShell-Befehlsshell in Visual Studio, um den folgenden Befehl auszuführen. Bevor Sie den Befehl ausführen, ändern Sie das Verzeichnis mit dem Befehl cd in das Verzeichnis des Serverprojekts. Der Befehl richtet einen Benutzer-Geheimnis-Bezeichner („<UserSecretsId>“) in der Projektdatei der Server-App ein, der intern vom Tool zur Nachverfolgung von Geheimnissen für die App verwendet wird:

dotnet user-secrets init

Führen Sie den folgenden Befehl aus, um den geheimen Clientschlüssel festzulegen. Der {SECRET}-Platzhalter ist der geheime Clientschlüssel, der aus der Entra-Registrierung der App erhalten wurde:

dotnet user-secrets set "AzureAd:ClientSecret" "{SECRET}"

Wenn Sie Visual Studio verwenden, können Sie bestätigen, dass der geheime Schlüssel festgelegt ist, indem Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Serverprojekt klicken und " Benutzergeheimnisse verwalten" auswählen.

Azure Key Vault (ein Dienst zur sicheren Verwaltung kryptografischer Schlüssel)

Azure Key Vault bietet einen sicheren Ansatz für die Bereitstellung des geheimen Clientschlüssels der App für die App.

Informationen zum Erstellen eines Schlüsseltresors und zum Festlegen eines geheimen Clientschlüssels finden Sie unter Informationen zu Azure Key Vault-Geheimnissen (Azure-Dokumentation) sowie in den darin aufgeführten Ressourcen für den Einstieg in Azure Key Vault. Zum Implementieren des in diesem Abschnitt aufgeführten Codes notieren Sie sich die URI des Schlüsseltresors und den geheimen Namen, wenn Sie in Azure den Schlüsseltresor und das Geheimnis erstellen. Für das Beispiel in diesem Abschnitt lautet der geheime Name "BlazorWebAppEntraClientSecret."

Beim Einrichten des Schlüsseltresors im Entra- oder Azure-Portal:

  • Konfigurieren Sie den Schlüsseltresor für die Verwendung der rollenbasierten Zugriffssteuerung (Azure Role-Based Access Control, RABC). Wenn Sie nicht in einem virtuellen Azure-Netzwerk arbeiten, einschließlich für lokale Entwicklung und Tests, bestätigen Sie, dass der öffentliche Zugriff auf den Netzwerkschrittaktiviert ist (aktiviert). Das Aktivieren des öffentlichen Zugriffs macht nur den Schlüsseltresor-Endpunkt verfügbar. Authentifizierte Konten sind weiterhin für den Zugriff erforderlich.

  • Erstellen Sie eine Azure verwaltete Identity (oder fügen Sie eine Rolle zur bestehenden verwalteten Identity hinzu, die Sie zur Nutzung planen) mit der Key Vault Secrets Benutzer Rolle. Weisen Sie das verwaltete Identity dem Azure App-Dienst zu, der die Bereitstellung hostet: Einstellungen>Identity>Vom Benutzer zugewiesen>Hinzufügen.

    Note

    Wenn Sie auch beabsichtigen, eine App lokal mit einem autorisierten Benutzer für den Schlüsseltresorzugriff mithilfe der Azure CLI oder der Azure Service Authentication von Visual Studio auszuführen, fügen Sie Ihr Entwickler-Azure-Benutzerkonto in Access Control (IAM) mit der Rolle " Schlüsseltresorschlüsselbenutzer " hinzu. Wenn Sie die Azure CLI über Visual Studio verwenden möchten, führen Sie den az login Befehl im PowerShell-Bereich "Entwicklertools" aus, und folgen Sie den Anweisungen, um sich beim Mandanten zu authentifizieren.

Um den Code in diesem Abschnitt zu implementieren, erfassen Sie die Schlüsseltresor-URI (Beispiel: https://contoso.vault.azure.net/, nachstehender Schrägstrich erforderlich) und der Geheimnisname (Beispiel: BlazorWebAppEntraClientSecret") von Azure, wenn Sie den Schlüsseltresor und das Geheimnis erstellen.

Important

Ein Schlüsseltresorgeheimnis wird mit einem Ablaufdatum erstellt. Verfolgen Sie nach, wann ein Schlüsseltresorgeheimnis abläuft, und erstellen Sie für die App ein neues Geheimnis, bevor dieses Datum erreicht wird.

Fügen Sie dem Serverprojekt die folgende AzureHelper Klasse hinzu. Die GetKeyVaultSecret-Methode ruft einen geheimen Schlüssel aus einem Schlüsseltresor ab. Passen Sie den Namespace (BlazorSample.Helpers) an das Schema Ihres Projekt-Namespaces an.

Helpers/AzureHelper.cs:

using Azure.Core;
using Azure.Security.KeyVault.Secrets;

namespace BlazorWebAppEntra.Helpers;

public static class AzureHelper
{
    public static string GetKeyVaultSecret(string vaultUri, 
        TokenCredential credential, string secretName)
    {
        var client = new SecretClient(new Uri(vaultUri), credential);
        var secret = client.GetSecretAsync(secretName).Result;

        return secret.Value.Value;
    }
}

Note

Im vorherigen Beispiel wird DefaultAzureCredential verwendet, um die Authentifizierung zu vereinfachen, indem Anmeldeinformationen in Azure-Hostingumgebungen mit Anmeldeinformationen kombiniert werden, die in der lokalen Entwicklung genutzt werden, während Apps entwickelt werden, die für Azure bereitgestellt werden. Wenn Sie zur Produktion wechseln, ist eine Alternative eine bessere Wahl, wie zum Beispiel ManagedIdentityCredential. Weitere Informationen finden Sie unter Authentifizieren von von Azure gehosteten .NET-Apps für Azure-Ressourcen mithilfe einer vom System zugewiesenen verwalteten Identität.

Wenn Dienste in der Program -Datei des Serverprojekts registriert sind, erhalten Sie das Client-Geheimnis mit dem folgenden Code und wenden es an:

TokenCredential? credential;

if (builder.Environment.IsProduction())
{
    credential = new ManagedIdentityCredential("{MANAGED IDENTITY CLIENT ID}");
}
else
{
    // Local development and testing only
    DefaultAzureCredentialOptions options = new()
    {
        // Specify the tenant ID to use the dev credentials when running the app locally
        // in Visual Studio.
        VisualStudioTenantId = "{TENANT ID}",
        SharedTokenCacheTenantId = "{TENANT ID}"
    };

    credential = new DefaultAzureCredential(options);
}

Wo MicrosoftIdentityOptions festgelegt sind, rufen Sie auf GetKeyVaultSecret , um den geheimen Clientschlüssel der App zu empfangen und zuzuweisen:

msIdentityOptions.ClientSecret = AzureHelper.GetKeyVaultSecret("{VAULT URI}", 
    credential, "{SECRET NAME}");

{MANAGED IDENTITY CLIENT ID}: Die Azure verwaltete Identity Client-ID (GUID).

{TENANT ID}: Die Registrierungs-ID (Mandant). Beispiel: aaaabbbb-0000-cccc-1111-dddd2222eeee

{VAULT URI}: Schlüsseltresor-URI Fügen Sie den nachgestellten Schrägstrich in die URI ein. Beispiel: https://contoso.vault.azure.net/

{SECRET NAME}: Geheimer Name. Beispiel: BlazorWebAppEntraClientSecret

Die Konfiguration wird verwendet, um die Bereitstellung spezieller Schlüsseltresore und geheimer Namen auf der Grundlage der Umgebungskonfigurationsdateien der App zu erleichtern. Zum Beispiel können Sie unterschiedliche Konfigurationswerte für appsettings.Development.json in der Entwicklung, appsettings.Staging.json beim Staging und appsettings.Production.json für die Produktionsbereitstellung bereitstellen. Weitere Informationen finden Sie unter ASP.NET Core-KonfigurationBlazor.

Nur den Namen und die Rollenansprüche serialisieren

In der Program-Datei werden alle Claims serialisiert, indem SerializeAllClaims auf true gesetzt wird. Wenn Sie nur die Namens- und Rollenansprüche für CSR serialisiert haben möchten, entfernen Sie die Option oder setzen Sie sie auf false.

Liefern Sie die Konfiguration mit dem JSON-Konfigurationsanbieter

Die Beispiellösungsprojekte konfigurieren die Microsoft Identity Web- und JWT-Bearerauthentifizierung in ihren Program Dateien, um Konfigurationseinstellungen mithilfe von C#-AutoVervollständigen auffindbar zu machen. Professionelle Apps verwenden in der Regel einen Konfigurationsanbieter , um OIDC-Optionen zu konfigurieren, z. B. den standardmäßigen JSON-Konfigurationsanbieter. Der JSON-Konfigurationsanbieter lädt die Konfiguration aus App-Einstellungsdateien appsettings.json/appsettings.{ENVIRONMENT}.json, wobei der {ENVIRONMENT} Platzhalter die Laufzeitumgebung der App ist. Befolgen Sie die Anweisungen in diesem Abschnitt, um App-Einstellungsdateien für die Konfiguration zu verwenden.

Fügen Sie in der App-Einstellungsdatei (appsettings.json) des BlazorWebAppEntra Projekts die folgende JSON-Konfiguration hinzu:

{
  "AzureAd": {
    "CallbackPath": "/signin-oidc",
    "ClientId": "{CLIENT ID (BLAZOR APP)}",
    "Domain": "{DIRECTORY NAME}.onmicrosoft.com",
    "Instance": "https://login.microsoftonline.com/",
    "ResponseType": "code",
    "TenantId": "{TENANT ID}"
  },
  "DownstreamApi": {
    "BaseUrl": "{BASE ADDRESS}",
    "Scopes": ["{APP ID URI}/Weather.Get"]
  }
}

Aktualisieren Sie die Platzhalter in der vorherigen Konfiguration so, dass sie den Werten entsprechen, die die App in der Program Datei verwendet:

  • {CLIENT ID (BLAZOR APP)}: Die Client-ID der Anwendung.
  • {DIRECTORY NAME}: Der Verzeichnisname der Mandantendomäne.
  • {TENANT ID}: Die Registrierungs-ID (Mandant).
  • {BASE ADDRESS}: Die Basisadresse der Web-API.
  • {APP ID URI}: Die App-ID-URI für Web-API-Bereiche. Eines der folgenden Formate wird verwendet, wobei der {CLIENT ID (WEB API)} Platzhalter die Client-ID der Entra-Registrierung der Web-API ist, und der {DIRECTORY NAME} Platzhalter ist der Verzeichnisname der Domäne des Mandanten (Herausgeber) (Beispiel: contoso).
    • ME-ID Mandant Format: api://{CLIENT ID (WEB API)}
    • B2C-Mandant-Format https://{DIRECTORY NAME}.onmicrosoft.com/{CLIENT ID (WEB API)}

Example:

"AzureAd": {
  "CallbackPath": "/signin-oidc",
  "ClientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "Domain": "contoso.onmicrosoft.com",
  "Instance": "https://login.microsoftonline.com/",
  "ResponseType": "code",
  "TenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
},
"DownstreamApi": {
  "BaseUrl": "https://localhost:7277",
  "Scopes": ["api://11112222-bbbb-3333-cccc-4444dddd5555/Weather.Get"]
}

Aktualisieren Sie alle anderen Werte in der vorherigen Konfiguration so, dass sie mit benutzerdefinierten/nicht standardmäßigen Werten übereinstimmen, die in der Program Datei verwendet werden.

Die Konfiguration wird automatisch vom Authentifizierungs-Generator aufgenommen.

Nehmen Sie die folgenden Änderungen in der Program Datei vor:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
-   .AddMicrosoftIdentityWebApp(msIdentityOptions =>
-   {
-       msIdentityOptions.CallbackPath = "...";
-       msIdentityOptions.ClientId = "...";
-       msIdentityOptions.Domain = "...";
-       msIdentityOptions.Instance = "...";
-       msIdentityOptions.ResponseType = "...";
-       msIdentityOptions.TenantId = "...";
-   })
+   .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
-   .AddDownstreamApi("DownstreamApi", configOptions =>
-   {
-       configOptions.BaseUrl = "...";
-       configOptions.Scopes = ["..."];
-   })
+   .AddDownstreamApi("DownstreamApi", builder.Configuration.GetSection("DownstreamApi"))
    .AddDistributedTokenCaches();

- List<string> scopes = ["{APP ID URI}/Weather.Get"];
- var accessToken = await tokenAcquisition.GetAccessTokenForUserAsync(scopes);
+ var configuration = transformContext.HttpContext.RequestServices.GetRequiredService<IConfiguration>();
+ var scopes = configuration.GetSection("DownstreamApi:Scopes").Get<IEnumerable<string>>();
+ var accessToken = await tokenAcquisition.GetAccessTokenForUserAsync(scopes ??
+     throw new InvalidOperationException("No downstream API scopes!"));

Note

Produktions-Apps sollten einen anbieter für verteilte Produktionstokencache verwenden. Andernfalls kann die App in einigen Szenarien eine schlechte Leistung aufweisen. Weitere Informationen finden Sie im Abschnitt "Verwenden eines verteilten Cacheanbieters für verteilte Produktionstoken ".

Fügen Sie im MinimalApiJwt Projekt in der Datei appsettings.json die folgende Konfiguration der Anwendungseinstellungen hinzu:

"Authentication": {
  "Schemes": {
    "Bearer": {
      "Authority": "https://sts.windows.net/{TENANT ID (WEB API)}",
      "ValidAudiences": ["{APP ID URI (WEB API)}"]
    }
  }
},

Aktualisieren Sie die Platzhalter in der vorherigen Konfiguration so, dass sie den Werten entsprechen, die die App in der Program Datei verwendet:

  • {TENANT ID (WEB API)}: Die Mandanten-ID der Web-API.
  • {APP ID URI (WEB API)}: Der App-ID-URI der Web-API.

Autoritative Stellen übernehmen die folgenden Muster:

  • ME-ID Mandantentyp: https://sts.windows.net/{TENANT ID}
  • Externe Microsoft Entra Identifikationsnummer: https://{DIRECTORY NAME}.ciamlogin.com/{TENANT ID}/v2.0
  • B2C-Mandantentyp https://login.microsoftonline.com/{TENANT ID}/v2.0

Zielgruppenformate übernehmen die folgenden Muster ({CLIENT ID} ist die Client-ID der Web-API; {DIRECTORY NAME} ist der Verzeichnisname, zum Beispiel contoso).

  • ME-ID Mandantentyp: api://{CLIENT ID}
  • Externe Microsoft Entra-ID: {CLIENT ID}
  • B2C-Mandantentyp https://{DIRECTORY NAME}.onmicrosoft.com/{CLIENT ID}

Die Konfiguration wird automatisch vom JWT-Bearerauthentifizierungs-Generator aufgenommen.

Entfernen Sie die folgenden Zeilen aus der Program Datei:

- jwtOptions.Authority = "...";
- jwtOptions.Audience = "...";

Weitere Informationen zur Konfiguration finden Sie in den folgenden Ressourcen:

Verwenden Sie einen verteilten Token-Cache-Anbieter in der Produktion

Im Arbeitsspeicher verteilte Tokencaches werden beim Aufrufen AddDistributedTokenCaches erstellt, um sicherzustellen, dass eine Basisimplementierung für die verteilte Tokenzwischenspeicherung verfügbar ist.

Produktionsweb-Apps und Web-APIs sollten einen verteilten Produktionstokencache verwenden (z. B. Redis, Microsoft SQL Server, Microsoft Azure Cosmos DB).

Note

Für lokale Entwicklung und Tests auf einem einzelnen Computer können Sie Caches im Arbeitsspeicher anstelle von verteilten Tokencaches verwenden:

builder.Services.AddInMemoryTokenCaches();

Später in der Entwicklungs- und Testphase führen Sie einen Produktions-verteilten Token-Cache-Anbieter ein.

AddDistributedMemoryCache fügt eine Standardimplementierung für IDistributedCache hinzu, die Cacheelemente im Arbeitsspeicher speichert und von Microsoft Identity Web für das Zwischenspeichern von Token verwendet wird.

Der verteilte Tokencache wird konfiguriert durch MsalDistributedTokenCacheAdapterOptions:

  • In der Entwicklung zum Debuggen können Sie den L1-Cache deaktivieren, indem Sie DisableL1Cache auf true festlegen. Stellen Sie sicher, dass Sie es für die Produktion wieder auf false zurücksetzen.
  • Legen Sie die maximale Größe des L1-Caches fest L1CacheOptions.SizeLimit , um zu verhindern, dass der Cache den Arbeitsspeicher des Servers überholt. Der Standardwert ist 500 MB.
  • In der Entwicklung für Debuggingzwecke können Sie die Tokenverschlüsselung im Ruhezustand deaktivieren, indem Sie Encrypt auf false setzen, was der Standardwert ist. Stellen Sie sicher, dass Sie es für die Produktion wieder auf true zurücksetzen.
  • Legen Sie das Entfernen von Tokens aus dem Cache mit SlidingExpiration fest. Der Standardwert ist 1 Stunde.
  • Weitere Informationen, einschließlich Anleitungen zum Rückruf für L2-Cachefehler (OnL2CacheFailure) und asynchrone L2-Cache-Schreibvorgänge (EnableAsyncL2Write), finden Sie unter MsalDistributedTokenCacheAdapterOptions und Tokencache serialisierung: Verteilte Tokencaches.
builder.Services.AddDistributedMemoryCache();

builder.Services.Configure<MsalDistributedTokenCacheAdapterOptions>(
    options => 
    {
      // The following lines that are commented out reflect
      // default values. We recommend overriding the default
      // value of Encrypt to encrypt tokens at rest.

      //options.DisableL1Cache = false;
      //options.L1CacheOptions.SizeLimit = 500 * 1024 * 1024;
      options.Encrypt = true;
      //options.SlidingExpiration = TimeSpan.FromHours(1);
    });

AddDistributedMemoryCache erfordert einen Paketverweis auf das Microsoft.Extensions.Caching.Memory NuGet-Paket.

Note

Eine Anleitung zum Hinzufügen von Paketen zu .NET-Anwendungen finden Sie in den Artikeln unter Pakete installieren und verwalten unter Workflow für die Paketnutzung (NuGet-Dokumentation). Überprüfen Sie unter NuGet.org, ob die richtige Paketversion verwendet wird.

Informationen zum Konfigurieren eines verteilten Produktionscacheanbieters finden Sie unter "Verteiltes Zwischenspeichern" in ASP.NET Core.

Warning

Ersetzen Sie beim Bereitstellen der App in einer Produktionsumgebung immer die im Arbeitsspeicher verteilten Tokencaches durch einen wirklichen Tokencacheanbieter. Wenn Sie es versäumen, einen Produktions-verteilten Token-Cache-Anbieter einzuführen, kann die App erheblich an Leistung verlieren.

Weitere Informationen finden Sie unter Serialisierung des Tokencaches: Verteilte Caches. Die gezeigten Codebeispiele gelten jedoch nicht für ASP.NET Core-Apps, die verteilte Caches über AddDistributedMemoryCache, nicht AddDistributedTokenCachekonfigurieren.

Verwenden Sie einen freigegebenen Datenschutz-Schlüsselring im Produktivbetrieb, damit Instanzen der App auf Servern in einer Webfarm Token entschlüsseln können, wenn MsalDistributedTokenCacheAdapterOptions.Encrypt auf true gesetzt ist.

Note

Für die frühe Entwicklung und das lokale Testen auf einem einzelnen Computer können Sie Encrypt auf false setzen und später einen freigegebenen Schutz von Daten-Schlüsselring konfigurieren:

options.Encrypt = false;

Später im Entwicklungs- und Testzeitraum aktivieren Sie die Tokenverschlüsselung und übernehmen einen freigegebenen Schlüsselring für den Datenschutz.

Das folgende Beispiel zeigt, wie Sie Azure Blob Storage und Azure Key Vault (PersistKeysToAzureBlobStorage/ProtectKeysWithAzureKeyVault) für den freigegebenen Schlüsselring verwenden. Die Dienstkonfigurationen sind Basisfallszenarien für Demonstrationszwecke. Bevor Sie Produktions-Apps bereitstellen, machen Sie sich mit den Azure-Diensten vertraut, und übernehmen Sie bewährte Methoden mithilfe der dedizierten Dokumentationssätze der Azure-Dienste, die am Ende dieses Abschnitts verknüpft sind.

Bestätigen Sie das Vorhandensein der folgenden Pakete im Serverprojekt der Blazor Web App:

Note

Eine Anleitung zum Hinzufügen von Paketen zu .NET-Anwendungen finden Sie in den Artikeln unter Pakete installieren und verwalten unter Workflow für die Paketnutzung (NuGet-Dokumentation). Überprüfen Sie unter NuGet.org, ob die richtige Paketversion verwendet wird.

Note

Bevor Sie mit den folgenden Schritten fortfahren, vergewissern Sie sich, dass die App bei Microsoft Entra registriert ist.

Der folgende Code wird normalerweise gleichzeitig implementiert, wenn ein „Produktions-verteiltes Token-Cache-Anbieter“ implementiert wird. Andere Optionen, sowohl innerhalb von Azure als auch außerhalb von Azure, stehen für die Verwaltung von Datenschutzschlüsseln in mehreren App-Instanzen zur Verfügung, die Beispiel-App veranschaulicht jedoch die Verwendung von Azure-Diensten.

Konfigurieren Sie Azure Blob Storage, um Datenschutzschlüssel zu verwalten. Befolgen Sie die Anleitungen in key storage providers in ASP.NET Core.

Konfigurieren Sie Azure Key Vault, um die ruhenden Datenschutzschlüssel zu verschlüsseln. Befolgen Sie die Anweisungen unter "Konfigurieren ASP.NET Kerndatenschutz".

Verwenden Sie den folgenden Code in der Datei, in der Program Dienste registriert sind:

TokenCredential? credential;

if (builder.Environment.IsProduction())
{
    credential = new ManagedIdentityCredential("{MANAGED IDENTITY CLIENT ID}");
}
else
{
    // Local development and testing only
    DefaultAzureCredentialOptions options = new()
    {
        // Specify the tenant ID to use the dev credentials when running the app locally
        // in Visual Studio.
        VisualStudioTenantId = "{TENANT ID}",
        SharedTokenCacheTenantId = "{TENANT ID}"
    };

    credential = new DefaultAzureCredential(options);
}

builder.Services.AddDataProtection()
    .SetApplicationName("BlazorWebAppEntra")
    .PersistKeysToAzureBlobStorage(new Uri("{BLOB URI}"), credential)
    .ProtectKeysWithAzureKeyVault(new Uri("{KEY IDENTIFIER}"), credential);

Sie können einen beliebigen App-Namen an SetApplicationName übergeben. Vergewissern Sie sich einfach, dass alle App-Bereitstellungen denselben Wert verwenden.

{MANAGED IDENTITY CLIENT ID}: Die Azure verwaltete Identity Client-ID (GUID).

{TENANT ID}: Mandanten-ID.

{BLOB URI}: Vollständiger URI für die Schlüsseldatei. Der URI wird von Azure Storage generiert, wenn Sie die Schlüsseldatei erstellen. NICHT SAS nutzen.

{KEY IDENTIFIER}: Azure Key Vault-Schlüsselbezeichner, der für die Schlüsselverschlüsselung verwendet wird. Eine Zugriffsrichtlinie ermöglicht der Anwendung den Zugriff auf den Schlüsseltresor mit Get, Unwrap Keyund Wrap Key Berechtigungen. Die Version des Schlüssels wird aus dem Schlüssel im Entra- oder Azure-Portal abgerufen, nachdem er erstellt wurde. Wenn Sie die AutomatischeRotation des Schlüsseltresorschlüssels aktivieren, stellen Sie sicher, dass Sie in der Schlüsseltresorkonfiguration der App einen versionslosen Schlüsselbezeichner verwenden, bei dem keine Schlüssel-GUID am Ende des Bezeichners platziert wird (Beispiel: https://contoso.vault.azure.net/keys/data-protection).

Note

In Nicht-Produktionsumgebungen wird im vorherigen Beispiel die Authentifizierung mithilfe von DefaultAzureCredential vereinfacht. Dabei werden Anmeldeinformationen kombiniert, die sowohl in Azure-Hostingumgebungen als auch in der lokalen Entwicklung verwendet werden, während Apps entwickelt werden, die in Azure bereitgestellt werden. Weitere Informationen finden Sie unter Authentifizieren von von Azure gehosteten .NET-Apps für Azure-Ressourcen mithilfe einer vom System zugewiesenen verwalteten Identität.

Alternativ können Sie die App so konfigurieren, dass die Werte aus App-Einstellungsdateien mithilfe des JSON-Konfigurationsanbieters bereitgestellt werden. Fügen Sie der App-Einstellungsdatei Folgendes hinzu:

"DistributedTokenCache": {
  "DisableL1Cache": false,
  "L1CacheSizeLimit": 524288000,
  "Encrypt": true,
  "SlidingExpirationInHours": 1
},
"DataProtection": {
  "BlobUri": "{BLOB URI}",
  "KeyIdentifier": "{KEY IDENTIFIER}"
}

Beispielabschnitt DataProtection :

"DataProtection": {
  "BlobUri": "https://contoso.blob.core.windows.net/data-protection/keys.xml",
  "KeyIdentifier": "https://contoso.vault.azure.net/keys/data-protection"
}

Note

Der Schlüsselbezeichner im vorherigen Beispiel ist versionslos. Es gibt keine GUID-Schlüsselversion am Ende des Bezeichners. Dies ist besonders wichtig, wenn Sie die automatische Schlüsseldrehung für den Schlüssel konfigurieren. Weitere Informationen finden Sie unter Kryptografische Schlüssel-Autorotation in Azure Key Vault konfigurieren: Richtlinie zur Schlüsselrotation.

Nehmen Sie die folgenden Änderungen in der Program Datei vor:

builder.Services.Configure<MsalDistributedTokenCacheAdapterOptions>(
    options =>
    {
+       var config = builder.Configuration.GetSection("DistributedTokenCache");

-       options.DisableL1Cache = false;
+       options.DisableL1Cache = config.GetValue<bool>("DisableL1Cache");

-       options.L1CacheOptions.SizeLimit = 500 * 1024 * 1024;
+       options.L1CacheOptions.SizeLimit = config.GetValue<long>("L1CacheSizeLimit");

-       options.Encrypt = true;
+       options.Encrypt = config.GetValue<bool>("Encrypt");

-       options.SlidingExpiration = TimeSpan.FromHours(1);
+       options.SlidingExpiration = 
+           TimeSpan.FromHours(config.GetValue<int>("SlidingExpirationInHours"));
    });

- builder.Services.AddDataProtection()
-     .SetApplicationName("BlazorWebAppEntra")
-     .PersistKeysToAzureBlobStorage(new Uri("{BLOB URI}"), credential)
-     .ProtectKeysWithAzureKeyVault(new Uri("{KEY IDENTIFIER}"), credential);

Fügen Sie den folgenden Code hinzu, in dem Dienste in der Program Datei konfiguriert sind:

var config = builder.Configuration.GetSection("DataProtection");

builder.Services.AddDataProtection()
    .SetApplicationName("BlazorWebAppEntra")
    .PersistKeysToAzureBlobStorage(
        new Uri(config.GetValue<string>("BlobUri") ??
        throw new Exception("Missing Blob URI")),
        credential)
    .ProtectKeysWithAzureKeyVault(
        new Uri(config.GetValue<string>("KeyIdentifier") ?? 
        throw new Exception("Missing Key Identifier")), 
        credential);

Weitere Informationen über die Nutzung eines gemeinsamen Schlüsselrings und Schlüsselspeicherdienste für den Datenschutz finden Sie in den folgenden Ressourcen:

YaRP-Weiterleitungszielpräfix

Das Blazor Web App-Serverprojekt verwendet die YARP-Weiterleitung, bei der das Zugriffstoken des Benutzers an den MinimalApiJwt-Web-API-Aufruf angeschlossen wird und ein Zielpräfix von https://weatherapi spezifiziert wird. Dieser Wert entspricht dem Projektnamen, der an AddProject in der Program Datei des Aspire.AppHost Projekts übergeben wird.

Weiterleitung im Blazor Web App-Serverprojekt (BlazorWebAppEntra):

app.MapForwarder("/weather-forecast", "https://weatherapi", transformBuilder =>
{
    ...
}).RequireAuthorization();

Übereinstimmender Projektname in der Program Datei des Aspire App-Hostprojekts (Aspire.AppHost):

var weatherApi = builder.AddProject<Projects.MinimalApiJwt>("weatherapi");

Es ist nicht erforderlich, das Zielpräfix der YARP-Weiterleitung zu ändern, wenn Sie die Blazor Web App in die Produktion bereitstellen. Das Microsoft Identity Web-Downstream-API-Paket verwendet die Basis-URI, die über die Konfiguration übergeben wird, um den Web-API-Aufruf von der ServerWeatherForecaster zu machen, nicht das Zielpräfix der YARP-Weiterleitung. In der Produktion transformiert der YARP-Weiterleitungsdienst lediglich die Anforderung und fügt das Zugriffstoken des Benutzers hinzu.

Umleitung zur Startseite beim Abmelden

Die LogInOrOut Komponente (Layout/LogInOrOut.razor) legt ein verstecktes Feld für die Rückgabe-URL (ReturnUrl) auf die aktuelle URL (currentURL) fest. Wenn sich der Benutzer bei der App abmeldet, gibt der Identitätsanbieter den Benutzer auf die Seite zurück, von der er sich abgemeldet hat. Wenn sich der Benutzer von einer sicheren Seite abmeldet, wird er zur gleichen sicheren Seite zurückgesendet und über den Authentifizierungsprozess zurückgesendet. Dieser Authentifizierungsfluss ist angemessen, wenn Benutzer Konten regelmäßig ändern müssen.

Verwenden Sie alternativ die folgende LogInOrOut Komponente, die beim Abmelden keine Rückgabe-URL angibt.

Layout/LogInOrOut.razor:

<div class="nav-item px-3">
    <AuthorizeView>
        <Authorized>
            <form action="authentication/logout" method="post">
                <AntiforgeryToken />
                <button type="submit" class="nav-link">
                    <span class="bi bi-arrow-bar-left-nav-menu" aria-hidden="true">
                    </span> Logout
                </button>
            </form>
        </Authorized>
        <NotAuthorized>
            <a class="nav-link" href="authentication/login">
                <span class="bi bi-person-badge-nav-menu" aria-hidden="true"></span>
                Login
            </a>
        </NotAuthorized>
    </AuthorizeView>
</div>

Wetterdatensicherheit

Weitere Informationen dazu, wie diese App ihre Wetterdaten sichert, finden Sie unter Gesicherte Daten in Blazor Web Apps mit interaktivem automatischen Rendering.

Troubleshoot

Logging

Die Server-App ist eine Standard-ASP.NET Core-App. Weitere Informationen finden Sie in den ASP.NET Core-Protokollierungsanleitungen , um eine niedrigere Protokollierungsebene in der Server-App zu ermöglichen.

Um Debuggen oder Ablaufprotokollierung für die Blazor WebAssembly Authentifizierung zu aktivieren, siehe den Abschnitt Clientseitige Authentifizierungsprotokollierung von ASP.NET Core Blazor Protokollierung mit dem Artikelversionsselektor, der auf ASP.NET Core in .NET 7 oder höher eingestellt ist.

Häufige Fehler

  • Debugger bricht bei einer Ausnahme während der Abmeldung mit Microsoft Entra External ID ab

    Die folgende Ausnahme stoppt den Visual Studio-Debugger während der Abmeldung mit der externen Microsoft Entra-ID:

    Uncaught TypeError TypeError: Failed to execute 'postMessage' on 'Window': The provided value cannot be converted to a sequence.

    Visual Studio Debugger bricht bei JavaScript-Ausnahme während der Abmeldung ab

    Die Ausnahme wird aus Entra-JavaScript-Code ausgelöst, daher ist dies kein Problem mit ASP.NET Core. Die Ausnahme wirkt sich nicht auf die App-Funktionalität in der Produktion aus, sodass die Ausnahme während der lokalen Entwicklungstests ignoriert werden kann.

  • Falsche Konfiguration der App oder des Identity-Anbieters (Identity Provider, IP)

    Die häufigsten Fehler werden durch eine falsche Konfiguration verursacht. Im Folgenden finden Sie einige Beispiele:

    • In Abhängigkeit von den Anforderungen des Szenarios verhindert eine fehlende oder falsche Autorität, Instanz, Mandanten-ID, Mandantendomäne oder Client-ID oder ein fehlender oder falscher Umleitungs-URI, dass Clients von einer App authentifiziert werden.
    • Falsche Anforderungsbereiche verhindern, dass Clients auf die Web-API-Endpunkte des Servers zugreifen können.
    • Falsche oder fehlende Server-API-Berechtigungen verhindern, dass Clients auf Server-Web-API-Endpunkte zugreifen können.
    • Das Ausführen der App an einem anderen Port als dem, der im Umleitungs-URI der App-Registrierung für die IP konfiguriert ist. Beachten Sie, dass für Microsoft Entra ID und eine App, die an einer localhost-Entwicklungstestadresse ausgeführt wird, kein Port erforderlich ist. Die Portkonfiguration der App und der Port, an dem die App ausgeführt wird, müssen jedoch für Nicht-localhost-Adressen übereinstimmen.

    Die Konfigurationsabdeckung in diesem Artikel enthält Beispiele für die richtige Konfiguration. Überprüfen Sie sorgfältig die Konfiguration, die nach App- und IP-Fehlkonfigurationen sucht.

    Wenn die Konfiguration anscheinend korrekt ist:

    • Analysieren Sie Anwendungsprotokolle.

    • Überprüfen Sie den Netzwerkdatenverkehr zwischen der Client-App und dem IP oder der Server-App mit den Entwicklertools des Browsers. Häufig wird vom IP oder von der Server-App eine präzise Fehlermeldung oder eine Meldung mit einem Hinweis auf die Ursache des Problems zurückgegeben, nachdem eine Anforderung erfolgt ist. Anleitungen zu den Entwicklertools finden Sie in den folgenden Artikeln:

    Das Dokumentationsteam reagiert auf Dokumentfeedback und Fehler in Artikeln (öffnen Sie ein Problem im Abschnitt "Feedback" dieser Seite ), kann aber keinen Produktsupport bereitstellen. Es gibt einige öffentliche Supportforen, die bei der Problembehandlung für eine App weiterhelfen. Wir empfehlen Folgendes:

    Die vorangehenden Foren sind nicht eigentum oder werden von Microsoft gesteuert.

    Bei nicht sicherheitsbezogenen, nicht sensiblen und nicht vertraulichen Fehlerberichten zum Framework wird legen Sie ein Ticket für die ASP.NET Core-Produkteinheit an. Legen Sie ein Ticket für die Produkteinheit erst an, wenn Sie die Ursache eines Problems gründlich untersucht haben und es nicht selbst oder mithilfe der Community in einem öffentlichen Supportforum lösen konnten. Die Produkteinheit kann keine Problembehandlung für einzelne Apps durchführen, die aufgrund einer einfachen Fehlkonfiguration oder in Anwendungsfällen mit Drittanbieterdiensten nicht funktionieren. Wenn ein Bericht vertraulich oder sensibel ist oder einen potenziellen Sicherheitsfehler im Produkt beschreibt, den Cyberangreifer ausnutzen könnten, siehe Meldung von Sicherheitsproblemen und Fehlern (dotnet/aspnetcore GitHub-Repository).

  • Nicht autorisierter Client für ME-ID

    Info: Die Autorisierung von Microsoft.AspNetCore.Authorization.DefaultAuthorizationService[2] Authorization ist fehlgeschlagen. Diese Anforderungen wurden nicht erfüllt: DenyAnonymousAuthorizationRequirement: Erfordert einen authentifizierten Benutzer.

    Anmelderückruffehler von ME-ID:

    • Fehler: unauthorized_client
    • Description (Beschreibung): AADB2C90058: The provided application is not configured to allow public clients.

    So beheben Sie den Fehler

    1. Greifen Sie im Azure-Portal auf das Manifest der App zu.
    2. Legen Sie das allowPublicClient Attribut auf null oder true.

Cookies und Standortdaten

Cookies und Standortdaten können über App-Updates hinweg beibehalten werden und das Testen und die Problembehandlung beeinträchtigen. Entfernen Sie Folgendes, wenn Sie Änderungen am App-Code, Änderungen an den Benutzerkonten beim Anbieter oder Konfigurationsänderungen an Anbieter-Apps vornehmen:

  • Anmelde-Cookies von Benutzern
  • App-Cookies
  • Zwischengespeicherte und gespeicherte Standortdaten

Ein Ansatz, um zu verhindern, dass veraltete Cookies und Standortdaten das Testen und die Problembehandlung beeinträchtigen, ist folgender:

  • Browser konfigurieren
    • Verwenden Sie zum Testen einen Browser, den Sie so konfigurieren können, dass alle cookies und Standortdaten jedes Mal gelöscht werden, wenn der Browser geschlossen wird.
    • Stellen Sie sicher, dass der Browser manuell oder durch die IDE für alle Änderungen an der App, dem Testbenutzer oder der Anbieterkonfiguration geschlossen wird.
  • Verwenden Sie einen benutzerdefinierten Befehl, um in Visual Studio einen Browser im privaten oder Inkognito-Modus zu öffnen:
    • Öffnen des Dialogfelds "Durchsuchen mit " über die Schaltfläche " Ausführen " von Visual Studio
    • Wählen Sie die Schaltfläche "Hinzufügen " aus.
    • Geben Sie den Pfad zu Ihrem Browser im Feld "Programm " an. Die folgenden Pfade für ausführbare Dateien sind typische Installationspfade für Windows 10. Wenn Ihr Browser an einem anderen Speicherort installiert ist oder Sie nicht Windows 10 verwenden, geben Sie den Pfad zur ausführbaren Datei des Browsers an.
      • Microsoft Edge: C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
      • Google Chrome: C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
      • Mozilla Firefox: C:\Program Files\Mozilla Firefox\firefox.exe
    • Geben Sie im Feld "Argumente " die Befehlszeilenoption an, die der Browser zum Öffnen im InPrivate- oder Inkognito-Modus verwendet. Für einige Browser ist die URL der App erforderlich.
      • Microsoft Edge: Verwenden Sie -inprivate.
      • Google Chrom: Verwenden Sie --incognito --new-window {URL}, wobei der {URL}-Platzhalter die zu öffnende URL ist (zum Beispiel https://localhost:5001).
      • Mozilla Firefox Verwenden Sie -private -url {URL}, wobei der {URL}-Platzhalter die zu öffnende URL ist (zum Beispiel https://localhost:5001).
    • Geben Sie im Feld Anzeigename einen Namen ein. Beispiel: Firefox Auth Testing.
    • Wählen Sie die Schaltfläche "OK " aus.
    • Um zu vermeiden, dass Sie das Browserprofil für jede Iteration der Tests mit einer App auswählen müssen, legen Sie das Profil als Standard mit der Schaltfläche "Als Standard festlegen " fest.
    • Stellen Sie sicher, dass der Browser von der IDE für alle Änderungen an der App, dem Testbenutzer oder der Anbieterkonfiguration geschlossen wird.

App-Upgrades

Eine funktionierende App kann unmittelbar nach dem Upgrade des .NET SDK auf dem Entwicklungscomputer oder beim Ändern von Paketversionen innerhalb der App fehlschlagen. In einigen Fällen können inkohärente Pakete eine App beschädigen, wenn größere Upgrades durchgeführt werden. Die meisten dieser Probleme können durch Befolgung der folgenden Anweisungen behoben werden:

  1. Löschen Sie die Caches für NuGet-Pakete auf dem lokalen System, indem Sie dotnet nuget locals all --clear in einer Befehlsshell ausführen.
  2. Löschen Sie die Ordner bin und obj des Projekts.
  3. Stellen Sie das Projekt wieder her und erstellen Sie es neu.
  4. Löschen Sie alle Dateien im Bereitstellungsordner auf dem Server, bevor Sie die App noch mal bereitstellen.

Note

Die Verwendung von Paketversionen, die mit dem Zielframework der App nicht kompatibel sind, wird nicht unterstützt. Verwenden Sie den NuGet-Katalog, um Informationen zu einem Paket zu erhalten.

Starten Sie die Lösung aus dem richtigen Projekt

Blazor Web Apps:

  • Starten Sie für eines der BFF-Musterbeispiele (Back-End-for-Frontend) die Lösung aus dem Aspire/Aspire.AppHost Projekt.
  • Starten Sie für eines der nicht-BFF strukturierten Beispiele die Lösung aus dem Server-Projekt.

Blazor Server:

Starten Sie die Lösung vom Serverprojekt.

Überprüfen des Benutzers

Die folgende UserClaims-Komponente kann direkt in Anwendungen verwendet werden oder als Grundlage für weitere Anpassungen dienen.

UserClaims.razor:

@page "/user-claims"
@using System.Security.Claims
@using Microsoft.AspNetCore.Authorization
@attribute [Authorize]

<PageTitle>User Claims</PageTitle>

<h1>User Claims</h1>

@if (claims.Any())
{
    <ul>
        @foreach (var claim in claims)
        {
            <li><b>@claim.Type:</b> @claim.Value</li>
        }
    </ul>
}

@code {
    private IEnumerable<Claim> claims = Enumerable.Empty<Claim>();

    [CascadingParameter]
    private Task<AuthenticationState>? AuthState { get; set; }

    protected override async Task OnInitializedAsync()
    {
        if (AuthState == null)
        {
            return;
        }

        var authState = await AuthState;
        claims = authState.User.Claims;
    }
}

Weitere Ressourcen

  • Last updated on