Zabezpieczanie ASP.NET Core Blazor Web App za pomocą technologii OpenID Connect (OIDC)

W tym artykule opisano sposób zabezpieczania za Blazor Web App przy użyciu przykładowej aplikacji w (dotnet/blazor-samples).

W tej wersji artykułu opisano implementację OIDC bez wdrażania wzorca zaplecza frontonu (BFF) z aplikacją, która przyjmuje globalne renderowanie interakcyjne (serwer i projekty .Client). Wzorzec BFF jest przydatny do podejmowania uwierzytelnionych żądań do usług zewnętrznych. Zmień selektor wersji artykułu na OIDC ze wzorcem BFF, jeśli specyfikacja aplikacji wywołuje wdrożenie wzorca BFF.

Opisano następującą specyfikację:

• Funkcja Blazor Web App używa trybu automatycznego renderowania z globalną interakcyjnością.
• Niestandardowe usługi dostawcy stanu uwierzytelniania są używane przez serwer i aplikacje klienckie do przechwytywania stanu uwierzytelniania użytkownika i przepływu go między serwerem a klientem.
• Ta aplikacja jest punktem wyjścia dla dowolnego przepływu uwierzytelniania OIDC. OIDC jest konfigurowany ręcznie w aplikacji i nie polega na pakietach Microsoft Entra ID ani Microsoft Identity Web , ani nie wymaga hostingu platformy Microsoft Azure . Jednak przykładowa aplikacja może być używana z aplikacją Entra, Microsoft Identity Web i hostowaną na platformie Azure.
• Automatyczne odświeżanie tokenu nieinterakcyjnego.
• Bezpiecznie wywołuje (internetowy) interfejs API w projekcie serwera na potrzeby danych.

Aby uzyskać alternatywne środowisko korzystania z biblioteki Microsoft Authentication Library for .NET, Microsoft Identity Webi Microsoft Entra ID, zobacz Secure an ASP.NET Core Blazor Web App with Microsoft Entra ID.

Przykładowa aplikacja

Przykładowa aplikacja składa się z dwóch projektów:

• BlazorWebAppOidc: Projekt po stronie serwera obiektu , zawierający przykładowy punkt końcowy interfejsu Blazor Web AppAPI Minimalny dla danych pogodowych.
• BlazorWebAppOidc.Client: projekt po stronie klienta obiektu Blazor Web App.

Uzyskaj dostęp do przykładowych aplikacji za pośrednictwem folderu najnowszej wersji z katalogu głównego repozytorium przy użyciu następującego linku. Projekty znajdują się w folderze BlazorWebAppOidc .NET 8 lub nowszym.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Projekt po stronie Blazor Web App serwera (BlazorWebAppOidc)

Projekt BlazorWebAppOidc jest projektem po stronie serwera programu Blazor Web App.

Plik BlazorWebAppOidc.http może służyć do testowania żądania danych pogodowych. Należy pamiętać, że BlazorWebAppOidc projekt musi być uruchomiony, aby przetestować punkt końcowy, a punkt końcowy jest zakodowany w pliku. Aby uzyskać więcej informacji, zobacz Use .http files in Visual Studio 2022 (Używanie plików HTTP w programie Visual Studio 2022).

Konfigurowanie

W tej sekcji wyjaśniono, jak skonfigurować przykładową aplikację.

Uwaga

W przypadku identyfikatora Entra firmy Microsoft lub usługi Azure AD B2C można użyć z AddMicrosoftIdentityWebAppwitryny Microsoft Identity Web (Microsoft.Identity.Web pakiet NuGet, dokumentacja interfejsu API), która dodaje zarówno identyfikator OIDC, jak i Cookie programy obsługi uwierzytelniania z odpowiednimi wartościami domyślnymi. Przykładowa aplikacja i wskazówki zawarte w tej sekcji nie korzystają z witryny Microsoft Identity Web. Wskazówki pokazują, jak ręcznie skonfigurować procedurę obsługi OIDC dla dowolnego dostawcy OIDC. Aby uzyskać więcej informacji na temat implementowania sieci Web firmy Microsoft Identity , zobacz połączone zasoby.

Ustanawianie wpisu tajnego klienta

Ostrzeżenie

Nie przechowuj wpisów tajnych aplikacji, parametry połączenia, poświadczeń, haseł, osobistych numerów identyfikacyjnych (PIN), prywatnego kodu C#/.NET lub kluczy prywatnych/tokenów w kodzie po stronie klienta, który jest zawsze niepewny. W środowiskach testowych/przejściowych i produkcyjnych kod po stronie Blazor serwera i internetowe interfejsy API powinny używać bezpiecznych przepływów uwierzytelniania, które unikają utrzymywania poświadczeń w kodzie projektu lub plikach konfiguracji. Poza lokalnymi testami programistycznymi zalecamy unikanie używania zmiennych środowiskowych do przechowywania poufnych danych, ponieważ zmienne środowiskowe nie są najbezpieczniejszym podejściem. W przypadku lokalnego testowania programistycznego narzędzie Secret Manager jest zalecane do zabezpieczania poufnych danych. Aby uzyskać więcej informacji, zobacz Bezpieczne utrzymywanie poufnych danych i poświadczeń.

W przypadku lokalnego testowania programistycznego użyj narzędzia Secret Manager do przechowywania wpisu tajnego klienta aplikacji serwera w kluczu Authentication:Schemes:MicrosoftOidc:ClientSecretkonfiguracji .

Uwaga

Jeśli aplikacja używa identyfikatora Entra firmy Microsoft lub usługi Azure AD B2C, utwórz wpis tajny klienta w rejestracji aplikacji w witrynie Entra lub w witrynie Azure Portal (>Nowy klucz tajny klienta). Użyj wartości nowego wpisu tajnego w poniższych wskazówkach.

Przykładowa aplikacja nie została zainicjowana dla narzędzia Secret Manager. Użyj powłoki poleceń, takiej jak powłoka poleceń programu PowerShell dla deweloperów w programie Visual Studio, aby wykonać następujące polecenie. Przed wykonaniem polecenia zmień katalog za cd pomocą polecenia na katalog projektu serwera. Polecenie ustanawia identyfikator wpisów tajnych użytkownika (<UserSecretsId> w pliku projektu aplikacji serwera):

dotnet user-secrets init

Wykonaj następujące polecenie, aby ustawić klucz tajny klienta. Symbol {SECRET} zastępczy to klucz tajny klienta uzyskany z rejestracji aplikacji:

dotnet user-secrets set "Authentication:Schemes:MicrosoftOidc:ClientSecret" "{SECRET}"

Jeśli używasz programu Visual Studio, możesz potwierdzić, że wpis tajny został ustawiony, klikając prawym przyciskiem myszy projekt serwera w Eksplorator rozwiązań i wybierając polecenie Zarządzaj wpisami tajnymi użytkownika.

Konfigurowanie aplikacji

Następująca OpenIdConnectOptions konfiguracja znajduje się w pliku projektu Program w wywołaniu metody AddOpenIdConnect:

• SignInScheme: Ustawia schemat uwierzytelniania odpowiadający oprogramowaniu pośredniczącemu odpowiedzialnemu za przechowywanie tożsamości użytkownika po pomyślnym uwierzytelnieniu. Procedura obsługi OIDC musi używać schematu logowania, który może utrwalać poświadczenia użytkownika między żądaniami. Poniższy wiersz jest obecny jedynie w celach demonstracyjnych. W przypadku pominięcia DefaultSignInScheme parametr jest używany jako wartość rezerwowa.

  oidcOptions.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
  

• Zakresy dla openid elementów i profile () (Scopeopcjonalnie): openid zakresy i profile są również konfigurowane domyślnie, ponieważ są one wymagane, aby program obsługi OIDC działał, ale może być konieczne ponowne dodanie tych zakresów, jeśli zakresy są uwzględnione w Authentication:Schemes:MicrosoftOidc:Scope konfiguracji. Aby uzyskać ogólne wskazówki dotyczące konfiguracji, zobacz Konfiguracja w konfiguracji ASP.NET Core i ASP.NET CoreBlazor.

  oidcOptions.Scope.Add(OpenIdConnectScope.OpenIdProfile);
  

• SaveTokens: określa, czy tokeny dostępu i odświeżania powinny być przechowywane w AuthenticationProperties tokenach po pomyślnym uwierzytelnieniu. Ta właściwość jest ustawiona na true, aby token odświeżania był przechowywany na potrzeby nieinterakcyjnego odświeżania tokenu.

  oidcOptions.SaveTokens = true;
  

• Zakres dostępu w trybie offline (Scope): offline_access zakres jest wymagany dla tokenu odświeżania.

  oidcOptions.Scope.Add(OpenIdConnectScope.OfflineAccess);
  

• Authority i ClientId: Ustawia urząd i identyfikator klienta dla wywołań OIDC.

  oidcOptions.Authority = "{AUTHORITY}";
  oidcOptions.ClientId = "{CLIENT ID}";
  

  Przykład:

  • Urząd (): {AUTHORITY} (https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/używa identyfikatora aaaabbbb-0000-cccc-1111-dddd2222eeeedzierżawy )
  • Identyfikator klienta ({CLIENT ID}): 00001111-aaaa-2222-bbbb-3333cccc4444

  oidcOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/";
  oidcOptions.ClientId = "00001111-aaaa-2222-bbbb-3333cccc4444";
  

  Przykład dla urzędu "common" platformy Microsoft Azure:

  Dla aplikacji wielodostępnych należy używać "wspólnego" urzędu. Możesz również użyć "wspólnego" urzędu dla aplikacji z jedną dzierżawą, ale jest wymagany niestandardowy IssuerValidator , jak pokazano w dalszej części tej sekcji.

  oidcOptions.Authority = "https://login.microsoftonline.com/common/v2.0/";
  

• ResponseType: Konfiguruje procedurę obsługi OIDC tak, aby wykonywała tylko przepływ kodu autoryzacji. Niejawne dotacje i przepływy hybrydowe są niepotrzebne w tym trybie. Procedura obsługi OIDC automatycznie żąda odpowiednich tokenów przy użyciu kodu zwróconego z punktu końcowego autoryzacji.

  oidcOptions.ResponseType = OpenIdConnectResponseType.Code;
  

  Uwaga

  W konfiguracji niejawnej rejestracji aplikacji Entra lub Witryny Azure Portal i przepływów hybrydowych nie zaznaczaj pola wyboru dla punktu końcowego autoryzacji w celu zwrócenia tokenów dostępu lub tokenów identyfikatorów.

• MapInboundClaims i konfiguracja NameClaimType i RoleClaimType: Wiele serwerów OIDC używa wartości "name" i "role", a nie wartości domyślnych protokołu SOAP/WS-Fed w systemie ClaimTypes. Gdy MapInboundClaims jest ustawiona wartość false, program obsługi nie wykonuje mapowań oświadczeń, a nazwy oświadczeń z zestawu JWT są używane bezpośrednio przez aplikację. W poniższym przykładzie typ oświadczenia roli jest ustawiany na "roles", który jest odpowiedni dla identyfikatora Entra firmy Microsoft (ME-ID). Aby uzyskać więcej informacji, zapoznaj się z dokumentacją dostawcy tożsamości.

  Uwaga

  MapInboundClaims musi być ustawiona na false wartość dla większości dostawców OIDC, co uniemożliwia zmianę nazw oświadczeń.

  oidcOptions.MapInboundClaims = false;
  oidcOptions.TokenValidationParameters.NameClaimType = "name";
  oidcOptions.TokenValidationParameters.RoleClaimType = "roles";
  

• Konfiguracja ścieżki: ścieżki muszą być zgodne z identyfikatorem URI przekierowania (ścieżką wywołania zwrotnego logowania) i ścieżkami przekierowania wylogowania (ścieżki wywołania zwrotnego wylogowywanego) skonfigurowanymi podczas rejestrowania aplikacji u dostawcy OIDC. W witrynie Azure Portal ścieżki są konfigurowane w bloku Uwierzytelnianie rejestracji aplikacji. Zarówno ścieżki logowania, jak i wylogowania muszą być zarejestrowane jako identyfikatory URI przekierowania. Wartości domyślne to /signin-oidc i /signout-callback-oidc.

  • CallbackPath: ścieżka żądania w ścieżce podstawowej aplikacji, w której jest zwracany agent użytkownika.

    Skonfiguruj ścieżkę wywołania zwrotnego dla wylogowania w rejestracji dostawcy OIDC aplikacji. W poniższym przykładzie symbol zastępczy {PORT} jest portem aplikacji:

    https://localhost:{PORT}/signin-oidc

    Uwaga

    Port nie jest wymagany dla localhost adresów w przypadku korzystania z identyfikatora Entra firmy Microsoft. Większość innych dostawców OIDC wymaga poprawnego portu.

  • SignedOutCallbackPath (klucz konfiguracji: "SignedOutCallbackPath"): ścieżka żądania w ścieżce podstawowej aplikacji przechwycona przez program obsługi OIDC, gdzie agent użytkownika jest najpierw zwracany po wylogowaniu się z dostawcy tożsamości. Przykładowa aplikacja nie ustawia wartości dla ścieżki, ponieważ jest używana domyślna wartość "/signout-callback-oidc". Po przechwyceniu żądania, handler OIDC przekierowuje do SignedOutRedirectUri lub RedirectUri, jeśli określono.

    Skonfiguruj ścieżkę wywołania zwrotnego dla wylogowania w rejestracji dostawcy OIDC aplikacji. W poniższym przykładzie symbol zastępczy {PORT} jest portem aplikacji:

    https://localhost:{PORT}/signout-callback-oidc

    Uwaga

    Podczas korzystania z Microsoft Entra ID, ustaw ścieżkę w konfiguracji platformy webowej we wpisach URI przekierowania w portalu Entra lub Azure. Port nie jest wymagany dla adresów localhost w przypadku korzystania z usługi Entra. Większość innych dostawców OIDC wymaga poprawnego portu. Jeśli nie dodasz identyfikatora URI ścieżki wywołania zwrotnego po wylogowaniu do rejestracji aplikacji w Entra, Entra odmawia przekierowania użytkownika z powrotem do aplikacji i prosi jedynie o zamknięcie okna przeglądarki.

  • RemoteSignOutPath: Żądania odebrane na tej ścieżce powodują, że program obsługi wywołuje wylogowywanie przy użyciu schematu wylogowywanie.

    W poniższym przykładzie symbol zastępczy {PORT} jest portem aplikacji:

    https://localhost/signout-oidc

    Uwaga

    Podczas korzystania z Microsoft Entra ID, ustaw adres URL wylogowywania na kanale frontowym w portalu Entra lub Azure. Port nie jest wymagany dla adresów localhost w przypadku korzystania z usługi Entra. Większość innych dostawców OIDC wymaga poprawnego portu.

    oidcOptions.CallbackPath = new PathString("{PATH}");
    oidcOptions.SignedOutCallbackPath = new PathString("{PATH}");
    oidcOptions.RemoteSignOutPath = new PathString("{PATH}");
    

    Przykłady (wartości domyślne):

    oidcOptions.CallbackPath = new PathString("/signin-oidc");
    oidcOptions.SignedOutCallbackPath = new PathString("/signout-callback-oidc");
    oidcOptions.RemoteSignOutPath = new PathString("/signout-oidc");
    

• (Platforma Microsoft Azure tylko w przypadku "wspólnego" punktu końcowego): TokenValidationParameters.IssuerValidatorwielu dostawców OIDC współpracuje z domyślnym modułem sprawdzania poprawności wystawcy, ale musimy uwzględnić wystawcę sparametryzowanego przy użyciu identyfikatora dzierżawy ({TENANT ID}) zwróconego przez https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Aby uzyskać więcej informacji, zobacz SecurityTokenInvalidIssuerException with OpenID Connect and the Azure AD "common" endpoint (AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet #1731).

  Tylko w przypadku aplikacji korzystających z identyfikatora Entra firmy Microsoft lub usługi Azure AD B2C z "wspólnym" punktem końcowym:

  var microsoftIssuerValidator = AadIssuerValidator.GetAadIssuerValidator(oidcOptions.Authority);
  oidcOptions.TokenValidationParameters.IssuerValidator = microsoftIssuerValidator.Validate;
  

Przykładowy kod aplikacji

Sprawdź przykładową aplikację pod kątem następujących funkcji:

• Automatyczne odświeżanie tokenu nieinterakcyjnego przy użyciu niestandardowego cookie modułu odświeżania (CookieOidcRefresher.cs).
• Projekt serwera wywołuje polecenie AddAuthenticationStateSerialization , aby dodać dostawcę stanu uwierzytelniania po stronie serwera, który używa PersistentComponentState do przepływu stanu uwierzytelniania do klienta. Klient wywołuje AddAuthenticationStateDeserialization metodę deserializacji i użyj stanu uwierzytelniania przekazanego przez serwer. Stan uwierzytelniania jest stały dla okresu istnienia aplikacji WebAssembly.
• Przykładowe żądania dotyczące Blazor Web App danych pogodowych są obsługiwane przez minimalny punkt końcowy interfejsu /weather-forecast API (Program) w pliku (Program.cs). Punkt końcowy wymaga autoryzacji przez wywołanie metody RequireAuthorization. W przypadku wszystkich kontrolerów dodanych do projektu dodaj [Authorize] atrybut do kontrolera lub akcji. Aby uzyskać więcej informacji na temat wymagania autoryzacji w aplikacji za pośrednictwem zasad autoryzacji i pominięcia autoryzacji w przypadku pewnego podzbioru publicznych punktów końcowych, zobacz wskazówki Razor Pages OIDC.
• Aplikacja bezpiecznie wywołuje (internetowy) interfejs API w projekcie serwera na potrzeby danych pogodowych:
  • Podczas renderowania Weather składnika na serwerze składnik używa ServerWeatherForecaster elementu na serwerze do bezpośredniego uzyskiwania danych pogodowych (nie za pośrednictwem wywołania internetowego interfejsu API).
  • Gdy składnik jest renderowany na kliencie, składnik używa ClientWeatherForecaster implementacji usługi, która używa wstępnie skonfigurowanego HttpClient (w pliku projektu Program klienta) do wywołania internetowego interfejsu API do projektu serwera. Minimalny punkt końcowy interfejsu API (/weather-forecast) zdefiniowany w pliku projektu Program serwera uzyskuje dane pogodowe z ServerWeatherForecaster elementu i zwraca dane do klienta.

Aby uzyskać więcej informacji na temat wywołań interfejsu API sieci Web przy użyciu abstrakcji usługi w Blazor Web Appprogramie s, zobacz Blazor ASP.NET Core.

Projekt po stronie Blazor Web App klienta (BlazorWebAppOidc.Client)

Projekt BlazorWebAppOidc.Client jest projektem po stronie klienta programu Blazor Web App.

Klient wywołuje AddAuthenticationStateDeserialization metodę deserializacji i użyj stanu uwierzytelniania przekazanego przez serwer. Stan uwierzytelniania jest stały dla okresu istnienia aplikacji WebAssembly.

Jeśli użytkownik musi się zalogować lub wylogować, wymagane jest ponowne załadowanie pełnej strony.

Przykładowa aplikacja udostępnia tylko nazwę użytkownika i adres e-mail do celów wyświetlania. Nie obejmuje tokenów uwierzytelniających się na serwerze podczas podejmowania kolejnych żądań, które działają oddzielnie przy użyciu elementu cookie uwzględnionego w HttpClient żądaniach do serwera.

W tej wersji artykułu opisano implementację OIDC bez stosowania wzorca Backend for Frontend (BFF) z aplikacją, która korzysta z globalnego interaktywnego renderowania serwera (jeden projekt). Wzorzec BFF jest przydatny do podejmowania uwierzytelnionych żądań do usług zewnętrznych. Zmień selektor wersji artykułu na , używając OIDC ze wzorcem BFF, jeśli specyfikacja aplikacji wymaga wdrożenia wzorca BFF z globalnym interaktywnym renderowaniem automatycznym.

Opisano następującą specyfikację:

• Blazor Web App używa trybu renderowania serwera z globalną interaktywnością.
• Ta aplikacja jest punktem wyjścia dla dowolnego przepływu uwierzytelniania OIDC. OIDC jest konfigurowany ręcznie w aplikacji i nie polega na pakietach Microsoft Entra ID ani Microsoft Identity Web , ani nie wymaga hostingu platformy Microsoft Azure . Jednak przykładowa aplikacja może być używana z aplikacją Entra, Microsoft Identity Web i hostowaną na platformie Azure.
• Automatyczne odświeżanie tokenu nieinterakcyjnego.

Aby uzyskać alternatywne środowisko korzystania z biblioteki Microsoft Authentication Library for .NET, Microsoft Identity Webi Microsoft Entra ID, zobacz Secure an ASP.NET Core Blazor Web App with Microsoft Entra ID.

Przykładowa aplikacja

Przykładowa aplikacja składa się z pojedynczego projektu Blazor Web App po stronie serwera (BlazorWebAppOidcServer).

Uzyskaj dostęp do przykładowej aplikacji za pośrednictwem folderu najnowszej wersji z katalogu głównego repozytorium przy użyciu następującego linku. Projekt znajduje się w folderze BlazorWebAppOidcServer dla platformy .NET 8 lub nowszej.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Konfigurowanie

W tej sekcji wyjaśniono, jak skonfigurować przykładową aplikację.

Uwaga

W przypadku identyfikatora Entra firmy Microsoft lub usługi Azure AD B2C można użyć z AddMicrosoftIdentityWebAppwitryny Microsoft Identity Web (Microsoft.Identity.Web pakiet NuGet, dokumentacja interfejsu API), która dodaje zarówno identyfikator OIDC, jak i Cookie programy obsługi uwierzytelniania z odpowiednimi wartościami domyślnymi. Przykładowa aplikacja i wskazówki zawarte w tej sekcji nie korzystają z witryny Microsoft Identity Web. Wskazówki pokazują, jak ręcznie skonfigurować procedurę obsługi OIDC dla dowolnego dostawcy OIDC. Aby uzyskać więcej informacji na temat implementowania sieci Web firmy Microsoft Identity , zobacz połączone zasoby.

Ustanawianie wpisu tajnego klienta

Ostrzeżenie

Nie przechowuj wpisów tajnych aplikacji, parametry połączenia, poświadczeń, haseł, osobistych numerów identyfikacyjnych (PIN), prywatnego kodu C#/.NET lub kluczy prywatnych/tokenów w kodzie po stronie klienta, który jest zawsze niepewny. W środowiskach testowych/przejściowych i produkcyjnych kod po stronie Blazor serwera i internetowe interfejsy API powinny używać bezpiecznych przepływów uwierzytelniania, które unikają utrzymywania poświadczeń w kodzie projektu lub plikach konfiguracji. Poza lokalnymi testami programistycznymi zalecamy unikanie używania zmiennych środowiskowych do przechowywania poufnych danych, ponieważ zmienne środowiskowe nie są najbezpieczniejszym podejściem. W przypadku lokalnego testowania programistycznego narzędzie Secret Manager jest zalecane do zabezpieczania poufnych danych. Aby uzyskać więcej informacji, zobacz Bezpieczne utrzymywanie poufnych danych i poświadczeń.

W przypadku lokalnego testowania programistycznego użyj narzędzia Secret Manager, aby przechowywać tajny klucz klienta aplikacji pod kluczem konfiguracji Authentication:Schemes:MicrosoftOidc:ClientSecret.

Uwaga

Jeśli aplikacja używa identyfikatora Entra firmy Microsoft lub usługi Azure AD B2C, utwórz wpis tajny klienta w rejestracji aplikacji w witrynie Entra lub w witrynie Azure Portal (>Nowy klucz tajny klienta). Użyj wartości nowego wpisu tajnego w poniższych wskazówkach.

Przykładowa aplikacja nie została zainicjowana dla narzędzia Secret Manager. Użyj powłoki poleceń, takiej jak powłoka poleceń programu PowerShell dla deweloperów w programie Visual Studio, aby wykonać następujące polecenie. Przed wykonaniem polecenia zmień katalog za pomocą polecenia cd na katalog projektu. Polecenie ustanawia identyfikator tajnych danych użytkownika w pliku projektu aplikacji (<UserSecretsId>):

dotnet user-secrets init

Wykonaj następujące polecenie, aby ustawić klucz tajny klienta. Symbol {SECRET} zastępczy to klucz tajny klienta uzyskany z rejestracji aplikacji:

dotnet user-secrets set "Authentication:Schemes:MicrosoftOidc:ClientSecret" "{SECRET}"

Jeśli używasz programu Visual Studio, możesz potwierdzić, że wpis tajny został ustawiony, klikając prawym przyciskiem myszy projekt w eksploratorze rozwiązań i wybierając pozycję Zarządzaj wpisami tajnymi użytkownika.

Konfigurowanie aplikacji

Następująca OpenIdConnectOptions konfiguracja znajduje się w pliku projektu Program w wywołaniu metody AddOpenIdConnect:

• SignInScheme: Ustawia schemat uwierzytelniania odpowiadający oprogramowaniu pośredniczącemu odpowiedzialnemu za przechowywanie tożsamości użytkownika po pomyślnym uwierzytelnieniu. Procedura obsługi OIDC musi używać schematu logowania, który może utrwalać poświadczenia użytkownika między żądaniami. Poniższy wiersz jest obecny jedynie w celach demonstracyjnych. W przypadku pominięcia DefaultSignInScheme parametr jest używany jako wartość rezerwowa.

  oidcOptions.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
  

• Zakresy dla openid elementów i profile () (Scopeopcjonalnie): openid zakresy i profile są również konfigurowane domyślnie, ponieważ są one wymagane, aby program obsługi OIDC działał, ale może być konieczne ponowne dodanie tych zakresów, jeśli zakresy są uwzględnione w Authentication:Schemes:MicrosoftOidc:Scope konfiguracji. Aby uzyskać ogólne wskazówki dotyczące konfiguracji, zobacz Konfiguracja w konfiguracji ASP.NET Core i ASP.NET CoreBlazor.

  oidcOptions.Scope.Add(OpenIdConnectScope.OpenIdProfile);
  

• SaveTokens: określa, czy tokeny dostępu i odświeżania powinny być przechowywane w AuthenticationProperties tokenach po pomyślnym uwierzytelnieniu. Ta właściwość jest ustawiona na true, aby token odświeżania był przechowywany na potrzeby nieinterakcyjnego odświeżania tokenu.

  oidcOptions.SaveTokens = true;
  
  

• Zakres dostępu w trybie offline (Scope): offline_access zakres jest wymagany dla tokenu odświeżania.

  oidcOptions.Scope.Add(OpenIdConnectScope.OfflineAccess);
  

• Authority i ClientId: Ustawia urząd i identyfikator klienta dla wywołań OIDC.

  oidcOptions.Authority = "{AUTHORITY}";
  oidcOptions.ClientId = "{CLIENT ID}";
  

  Przykład:

  • Urząd (): {AUTHORITY} (https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/używa identyfikatora aaaabbbb-0000-cccc-1111-dddd2222eeeedzierżawy )
  • Identyfikator klienta ({CLIENT ID}): 00001111-aaaa-2222-bbbb-3333cccc4444

  oidcOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/";
  oidcOptions.ClientId = "00001111-aaaa-2222-bbbb-3333cccc4444";
  

  Przykład dla urzędu "common" platformy Microsoft Azure:

  Dla aplikacji wielodostępnych należy używać "wspólnego" urzędu. Możesz również użyć "wspólnego" urzędu dla aplikacji z jedną dzierżawą, ale jest wymagany niestandardowy IssuerValidator , jak pokazano w dalszej części tej sekcji.

  oidcOptions.Authority = "https://login.microsoftonline.com/common/v2.0/";
  

• ResponseType: Konfiguruje procedurę obsługi OIDC tak, aby wykonywała tylko przepływ kodu autoryzacji. Niejawne dotacje i przepływy hybrydowe są niepotrzebne w tym trybie. Procedura obsługi OIDC automatycznie żąda odpowiednich tokenów przy użyciu kodu zwróconego z punktu końcowego autoryzacji.

  oidcOptions.ResponseType = OpenIdConnectResponseType.Code;
  

  Uwaga

  W konfiguracji niejawnej rejestracji aplikacji Entra lub Witryny Azure Portal i przepływów hybrydowych nie zaznaczaj pola wyboru dla punktu końcowego autoryzacji w celu zwrócenia tokenów dostępu lub tokenów identyfikatorów.

• MapInboundClaims i konfiguracja NameClaimType i RoleClaimType: Wiele serwerów OIDC używa wartości "name" i "role", a nie wartości domyślnych protokołu SOAP/WS-Fed w systemie ClaimTypes. Gdy MapInboundClaims jest ustawiona wartość false, program obsługi nie wykonuje mapowań oświadczeń, a nazwy oświadczeń z zestawu JWT są używane bezpośrednio przez aplikację. W poniższym przykładzie typ oświadczenia roli jest ustawiany na "roles", który jest odpowiedni dla identyfikatora Entra firmy Microsoft (ME-ID). Aby uzyskać więcej informacji, zapoznaj się z dokumentacją dostawcy tożsamości.

  Uwaga

  MapInboundClaims musi być ustawiona na false wartość dla większości dostawców OIDC, co uniemożliwia zmianę nazw oświadczeń.

  oidcOptions.MapInboundClaims = false;
  oidcOptions.TokenValidationParameters.NameClaimType = "name";
  oidcOptions.TokenValidationParameters.RoleClaimType = "roles";
  

• Konfiguracja ścieżki: ścieżki muszą być zgodne z identyfikatorem URI przekierowania (ścieżką wywołania zwrotnego logowania) i ścieżkami przekierowania wylogowania (ścieżki wywołania zwrotnego wylogowywanego) skonfigurowanymi podczas rejestrowania aplikacji u dostawcy OIDC. W witrynie Azure Portal ścieżki są konfigurowane w bloku Uwierzytelnianie rejestracji aplikacji. Zarówno ścieżki logowania, jak i wylogowania muszą być zarejestrowane jako identyfikatory URI przekierowania. Wartości domyślne to /signin-oidc i /signout-callback-oidc.

  • CallbackPath: ścieżka żądania w ścieżce podstawowej aplikacji, w której jest zwracany agent użytkownika.

    Skonfiguruj ścieżkę wywołania zwrotnego dla wylogowania w rejestracji dostawcy OIDC aplikacji. W poniższym przykładzie symbol zastępczy {PORT} jest portem aplikacji:

    https://localhost:{PORT}/signin-oidc

    Uwaga

    Port nie jest wymagany dla localhost adresów w przypadku korzystania z identyfikatora Entra firmy Microsoft. Większość innych dostawców OIDC wymaga poprawnego portu.

  • SignedOutCallbackPath (klucz konfiguracji: "SignedOutCallbackPath"): ścieżka żądania w ścieżce podstawowej aplikacji przechwycona przez program obsługi OIDC, gdzie agent użytkownika jest najpierw zwracany po wylogowaniu się z dostawcy tożsamości. Przykładowa aplikacja nie ustawia wartości dla ścieżki, ponieważ jest używana domyślna wartość "/signout-callback-oidc". Po przechwyceniu żądania, handler OIDC przekierowuje do SignedOutRedirectUri lub RedirectUri, jeśli określono.

    Skonfiguruj ścieżkę wywołania zwrotnego dla wylogowania w rejestracji dostawcy OIDC aplikacji. W poniższym przykładzie symbol zastępczy {PORT} jest portem aplikacji:

    https://localhost:{PORT}/signout-callback-oidc

    Uwaga

    Podczas korzystania z Microsoft Entra ID, ustaw ścieżkę w konfiguracji platformy webowej we wpisach URI przekierowania w portalu Entra lub Azure. Port nie jest wymagany dla adresów localhost w przypadku korzystania z usługi Entra. Większość innych dostawców OIDC wymaga poprawnego portu. Jeśli nie dodasz identyfikatora URI ścieżki wywołania zwrotnego po wylogowaniu do rejestracji aplikacji w Entra, Entra odmawia przekierowania użytkownika z powrotem do aplikacji i prosi jedynie o zamknięcie okna przeglądarki.

  • RemoteSignOutPath: Żądania odebrane na tej ścieżce powodują, że program obsługi wywołuje wylogowywanie przy użyciu schematu wylogowywanie.

    W poniższym przykładzie symbol zastępczy {PORT} jest portem aplikacji:

    https://localhost/signout-oidc

    Uwaga

    Podczas korzystania z Microsoft Entra ID, ustaw adres URL wylogowywania na kanale frontowym w portalu Entra lub Azure. Port nie jest wymagany dla adresów localhost w przypadku korzystania z usługi Entra. Większość innych dostawców OIDC wymaga poprawnego portu.

    oidcOptions.CallbackPath = new PathString("{PATH}");
    oidcOptions.SignedOutCallbackPath = new PathString("{PATH}");
    oidcOptions.RemoteSignOutPath = new PathString("{PATH}");
    

    Przykłady (wartości domyślne):

    oidcOptions.CallbackPath = new PathString("/signin-oidc");
    oidcOptions.SignedOutCallbackPath = new PathString("/signout-callback-oidc");
    oidcOptions.RemoteSignOutPath = new PathString("/signout-oidc");
    

• (Platforma Microsoft Azure tylko w przypadku "wspólnego" punktu końcowego): TokenValidationParameters.IssuerValidatorwielu dostawców OIDC współpracuje z domyślnym modułem sprawdzania poprawności wystawcy, ale musimy uwzględnić wystawcę sparametryzowanego przy użyciu identyfikatora dzierżawy ({TENANT ID}) zwróconego przez https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Aby uzyskać więcej informacji, zobacz SecurityTokenInvalidIssuerException with OpenID Connect and the Azure AD "common" endpoint (AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet #1731).

  Tylko w przypadku aplikacji korzystających z identyfikatora Entra firmy Microsoft lub usługi Azure AD B2C z "wspólnym" punktem końcowym:

  var microsoftIssuerValidator = AadIssuerValidator.GetAadIssuerValidator(oidcOptions.Authority);
  oidcOptions.TokenValidationParameters.IssuerValidator = microsoftIssuerValidator.Validate;
  

Przykładowy kod aplikacji

Sprawdź przykładową aplikację pod kątem następujących funkcji:

• Automatyczne odświeżanie tokenu nieinterakcyjnego przy użyciu niestandardowego cookie modułu odświeżania (CookieOidcRefresher.cs).
• Składnik Weather używa atrybutu [Authorize] o nazwie, aby zapobiec nieautoryzowanemu dostępowi. Aby uzyskać więcej informacji na temat wymagania autoryzacji w aplikacji za pośrednictwem zasad autoryzacji i pominięcia autoryzacji w przypadku pewnego podzbioru publicznych punktów końcowych, zobacz wskazówki Razor Pages OIDC.

W tej wersji artykułu opisano implementację OIDC ze wzorcem zaplecza frontonu (BFF). Zmień selektor wersji artykułu na OIDC bez wzorca BFF, jeśli specyfikacja aplikacji nie wywołuje wdrożenia wzorca BFF.

Opisano następującą specyfikację:

• Funkcja Blazor Web App używa trybu automatycznego renderowania z globalną interakcyjnością.
• Niestandardowe usługi dostawcy stanu uwierzytelniania są używane przez serwer i aplikacje klienckie do przechwytywania stanu uwierzytelniania użytkownika i przepływu go między serwerem a klientem.
• Ta aplikacja jest punktem wyjścia dla dowolnego przepływu uwierzytelniania OIDC. OIDC jest konfigurowany ręcznie w aplikacji i nie polega na pakietach Microsoft Entra ID ani Microsoft Identity Web , ani nie wymaga hostingu platformy Microsoft Azure . Jednak przykładowa aplikacja może być używana z aplikacją Entra, Microsoft Identity Web i hostowaną na platformie Azure.
• Automatyczne odświeżanie tokenu nieinterakcyjnego.
• Wzorzec zaplecza frontonu (BFF) jest używany na .NET Aspire potrzeby odnajdywania usług i yaRP na potrzeby proxy żądań do punktu końcowego prognozy pogody w aplikacji zaplecza.
  • Internetowy interfejs API zaplecza używa uwierzytelniania elementu nośnego JWT do weryfikowania tokenów JWT zapisanych w Blazor Web App logowaniu cookie.
  • Aspirowanie usprawnia tworzenie aplikacji natywnych dla chmury platformy .NET. Zapewnia spójny, opiniowany zestaw narzędzi i wzorców do tworzenia i uruchamiania aplikacji rozproszonych.
  • YARP (Jeszcze inny zwrotny serwer proxy) to biblioteka używana do tworzenia zwrotnego serwera proxy.

Aby uzyskać więcej informacji na temat .NET Aspireprogramu , zobacz Ogólna dostępność .NET Aspire: Upraszczanie tworzenia aplikacji natywnych dla chmury platformy .NET (maj 2024 r.).

Warunek wstępny

.NET Aspire program Wymaga programu Visual Studio w wersji 17.10 lub nowszej.

Przykładowa aplikacja

Przykładowa aplikacja składa się z pięciu projektów:

• .NET Aspire:
  • Aspire.AppHost: służy do zarządzania problemami dotyczącymi orkiestracji wysokiego poziomu aplikacji.
  • Aspire.ServiceDefaults: zawiera domyślne .NET Aspire konfiguracje aplikacji, które można rozszerzyć i dostosować zgodnie z potrzebami.
• MinimalApiJwt: internetowy interfejs API zaplecza zawierający przykładowy minimalny punkt końcowy interfejsu API dla danych pogodowych.
• BlazorWebAppOidc: Projekt po stronie serwera programu Blazor Web App.
• BlazorWebAppOidc.Client: projekt po stronie klienta obiektu Blazor Web App.

Uzyskaj dostęp do przykładowych aplikacji za pośrednictwem folderu najnowszej wersji z katalogu głównego repozytorium przy użyciu następującego linku. Projekty znajdują się w folderze BlazorWebAppOidcBff .NET 8 lub nowszym.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Projekty: .NET Aspire

Aby uzyskać więcej informacji na temat korzystania .NET Aspire z przykładowej aplikacji oraz szczegółów .AppHost dotyczących projektów i.ServiceDefaults, zobacz dokumentację.NET Aspire.

Upewnij się, że zostały spełnione wymagania wstępne dotyczące programu .NET Aspire. Aby uzyskać więcej informacji, zobacz sekcję Wymagania wstępne przewodnika Szybki start: tworzenie pierwszej .NET Aspire aplikacji.

Przykładowa aplikacja konfiguruje tylko niezabezpieczony profil uruchamiania HTTP (http) do użycia podczas testowania programistycznego. Aby uzyskać więcej informacji, w tym przykład niezabezpieczonych i bezpiecznych profilów ustawień uruchamiania, zobacz Zezwalanie na niezabezpieczony transport w .NET Aspire (.NET Aspire dokumentacja).

Projekt po stronie Blazor Web App serwera (BlazorWebAppOidc)

Projekt BlazorWebAppOidc jest projektem po stronie serwera programu Blazor Web App. Projekt używa yaRP do proxy żądań do punktu końcowego prognozy pogody w projekcie internetowego interfejsu API zaplecza (MinimalApiJwt) z przechowywanym access_token w uwierzytelnianiu cookie.

Plik BlazorWebAppOidc.http może służyć do testowania żądania danych pogodowych. Należy pamiętać, że BlazorWebAppOidc projekt musi być uruchomiony, aby przetestować punkt końcowy, a punkt końcowy jest zakodowany w pliku. Aby uzyskać więcej informacji, zobacz Use .http files in Visual Studio 2022 (Używanie plików HTTP w programie Visual Studio 2022).

Konfigurowanie

W tej sekcji wyjaśniono, jak skonfigurować przykładową aplikację.

Uwaga

W przypadku identyfikatora Entra firmy Microsoft lub usługi Azure AD B2C można użyć z AddMicrosoftIdentityWebAppwitryny Microsoft Identity Web (Microsoft.Identity.Web pakiet NuGet, dokumentacja interfejsu API), która dodaje zarówno identyfikator OIDC, jak i Cookie programy obsługi uwierzytelniania z odpowiednimi wartościami domyślnymi. Przykładowa aplikacja i wskazówki zawarte w tej sekcji nie korzystają z witryny Microsoft Identity Web. Wskazówki pokazują, jak ręcznie skonfigurować procedurę obsługi OIDC dla dowolnego dostawcy OIDC. Aby uzyskać więcej informacji na temat implementowania sieci Web firmy Microsoft Identity , zobacz połączone zasoby.

Ustanawianie wpisu tajnego klienta

Ostrzeżenie

Nie przechowuj wpisów tajnych aplikacji, parametry połączenia, poświadczeń, haseł, osobistych numerów identyfikacyjnych (PIN), prywatnego kodu C#/.NET lub kluczy prywatnych/tokenów w kodzie po stronie klienta, który jest zawsze niepewny. W środowiskach testowych/przejściowych i produkcyjnych kod po stronie Blazor serwera i internetowe interfejsy API powinny używać bezpiecznych przepływów uwierzytelniania, które unikają utrzymywania poświadczeń w kodzie projektu lub plikach konfiguracji. Poza lokalnymi testami programistycznymi zalecamy unikanie używania zmiennych środowiskowych do przechowywania poufnych danych, ponieważ zmienne środowiskowe nie są najbezpieczniejszym podejściem. W przypadku lokalnego testowania programistycznego narzędzie Secret Manager jest zalecane do zabezpieczania poufnych danych. Aby uzyskać więcej informacji, zobacz Bezpieczne utrzymywanie poufnych danych i poświadczeń.

W przypadku lokalnego testowania programistycznego użyj narzędzia Secret Manager do przechowywania wpisu tajnego klienta aplikacji serwera w kluczu Authentication:Schemes:MicrosoftOidc:ClientSecretkonfiguracji .

Uwaga

Jeśli aplikacja używa identyfikatora Entra firmy Microsoft lub usługi Azure AD B2C, utwórz wpis tajny klienta w rejestracji aplikacji w witrynie Entra lub w witrynie Azure Portal (>Nowy klucz tajny klienta). Użyj wartości nowego wpisu tajnego w poniższych wskazówkach.

Przykładowa aplikacja nie została zainicjowana dla narzędzia Secret Manager. Użyj powłoki poleceń, takiej jak powłoka poleceń programu PowerShell dla deweloperów w programie Visual Studio, aby wykonać następujące polecenie. Przed wykonaniem polecenia zmień katalog za cd pomocą polecenia na katalog projektu serwera. Polecenie ustanawia identyfikator wpisów tajnych użytkownika (<UserSecretsId> w pliku projektu aplikacji serwera):

dotnet user-secrets init

Wykonaj następujące polecenie, aby ustawić klucz tajny klienta. Symbol {SECRET} zastępczy to klucz tajny klienta uzyskany z rejestracji aplikacji:

dotnet user-secrets set "Authentication:Schemes:MicrosoftOidc:ClientSecret" "{SECRET}"

Jeśli używasz programu Visual Studio, możesz potwierdzić, że wpis tajny został ustawiony, klikając prawym przyciskiem myszy projekt serwera w Eksplorator rozwiązań i wybierając polecenie Zarządzaj wpisami tajnymi użytkownika.

Konfigurowanie aplikacji

Następująca OpenIdConnectOptions konfiguracja znajduje się w pliku projektu Program w wywołaniu metody AddOpenIdConnect:

• SignInScheme: Ustawia schemat uwierzytelniania odpowiadający oprogramowaniu pośredniczącemu odpowiedzialnemu za przechowywanie tożsamości użytkownika po pomyślnym uwierzytelnieniu. Procedura obsługi OIDC musi używać schematu logowania, który może utrwalać poświadczenia użytkownika między żądaniami. Poniższy wiersz jest obecny jedynie w celach demonstracyjnych. W przypadku pominięcia DefaultSignInScheme parametr jest używany jako wartość rezerwowa.

  oidcOptions.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
  

• Zakresy dla openid elementów i profile () (Scopeopcjonalnie): openid zakresy i profile są również konfigurowane domyślnie, ponieważ są one wymagane, aby program obsługi OIDC działał, ale może być konieczne ponowne dodanie tych zakresów, jeśli zakresy są uwzględnione w Authentication:Schemes:MicrosoftOidc:Scope konfiguracji. Aby uzyskać ogólne wskazówki dotyczące konfiguracji, zobacz Konfiguracja w konfiguracji ASP.NET Core i ASP.NET CoreBlazor.

  oidcOptions.Scope.Add(OpenIdConnectScope.OpenIdProfile);
  

• SaveTokens: określa, czy tokeny dostępu i odświeżania powinny być przechowywane w AuthenticationProperties tokenach po pomyślnym uwierzytelnieniu. Wartość jest ustawiona na wartość , aby uwierzytelniać true żądania dotyczące danych pogodowych z projektu internetowego interfejsu API zaplecza (MinimalApiJwt).

  oidcOptions.SaveTokens = true;
  

• Zakres dostępu w trybie offline (Scope): offline_access zakres jest wymagany dla tokenu odświeżania.

  oidcOptions.Scope.Add(OpenIdConnectScope.OfflineAccess);
  

• Zakresy uzyskiwania danych pogodowych z internetowego interfejsu API (Scope): jest to konieczne, aby projekt internetowego interfejsu API zaplecza (MinimalApiJwt) zweryfikował token dostępu za pomocą elementu nośnego JWT.

  oidcOptions.Scope.Add("{APP ID URI}/{API NAME}");
  

  Uwaga

  W przypadku korzystania z Microsoft Entra ID zakres Weather.Get jest konfigurowany w portalu Azure lub portalu Entra w sekcji Eksponowanie interfejsu API.

  Przykład:

  • Identyfikator URI identyfikatora aplikacji ({APP ID URI}): https://{DIRECTORY NAME}.onmicrosoft.com/{CLIENT ID}
    • Nazwa katalogu ({DIRECTORY NAME}): contoso
    • Identyfikator aplikacji (klienta) ({CLIENT ID}): 00001111-aaaa-2222-bbbb-3333cccc4444
  • Zakres skonfigurowany dla danych pogodowych z MinimalApiJwt ({API NAME}): Weather.Get

  oidcOptions.Scope.Add("https://contoso.onmicrosoft.com/00001111-aaaa-2222-bbbb-3333cccc4444/Weather.Get");
  

  Powyższy przykład dotyczy aplikacji zarejestrowanej w dzierżawie z typem dzierżawy usługi AAD B2C. Jeśli aplikacja jest zarejestrowana w dzierżawie ME-ID, identyfikator URI identyfikatora aplikacji jest inny, dlatego zakres jest inny.

  Przykład:

  • Identyfikator URI identyfikatora aplikacji ({APP ID URI}): api://{CLIENT ID} z identyfikatorem aplikacji (klient) ({CLIENT ID}): 00001111-aaaa-2222-bbbb-3333cccc4444
  • Zakres skonfigurowany dla danych pogodowych z MinimalApiJwt ({API NAME}): Weather.Get

  oidcOptions.Scope.Add("api://00001111-aaaa-2222-bbbb-3333cccc4444/Weather.Get");
  

• Authority i ClientId: Ustawia urząd i identyfikator klienta dla wywołań OIDC.

  oidcOptions.Authority = "{AUTHORITY}";
  oidcOptions.ClientId = "{CLIENT ID}";
  

  Przykład:

  • Urząd (): {AUTHORITY} (https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/używa identyfikatora aaaabbbb-0000-cccc-1111-dddd2222eeeedzierżawy )
  • Identyfikator klienta ({CLIENT ID}): 00001111-aaaa-2222-bbbb-3333cccc4444

  oidcOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/";
  oidcOptions.ClientId = "00001111-aaaa-2222-bbbb-3333cccc4444";
  

  Przykład dla urzędu "common" platformy Microsoft Azure:

  Dla aplikacji wielodostępnych należy używać "wspólnego" urzędu. Możesz również użyć "wspólnego" urzędu dla aplikacji z jedną dzierżawą, ale jest wymagany niestandardowy IssuerValidator , jak pokazano w dalszej części tej sekcji.

  oidcOptions.Authority = "https://login.microsoftonline.com/common/v2.0/";
  

• ResponseType: Konfiguruje procedurę obsługi OIDC tak, aby wykonywała tylko przepływ kodu autoryzacji. Niejawne dotacje i przepływy hybrydowe są niepotrzebne w tym trybie. Procedura obsługi OIDC automatycznie żąda odpowiednich tokenów przy użyciu kodu zwróconego z punktu końcowego autoryzacji.

  oidcOptions.ResponseType = OpenIdConnectResponseType.Code;
  

  Uwaga

  W przypadku korzystania z identyfikatora Entra firmy Microsoft nie zaznacz pole wyboru, aby punkt końcowy autoryzacji zwracał tokeny dostępu lub tokeny identyfikatorów w niejawne udzielanie i przepływy hybrydowe konfiguracji rejestracji aplikacji.

• MapInboundClaims i konfiguracja NameClaimType i RoleClaimType: Wiele serwerów OIDC używa wartości "name" i "role", a nie wartości domyślnych protokołu SOAP/WS-Fed w systemie ClaimTypes. Gdy MapInboundClaims jest ustawiona wartość false, program obsługi nie wykonuje mapowań oświadczeń, a nazwy oświadczeń z zestawu JWT są używane bezpośrednio przez aplikację. W poniższym przykładzie typ oświadczenia roli jest ustawiany na "roles", który jest odpowiedni dla identyfikatora Entra firmy Microsoft (ME-ID). Aby uzyskać więcej informacji, zapoznaj się z dokumentacją dostawcy tożsamości.

  Uwaga

  MapInboundClaims musi być ustawiona na false wartość dla większości dostawców OIDC, co uniemożliwia zmianę nazw oświadczeń.

  oidcOptions.MapInboundClaims = false;
  oidcOptions.TokenValidationParameters.NameClaimType = "name";
  oidcOptions.TokenValidationParameters.RoleClaimType = "roles";
  

• Konfiguracja ścieżki: ścieżki muszą być zgodne z identyfikatorem URI przekierowania (ścieżką wywołania zwrotnego logowania) i ścieżkami przekierowania wylogowania (ścieżki wywołania zwrotnego wylogowywanego) skonfigurowanymi podczas rejestrowania aplikacji u dostawcy OIDC. W witrynie Azure Portal ścieżki są konfigurowane w bloku Uwierzytelnianie rejestracji aplikacji. Zarówno ścieżki logowania, jak i wylogowania muszą być zarejestrowane jako identyfikatory URI przekierowania. Wartości domyślne to /signin-oidc i /signout-callback-oidc.

  Skonfiguruj ścieżkę wywołania zwrotnego dla wylogowania w rejestracji dostawcy OIDC aplikacji. W poniższym przykładzie symbol zastępczy {PORT} jest portem aplikacji:

  https://localhost:{PORT}/signin-oidc

  Uwaga

  Port nie jest wymagany dla localhost adresów w przypadku korzystania z identyfikatora Entra firmy Microsoft. Większość innych dostawców OIDC wymaga poprawnego portu.

  • SignedOutCallbackPath (klucz konfiguracji: "SignedOutCallbackPath"): ścieżka żądania w ścieżce podstawowej aplikacji przechwycona przez program obsługi OIDC, gdzie agent użytkownika jest najpierw zwracany po wylogowaniu się z dostawcy tożsamości. Przykładowa aplikacja nie ustawia wartości dla ścieżki, ponieważ jest używana domyślna wartość "/signout-callback-oidc". Po przechwyceniu żądania, handler OIDC przekierowuje do SignedOutRedirectUri lub RedirectUri, jeśli określono.

    Skonfiguruj ścieżkę wywołania zwrotnego dla wylogowania w rejestracji dostawcy OIDC aplikacji. W poniższym przykładzie symbol zastępczy {PORT} jest portem aplikacji:

    https://localhost:{PORT}/signout-callback-oidc

    Uwaga

    Podczas korzystania z Microsoft Entra ID, ustaw ścieżkę w konfiguracji platformy webowej we wpisach URI przekierowania w portalu Entra lub Azure. Port nie jest wymagany dla adresów localhost w przypadku korzystania z usługi Entra. Większość innych dostawców OIDC wymaga poprawnego portu. Jeśli nie dodasz identyfikatora URI ścieżki wywołania zwrotnego po wylogowaniu do rejestracji aplikacji w Entra, Entra odmawia przekierowania użytkownika z powrotem do aplikacji i prosi jedynie o zamknięcie okna przeglądarki.

  • RemoteSignOutPath: Żądania odebrane na tej ścieżce powodują, że program obsługi wywołuje wylogowywanie przy użyciu schematu wylogowywanie.

    W poniższym przykładzie symbol zastępczy {PORT} jest portem aplikacji:

    https://localhost/signout-oidc

    Uwaga

    Podczas korzystania z Microsoft Entra ID, ustaw adres URL wylogowywania na kanale frontowym w portalu Entra lub Azure. Port nie jest wymagany dla adresów localhost w przypadku korzystania z usługi Entra. Większość innych dostawców OIDC wymaga poprawnego portu.

    oidcOptions.CallbackPath = new PathString("{PATH}");
    oidcOptions.SignedOutCallbackPath = new PathString("{PATH}");
    oidcOptions.RemoteSignOutPath = new PathString("{PATH}");
    

    Przykłady (wartości domyślne):

    oidcOptions.CallbackPath = new PathString("/signin-oidc");
    oidcOptions.SignedOutCallbackPath = new PathString("/signout-callback-oidc");
    oidcOptions.RemoteSignOutPath = new PathString("/signout-oidc");
    

• (Platforma Microsoft Azure tylko w przypadku "wspólnego" punktu końcowego): TokenValidationParameters.IssuerValidatorwielu dostawców OIDC współpracuje z domyślnym modułem sprawdzania poprawności wystawcy, ale musimy uwzględnić wystawcę sparametryzowanego przy użyciu identyfikatora dzierżawy ({TENANT ID}) zwróconego przez https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Aby uzyskać więcej informacji, zobacz SecurityTokenInvalidIssuerException with OpenID Connect and the Azure AD "common" endpoint (AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet #1731).

  Tylko w przypadku aplikacji korzystających z identyfikatora Entra firmy Microsoft lub usługi Azure AD B2C z "wspólnym" punktem końcowym:

  var microsoftIssuerValidator = AadIssuerValidator.GetAadIssuerValidator(oidcOptions.Authority);
  oidcOptions.TokenValidationParameters.IssuerValidator = microsoftIssuerValidator.Validate;
  

Przykładowy kod aplikacji

Sprawdź przykładową aplikację pod kątem następujących funkcji:

• Automatyczne odświeżanie tokenu nieinterakcyjnego przy użyciu niestandardowego cookie modułu odświeżania (CookieOidcRefresher.cs).
• Projekt serwera wywołuje polecenie AddAuthenticationStateSerialization , aby dodać dostawcę stanu uwierzytelniania po stronie serwera, który używa PersistentComponentState do przepływu stanu uwierzytelniania do klienta. Klient wywołuje AddAuthenticationStateDeserialization metodę deserializacji i użyj stanu uwierzytelniania przekazanego przez serwer. Stan uwierzytelniania jest stały dla okresu istnienia aplikacji WebAssembly.
• Żądania do elementu Blazor Web App są kierowane do projektu internetowego interfejsu API zaplecza (MinimalApiJwt). MapForwarder Program w pliku dodaje bezpośrednie przekazywanie żądań HTTP, które pasują do określonego wzorca do określonego miejsca docelowego przy użyciu domyślnej konfiguracji dla żądania wychodzącego, dostosowanych przekształceń i domyślnego klienta HTTP:
  • Podczas renderowania składnika Weather na serwerze składnik używa klasy ServerWeatherForecaster jako pośrednika na żądanie danych pogodowych przy użyciu tokenu dostępu użytkownika. IHttpContextAccessor.HttpContext określa, czy HttpContext jest dostępny do użycia przez metodę GetWeatherForecastAsync. Aby uzyskać więcej informacji, zobacz ASP.NET Core Razor components.
  • Gdy składnik jest renderowany na kliencie, składnik używa ClientWeatherForecaster implementacji usługi, która używa wstępnie skonfigurowanego HttpClient (w pliku projektu Program klienta) do wywołania internetowego interfejsu API do projektu serwera. Minimalny punkt końcowy interfejsu API (/weather-forecast) zdefiniowany w pliku projektu Program serwera przekształca żądanie przy użyciu tokenu dostępu użytkownika w celu uzyskania danych pogodowych.

Aby uzyskać więcej informacji na temat wywołań interfejsu API sieci Web przy użyciu abstrakcji usługi w Blazor Web Appprogramie s, zobacz Blazor ASP.NET Core.

Projekt po stronie Blazor Web App klienta (BlazorWebAppOidc.Client)

Projekt BlazorWebAppOidc.Client jest projektem po stronie klienta programu Blazor Web App.

Klient wywołuje AddAuthenticationStateDeserialization metodę deserializacji i użyj stanu uwierzytelniania przekazanego przez serwer. Stan uwierzytelniania jest stały dla okresu istnienia aplikacji WebAssembly.

Jeśli użytkownik musi się zalogować lub wylogować, wymagane jest ponowne załadowanie pełnej strony.

Przykładowa aplikacja udostępnia tylko nazwę użytkownika i adres e-mail do celów wyświetlania. Nie obejmuje tokenów uwierzytelniających się na serwerze podczas podejmowania kolejnych żądań, które działają oddzielnie przy użyciu elementu cookie uwzględnionego w HttpClient żądaniach do serwera.

Projekt internetowego interfejsu API zaplecza (MinimalApiJwt)

Projekt MinimalApiJwt jest internetowym interfejsem API zaplecza dla wielu projektów frontonu. Projekt konfiguruje minimalny punkt końcowy interfejsu API dla danych pogodowych. Żądania z Blazor Web App projektu po stronie serwera (BlazorWebAppOidc) są kierowane do MinimalApiJwt projektu.

Konfigurowanie

Skonfiguruj projekt w JwtBearerOptions wywołaniu AddJwtBearer w pliku projektu Program :

• Audience: ustawia grupę odbiorców dla dowolnego odebranego tokenu OIDC.

  jwtOptions.Audience = "{APP ID URI}";
  

  Uwaga

  W przypadku korzystania z identyfikatora Entra firmy Microsoft dopasuj wartość tylko do ścieżki identyfikatora URI identyfikatora aplikacji skonfigurowanego podczas dodawania zakresu w obszarze Uwidaczniaj interfejsu API w witrynie Azure lub Entra Portal.

  Przykład:

  Identyfikator URI identyfikatora aplikacji ({APP ID URI}): : https://{DIRECTORY NAME}.onmicrosoft.com/{CLIENT ID}

  • Nazwa katalogu ({DIRECTORY NAME}): contoso
  • Identyfikator aplikacji (klienta) ({CLIENT ID}): 00001111-aaaa-2222-bbbb-3333cccc4444

  jwtOptions.Audience = "https://contoso.onmicrosoft.com/00001111-aaaa-2222-bbbb-3333cccc4444";
  

  Powyższy przykład dotyczy aplikacji zarejestrowanej w dzierżawie z typem dzierżawy usługi AAD B2C. Jeśli aplikacja jest zarejestrowana w dzierżawie ME-ID, identyfikator URI identyfikatora aplikacji jest inny, w związku z czym odbiorcy są różni.

  Przykład:

  Identyfikator URI identyfikatora aplikacji ({APP ID URI}): api://{CLIENT ID} z identyfikatorem aplikacji (klient) ({CLIENT ID}): 00001111-aaaa-2222-bbbb-3333cccc4444

  jwtOptions.Audience = "api://00001111-aaaa-2222-bbbb-3333cccc4444";
  

• Authority: Konfiguruje autoryzację do wykonywania wywołań OIDC. Dopasuj wartość do urzędu skonfigurowanego dla programu obsługi OIDC w programie BlazorWebAppOidc/Program.cs:

  jwtOptions.Authority = "{AUTHORITY}";
  

  Przykład:

  Urząd (): {AUTHORITY} (https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/używa identyfikatora aaaabbbb-0000-cccc-1111-dddd2222eeeedzierżawy )

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

  Powyższy przykład dotyczy aplikacji zarejestrowanej w dzierżawie z typem dzierżawy usługi AAD B2C. Jeśli aplikacja jest zarejestrowana w dzierżawie ME-ID, autorytet powinien być zgodny z wydawcą (iss) tokenu JWT zwróconego przez dostawcę tożsamości.

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

Minimalny interfejs API dla danych pogodowych

Zabezpieczanie punktu końcowego danych prognozy pogody w pliku projektu Program :

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();

Metoda RequireAuthorization rozszerzenia wymaga autoryzacji dla definicji trasy. W przypadku wszystkich kontrolerów dodanych do projektu dodaj [Authorize] atrybut do kontrolera lub akcji.

Przekieruj do strony głównej po wylogowaniu

Składnik LogInOrOut (Layout/LogInOrOut.razor) ustawia ukryte pole dla zwracanego adresu URL (ReturnUrl) na bieżący adres URL (currentURL). Gdy użytkownik wyloguje się z aplikacji, dostawca tożsamości zwraca użytkownika do strony, z której się wylogował. Jeśli użytkownik wyloguje się z bezpiecznej strony, zostanie zwrócony do tej samej bezpiecznej strony i odesłany przez proces uwierzytelniania. Ten przepływ uwierzytelniania jest rozsądny, gdy użytkownicy muszą regularnie zmieniać konta.

Alternatywnie użyj następującego składnika LogInOrOut, który nie dostarcza adresu URL zwrotnego podczas wylogowywania.

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 @context.User.Identity?.Name
                </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>

Odświeżenie tokenu

Implementacja niestandardowego modułu odświeżania cookie (CookieOidcRefresher.cs) automatycznie aktualizuje roszczenia użytkownika, gdy wygasną. Bieżąca implementacja oczekuje otrzymania tokenu identyfikatora z punktu końcowego tokenu w zamian za token odświeżania. Oświadczenia w tym tokenie identyfikatora są następnie używane do zastępowania oświadczeń użytkownika.

Przykładowa implementacja nie zawiera kodu do żądania oświadczeń z punktu końcowego UserInfo podczas odświeżania tokenu. Aby uzyskać więcej informacji, zobacz BlazorWebAppOidc AddOpenIdConnect with GetClaimsFromUserInfoEndpoint = true doesn't propogate role claims to client (dotnet/aspnetcore #58826).

Uwaga

Niektórzy dostawcy tożsamości zwracają token dostępu tylko wtedy, gdy używany jest token odświeżania. CookieOidcRefresher można zaktualizować za pomocą dodatkowej logiki, aby można było dalej korzystać z wcześniejszego zestawu roszczeń przechowywanych w autoryzacji cookie lub użyć tokenu dostępu do żądania roszczeń z punktu końcowego UserInfo.

Kryptograficzne spoza

Nonce to wartość ciągu, która kojarzy sesję klienta z tokenem identyfikatora w celu wyeliminowania ataków powtarzania.

Jeśli podczas opracowywania i testowania uwierzytelniania wystąpi błąd inny niż błąd, użyj nowej sesji przeglądarki InPrivate/incognito dla każdego przebiegu testu, bez względu na to, jak mała zmiana wprowadzona w aplikacji lub użytkowniku testowym, ponieważ nieaktualne cookie dane mogą prowadzić do błędu nieocenego. Aby uzyskać więcej informacji, zobacz sekcję Pliki cookie i dane witryny.

Wartość nie jest wymagana lub używana, gdy token odświeżania jest wymieniany na potrzeby nowego tokenu dostępu. W przykładowej aplikacji CookieOidcRefresher element (CookieOidcRefresher.cs) celowo ustawia wartość OpenIdConnectProtocolValidator.RequireNoncefalse.

Role aplikacji dla aplikacji, które nie zostały zarejestrowane w usłudze Microsoft Entra (ME-ID)

Ta sekcja dotyczy aplikacji, które nie używają Microsoft Entra ID (ME-ID) jako dostawcy tożsamości. W przypadku aplikacji zarejestrowanych przy użyciu identyfikatora ME zobacz sekcję Role aplikacji dla aplikacji zarejestrowanych w usłudze Microsoft Entra (ME-ID).

Skonfiguruj typ oświadczenia roli (TokenValidationParameters.RoleClaimType) w elemecie OpenIdConnectOptions :Program.cs

oidcOptions.TokenValidationParameters.RoleClaimType = "{ROLE CLAIM TYPE}";

W przypadku wielu dostawców tożsamości OIDC typ oświadczenia roli jest role. Sprawdź dokumentację dostawcy tożsamości, aby uzyskać poprawną wartość.

Zastąp klasę UserInfo w projekcie BlazorWebAppOidc.Client następującą klasą.

UserInfo.cs:

using Microsoft.AspNetCore.Components.WebAssembly.Authentication;
using System.Security.Claims;

namespace BlazorWebAppOidc.Client;

// Add properties to this class and update the server and client 
// AuthenticationStateProviders to expose more information about 
// the authenticated user to the client.
public sealed class UserInfo
{
    public required string UserId { get; init; }
    public required string Name { get; init; }
    public required string[] Roles { get; init; }

    public const string UserIdClaimType = "sub";
    public const string NameClaimType = "name";
    private const string RoleClaimType = "role";

    public static UserInfo FromClaimsPrincipal(ClaimsPrincipal principal) =>
        new()
        {
            UserId = GetRequiredClaim(principal, UserIdClaimType),
            Name = GetRequiredClaim(principal, NameClaimType),
            Roles = principal.FindAll(RoleClaimType).Select(c => c.Value)
                .ToArray(),
        };

    public ClaimsPrincipal ToClaimsPrincipal() =>
        new(new ClaimsIdentity(
            Roles.Select(role => new Claim(RoleClaimType, role))
                .Concat([
                    new Claim(UserIdClaimType, UserId),
                    new Claim(NameClaimType, Name),
                ]),
            authenticationType: nameof(UserInfo),
            nameType: NameClaimType,
            roleType: RoleClaimType));

    private static string GetRequiredClaim(ClaimsPrincipal principal,
        string claimType) =>
            principal.FindFirst(claimType)?.Value ??
            throw new InvalidOperationException(
                $"Could not find required '{claimType}' claim.");
}

W tym momencie Razor składniki mogą przyjąć autoryzację opartą na rolach i opartą na zasadach. Role aplikacji są wyświetlane w role oświadczeniach— jedno oświadczenie na rolę.

Role aplikacji dla aplikacji zarejestrowanych w usłudze Microsoft Entra (ME-ID)

Skorzystaj ze wskazówek w tej sekcji, aby zaimplementować role aplikacji, grupy zabezpieczeń ME-ID i wbudowane role administratora ME-ID dla aplikacji przy użyciu identyfikatora Entra (ME-ID) firmy Microsoft.

Podejście opisane w tej sekcji konfiguruje identyfikator ME-ID do wysyłania grup i ról w nagłówku uwierzytelniania cookie . Jeśli użytkownicy są tylko członkami kilku grup zabezpieczeń i ról, poniższe podejście powinno działać w przypadku większości platform hostingu bez wystąpienia problemu, w którym nagłówki są zbyt długie, na przykład w przypadku hostingu usług IIS, który ma domyślny limit długości nagłówka 16 KB (MaxRequestBytes). Jeśli długość nagłówka jest problemem z powodu członkostwa w grupie lub roli, zalecamy, aby nie przestrzegać wskazówek w tej sekcji na rzecz implementacji programu Microsoft Graph w celu uzyskania grup i ról użytkownika z identyfikatora ME-ID oddzielnie, podejście, które nie zawyża rozmiaru uwierzytelniania cookie. Aby uzyskać więcej informacji, zobacz Nieprawidłowe żądanie — zbyt długie żądanie — serwer IIS (dotnet/aspnetcore #57545).

Skonfiguruj typ oświadczenia roli (TokenValidationParameters.RoleClaimType) w OpenIdConnectOptions pliku Program.cs. Ustaw wartość na roles:

oidcOptions.TokenValidationParameters.RoleClaimType = "roles";

Chociaż nie można przypisywać ról do grup bez konta premium ME-ID, możesz przypisać role do użytkowników i odbierać oświadczenia ról dla użytkowników przy użyciu standardowego konta platformy Azure. Wskazówki w tej sekcji nie wymagają konta Premium z identyfikatorem ME.ID.

Podczas pracy z katalogiem domyślnym postępuj zgodnie ze wskazówkami w temacie Dodawanie ról aplikacji do aplikacji i odbieranie ich w tokenie (dokumentacja me-ID), aby skonfigurować i przypisać role. Jeśli nie pracujesz z katalogiem domyślnym, zmodyfikuj manifest aplikacji w witrynie Azure Portal, aby ręcznie ustanowić role aplikacji we appRoles wpisie pliku manifestu. Aby uzyskać więcej informacji, zobacz Konfigurowanie oświadczenia roli (dokumentacja ME-ID)..

Grupy zabezpieczeń platformy Azure użytkownika docierają do groups oświadczeń, a wbudowane przypisania ról administratora ME-ID użytkownika docierają do wids (). Wartości obu typów oświadczeń to identyfikatory GUID. Po odebraniu przez aplikację te oświadczenia mogą służyć do ustanawiania autoryzacji roli i zasad w Razor składnikach.

W manifeście aplikacji w witrynie Azure Portal ustaw groupMembershipClaims atrybut na All. Wartość All powoduje wysłanie wszystkich grup zabezpieczeń/dystrybucji (groups oświadczeń) i ról (wids oświadczeń) zalogowanego użytkownika za pomocą identyfikatora ME-ID. Aby ustawić groupMembershipClaims atrybut:

1. Otwórz rejestrację aplikacji w witrynie Azure Portal.
2. Wybierz pozycję Zarządzaj>manifestem na pasku bocznym.
3. groupMembershipClaims Znajdź atrybut .
4. Ustaw wartość na All ("groupMembershipClaims": "All").
5. Wybierz przycisk zapisywania.

Zastąp klasę UserInfo w projekcie BlazorWebAppOidc.Client następującą klasą.

UserInfo.cs:

using Microsoft.AspNetCore.Components.WebAssembly.Authentication;
using System.Security.Claims;

namespace BlazorWebAppOidc.Client;

// Add properties to this class and update the server and client 
// AuthenticationStateProviders to expose more information about 
// the authenticated user to the client.
public sealed class UserInfo
{
    public required string UserId { get; init; }
    public required string Name { get; init; }
    public required string[] Roles { get; init; }
    public required string[] Groups { get; init; }
    public required string[] Wids { get; init; }

    public const string UserIdClaimType = "sub";
    public const string NameClaimType = "name";
    private const string RoleClaimType = "roles";
    private const string GroupsClaimType = "groups";
    private const string WidsClaimType = "wids";

    public static UserInfo FromClaimsPrincipal(ClaimsPrincipal principal) =>
        new()
        {
            UserId = GetRequiredClaim(principal, UserIdClaimType),
            Name = GetRequiredClaim(principal, NameClaimType),
            Roles = principal.FindAll(RoleClaimType).Select(c => c.Value)
                .ToArray(),
            Groups = principal.FindAll(GroupsClaimType).Select(c => c.Value)
                .ToArray(),
            Wids = principal.FindAll(WidsClaimType).Select(c => c.Value)
                .ToArray(),
        };

    public ClaimsPrincipal ToClaimsPrincipal() =>
        new(new ClaimsIdentity(
            Roles.Select(role => new Claim(RoleClaimType, role))
                .Concat(Groups.Select(role => new Claim(GroupsClaimType, role)))
                .Concat(Wids.Select(role => new Claim(WidsClaimType, role)))
                .Concat([
                    new Claim(UserIdClaimType, UserId),
                    new Claim(NameClaimType, Name),
                ]),
            authenticationType: nameof(UserInfo),
            nameType: NameClaimType,
            roleType: RoleClaimType));

    private static string GetRequiredClaim(ClaimsPrincipal principal,
        string claimType) =>
            principal.FindFirst(claimType)?.Value ??
            throw new InvalidOperationException(
                $"Could not find required '{claimType}' claim.");
}

Na tym etapie Razor składniki mogą przyjąć autoryzację opartą na rolach i opartą na zasadach:

• Role aplikacji są wyświetlane w roles oświadczeniach— jedno oświadczenie na rolę.
• Grupy zabezpieczeń są wyświetlane w groups oświadczeniach, jedno oświadczenie na grupę. Identyfikatory GUID grupy zabezpieczeń są wyświetlane w witrynie Azure Portal podczas tworzenia grupy zabezpieczeń i są wyświetlane podczas wybierania widoku Identity>Grupy przeglądów.>>
• Wbudowane role administratora ME-ID są wyświetlane w wids oświadczeniach, po jednym oświadczeniu na rolę. Oświadczenie wids z wartością b79fbf4d-3ef9-4689-8143-76b194e85509 jest zawsze wysyłane przez me-ID dla kont innych niż gości dzierżawy i nie odnosi się do roli administratora. Identyfikatory GUID ról administratora (identyfikatory szablonów ról) są wyświetlane w witrynie Azure Portal podczas wybierania ról i administratorów, a następnie wielokropka (...) >Opis roli wymienionej. Identyfikatory szablonów ról są również wymienione we wbudowanych rolach firmy Microsoft (dokumentacja entra).

Rozwiązywanie problemów

Rejestrowanie

Aplikacja serwera jest standardową aplikacją ASP.NET Core. Zobacz wskazówki dotyczące rejestrowania ASP.NET Core, aby włączyć niższy poziom rejestrowania w aplikacji serwera.

Aby włączyć rejestrowanie debugowania lub śledzenia na potrzeby Blazor WebAssembly uwierzytelniania, zobacz sekcję Rejestrowanie uwierzytelniania po stronie klienta ASP.NET Core Blazor z selektorem wersji artykułu ustawionym na ASP.NET Core 7.0 lub nowszym.

Typowe błędy

• Błędna konfiguracja aplikacji lub Identity dostawcy (IP)

  Najczęstsze błędy są spowodowane nieprawidłową konfiguracją. Poniżej przedstawiono kilka przykładów:

  • W zależności od wymagań scenariusza brakujący lub niepoprawny urząd, wystąpienie, identyfikator dzierżawy, domena dzierżawy, identyfikator klienta lub identyfikator URI przekierowania uniemożliwia aplikacji uwierzytelnianie klientów.
  • Nieprawidłowe zakresy żądań uniemożliwiają klientom uzyskiwanie dostępu do punktów końcowych internetowego interfejsu API serwera.
  • Nieprawidłowe lub brakujące uprawnienia interfejsu API serwera uniemożliwiają klientom uzyskiwanie dostępu do punktów końcowych internetowego interfejsu API serwera.
  • Uruchamianie aplikacji na innym porcie niż jest skonfigurowane w identyfikatorze URI przekierowania rejestracji aplikacji adresu IP. Należy pamiętać, że port nie jest wymagany dla identyfikatora Entra firmy Microsoft i aplikacji działającej localhost na adresie testowania programowania, ale konfiguracja portu aplikacji i port, na którym działa aplikacja, musi być zgodna z adresami innychlocalhost niż.

  Pokrycie konfiguracji w tym artykule przedstawia przykłady prawidłowej konfiguracji. Dokładnie sprawdź konfigurację wyszukując błędną konfigurację aplikacji i adresu IP.

  Jeśli konfiguracja jest poprawna:

  • Analizowanie dzienników aplikacji.

  • Sprawdź ruch sieciowy między aplikacją kliencka a adresem IP lub aplikacją serwera przy użyciu narzędzi deweloperskich przeglądarki. Często dokładny komunikat o błędzie lub komunikat zawierający wskazówki dotyczące przyczyn problemu jest zwracany do klienta przez adres IP lub aplikację serwera po wykonaniu żądania. Narzędzia programistyczne wskazówki można znaleźć w następujących artykułach:

    • Google Chrome (dokumentacja Google)
    • Microsoft Edge
    • Mozilla Firefox (dokumentacja Mozilla)

  Zespół dokumentacji odpowiada na opinie dotyczące dokumentów i usterek w artykułach (otwórz problem z sekcji Ta strona opinii), ale nie może zapewnić pomocy technicznej dotyczącej produktów. Dostępnych jest kilka publicznych forów pomocy technicznej, które ułatwiają rozwiązywanie problemów z aplikacją. Zalecamy:

  • Stack Overflow (tag: blazor)
  • ASP.NET Core Slack Team
  • Blazor Gitter

  Poprzednie fora nie należą do firmy Microsoft ani nie są kontrolowane przez firmę Microsoft.

  W przypadku raportów usterek struktury niezwiązanych z zabezpieczeniami, niewrażliwych i nieufnych, otwórz problem z jednostką produktu ASP.NET Core. Nie otwieraj problemu z jednostką produktu, dopóki nie zbadasz dokładnie przyczyny problemu i nie możesz go rozwiązać samodzielnie i z pomocą społeczności na publicznym forum pomocy technicznej. Jednostka produktu nie może rozwiązywać problemów z poszczególnymi aplikacjami, które są uszkodzone z powodu prostej błędnej konfiguracji lub przypadków użycia obejmujących usługi innych firm. Jeśli raport jest poufny lub poufny lub opisuje potencjalną lukę w zabezpieczeniach produktu, którą mogą wykorzystać cyberataki, zobacz Raportowanie problemów z zabezpieczeniami i usterek (dotnet/aspnetcorerepozytorium GitHub).

• Nieautoryzowany klient dla identyfikatora ME

  info: Autoryzacja Microsoft.AspNetCore.Authorization.DefaultAuthorizationService[2] nie powiodła się. Te wymagania nie zostały spełnione: DenyAnonymousAuthorizationRequirement: Wymaga uwierzytelnionego użytkownika.

  Błąd wywołania zwrotnego logowania z identyfikatora ME-ID:

  • Błąd: unauthorized_client
  • Opis: AADB2C90058: The provided application is not configured to allow public clients.

  Aby naprawić ten błąd:

  1. W witrynie Azure Portal uzyskaj dostęp do manifestu aplikacji.
  2. allowPublicClient Ustaw atrybut na null lub true.

Pliki cookie i dane witryn

Pliki cookie i dane witryn mogą być utrwalane w aktualizacjach aplikacji i zakłócać testowanie i rozwiązywanie problemów. Wyczyść następujące informacje podczas wprowadzania zmian w kodzie aplikacji, zmiany konta użytkownika w dostawcy lub zmiany konfiguracji aplikacji dostawcy:

• Pliki cookie logowania użytkownika
• Pliki cookie aplikacji
• Buforowane i przechowywane dane lokacji

Jednym z metod zapobiegania utrzymującym się plikom cookie i danym witryny jest zakłócanie testowania i rozwiązywania problemów:

• Konfigurowanie przeglądarki
  • Użyj przeglądarki do testowania, które można skonfigurować, aby usuwać wszystkie cookie dane witryny i za każdym razem, gdy przeglądarka jest zamknięta.
  • Upewnij się, że przeglądarka jest zamknięta ręcznie lub przez środowisko IDE w celu zmiany konfiguracji aplikacji, użytkownika testowego lub dostawcy.
• Użyj polecenia niestandardowego, aby otworzyć przeglądarkę w trybie InPrivate lub Incognito w programie Visual Studio:
  • Otwórz okno dialogowe Przeglądaj za pomocą z przycisku Uruchom programu Visual Studio.
  • Kliknij przycisk Dodaj.
  • Podaj ścieżkę do przeglądarki w polu Program . Następujące ścieżki wykonywalne to typowe lokalizacje instalacji systemu Windows 10. Jeśli przeglądarka jest zainstalowana w innej lokalizacji lub nie używasz systemu Windows 10, podaj ścieżkę do pliku wykonywalnego przeglądarki.
    • 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
  • W polu Argumenty podaj opcję wiersza polecenia używaną przez przeglądarkę do otwierania w trybie InPrivate lub Incognito. Niektóre przeglądarki wymagają adresu URL aplikacji.
    • Microsoft Edge: użyj polecenia -inprivate.
    • Google Chrome: użyj symbolu --incognito --new-window {URL}{URL} zastępczego , gdzie symbol zastępczy to adres URL do otwarcia (na przykład https://localhost:5001).
    • Mozilla Firefox: użyj symbolu -private -url {URL}zastępczego {URL} , gdzie symbol zastępczy jest adresem URL do otwarcia (na przykład https://localhost:5001).
  • Podaj nazwę w polu Przyjazna nazwa . Na przykład Firefox Auth Testing.
  • Wybierz przycisk OK.
  • Aby uniknąć konieczności wybierania profilu przeglądarki dla każdej iteracji testowania za pomocą aplikacji, ustaw profil jako domyślny przy użyciu przycisku Ustaw jako domyślny .
  • Upewnij się, że przeglądarka jest zamknięta przez środowisko IDE w celu zmiany konfiguracji aplikacji, użytkownika testowego lub dostawcy.

Uaktualnienia aplikacji

Działająca aplikacja może zakończyć się niepowodzeniem natychmiast po uaktualnieniu zestawu .NET Core SDK na komputerze deweloperskim lub zmianie wersji pakietów w aplikacji. W niektórych przypadkach niespójne pakiety mogą spowodować przerwanie aplikacji podczas przeprowadzania głównych uaktualnień. Większość z tych problemów można rozwiązać, wykonując następujące instrukcje:

1. Wyczyść pamięć podręczną pakietów NuGet systemu lokalnego, wykonując polecenie dotnet nuget locals all --clear z powłoki poleceń.
2. Usuń foldery i bin foldery obj projektu.
3. Przywracanie i ponowne kompilowanie projektu.
4. Usuń wszystkie pliki w folderze wdrażania na serwerze przed ponownym wdrożeniem aplikacji.

Uwaga

Korzystanie z wersji pakietów niezgodnych z platformą docelową aplikacji nie jest obsługiwane. Aby uzyskać informacje na temat pakietu, użyj galerii NuGet lub Eksploratora pakietów FuGet.

Uruchamianie aplikacji serwera

Podczas testowania i rozwiązywania problemów Blazor Web Appupewnij się, że aplikacja jest uruchamiana z projektu serwera.

Sprawdzanie użytkownika

Poniższy UserClaims składnik może być używany bezpośrednio w aplikacjach lub służyć jako podstawa dalszego dostosowywania.

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;
    }
}

Dodatkowe zasoby

• AzureAD/microsoft-identity-web Repozytorium GitHub: przydatne wskazówki dotyczące implementowania usługi Microsoft Identity Web for Microsoft Entra ID i Azure Active Directory B2C dla aplikacji ASP.NET Core, w tym linki do przykładowych aplikacji i powiązanej dokumentacji platformy Azure. Obecnie nie są jawnie rozwiązywane przez dokumentację platformy Azure, Blazor Web Appale konfiguracja i konfiguracja Blazor Web App identyfikatora ME-ID i hostingu platformy Azure są takie same jak w przypadku dowolnej aplikacji internetowej ASP.NET Core.
• AuthenticationStateProvider usługa
• Zarządzanie stanem uwierzytelniania w s Blazor Web App
• Odświeżanie tokenu podczas żądania HTTP na Blazor serwerze interaktywnym za pomocą identyfikatora OIDC (dotnet/aspnetcore #55213)