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

W tym artykule opisano sposób zabezpieczania za pomocą protokołu OpenID Connect (OIDC) przy użyciu przykładowej aplikacji w dotnet/blazor-samples repozytorium GitHub (.NET 8 lub nowszym) (jak pobrać).Blazor Web App

W tej wersji artykułu opisano implementację OIDC bez wdrażania wzorca zaplecza dla frontonu (BFF). 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.

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).

Uwaga

Projekt serwera używa elementu IHttpContextAccessor/HttpContext, ale nigdy nie jest używany w przypadku składników renderowanych interaktywnie. Aby uzyskać więcej informacji, zobacz Wskazówki dotyczące ograniczania zagrożeń dotyczące renderowania interaktywnego po stronie serwera ASP.NET CoreBlazor.

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 AddMicrosoftIdentityWebApp witryny 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 (Zarządzaj>certyfikatami i wpisami tajnymi>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 programowi pośredniczącemu odpowiedzialnemu za utrwalanie użytkowników identity 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 wartość , aby zmniejszyć false rozmiar uwierzytelniania cookiekońcowego.

  oidcOptions.SaveTokens = false;
  

• 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 (): https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/ ({AUTHORITY}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.

  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. Procedura obsługi OIDC automatycznie żąda odpowiednich tokenów przy użyciu kodu zwróconego z punktu końcowego autoryzacji.

  oidcOptions.ResponseType = OpenIdConnectResponseType.Code;
  

• 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). identity Aby uzyskać więcej informacji, zapoznaj się z dokumentacją dostawcy.

  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.

    W witrynie Entra lub Azure Portal ustaw ścieżkę w identyfikatorze URI przekierowania platformy internetowej:

    https://localhost/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: ścieżka żądania w ścieżce podstawowej aplikacji, w której agent użytkownika jest zwracany po wylogowaniu się od dostawcy identity .

    W witrynie Entra lub Azure Portal ustaw ścieżkę w identyfikatorze URI przekierowania platformy internetowej:

    https://localhost/signout-callback-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.

    Uwaga

    Jeśli korzystasz z sieci Web firmy Microsoft Identity , dostawca obecnie przekierowuje tylko z powrotem do SignedOutCallbackPath adresu , jeśli microsoftonline.com jest używany urząd (https://login.microsoftonline.com/{TENANT ID}/v2.0/). To ograniczenie nie istnieje, jeśli możesz użyć "wspólnego" urzędu z siecią Microsoft Identity Web. Aby uzyskać więcej informacji, zobacz postLogoutRedirectUri nie działa, gdy adres URL urzędu zawiera identyfikator dzierżawy (AzureAD/microsoft-authentication-library-for-js #5783).

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

    W witrynie Entra lub Azure Portal ustaw adres URL wylogowywania kanału frontonu:

    https://localhost/signout-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.

    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 Program API (/weather-forecast) 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.
• 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 Wywoływanie internetowego interfejsu API z aplikacji ASP.NET CoreBlazor.

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 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).

Uwaga

Projekt serwera używa elementu IHttpContextAccessor/HttpContext, ale nigdy nie jest używany w przypadku składników renderowanych interaktywnie. Aby uzyskać więcej informacji, zobacz Wskazówki dotyczące ograniczania zagrożeń dotyczące renderowania interaktywnego po stronie serwera ASP.NET CoreBlazor.

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 AddMicrosoftIdentityWebApp witryny 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 (Zarządzaj>certyfikatami i wpisami tajnymi>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 programowi pośredniczącemu odpowiedzialnemu za utrwalanie użytkowników identity 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): Weather.Get zakres jest skonfigurowany w witrynie Azure lub w witrynie Entra Portal w obszarze Uwidacznij interfejs API. 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}");
  

  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 (): https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/ ({AUTHORITY}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.

  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. Procedura obsługi OIDC automatycznie żąda odpowiednich tokenów przy użyciu kodu zwróconego z punktu końcowego autoryzacji.

  oidcOptions.ResponseType = OpenIdConnectResponseType.Code;
  

• 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). identity Aby uzyskać więcej informacji, zapoznaj się z dokumentacją dostawcy.

  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.

    W witrynie Entra lub Azure Portal ustaw ścieżkę w identyfikatorze URI przekierowania platformy internetowej:

    https://localhost/signin-oidc

    Uwaga

    Port nie jest wymagany dla localhost adresów.

  • SignedOutCallbackPath: ścieżka żądania w ścieżce podstawowej aplikacji, w której agent użytkownika jest zwracany po wylogowaniu się od dostawcy identity .

    W witrynie Entra lub Azure Portal ustaw ścieżkę w identyfikatorze URI przekierowania platformy internetowej:

    https://localhost/signout-callback-oidc

    Uwaga

    Port nie jest wymagany dla localhost adresów.

    Uwaga

    Jeśli korzystasz z sieci Web firmy Microsoft Identity , dostawca obecnie przekierowuje tylko z powrotem do SignedOutCallbackPath adresu , jeśli microsoftonline.com jest używany urząd (https://login.microsoftonline.com/{TENANT ID}/v2.0/). To ograniczenie nie istnieje, jeśli możesz użyć "wspólnego" urzędu z siecią Microsoft Identity Web. Aby uzyskać więcej informacji, zobacz postLogoutRedirectUri nie działa, gdy adres URL urzędu zawiera identyfikator dzierżawy (AzureAD/microsoft-authentication-library-for-js #5783).

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

    W witrynie Entra lub Azure Portal ustaw adres URL wylogowywania kanału frontonu:

    https://localhost/signout-oidc

    Uwaga

    Port nie jest wymagany dla localhost adresów.

    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). MapForwarderProgram 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 Weather składnika na serwerze składnik używa ServerWeatherForecaster elementu do obsługi serwera proxy żądania danych pogodowych przy użyciu tokenu dostępu użytkownika.
  • 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 Wywoływanie internetowego interfejsu API z aplikacji ASP.NET CoreBlazor.

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 OpenID Connect.

  W witrynie Azure lub Entra Portal: dopasuj wartość do ścieżki identyfikatora URI identyfikatora aplikacji skonfigurowanego podczas dodawania Weather.Get zakresu w obszarze Uwidacznij interfejs API:

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

  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: Ustawia urząd do wykonywania wywołań OpenID Connect. Dopasuj wartość do urzędu skonfigurowanego dla programu obsługi OIDC w programie BlazorWebAppOidc/Program.cs:

  jwtOptions.Authority = "{AUTHORITY}";
  

  Przykład:

  Urząd (): https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/ ({AUTHORITY}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, urząd powinien być zgodny z parametrem issurer (iss) JWT zwróconym przez dostawcę identity :

  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 w home ramach wylogowania

Gdy użytkownik przechodzi po aplikacji, LogInOrOut składnik (Layout/LogInOrOut.razor) ustawia ukryte pole dla zwracanego adresu URL (ReturnUrl) na wartość bieżącego adresu URL (currentURL). Gdy użytkownik wyloguje się z aplikacji, dostawca zwraca je do strony, identity z której się wylogował.

Jeśli użytkownik wyloguje się z bezpiecznej strony, zostanie zwrócony z powrotem do tej samej bezpiecznej strony po wylogowaniu się tylko do wysłania z powrotem za pośrednictwem procesu uwierzytelniania. To zachowanie jest w porządku, gdy użytkownicy muszą często przełączać konta. Jednak alternatywna specyfikacja aplikacji może wywołać zwrócenie użytkownika do strony aplikacji home lub innej strony po wylogowaniu. W poniższym przykładzie pokazano, jak ustawić stronę aplikacji home jako zwracany adres URL operacji wylogowywania.

Ważne zmiany w składniku LogInOrOut przedstawiono w poniższym przykładzie. Nie ma potrzeby podawania ukrytego pola dla ReturnUrl zestawu na home stronie, / ponieważ jest to ścieżka domyślna. IDisposable program nie jest już implementowany. Lek NavigationManager nie jest już wstrzykiwany. Cały @code blok zostanie usunięty.

Layout/LogInOrOut.razor:

@using Microsoft.AspNetCore.Authorization

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

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.RequireNonce false.

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ą identyfikatora Microsoft Entra ID (ME-ID) jako dostawcy identity . 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 OIDC identity typ oświadczenia roli to role. identity Sprawdź dokumentację dostawcy, 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 dobrze znanych oświadczeń (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 obj foldery bin 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)