Samouczek: tworzenie i zabezpieczanie internetowego interfejsu API ASP.NET Core za pomocą platformy tożsamości firmy Microsoft
pl-PL: Dotyczy: 
Najemcy Workforce Zewnętrzni najemcy (więcej informacji)
W tej serii samouczków pokazano, jak chronić internetowy interfejs API ASP.NET Core za pomocą platformy tożsamości firmy Microsoft, aby ograniczyć dostęp tylko do autoryzowanych użytkowników i aplikacji klienckich. Kompilowany internetowy interfejs API używa uprawnień delegowanych (zakresów) i uprawnień aplikacji (ról aplikacji).
W tym samouczku nauczysz się:
- Tworzenie internetowego interfejsu API platformy ASP.NET Core
- Skonfiguruj internetowy interfejs API, aby używać szczegółów rejestracji aplikacji Microsoft Entra
- Chroń punkty końcowe interfejsu API
- Uruchom internetowy interfejs API, aby upewnić się, że nasłuchuje żądań HTTP
Warunki wstępne
- Jeśli jeszcze tego nie zrobiłeś, wykonaj kroki opisane w Szybki start: zalogowanie się użytkowników w przykładowej aplikacji internetowej. W przewodniku Szybki start nie trzeba klonować i uruchamiać przykładowego kodu.
- zestaw SDK platformy .NET 8.0 lub nowszy.
- programu Visual Studio Code lub innego edytora kodu.
Tworzenie nowego projektu internetowego interfejsu API platformy ASP.NET Core
Aby utworzyć minimalny projekt internetowego interfejsu API platformy ASP.NET Core, wykonaj następujące kroki:
Otwórz terminal w programie Visual Studio Code lub innym edytorze kodu i przejdź do katalogu, w którym chcesz utworzyć projekt.
Uruchom następujące polecenia w interfejsie wiersza polecenia platformy .NET lub innym narzędziu wiersza polecenia.
dotnet new webapi -n MyProtectedApi cd MyProtectedApiWybierz pozycję Tak, gdy zostanie wyświetlone okno dialogowe z pytaniem, czy chcesz ufać autorom.
Wybierz pozycję Tak Gdy w oknie dialogowym zostanie wyświetlone pytanie, czy chcesz dodać wymagane zasoby do projektu.
Instalowanie wymaganych pakietów
Aby chronić internetowy interfejs API platformy ASP.NET Core, potrzebny jest pakiet Microsoft.Identity.Web — zestaw bibliotek ASP.NET Core, które upraszczają dodawanie obsługi uwierzytelniania i autoryzacji do aplikacji internetowych i internetowych interfejsów API integrujących się z platformą tożsamości firmy Microsoft.
Aby zainstalować pakiet, użyj:
dotnet add package Microsoft.Identity.Web
Konfigurowanie szczegółów rejestracji aplikacji
Otwórz plik appsettings.json w folderze aplikacji i dodaj szczegóły rejestracji aplikacji, które zapisałeś po zarejestrowaniu interfejsu API sieci.
{
"AzureAd": {
"Instance": "Enter_the_Authority_URL_Here",
"TenantId": "Enter_the_Tenant_Id_Here",
"ClientId": "Enter_the_Application_Id_Here",
},
"Logging": {...},
"AllowedHosts": "*"
}
Zastąp następujące elementy zastępcze zgodnie z poniższymi instrukcjami.
- Zastąp
Enter_the_Application_Id_Hereidentyfikatorem aplikacji (klienta). - Zastąp
Enter_the_Tenant_Id_Hereswoim identyfikatorem katalogu (dzierżawcy). - Zastąp
Enter_the_Authority_URL_Hereadresem URL autorytetu, jak wyjaśniono w następnej sekcji.
Adres URL autoryzacji dla aplikacji
Adres URL urzędu określa katalog, z którego biblioteka Microsoft Authentication Library (MSAL) może żądać tokenów. Jest on zorganizowany inaczej zarówno pod względem zasobów ludzkich, jak i najemców zewnętrznych, jak pokazano.
//Instance for workforce tenant
Instance: "https://login.microsoftonline.com/"
Użyj niestandardowej domeny adresu URL (opcjonalnie)
Niestandardowe domeny adresów URL nie są obsługiwane w dzierżawach dla zespołów pracowniczych.
Dodawanie roli i zakresu aplikacji
Wszystkie interfejsy API muszą opublikować co najmniej jeden zakres, nazywany również uprawnieniem delegowanym, aby aplikacje klienckie pomyślnie uzyskały token dostępu dla użytkownika. Interfejsy API powinny również publikować co najmniej jedną rolę aplikacji, nazywaną również uprawnieniami aplikacji, aby aplikacje klienckie mogły uzyskać token dostępu jako siebie, czyli wtedy, gdy użytkownik nie loguje się.
Określamy te uprawnienia w pliku appsettings.json. W tym samouczku zarejestrujesz uprawnienia delegowane oraz uprawnienia aplikacji o zakresie "Forecast.Read". Oznacza to, że tylko użytkownicy lub aplikacje klienckie, które wywołają interfejs API z tokenem dostępu zawierającym zakres "Prognoza.Read", uzyskają autoryzację dostępu do chronionego punktu końcowego.
{
"AzureAd": {
"Instance": "Enter_the_Authority_URL_Here",
"TenantId": "Enter_the_Tenant_Id_Here",
"ClientId": "Enter_the_Application_Id_Here",
"Scopes": {
"Read": "Forecast.Read",
},
"AppPermissions": {
"Read": ["Forecast.Read"],
}
},
"Logging": {...},
"AllowedHosts": "*"
}
Implementowanie uwierzytelniania i autoryzacji w interfejsie API
Aby skonfigurować uwierzytelnianie i autoryzację, otwórz plik program.cs i zastąp jego zawartość następującymi fragmentami kodu:
Dodawanie schematu uwierzytelniania
W tym interfejsie API używamy schematu elementu nośnego JSON Web Token (JWT) jako domyślnego mechanizmu uwierzytelniania. Użyj metody AddAuthentication, aby zarejestrować schemat elementu nośnego JWT.
// Import the required packages
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;
var builder = WebApplication.CreateBuilder(args);
// Configure authentication
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
.AddMicrosoftIdentityWebApi(options =>
{
builder.Configuration.Bind("AzureAd", options);
options.TokenValidationParameters.NameClaimType = "name";
}, options => { builder.Configuration.Bind("AzureAd", options); });
Konfigurowanie autoryzacji
Autoryzacja określa, co może zrobić uwierzytelniony użytkownik. Definiujemy zasady o nazwie AuthZPolicy, które wymagają, aby klient wywołujący interfejs API miał rolę Forecast.Read dla aplikacji klienckich lub zakresu Forecast.Read dla zalogowanego użytkownika.
builder.Services.AddAuthorization(config =>
{
config.AddPolicy("AuthZPolicy", policy =>
policy.RequireRole("Forecast.Read"));
});
Metoda AddPolicy tworzy nazwaną zasadę (AuthZPolicy), która sprawdza obecność roli Forecast.Read w roszczeniach tokenu użytkownika. Jeśli token nie ma oświadczenia roles, dostęp do interfejsów końcowych wymagających tej zasady jest odmówiony.
Budowanie potoku żądania HTTP
W tym poradniku używamy minimalnej wersji interfejsu API bez użycia kontrolerów, ponieważ skupiamy się bardziej na jego ochronie. Konfigurujemy potok middleware interfejsu API, dodając następujące elementy:
- przekierowania HTTPS: wymuszaj bezpieczną komunikację, przekierowując żądania HTTP do protokołu HTTPS.
- oprogramowanie pośredniczące uwierzytelniania: weryfikuje tokeny przychodzące przed przetworzeniem żądań.
- oprogramowanie pośredniczące autoryzacji: stosuje zasady po uwierzytelnieniu, zapewniając, że tylko autoryzowani klienci mogą uzyskiwać dostęp do chronionych punktów końcowych.
var app = builder.Build();
// Configure the HTTP request pipeline
app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();
Definiowanie punktu końcowego prognozy pogody
Punkt końcowy /weatherforecast generuje losową pięciodniową prognozę chronioną przez politykę autoryzacji.
RequireAuthorization("AuthZPolicy") gwarantuje, że tylko klienci z rolą Forecast.Read będą mogli uzyskać do niej dostęp.
var summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
app.MapGet("/weatherforecast", () =>
{
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;
})
.WithName("weatherForecast")
.RequireAuthorization("AuthZPolicy"); // Protect this endpoint with the AuthZPolicy
app.Run();
record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}
Przepływ uwierzytelniania i autoryzacji w przykładowym internetowym interfejsie API, który utworzyliśmy, działa w następujący sposób:
- Klient wysyła żądanie GET do
/weatherforecast, z tokenem JWT w nagłówkuAuthorization. -
UseAuthenticationweryfikuje token względem identyfikatora Entra firmy Microsoft -
UseAuthorizationweryfikuje rolęForecast.Readw oświadczeniach tokenu. - W przypadku powodzenia punkt końcowy zwraca prognozę; w przeciwnym razie odpowiada komunikatem
401 Unauthorized(nieprawidłowy/brak tokenu) lub403 Forbidden(brak roli).
Uruchamianie interfejsu API
Uruchom interfejs API, aby upewnić się, że działa bez żadnych błędów przy użyciu polecenia dotnet run. Jeśli zamierzasz używać protokołu HTTPS nawet podczas testowania, musisz zaufać certyfikatowi programistycznemu .NET.
Uruchom aplikację, wpisując następujące polecenie w terminalu:
dotnet runPodobne dane wyjściowe do poniższych powinny być wyświetlane w terminalu, co potwierdza, że aplikacja działa na
http://localhost:{port}i nasłuchuje żądań.Building... info: Microsoft.Hosting.Lifetime[0] Now listening on: http://localhost:{port} info: Microsoft.Hosting.Lifetime[0] Application started. Press Ctrl+C to shut down. ...
Strona internetowa http://localhost:{host} wyświetla dane wyjściowe podobne do poniższego obrazu. Dzieje się tak, ponieważ interfejs API jest wywoływany bez uwierzytelniania. Aby wykonać autoryzowane wywołanie, zapoznaj się z Następne kroki, aby uzyskać wskazówki dotyczące uzyskiwania dostępu do chronionego sieciowego interfejsu API.
Pełny przykład tego kodu interfejsu API można znaleźć w pliku przykładów .