Geschützte Web-API: Codekonfiguration
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 seinorganizations
kann eine beliebige Organisation seinconsumers
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();
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für