Schnellstart: Schützen einer ASP.NET Core-Web-API mit Microsoft Identity Platform

Artikel
02/14/2024

Willkommen! Dies ist wahrscheinlich nicht die Seite, die Sie erwartet haben. Während wir an einer Korrektur arbeiten, sollten Sie über diesen Link zum richtigen Artikel gelangen:

Schnellstart: Aufrufen einer durch Microsoft Identity Platform geschützten ASP.NET Core Web-API

Wir entschuldigen uns für die Unannehmlichkeiten und bitten Sie um Geduld, während wir an einer Lösung arbeiten.

In der folgenden Schnellstartanleitung wird ein Codebeispiel für die ASP.NET Core-Web-API verwendet, um zu veranschaulichen, wie der Ressourcenzugriff auf autorisierte Konten eingeschränkt wird. Das Beispiel unterstützt die Autorisierung von persönlichen Microsoft-Konten sowie Konten in einer beliebigen Microsoft Entra-Organisation.

Voraussetzungen

Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
Microsoft Entra Mandant
Mindestanforderung: .NET 6.0 SDK
Visual Studio 2022 oder Visual Studio Code

Schritt 1: Registrieren der Anwendung

Registrieren Sie zunächst die Web-API in Ihrem Microsoft Entra-Mandanten, und fügen Sie einen Bereich hinzu:

Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Anwendungsadministrator an.
Navigieren Sie zu Identität>Anwendungen>App-Registrierungen.
Wählen Sie Neue Registrierung aus.
Geben Sie für Name einen Namen für die Anwendung ein. Geben Sie beispielsweise AspNetCoreWebApi-Quickstart ein. Dieser Name, der später noch geändert werden kann, wird den Benutzern der App angezeigt.
Wählen Sie Registrieren.
Wählen Sie unter Verwalten die Optionen Eine API verfügbar machen>Bereich hinzufügen aus. Übernehmen Sie für Anwendungs-ID-URI den Standardwert, indem Sie Speichern und fortfahren auswählen. Geben Sie dann die folgenden Informationen ein:

Bereichsname: access_as_user
Zum Einwilligen berechtigte Personen: Administratoren und Benutzer
Anzeigename der Administratoreinwilligung: Access AspNetCoreWebApi-Quickstart
Beschreibung der Administratoreinwilligung: Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
Anzeigename der Benutzereinwilligung: Access AspNetCoreWebApi-Quickstart
Beschreibung der Benutzereinwilligung: Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
Status:Aktiviert

Wählen Sie Bereich hinzufügen aus, um das Hinzufügen des Bereichs abzuschließen.

Schritt 2: Herunterladen des ASP.NET Core-Projekts

Laden Sie die ASP.NET Core-Lösung von GitHub herunter.

Hinweis

Das Codebeispiel ist derzeit auf ASP.NET Core 3.1 ausgerichtet. Das Beispiel kann für die Verwendung von .NET Core 6.0 aktualisiert werden und wird in den folgenden Schritten behandelt: Aktualisieren des Beispielcodes auf ASP.NET Core 6.0. Diese Schnellstartanleitung wird in naher Zukunft veraltet sein und für die Verwendung von .NET 6.0 aktualisiert.

Schritt 3: Konfigurieren des ASP.NET Core-Projekts

In diesem Schritt wird der Beispielcode für die Verwendung der zuvor erstellten App-Registrierung konfiguriert.

Entpacken Sie die ZIP-Datei in einen lokalen Ordner, der sich in der Nähe des Stammverzeichnisses des Datenträgers befindet, um Fehler durch Einschränkungen der Pfadlänge unter Windows zu vermeiden. Extrahieren Sie es beispielsweise in C:\Azure-Samples.
Öffnen Sie die Lösung aus dem Ordner webapi in Ihrem Code-Editor.
Ersetzen Sie in appsettings.json die Werte von ClientId und TenantId.
```
"ClientId": "Enter_the_Application_Id_here",
"TenantId": "Enter_the_Tenant_Info_Here"
```
- Enter_the_Application_Id_Here ist die Anwendungs-ID (Client-ID) für die registrierte Anwendung.
- Ersetzen Sie Enter_the_Tenant_Info_Here durch eine der folgenden Optionen:
  - Wenn die Anwendung Nur Konten in diesem Organisationsverzeichnis unterstützt, ersetzen Sie diesen Wert durch die Verzeichnis-ID (Mandant und GUID) oder den Mandantennamen (beispielsweise contoso.onmicrosoft.com). Die Verzeichnis-ID (Mandanten-ID) finden Sie auf der Seite Übersicht der App.
  - Falls die Anwendung Konten in einem beliebigen Organisationsverzeichnis unterstützt, ersetzen Sie diesen Wert durch organizations.
  - Wenn die Anwendung Alle Microsoft-Kontobenutzer unterstützt, behalten Sie common für diesen Wert bei.

Ändern Sie in dieser Schnellstartanleitung keine anderen Werte in der Datei appsettings.json.

Schritt 4: Aktualisieren des Beispielcodes auf ASP.NET Core 6.0

Führen Sie die folgenden Schritte aus, um dieses Codebeispiel auf ASP.NET Core 6.0 zu aktualisieren:

Öffnen Sie „webapi.csproj“.
Entfernen Sie die folgende Zeile:

<TargetFramework>netcoreapp3.1</TargetFramework>

Fügen Sie stattdessen die folgende Zeile ein:

<TargetFramework>netcoreapp6.0</TargetFramework>

Mit diesem Schritt wird sichergestellt, dass das Beispiel auf das .NET Core 6.0-Framework ausgerichtet ist.

Schritt 5: Ausführen des Beispiels

Öffnen Sie ein Terminal, und wechseln Sie in den Projektordner.
```
cd webapi
```
Führen Sie den folgenden Befehl aus, um die Lösung zu erstellen:

dotnet run

Wenn der Build erfolgreich war, wird die folgende Ausgabe angezeigt:

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

Funktionsweise des Beispiels

Startklasse

Von der Middleware Microsoft.AspNetCore.Authentication wird eine Klasse vom Typ Startup verwendet. Sie wird ausgeführt, wenn der Hostprozess gestartet wird. In der zugehörigen Methode ConfigureServices wird die von Microsoft.Identity.Web bereitgestellte Erweiterungsmethode AddMicrosoftIdentityWebApi aufgerufen.

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

Durch die Methode AddAuthentication() wird der Dienst konfiguriert, um die JwtBearer-basierte Authentifizierung hinzuzufügen.

Durch die Zeile mit .AddMicrosoftIdentityWebApi wird der Web-API die Microsoft Identity Platform-Autorisierung hinzugefügt. Diese wird anschließend für die Überprüfung von Zugriffstoken konfiguriert, die von Microsoft Identity Platform ausgegeben werden – basierend auf den Informationen im Abschnitt AzureAD der Konfigurationsdatei appsettings.json:

appsettings.json (Schlüssel)	Beschreibung
`ClientId`	Die Anwendungs-(Client-)ID der Anwendung, die Sie registriert haben.
`Instance`	STS-Endpunkt (Security Token Service, Sicherheitstokendienst) für den zu authentifizierenden Benutzer. Dieser Wert ist in der Regel `https://login.microsoftonline.com/` (öffentliche Azure-Cloud).
`TenantId`	Name Ihres Mandanten, zugehörige Mandanten-ID (eine GUID) oder `common` für die Anmeldung von Benutzern mit Geschäfts-, Schul- oder Unikonto oder mit persönlichem Microsoft-Konto.

Die Methode Configure() enthält mit app.UseAuthentication() und app.UseAuthorization() zwei wichtige Methoden, um die genannte Funktion zu aktivieren:

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

Schützen eines Controllers, der Methode eines Controllers oder einer Razor-Seite

Sie können einen Controller oder Controllermethoden mithilfe des [Authorize]-Attributs schützen. Dieses Attribut beschränkt den Zugriff auf den Controller oder die Methoden, indem nur authentifizierte Benutzer zugelassen werden. Wenn sich der Benutzer noch nicht authentifiziert hat, kann für den Zugriff auf den Controller eine Authentifizierungsabfrage gestartet werden.

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

Überprüfen des Bereichs im Controller

Durch den Code in der API wird mithilfe von HttpContext.VerifyUserHasAnyAcceptedScope> (scopeRequiredByApi); überprüft, ob die erforderlichen Bereiche im Token enthalten sind:

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

Hilfe und Support

Wenn Sie Hilfe benötigen, ein Problem melden möchten oder sich über Ihre Supportoptionen informieren möchten, finden Sie weitere Informationen unter Hilfe und Support für Entwickler.

Nächste Schritte

Das folgende GitHub-Repository enthält die Anweisungen für das Codebeispiel für die ASP.NET Core-Web-API und weitere Beispiele, die zeigen, wie Sie Folgendes erreichen:

Hinzufügen einer Authentifizierung zu einer neuen ASP.NET Core-Web-API
Aufrufen der Web-API über eine Desktopanwendung
Aufrufen von Downstream-APIs wie Microsoft Graph und anderen Microsoft-APIs

Tutorials für die ASP.NET Core-Web-API auf GitHub