Schnellstart: Schützen einer ASP.NET Core Web-API

In dieser Schnellstartanleitung schützen Sie eine ASP.NET Core Web-API mit Microsoft Entra ID mithilfe von Microsoft. Identity.Web. Sie fügen Middleware für die Authentifizierung hinzu, die Bearertoken überprüft und den Zugriff auf autorisierte Aufrufer beschränkt.

Wenn Sie noch kein Azure-Abonnement haben, erstellen Sie ein kostenloses Konto, bevor Sie beginnen.

Voraussetzungen

Option 1: Aus Vorlage erstellen (am schnellsten)

Verwenden Sie die ASP.NET Core-Vorlage mit integrierter Microsoft Entra-Authentifizierung, um ein geschütztes API-Projekt zu erstellen.

1. Erstellen des Projekts

Führen Sie die folgenden Befehle aus, um ein neues Web-API-Projekt mit einzelorganisationsbasierter Authentifizierung zu erstellen und in das Projektverzeichnis zu navigieren:

dotnet new webapi --auth SingleOrg --name MyWebApi
cd MyWebApi

2. Konfigurieren der App-Registrierung

Ersetzen Sie die Platzhalterwerte in appsettings.json durch Ihre Microsoft Entra App-Registrierungsdetails:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-api-client-id"
  }
}

3. Ausführen der API

Starten Sie die Anwendung:

dotnet run

Ihre API ist jetzt geschützt unter https://localhost:5001.

Fertig. Anforderungen erfordern jetzt ein gültiges Zugriffstoken.

Option 2: Hinzufügen zur vorhandenen Web-API

Wenn Sie bereits über eine ASP.NET Core Web-API verfügen, fügen Sie Microsoft Entra Authentifizierung mit den folgenden Schritten hinzu.

1. NuGet-Paket installieren

Fügen Sie das Microsoft.Identity.Web NuGet-Paket zu Ihrem Projekt hinzu.

dotnet add package Microsoft.Identity.Web

2. Konfigurieren der Authentifizierung in Program.cs

Registrieren Sie die Authentifizierungs- und Autorisierungsdienste in der Startpipeline Ihrer App. Der folgende Code konfiguriert die JWT-Bearer-Authentifizierung mit der Microsoft Entra-Überprüfung:

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

var builder = WebApplication.CreateBuilder(args);

// Add authentication
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(builder.Configuration, "AzureAd");

// Add authorization
builder.Services.AddAuthorization();

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthentication(); //  Add authentication middleware
app.UseAuthorization();

app.MapControllers();

app.Run();

3. Konfiguration zu appsettings.json hinzufügen

Fügen Sie den Microsoft Entra Konfigurationsabschnitt mit Ihren Mandanten- und Anwendungsdetails hinzu. Legen Sie die Protokollierungsebene für Microsoft.Identity.Web auf Information fest, um die Behandlung von Tokenüberprüfungsproblemen zu unterstützen:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-api-client-id"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Identity.Web": "Information"
    }
  }
}

4. Schützen Ihrer API-Endpunkte

Wenden Sie das [Authorize] Attribut auf Controller oder Aktionen an, die ein gültiges Zugriffstoken erfordern.

Authentifizierung für alle Endpunkte erforderlich:

Der folgende Controller erfordert ein gültiges Zugriffstoken für alle Aktionen und zeigt, wie auf Benutzeransprüche zugegriffen werden kann:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[Authorize] //  Require valid access token
[ApiController]
[Route("api/[controller]")]
public class WeatherForecastController : ControllerBase
{
    [HttpGet]
    public IEnumerable<WeatherForecast> Get()
    {
        // Access user information
        var userId = User.FindFirst("oid")?.Value;
        var userName = User.Identity?.Name;

        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = "Protected data"
        });
    }
}

Bestimmte Bereiche erfordern:

Verwenden Sie das [RequiredScope] Attribut, um differenzierte Berechtigungen für einzelne Aktionen zu erzwingen:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Identity.Web;

[Authorize]
[ApiController]
[Route("api/[controller]")]
public class TodoController : ControllerBase
{
    [HttpGet]
    [RequiredScope("access_as_user")] //  Require specific scope
    public IActionResult GetAll()
    {
        return Ok(new[] { "Todo 1", "Todo 2" });
    }

    [HttpPost]
    [RequiredScope("write")] //  Different scope for write operations
    public IActionResult Create([FromBody] string item)
    {
        return Created("", item);
    }
}

5. Ausführen und Testen

Starten Sie die Anwendung, und stellen Sie sicher, dass nicht authentifizierte Anforderungen abgelehnt werden:

dotnet run

Testen Sie mit einem Tool wie Postman oder Curl. Eine nicht authentifizierte Anforderung gibt folgendes zurück 401 Unauthorized:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://localhost:5001/api/weatherforecast

Erfolg! Ihre API überprüft jetzt Bearertoken.

Einrichtung der App-Registrierung

Bevor Ihre API Token überprüfen kann, benötigen Sie eine Microsoft Entra App-Registrierung. Führen Sie die folgenden Schritte im Azure-Portal aus.

1. Registrieren Ihrer API

  1. Melden Sie sich beim portal Azure
  2. Navigieren Sie zu Microsoft Entra ID>App-Registrierungen>Neue Registrierung
  3. Geben Sie einen Namen ein (z. B. "Meine Web-API")
  4. Auswählen eines einzelnen Mandanten (am häufigsten für APIs)
  5. Kein Umleitungs-URI für APIs erforderlich
  6. Klicken Sie auf Registrieren.

2. Bereitstellen eines API-Geltungsbereichs

Definieren Sie die Berechtigungen (Bereiche), die Client-Apps beim Aufrufen Ihrer API anfordern können.

  1. Wechseln Sie in Ihrer API-App-Registrierung zu "Verfügbarmachen einer API".
  2. Klicken Sie auf "Bereich hinzufügen"
  3. Übernehmen Sie den standardanwendungs-ID-URI, oder passen Sie ihn an (z. B. api://your-api-client-id)
  4. Hinzufügen eines Bereichs:
    • Bereichsname:access_as_user
    • Wer kann zustimmen: Administratoren und Benutzer
    • Anzeigename der Administratorzustimmung: "Auf meine Web-API zugreifen"
    • Beschreibung der Administratorzustimmung: "Ermöglicht der App den Zugriff auf die Web-API im Namen des angemeldeten Benutzers"
  5. Klicken Sie auf "Bereich hinzufügen".

3. Beachten Sie die Anwendungs-ID.

Kopieren Sie die Anwendungs-ID (Client-ID) von der Übersichtsseite der App-Registrierung. Dieser Wert ist Ihr ClientId in appsettings.json.

Erstellen einer Client-App-Registrierung (zum Testen)

Um Ihre geschützte API zu testen, registrieren Sie eine separate Clientanwendung, die Token abruft und die API aufruft.

1. Registrieren einer Clientanwendung

  1. Erstellen Sie in Microsoft Entra ID>App-Registrierungen eine weitere Registrierung.
  2. Benennen Sie ihn (z. B. "Mein API-Client")
  3. Kontotypen auswählen
  4. Umleitungs-URI hinzufügen: https://localhost:7000/signin-oidc (wenn es sich um eine Web-App handelt)
  5. Klicken Sie auf Registrieren.

2. Erteilen von API-Berechtigungen

Erteilen Sie der Clientanwendung die Berechtigung, Ihre API mit den von Ihnen definierten Bereichen aufzurufen.

  1. Wechseln Sie in der Client-App-Registrierung zu API-Berechtigungen.
  2. Klicken Sie auf Eine Berechtigung hinzufügen>Meine APIs.
  3. Wählen Sie Ihre API-Registrierung aus.
  4. Überprüfen Sie den Bereich access_as_user
  5. Klicken Sie auf "Berechtigungen hinzufügen".
  6. Klicken Sie auf "Administratorzustimmung erteilen" (falls erforderlich)

3. Erstellen eines geheimen Clientschlüssels (für vertrauliche Clients)

Wenn Ihre Client-App auf einem Server (kein Browser oder mobiles Gerät) ausgeführt wird, erstellen Sie einen geheimen Clientschlüssel für die Authentifizierung.

  1. Gehen Sie zu Zertifikate & Geheimnisse.
  2. Klicken Sie auf "Neuer geheimer Clientschlüssel".
  3. Hinzufügen einer Beschreibung und eines Ablaufdatums
  4. Klicken Sie auf Hinzufügen.
  5. Kopieren Sie den geheimen Wert sofort . Sie können ihn nicht mehr sehen.

Testen der geschützten API

Überprüfen Sie, ob Ihre API Token korrekt validiert, indem Sie authentifizierte Anfragen senden.

Verwenden von Postman

Richten Sie die OAuth 2.0-Authentifizierung in Postman ein, um ein Token abzurufen und Ihre API aufzurufen.

  1. Erstellen einer neuen Anforderung in Postman
  2. OAuth 2.0-Authentifizierung einrichten:
    • Grant-Typ: Autorisierungscode (für Benutzerkontext) oder Clientanmeldeinformationen (für App-Kontext)
    • Authentifizierungs-URL:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
    • Zugriffstoken-URL:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
    • Client-ID: Client-ID Ihrer Client-App
    • Geheimer Clientschlüssel: Geheimer Client-App-Schlüssel
    • Umfang:api://your-api-client-id/access_as_user
  3. Klicken Sie auf "Neues Zugriffstoken abrufen"
  4. Verwenden des Tokens zum Aufrufen Ihrer API

Verwenden von Code (C#-Beispiel)

Im folgenden Beispiel wird MSAL.NET verwendet, um ein Token mit dem Client-Anmeldeinformationsfluss abzurufen und die geschützte API aufzurufen.

// In a console app or client application
using Microsoft.Identity.Client;

var app = ConfidentialClientApplicationBuilder
    .Create("client-app-id")
    .WithClientSecret("client-secret")
    .WithAuthority("https://login.microsoftonline.com/{tenant-id}")
    .Build();

var result = await app.AcquireTokenForClient(
    new[] { "api://your-api-client-id/.default" }
).ExecuteAsync();

var accessToken = result.AccessToken;

// Use the token to call your API
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", accessToken);

var response = await client.GetAsync("https://localhost:5001/api/weatherforecast");

Allgemeine Konfigurationsoptionen

Microsoft. Identity.Web unterstützt verschiedene Konfigurationsmuster für verschiedene Szenarien.

Erfordern spezifische Bereiche in der Konfiguration

Statt dem [RequiredScope]-Attribut zu verwenden, können Sie die erforderlichen Bereiche global in appsettings.json konfigurieren.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-api-client-id",
    "Scopes": "access_as_user"
  }
}

Token von mehreren Mandanten akzeptieren

Um Token von einem beliebigen Microsoft Entra Mandanten zu akzeptieren, legen Sie TenantId auf common fest:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "common",
    "ClientId": "your-api-client-id"
  }
}

Konfigurieren der Tokenüberprüfung

Wenn Ihre API nachgeschaltete APIs aufruft (z. B. Microsoft Graph), aktivieren Sie den Tokenerwerb und konfigurieren Sie einen Tokencache:

builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi() // If your API calls other APIs
    .AddInMemoryTokenCaches();

Nächste Schritte

Nachdem Sie nun über eine geschützte API verfügen, erkunden Sie die folgenden Themen:

Problembehandlung

401 Nicht autorisiert

Problem: API gibt 401 auch mit einem Token zurück.

Mögliche Ursachen:

  • Die Zielgruppe des Tokens (aud Anforderung) stimmt nicht mit Ihrer API ClientId überein.
  • Token ist abgelaufen
  • Token ist für den falschen Mandanten vorgesehen.
  • Erforderlicher Bereich fehlt

Lösung: Decodieren Sie das Token bei jwt.ms , und überprüfen Sie die Ansprüche. Siehe Protokollierung und Diagnose für eine detaillierte Problembehandlung.

AADSTS50013: Ungültige Signatur

Problem: Fehler bei der Tokensignaturüberprüfung.

Lösung: Stellen Sie sicher, dass TenantId und ClientId korrekt sind. Das Token muss von der erwarteten Autorität ausgestellt werden. Aktivieren Sie die detaillierte Protokollierung, um Überprüfungsfehler anzuzeigen.

Bereiche, die im Token nicht gefunden wurden

Problem:[RequiredScope] Das Attribut schlägt fehl.

Lösung:

  1. Überprüfen, ob die Client-App über die Berechtigung für den Bereich verfügt
  2. Sicherstellen, dass die Administratorzustimmung erteilt wurde (falls erforderlich)
  3. Siehe Autorisierungshandbuch für vollständige Gültigkeitsbereichsvalidierungsmuster
  4. Überprüfen Sie, ob der Bereich beim Abrufen des Tokens angefordert wird (z. B. api://your-api/.default oder bestimmte Bereiche)

Weitere Informationen finden Sieim Handbuch zur Problembehandlung für Web-API

Verwandte Inhalte

  • Last updated on