Geschützte Web-API: Codekonfiguration

  • Artikel

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?

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 standardmäßigen App-ID-URI akzeptiert haben, müssen Sie die Zielgruppe nicht angeben (siehe Anwendungs-ID-URI und Bereiche). 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

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