Szybki start: ochrona internetowego interfejsu API platformy ASP.NET Core przy użyciu Platforma tożsamości Microsoft

Artykuł
02/21/2024

Witamy! Prawdopodobnie nie jest to oczekiwana strona. Chociaż pracujemy nad poprawką, ten link powinien podjąć Cię do odpowiedniego artykułu:

Szybki start: wywoływanie internetowego interfejsu API platformy ASP.NET Core chronionego przez Platforma tożsamości Microsoft

Przepraszamy za niedogodności i doceniamy cierpliwość, podczas gdy pracujemy nad rozwiązaniem tego problemu.

W poniższym przewodniku Szybki start użyto przykładowego kodu internetowego interfejsu API platformy ASP.NET Core, aby zademonstrować sposób ograniczania dostępu zasobów do autoryzowanych kont. Przykład obsługuje autoryzację osobistych kont Microsoft i kont w dowolnej organizacji firmy Microsoft Entra.

Wymagania wstępne

Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
Dzierżawa firmy Microsoft Entra
Minimalne wymaganie zestawu .NET 6.0 SDK
Visual Studio 2022 lub Visual Studio Code

Krok 1. Rejestrowanie aplikacji

Najpierw zarejestruj internetowy interfejs API w dzierżawie firmy Microsoft Entra i dodaj zakres, wykonując następujące kroki:

Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako administrator aplikacji.
Przejdź do aplikacji tożsamości>> Rejestracje aplikacji.
Wybierz opcjęNowa rejestracja.
W polu Nazwa wprowadź nazwę aplikacji. Na przykład wprowadź ciąg AspNetCoreWebApi-Quickstart. Użytkownicy aplikacji zobaczą tę nazwę i mogą zostać później zmienieni.
Wybierz pozycję Zarejestruj.
W obszarze Zarządzanie wybierz pozycję Uwidaczniaj interfejs API>Dodaj zakres. W polu Identyfikator URI identyfikatora aplikacji zaakceptuj wartość domyślną, wybierając pozycję Zapisz i kontynuuj, a następnie wprowadź następujące szczegóły:

Nazwa zakresu: access_as_user
Kto może wyrazić zgodę?: Administratorzy i użytkownicy
Nazwa wyświetlana zgody administratora: Access AspNetCoreWebApi-Quickstart
Opis zgody administratora: Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
Nazwa wyświetlana zgody użytkownika: Access AspNetCoreWebApi-Quickstart
Opis zgody użytkownika: Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
Stan: Włączone

Wybierz pozycję Dodaj zakres , aby ukończyć dodawanie zakresu.

Krok 2. Pobieranie projektu ASP.NET Core

Pobierz rozwiązanie ASP.NET Core z usługi GitHub.

Uwaga

Przykładowy kod jest obecnie przeznaczony dla ASP.NET Core 3.1. Przykład można zaktualizować tak, aby korzystał z platformy .NET Core 6.0 i został omówiony w następujących krokach: Zaktualizuj przykładowy kod, aby ASP.NET Core 6.0. Ten przewodnik Szybki start zostanie wycofany w najbliższej przyszłości i zostanie zaktualizowany do korzystania z platformy .NET 6.0.

Krok 3. Konfigurowanie projektu ASP.NET Core

W tym kroku przykładowy kod zostanie skonfigurowany do pracy z rejestracją aplikacji, która została utworzona wcześniej.

Wyodrębnij plik .zip do folderu lokalnego, który znajduje się blisko katalogu głównego dysku, aby uniknąć błędów spowodowanych ograniczeniami długości ścieżki w systemie Windows. Na przykład wyodrębnij do folderu C:\Azure-Samples.
Otwórz rozwiązanie w folderze webapi w edytorze kodu.
W appsettings.json zastąp wartości ClientId, i TenantId.
```
"ClientId": "Enter_the_Application_Id_here",
"TenantId": "Enter_the_Tenant_Info_Here"
```
- Enter_the_Application_Id_Here to identyfikator aplikacji (klienta) zarejestrowanej aplikacji.
- Zastąp Enter_the_Tenant_Info_Here element jednym z następujących elementów:
  - Jeśli aplikacja obsługuje tylko konta w tym katalogu organizacyjnym, zastąp tę wartość identyfikatorem katalogu (dzierżawy) lub nazwą dzierżawy (na przykład contoso.onmicrosoft.com). Identyfikator katalogu (dzierżawy) można znaleźć na stronie Przegląd aplikacji.
  - Jeśli aplikacja obsługuje konta w dowolnym katalogu organizacyjnym, zastąp tę wartość wartością organizations.
  - Jeśli aplikacja obsługuje wszystkich użytkowników konta Microsoft, pozostaw tę wartość jako common.

W tym przewodniku Szybki start nie zmieniaj żadnych innych wartości w pliku appsettings.json .

Krok 4. Aktualizowanie przykładowego kodu w celu ASP.NET Core 6.0

Aby zaktualizować ten przykładowy kod do ASP.NET Core 6.0, wykonaj następujące kroki:

Otwórz plik webapi.csproj
Usuń następujący wiersz:

<TargetFramework>netcoreapp3.1</TargetFramework>

Dodaj następujący wiersz w swoim miejscu:

<TargetFramework>netcoreapp6.0</TargetFramework>

Ten krok zapewni, że przykład jest przeznaczony dla platformy .NET Core 6.0.

Krok 5. Uruchamianie przykładu

Otwórz terminal i zmień katalog na folder projektu.
```
cd webapi
```
Uruchom następujące polecenie, aby skompilować rozwiązanie:

dotnet run

Jeśli kompilacja zakończyła się pomyślnie, zostaną wyświetlone następujące dane wyjściowe:

Building...
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: https://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: http://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Application started. Press Ctrl+C to shut down.
...

Jak działa przykład

Klasa początkowa

Oprogramowanie pośredniczące Microsoft.AspNetCore.Authentication używa klasy wykonywanej Startup podczas uruchamiania procesu hostingu. W jej ConfigureServices metodzie wywoływana AddMicrosoftIdentityWebApi jest metoda rozszerzenia dostarczona przez microsoft.Identity.Web .

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, "AzureAd");
    }

Metoda AddAuthentication() konfiguruje usługę w celu dodania uwierzytelniania opartego na usłudze JwtBearer.

Wiersz zawierający .AddMicrosoftIdentityWebApi dodaje autoryzację Platforma tożsamości Microsoft do internetowego interfejsu API. Następnie jest skonfigurowany do weryfikowania tokenów dostępu wystawionych przez Platforma tożsamości Microsoft na podstawie informacji w AzureAD sekcji pliku konfiguracji appsettings.json:

klucz appsettings.json	opis
`ClientId`	Identyfikator aplikacji (klienta) zarejestrowanej aplikacji.
`Instance`	Punkt końcowy usługi tokenu zabezpieczającego (STS) dla użytkownika do uwierzytelniania. Ta wartość to zazwyczaj `https://login.microsoftonline.com/`wartość wskazująca chmurę publiczną platformy Azure.
`TenantId`	Nazwa dzierżawy lub identyfikator dzierżawy (identyfikator GUID) lub `common` logowanie użytkowników przy użyciu kont służbowych lub osobistych Microsoft.

Metoda Configure() zawiera dwie ważne metody app.UseAuthentication() i app.UseAuthorization(), które umożliwiają ich nazwane funkcje:

// The runtime calls this method. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // more code
    app.UseAuthentication();
    app.UseAuthorization();
    // more code
}

Ochrona kontrolera, metody kontrolera lub strony Razor

Metody kontrolera lub kontrolera mogą być chronione za pomocą atrybutu [Authorize] . Ten atrybut ogranicza dostęp do kontrolera lub metod, zezwalając tylko na uwierzytelnionych użytkowników. Jeśli użytkownik nie jest uwierzytelniony, może zostać uruchomiony problem z uwierzytelnianiem, aby uzyskać dostęp do kontrolera.

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase

Walidacja zakresu w kontrolerze

Kod w interfejsie API sprawdza, czy wymagane zakresy znajdują się w tokenie przy użyciu polecenia HttpContext.VerifyUserHasAnyAcceptedScope> (scopeRequiredByApi);:

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        // The web API will only accept tokens 1) for users, and 2) having the "access_as_user" scope for this API
        static readonly string[] scopeRequiredByApi = new string[] { "access_as_user" };

        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);

            // some code here
        }
    }
}

Pomoc i obsługa techniczna

Jeśli potrzebujesz pomocy, chcesz zgłosić problem lub poznać opcje pomocy technicznej, zobacz Pomoc i obsługa techniczna dla deweloperów.

Następne kroki

Następujące repozytorium GitHub zawiera przykładowe instrukcje kodu internetowego interfejsu API platformy ASP.NET Core i więcej przykładów, które pokazują, jak wykonać następujące czynności:

Dodaj uwierzytelnianie do nowego internetowego interfejsu API platformy ASP.NET Core.
Wywoływanie internetowego interfejsu API z aplikacji klasycznej.
Wywoływanie podrzędnych interfejsów API, takich jak program Microsoft Graph i inne interfejsy API firmy Microsoft.

Samouczki internetowego interfejsu API platformy ASP.NET Core w usłudze GitHub

Udostępnij za pośrednictwem