Udostępnij za pomocą

Chroniony internetowy interfejs API: konfiguracja kodu

Dotyczy: Zielony okrąg z białym symbolem znacznika wyboru, który wskazuje następującą zawartość dotyczy dzierżawców pracowników. Dzierżawcy pracowników (dowiedz się więcej)

Aby skonfigurować kod dla chronionego internetowego interfejsu API, zapoznaj się z tematem:

  • To, co definiuje interfejsy API jako chronione.
  • Jak skonfigurować token elementu nośnego.
  • Jak zweryfikować token.

Zaakceptowana wersja tokenu

Platforma tożsamości Microsoft może wystawiać tokeny w wersji 1.0 i tokeny w wersji 2.0. Aby uzyskać więcej informacji na temat tych tokenów, zapoznaj się z tematem Tokeny dostępu.

Wersja tokenu, którą może zaakceptować interfejs API, zależy od wyboru obsługiwanych typów kont podczas tworzenia rejestracji aplikacji internetowego interfejsu API w witrynie Azure Portal.

  • Jeśli wartość Obsługiwanych typów kont to Konta w dowolnym katalogu organizacyjnym i osobistych kontach Microsoft (takich jak Skype, Xbox, Outlook.com), zaakceptowana wersja tokenu musi być w wersji 2.0.
  • W przeciwnym razie zaakceptowana wersja tokenu może być w wersji 1.0.

Po utworzeniu aplikacji można określić lub zmienić zaakceptowaną wersję tokenu, wykonując następujące kroki:

  1. W centrum administracyjnym firmy Microsoft Entra wybierz aplikację, a następnie wybierz pozycję Manifest.
  2. Znajdź właściwość accessTokenAcceptedVersion w manifeście.
  3. Wartość określa dla Microsoft Entra, którą wersję tokenu akceptuje web API.
    • Jeśli wartość to 2, internetowy interfejs API akceptuje tokeny w wersji 2.0.
    • Jeśli wartość to null, internetowy interfejs API akceptuje tokeny w wersji 1.0.
  4. Jeśli zmieniono wersję tokenu, wybierz pozycję Zapisz.

Internetowy interfejs API określa wersję tokenu, którą akceptuje. Gdy klient żąda tokenu dla interfejsu API z platformy tożsamości Microsoft, otrzymuje on token wskazujący, którą wersję tokenu akceptuje interfejs API.

Co definiuje interfejsy API ASP.NET i ASP.NET Core jako chronione?

Podobnie jak w przypadku aplikacji internetowych, ASP.NET i ASP.NET Core internetowe interfejsy API są chronione, ponieważ ich akcje kontrolera są poprzedzone atrybutem [Autoryzuj]. Akcje kontrolera mogą być wywoływane tylko wtedy, gdy interfejs API jest wywoływany z autoryzowaną tożsamością.

Zastanów się nad następującymi pytaniami:

  • Tylko aplikacja może wywoływać internetowy interfejs API. Jak interfejs API zna tożsamość aplikacji, która ją wywołuje?
  • Jeśli aplikacja wywołuje interfejs API w imieniu użytkownika, jaka jest tożsamość użytkownika?

Token elementu nośnego

Token elementu nośnego ustawiony w nagłówku, gdy aplikacja jest wywoływana, przechowuje informacje o tożsamości aplikacji. Zawiera również informacje o użytkowniku, chyba że aplikacja internetowa akceptuje wywołania typu service-to-service z aplikacji demona.

Oto przykładowy kod języka C#, który pokazuje klienta wywołującego interfejs API po uzyskaniu tokenu z biblioteką Microsoft Authentication Library for .NET (MSAL.NET):

var scopes = new[] {$"api://.../access_as_user"};
var result = await app.AcquireToken(scopes)
                      .ExecuteAsync();

httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", result.AccessToken);

// Call the web API.
HttpResponseMessage response = await _httpClient.GetAsync(apiUri);

Ważne

Aplikacja kliencka żąda tokenu elementu nośnego do Platforma tożsamości Microsoft dla internetowego interfejsu API. Interfejs API jest jedyną aplikacją, która powinna zweryfikować token i wyświetlić zawarte w nim oświadczenia. Aplikacje klienckie nigdy nie powinny próbować sprawdzać oświadczeń w tokenach.

W przyszłości internetowy interfejs API może wymagać szyfrowania tokenu. To wymaganie uniemożliwiłoby dostęp do aplikacji klienckich, które mogą wyświetlać tokeny dostępu.

Konfiguracja JwtBearer

W tej sekcji opisano sposób konfigurowania tokenu elementu nośnego.

Plik konfiguracji

Należy określić TenantId tylko wtedy, gdy chcesz akceptować tokeny dostępu z jednej dzierżawy (aplikacji biznesowej). W przeciwnym razie może być pozostawiony jako common. Różne wartości mogą być następujące:

  • Identyfikator GUID (identyfikator dzierżawy = identyfikator katalogu)
  • common może być dowolnymi kontami organizacji i kontami osobistymi
  • organizations może być dowolną organizacją
  • consumers to konta osobiste Microsoft
{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "Enter_the_Application_(client)_ID_here",
    "TenantId": "common"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Używanie niestandardowego identyfikatora URI identyfikatora aplikacji dla internetowego interfejsu API

Jeśli zaakceptowano domyślny URI id. aplikacji proponowany przez Portal Azure, nie musisz określać odbiorcy. W przeciwnym razie dodaj właściwość, której wartością Audience jest identyfikator URI identyfikatora aplikacji dla internetowego interfejsu API. Zazwyczaj zaczyna się to od api://.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "Enter_the_Application_(client)_ID_here",
    "TenantId": "common",
    "Audience": "Enter_the_Application_ID_URI_here"
  },
}

Inicjowanie kodu

Gdy aplikacja jest wywoływana w akcji kontrolera, która zawiera atrybut [Autoryzuj], ASP.NET i ASP.NET Core wyodrębnić token dostępu z tokenu elementu nośnego nagłówka autoryzacji. Token dostępu jest następnie przekazywany do oprogramowania pośredniczącego JwtBearer, który wywołuje rozszerzenia Microsoft IdentityModel dla platformy .NET.

Microsoft.Identity.Web

Firma Microsoft zaleca użycie pakietu NuGet Microsoft.Identity.Web podczas tworzenia internetowego interfejsu API za pomocą platformy ASP.NET Core.

Microsoft.Identity.Web zapewnia klej między platformą ASP.NET Core, oprogramowaniem pośredniczącym uwierzytelniania i biblioteką Microsoft Authentication Library (MSAL) dla platformy .NET. Umożliwia to jaśniejsze, bardziej niezawodne środowisko deweloperskie i wykorzystuje możliwości Platforma tożsamości Microsoft i Azure AD B2C.

ASP.NET dla platformy .NET 6.0

Aby utworzyć nowy projekt internetowego interfejsu API, który używa biblioteki Microsoft.Identity.Web, użyj szablonu projektu w interfejsie wiersza polecenia platformy .NET 6.0 lub programie Visual Studio.

Interfejs wiersza polecenia platformy Dotnet Core

# Create new web API that uses Microsoft.Identity.Web
dotnet new webapi --auth SingleOrg

Visual Studio — aby utworzyć projekt internetowego interfejsu API w programie Visual Studio, wybierz pozycję >

Zarówno interfejs wiersza polecenia platformy .NET, jak i szablony projektów programu Visual Studio tworzą plik Program.cs , który wygląda podobnie do tego fragmentu kodu. Zwróć uwagę Microsoft.Identity.Web na użycie dyrektywy i wierszy zawierających uwierzytelnianie i autoryzację.

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();

app.Run();
  • Last updated on