Schnellstart: Schützen einer ASP.NET Core-Web-API mit Microsoft Identity Platform
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:
Wir entschuldigen uns für die Unannehmlichkeiten und bitten Sie um Geduld, während wir an einer Lösung arbeiten.
In dieser Schnellstartanleitung laden Sie ein ASP.NET Core-Web-API-Codebeispiel herunter und überprüfen, wie es den Ressourcenzugriff auf autorisierte Konten beschränkt. Das Beispiel unterstützt die Autorisierung von persönlichen Microsoft-Konten sowie Konten in einer beliebigen Azure AD-Organisation (Azure Active Directory).
Voraussetzungen
- Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
- Azure Active Directory-Mandant
- .NET Core SDK 3.1+
- Visual Studio 2019 oder Visual Studio Code
Schritt 1: Registrieren der Anwendung
Registrieren Sie zunächst die Web-API in Ihrem Azure AD-Mandanten, und fügen Sie einen Bereich hinzu:
- Melden Sie sich beim Azure-Portal an.
- Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie im Menü am oberen Rand den Filter Verzeichnis + Abonnement
, um den Mandanten auszuwählen, in dem Sie die Anwendung registrieren möchten.
- Suchen Sie nach Azure Active Directory, und wählen Sie diese Option aus.
- Wählen Sie unter Verwalten Folgendes aus: App-Registrierungen>Neue Registrierung.
- Geben Sie unter Name einen Namen für Ihre Anwendung ein. Geben Sie beispielsweise AspNetCoreWebApi-Quickstart ein. Benutzern Ihrer App wird dieser Name angezeigt. Sie können ihn später ändern.
- 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
- Bereichsname:
- 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.
Tipp
Es wird empfohlen, das Archiv in ein Verzeichnis in der Nähe des Stammverzeichnisses Ihres Laufwerks zu extrahieren, um Fehler zu vermeiden, die durch Beschränkungen der Pfadlänge unter Windows verursacht werden.
Schritt 3: Konfigurieren des ASP.NET Core-Projekts
In diesem Schritt wird der Beispielcode für die Verwendung der zuvor erstellten App-Registrierung konfiguriert.
Extrahieren Sie das ZIP-Archiv in einem Ordner in der Nähe des Stammverzeichnisses Ihres Laufwerks. Extrahieren Sie es beispielsweise in C:\Azure-Samples.
Es wird empfohlen, das Archiv in ein Verzeichnis in der Nähe des Stammverzeichnisses Ihres Laufwerks zu extrahieren, um Fehler zu vermeiden, die durch Beschränkungen der Pfadlänge unter Windows verursacht werden.
Öffnen Sie die Lösung aus dem Ordner webapi in Ihrem Code-Editor.
Öffnen Sie die Datei appsettings.json, und ändern Sie den folgenden Code:
"ClientId": "Enter_the_Application_Id_here", "TenantId": "Enter_the_Tenant_Info_Here"
- Ersetzen Sie
Enter_the_Application_Id_here
durch die Anwendungs-ID (Client) der im Azure-Portal registrierten Anwendung. Sie finden die Anwendungs-ID (Client) auf der Seite Übersicht der App. - Ersetzen Sie
Enter_the_Tenant_Info_Here
durch eine der folgenden Optionen:- Wenn Ihre Anwendung Nur Konten in diesem Organisationsverzeichnis unterstützt, ersetzen Sie diesen Wert durch die Verzeichnis-ID (Mandant) (eine GUID) oder durch den Mandantennamen (beispielsweise
contoso.onmicrosoft.com
). Die Verzeichnis-ID (Mandant) finden Sie auf der Seite Übersicht der App. - Falls Ihre Anwendung Konten in einem beliebigen Organisationsverzeichnis unterstützt, ersetzen Sie diesen Wert durch
organizations
. - Wenn Ihre Anwendung Alle Microsoft-Kontobenutzer unterstützt, behalten Sie
common
für diesen Wert bei.
- Wenn Ihre Anwendung Nur Konten in diesem Organisationsverzeichnis unterstützt, ersetzen Sie diesen Wert durch die Verzeichnis-ID (Mandant) (eine GUID) oder durch den Mandantennamen (beispielsweise
- Ersetzen Sie
Ändern Sie in dieser Schnellstartanleitung keine anderen Werte in der Datei appsettings.json.
Funktionsweise des Beispiels
Die Web-API empfängt ein Token von einer Clientanwendung, und das Token wird durch den Code in der Web-API überprüft. Eine ausführlichere Erläuterung dieses Szenarios finden Sie unter Szenario: Geschützte Web-API.
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 Ihrer 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 |
Anwendungs-ID (Client) der im Azure-Portal registrierten Anwendung. |
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 GitHub-Repository mit diesem Codebeispiel für die ASP.NET Core-Web-API enthält Anleitungen und weitere Codebeispiele für Folgendes:
- 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