Schnellstart: Schützen einer ASP.NET Core-Web-API mit Microsoft Identity PlatformQuickstart: Protect an ASP.NET Core web API with Microsoft identity platform

In dieser Schnellstartanleitung laden Sie ein ASP.NET Core-Web-API-Codebeispiel herunter und überprüfen den Code, der den Zugriff auf Ressourcen auf autorisierte Konten beschränkt.In this quickstart, you download an ASP.NET Core web API code sample and review its code that restricts access to resources to authorized accounts only. Das Beispiel unterstützt die Autorisierung von persönlichen Microsoft-Konten sowie Konten in einer beliebigen Azure AD-Organisation (Azure Active Directory).The sample supports authorization of personal Microsoft accounts and accounts in any Azure Active Directory (Azure AD) organization.

VoraussetzungenPrerequisites

Schritt 1: Registrieren der AnwendungStep 1: Register the application

Registrieren Sie zunächst die Web-API in Ihrem Azure AD-Mandanten, und fügen Sie einen Bereich hinzu:First, register the web API in your Azure AD tenant and add a scope by following these steps:

  1. Melden Sie sich beim Azure-Portal an.Sign in to the Azure portal.
  2. Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie im Menü am oberen Rand den Filter Verzeichnis + Abonnement  , um den Mandanten auszuwählen, für den Sie eine Anwendung registrieren möchten.
  3. Suchen Sie nach Azure Active Directory, und wählen Sie diese Option aus.Search for and select Azure Active Directory.
  4. Wählen Sie unter Verwalten Folgendes aus: App-Registrierungen > Neue Registrierung.Under Manage, select App registrations > New registration.
  5. Geben Sie unter Name einen Namen für Ihre Anwendung ein (beispielsweise AspNetCoreWebApi-Quickstart).Enter a Name for your application, for example AspNetCoreWebApi-Quickstart. Benutzern Ihrer App wird wahrscheinlich dieser Namen angezeigt. Sie können ihn später ändern.Users of your app might see this name, and you can change it later.
  6. Wählen Sie Registrieren.Select Register.
  7. Wählen Sie unter Verwalten die Optionen Eine API verfügbar machen > Bereich hinzufügen aus.Under Manage, select Expose an API > Add a scope. Übernehmen Sie den standardmäßigen Anwendungs-ID-URI, indem Sie Speichern und fortfahren auswählen. Geben Sie dann die folgenden Informationen ein:Accept the default Application ID URI by selecting Save and continue and enter the following details:
    • Bereichsname: access_as_userScope name: access_as_user
    • Zum Einwilligen berechtigte Personen: Administratoren und BenutzerWho can consent?: Admins and users
    • Anzeigename der Administratoreinwilligung: Access AspNetCoreWebApi-QuickstartAdmin consent display name: Access AspNetCoreWebApi-Quickstart
    • Beschreibung der Administratoreinwilligung: Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.Admin consent description: Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
    • Anzeigename der Benutzereinwilligung: Access AspNetCoreWebApi-QuickstartUser consent display name: Access AspNetCoreWebApi-Quickstart
    • Beschreibung der Benutzereinwilligung: Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.User consent description: Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
    • Status: AktiviertState: Enabled
  8. Wählen Sie Bereich hinzufügen aus, um das Hinzufügen des Bereichs abzuschließen.Select Add scope to complete the scope addition.

Schritt 2: Herunterladen des ASP.NET Core-ProjektsStep 2: Download the ASP.NET Core project

Schritt 3: Konfigurieren des ASP.NET Core-ProjektsStep 3: Configure the ASP.NET Core project

In diesem Schritt wird der Beispielcode für die Verwendung der zuvor erstellten App-Registrierung konfiguriert.In this step, configure the sample code to work with the app registration you created earlier.

  1. Extrahieren Sie das ZIP-Archiv in einem Ordner in der Nähe des Stammverzeichnisses Ihres Laufwerks.Extract the .zip archive into a folder near the root of your drive. Beispiel: C:\Azure-Samples.For example, into C:\Azure-Samples.

  2. Öffnen Sie die Lösung aus dem Ordner webapi in Ihrem Code-Editor.Open the solution in the webapi folder in your code editor.

  3. Öffnen Sie die Datei appsettings.json, und ändern Sie Folgendes:Open the appsettings.json file and modify the following:

    "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.Replace Enter_the_Application_Id_here with the Application (client) ID of the application you registered in the Azure portal. Den Wert für Anwendungs-ID (Client) finden Sie auf der Seite Übersicht der App.You can find Application (client) ID in the app's Overview page.
    • Ersetzen Sie Enter_the_Tenant_Info_Here durch eine der folgenden Optionen:Replace Enter_the_Tenant_Info_Here with one of the following:
      • 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).If your application supports Accounts in this organizational directory only, replace this value with the Directory (tenant) ID (a GUID) or tenant name (for example, contoso.onmicrosoft.com). Die Verzeichnis-ID (Mandant) finden Sie auf der Seite Übersicht der App.You can find the Directory (tenant) ID on the app's Overview page.
      • Unterstützt Ihre Anwendung Konten in einem beliebigen Organisationsverzeichnis, ersetzen Sie diesen Wert durch organizations.If your application supports Accounts in any organizational directory, replace this value with organizations
      • Wenn Ihre Anwendung Alle Microsoft-Kontobenutzer unterstützt, behalten Sie common für diesen Wert bei.If your application supports All Microsoft account users, leave this value as common

Ändern Sie in dieser Schnellstartanleitung keine anderen Werte in der Datei appsettings.json.For this quickstart, don't change any other values in the appsettings.json file.

Funktionsweise des BeispielsHow the sample works

Die Web-API empfängt ein Token von einer Clientanwendung, und das Token wird durch den Code in der Web-API überprüft.The web API receives a token from a client application, and the code in the web API validates the token. Eine ausführlichere Erläuterung dieses Szenarios finden Sie unter Szenario: Geschützte Web-API.This scenario is explained in more detail in Scenario: Protected web API.

StartklasseStartup class

Von der Middleware Microsoft.AspNetCore.Authentication wird eine Klasse vom Typ Startup verwendet, die ausgeführt wird, wenn der Hostprozess initialisiert wird.The Microsoft.AspNetCore.Authentication middleware uses a Startup class that's executed when the hosting process initializes. In der zugehörigen Methode ConfigureServices wird die von Microsoft.Identity.Web bereitgestellte Erweiterungsmethode AddMicrosoftIdentityWebApi aufgerufen.In its ConfigureServices method, the AddMicrosoftIdentityWebApi extension method provided by Microsoft.Identity.Web is called.

    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.The AddAuthentication() method configures the service to add JwtBearer-based authentication.

Durch die Zeile mit .AddMicrosoftIdentityWebApi wird Ihrer Web-API die Microsoft Identity Platform-Autorisierung hinzugefügt.The line containing .AddMicrosoftIdentityWebApi adds Microsoft identity platform authorization to your web API. Diese wird anschließend für die Überprüfung von Zugriffstoken konfiguriert, die vom Microsoft Identity Platform-Endpunkt ausgegeben werden – basierend auf den Informationen im Abschnitt AzureAD der Konfigurationsdatei appsettings.json:It's then configured to validate access tokens issued by the Microsoft identity platform endpoint based on the information in the AzureAD section of the appsettings.json configuration file:

appsettings.json (Schlüssel)appsettings.json key BeschreibungDescription
ClientId Anwendungs-ID (Client) der im Azure-Portal registrierten Anwendung.Application (client) ID of the application registered in the Azure portal.
Instance STS-Endpunkt (Security Token Service, Sicherheitstokendienst) für den zu authentifizierenden Benutzer.Security token service (STS) endpoint for the user to authenticate. Dieser Wert ist in der Regel https://login.microsoftonline.com/ (öffentliche Azure-Cloud).This value is typically https://login.microsoftonline.com/, indicating the Azure public 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.Name of your tenant or its tenant ID (a GUID), or common to sign in users with work or school accounts or Microsoft personal accounts.

Die Methode Configure() enthält mit app.UseAuthentication() und app.UseAuthorization() zwei wichtige Methoden, um die genannte Funktion zu aktivieren:The Configure() method contains two important methods, app.UseAuthentication() and app.UseAuthorization(), that enable their named functionality:

// This method gets called by the runtime. 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-SeiteProtect a controller, a controller's method, or a Razor page

Sie können einen Controller oder Controllermethoden mithilfe des [Authorize]-Attributs schützen.You can protect a controller or controller methods using the [Authorize] attribute. Dieses Attribut schränkt den Zugriff auf den Controller oder seine Methoden ein, indem es nur authentifizierte Benutzer zulässt. Das bedeutet, dass eine Authentifizierungsaufforderung für den Zugriff auf den Controller gestartet werden kann, wenn der Benutzer nicht authentifiziert ist.This attribute restricts access to the controller or methods by only allowing authenticated users, which means that authentication challenge can be started to access the controller if the user isn't authenticated.

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase

Überprüfen des Bereichs im ControllerValidate the scope in the controller

Anschließend wird durch den Code in der API mithilfe von HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi); überprüft, ob die erforderlichen Bereiche im Token enthalten sind.The code in the API then verifies that the required scopes are in the token by using HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);

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 SupportHelp and 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.If you need help, want to report an issue, or want to learn about your support options, see Help and support for developers.

Nächste SchritteNext steps

Das GitHub-Repository mit diesem Codebeispiel für die ASP.NET Core-Web-API enthält Anleitungen und weitere Codebeispiele für Folgendes:The GitHub repository that contains this ASP.NET Core web API code sample includes instructions and more code samples that show you how to:

  • Hinzufügen einer Authentifizierung zu einer neuen ASP.NET Core-Web-APIAdd authentication to a new ASP.NET Core web API
  • Aufrufen der Web-API über eine DesktopanwendungCall the web API from a desktop application
  • Aufrufen von Downstream-APIs wie Microsoft Graph und anderen Microsoft-APIsCall downstream APIs like Microsoft Graph and other Microsoft APIs