Geschützte Web-API: Codekonfiguration

Gilt für: Mitarbeitermandanten (weitere Informationen)

Beim Konfigurieren Ihrer geschützten Web-API müssen Sie Folgendes wissen:

• Wodurch werden APIs als geschützt definiert?
• Wie wird ein Bearertoken konfiguriert?
• Wie wird das Token überprüft?

Akzeptierte Tokenversion

Microsoft Identity Platform kann v1.0-Token und v2.0-Token ausgeben. Weitere Informationen zu diesen Token finden Sie unter Zugriffstoken.

Die Tokenversion, die von Ihrer API akzeptiert wird, richtet sich nach den unterstützten Kontotypen, die Sie beim Erstellen der Registrierung Ihrer Web-API-Anwendung im Azure-Portal ausgewählt haben.

• Wenn der Wert von Unterstützte Kontotypen auf Konten in allen Organisationsverzeichnissen und persönliche Microsoft-Konten (z. B. Skype, Xbox, Outlook.com) festgelegt ist, wird nur Tokenversion v2.0 akzeptiert.
• Andernfalls wird auch v1.0 als Tokenversion akzeptiert.

Nachdem Sie die Anwendung erstellt haben, können Sie die akzeptierte Tokenversion ermitteln oder ändern, indem Sie die folgenden Schritte ausführen:

1. Wählen Sie im Microsoft Entra Admin Center Ihre App und dann Manifest aus.
2. Suchen Sie im Manifest nach der Eigenschaft accessTokenAcceptedVersion.
3. Der Wert legt für Microsoft Entra fest, welche Token-Version die Web-API akzeptiert.
   • Mit dem Wert „2“ akzeptiert die Web-API v2.0-Token.
   • Ist der Wert Null, akzeptiert die Web-API v1.0-Token.
4. Falls Sie die Tokenversion geändert haben, wählen Sie Speichern aus.

Die Web-API gibt an, welche Tokenversion akzeptiert wird. Wenn ein Client ein Token für Ihre Web-API von Microsoft Identity Platform anfordert, erhält er ein Token, das angibt, welche Tokenversion die Web-API akzeptiert.

Wodurch werden ASP.NET- und ASP.NET Core-APIs als geschützt definiert?

Genau wie Web-Apps sind auch ASP.NET- und ASP.NET Core-Web-APIs geschützt, da ihren Controlleraktionen das Attribut [Authorize] vorangestellt ist. Die Controlleraktionen können nur aufgerufen werden, wenn die API mit einer autorisierten Identität aufgerufen wird.

Stellen Sie sich die folgenden Fragen:

• Eine Web-API kann nur von einer App aufgerufen werden. Woher kennt die API die Identität der aufrufenden App?
• Falls die App die API im Namen eines Benutzers aufruft: Welche Identität hat der Benutzer?

Bearertoken

Das Bearertoken, das beim Aufrufen der App im Header festgelegt wird, enthält Informationen zur App-Identität. Außerdem enthält es Informationen zum Benutzer. (Es sei denn, die Web-App akzeptiert Dienst-zu-Dienst-Aufrufe von einer Daemon-App).

Das folgende C#-Codebeispiel zeigt, wie ein Client die API aufruft, nachdem er ein Token für die Microsoft-Authentifizierungsbibliothek für .NET (MSAL.NET) abgerufen hat:

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);

Wichtig

Eine Clientanwendung fordert das Bearertoken für Microsoft Identity Platform für die Web-API an. Die API ist die einzige Anwendung, die das Token verifizieren und die darin enthaltenen Ansprüche anzeigen sollte. Client-Apps dürfen niemals versuchen, die Ansprüche in Token zu überprüfen.

Die Web-API kann später ggf. die Verschlüsselung des Tokens erforderlich machen. Diese Anforderung würde den Zugriff durch Client-Apps verhindern, die Zugriffstoken anzeigen können.

JwtBearer-Konfiguration

In diesem Abschnitt wird beschrieben, wie Sie ein Bearertoken konfigurieren.

Konfigurationsdatei

Sie müssen die TenantId nur angeben, wenn Sie Zugriffstoken von einem einzigen Mandanten (einer branchenspezifischen App) akzeptieren möchten. Andernfalls kann common beibehalten werden. Die verschiedenen Werte können folgende sein:

• GUID (Mandanten-ID = Verzeichnis-ID)
• common kann eine beliebige Organisation und ein persönliches Konto sein
• organizations kann eine beliebige Organisation sein
• consumers sind persönliche Microsoft-Konten

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "Enter_the_Application_(client)_ID_here",
    "TenantId": "common"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Verwenden eines benutzerdefinierten App-ID-URI für eine Web-API

Wenn Sie den vom Azure-Portal vorgeschlagenen Standard-App-ID-URI akzeptiert haben, müssen Sie die Zielgruppe nicht angeben. Fügen Sie andernfalls eine Audience-Eigenschaft hinzufügen, deren Wert der App-ID-URI für Ihre Web-API ist. Dieser beginnt in der Regel mit api://.

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

Codeinitialisierung

Wenn eine App in einer Controlleraktion aufgerufen wird, die ein Attribut vom Typ [Authorize] enthält, extrahieren ASP.NET und ASP.NET Core das Zugriffstoken aus dem Bearertoken des Autorisierungsheaders. Das Zugriffstoken wird dann an die JwtBearer-Middleware weitergeleitet, die die Microsoft-Identitätsmodellerweiterungen für .NET aufruft.

Microsoft.Identity.Web

ASP.NET Core

Microsoft empfiehlt die Verwendung des NuGet-Pakets Microsoft.Identity.Web beim Entwickeln einer Web-API mit ASP.NET Core.

Microsoft.Identity.Web ist die verbindende Komponente zwischen ASP.NET Core, der Authentifizierungsmiddleware und der Microsoft-Authentifizierungsbibliothek (Microsoft Authentication Library, MSAL) für .NET. Das Paket ermöglicht eine übersichtlichere, stabilere Entwicklerumgebung und nutzt die Leistungsfähigkeit von Microsoft Identity Platform und Azure AD B2C.

ASP.NET für .NET 6.0

Verwenden Sie zum Erstellen eines neuen Web-API-Projekts, das Microsoft.Identity.Web verwendet, eine Projektvorlage in der .NET 6.0 CLI oder in Visual Studio.

.NET Core-CLI

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

Visual Studio: Um ein Web-API-Projekt in Visual Studio zu erstellen, wählen Sie Datei>Neues>Projekt>ASP.NET Core Web-API aus.

Sowohl die .NET CLI- als auch die Visual Studio-Projektvorlagen erstellen eine Datei Program.cs ähnlich diesem Codeschnipsel. Beachten Sie die using-Anweisung Microsoft.Identity.Web und die Zeilen für Authentifizierung und Autorisierung.

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();

ASP.NET

Microsoft empfiehlt die Verwendung des NuGet-Pakets Microsoft.Identity.Web.OWIN beim Entwickeln einer Web-API mit ASP.NET.

Microsoft.Identity.Web.OWIN ist die verbindende Komponente zwischen ASP.NET, der ASP.NET-Authentifizierungsmiddleware und der Microsoft-Authentifizierungsbibliothek (Microsoft Authentication Library, MSAL) für .NET. Das Paket ermöglicht eine übersichtlichere, stabilere Entwicklerumgebung und nutzt die Leistungsfähigkeit von Microsoft Identity Platform und Azure AD B2C.

Es verwendet dieselbe Konfigurationsdatei wie ASP.NET Core (appsettings.json), und Sie müssen sicherstellen, dass diese Datei mit der Ausgabe Ihres Projekts kopiert wird (Eigenschaft immer in den Dateieigenschaften in Visual Studio oder in der CSPROJ kopieren)

Microsoft.Identity.Web.OWIN fügt IAppBuilder eine Erweiterungsmethode mit dem Namen AddMicrosoftIdentityWebApi hinzu. Diese Methode verwendet als Parameter eine Instanz von OwinTokenAcquirerFactory, die Sie durch Aufrufen von OwinTokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>() erhalten, und zeigt eine Instanz von IServiceCollection an, der Sie viele Dienste hinzufügen können, um Downstream-APIs aufzurufen oder den Tokencache zu konfigurieren.

Hier ist ein Beispielcode für Startup.Auth.cs. Der vollständige Code ist unter tests/DevApps/aspnet-mvc/OwinWebApp verfügbar.

using Microsoft.Owin.Security;
using Microsoft.Owin.Security.Cookies;
using Owin;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Identity.Client;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web.OWIN;
using System.Web.Services.Description;

namespace OwinWebApp
{
    public partial class Startup
    {
        public void ConfigureAuth(IAppBuilder app)
        {
            app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);
            app.UseCookieAuthentication(new CookieAuthenticationOptions());

            OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();

            app.AddMicrosoftIdentityWebApp(factory);
            factory.Services
                .Configure<ConfidentialClientApplicationOptions>(options => { options.RedirectUri = "https://localhost:44386/"; })
                .AddMicrosoftGraph()
                .AddDownstreamApi("DownstreamAPI1", factory.Configuration.GetSection("DownstreamAPI"))
                .AddInMemoryTokenCaches();
            factory.Build();
        }
    }
}

--

Tokenüberprüfung

Im obigen Codeausschnitt überprüft die JwtBearer-Middleware das Token auf der Grundlage des Werts von TokenValidationParameters (genau wie die OpenID Connect-Middleware in Web-Apps). Der Token wird bei Bedarf entschlüsselt, die Ansprüche werden extrahiert, und die Signatur wird überprüft. Die Middleware validiert dann das Token, indem sie auf diese Daten überprüft:

• Audience: Das Ziel des Tokens ist die Web-API.
• Antragsteller: Das Token wurde für eine App ausgestellt, die zum Aufrufen der Web-API berechtigt ist.
• Aussteller: Das Token wurde von einem vertrauenswürdigen Sicherheitstokendienst (Security Token Service, STS) ausgestellt.
• Ablauf: Die Tokenlebensdauer liegt innerhalb des zulässigen Bereichs.
• Signatur: Das Token wurde nicht manipuliert.

Es können auch spezielle Validierungen vorliegen. So kann beispielsweise sichergestellt werden, dass die Signaturschlüssel (bei Einbettung in ein Token) vertrauenswürdig sind und das Token nicht wiedergegeben wird. Für einige Protokolle sind bestimmte Validierungen erforderlich.

Validierungssteuerelemente

Die Schritte zur Überprüfung werden in Validierungssteuerelementen erfasst, die durch die Open-Source-Bibliothek Microsoft-Identitätsmodellerweiterungen für .NET bereitgestellt werden. Die Validierungssteuerelemente sind in der Quelldatei Microsoft.IdentityModel.Tokens/Validators.cs der Bibliothek definiert.

Die folgende Tabelle enthält eine Beschreibung der Validierungssteuerelemente:

Validierungssteuerelement	BESCHREIBUNG
ValidateAudience	Stellt sicher, dass das Token für die Anwendung bestimmt ist, die das Token für Sie überprüft.
ValidateIssuer	Stellt sicher, dass das Token von einem vertrauenswürdigen Sicherheitstokendienst ausgestellt wurde und somit von jemandem stammt, dem Sie vertrauen.
ValidateIssuerSigningKey	Stellt sicher, dass die Anwendung, die das Token validiert, dem Schlüssel vertraut, mit dem das Token signiert wurde. Es gibt einen Sonderfall, bei dem der Schlüssel in das Token eingebettet ist. Dies ist jedoch in der Regel nicht der Fall.
ValidateLifetime	Stellt sicher, dass das Token noch oder bereits gültig ist. Das Validierungssteuerelement überprüft, ob die Lebensdauer des Tokens innerhalb des durch die Ansprüche notbefore und expires angegebenen Bereichs liegt.
ValidateSignature	Stellt sicher, dass das Token nicht manipuliert wurde.
ValidateTokenReplay	Stellt sicher, dass das Token nicht wiedergegeben wird. Es gibt einen Sonderfall für einige Protokolle mit einmaliger Verwendung.

Anpassen der Tokenüberprüfung

Die Validierungssteuerelemente werden Eigenschaften der Klasse TokenValidationParameters zugeordnet. Die Eigenschaften werden von der ASP.NET- und ASP.NET Core-Konfiguration initialisiert.

In den meisten Fällen müssen die Parameter nicht geändert werden. Ausnahmen sind Apps, bei denen es sich nicht um Einzelmandanten handelt. Diese Web-Apps akzeptieren Benutzer aus einer beliebigen Organisation oder von persönlichen Microsoft-Konten. In diesem Fall ist eine Überprüfung der Aussteller erforderlich. Microsoft.Identity.Web übernimmt auch die Überprüfung des Ausstellers.

Wenn Sie in ASP.NET Core die Parameter für die Tokenüberprüfung anpassen möchten, verwenden Sie in der Datei Startup.cs den folgenden Codeausschnitt:

services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
        .AddMicrosoftIdentityWebApi(Configuration);
services.Configure<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme, options =>
{
  options.TokenValidationParameters.ValidAudiences = new[] { /* list of valid audiences */};
});

Für ASP.NET MVC veranschaulicht das folgende Codebeispiel die Ausführung einer benutzerdefinierten Tokenüberprüfung:

https://github.com/azure-samples/active-directory-dotnet-webapi-manual-jwt-validation

Tokenüberprüfung in Azure Functions

Eingehende Zugriffstoken können auch in Azure Functions überprüft werden. Beispiele für eine solche Überprüfung finden Sie in den folgenden Codebeispielen auf GitHub:

• .NET: Azure-Samples/ms-identity-dotnet-webapi-azurefunctions
• Node.js: Azure-Samples/ms-identity-nodejs-webapi-azurefunctions
• Python: Azure-Samples/ms-identity-python-webapi-azurefunctions)

Nächste Schritte

Fahren Sie mit dem nächsten Artikel in diesem Szenario fort: Überprüfen der Geltungsbereiche und App-Rollen in Ihrem Code.