Web-App für Benutzeranmeldungen: Codekonfiguration

Erfahren Sie, wie Sie den Code für Ihre Web-App zur Benutzeranmeldung konfigurieren.

Microsoft-Bibliotheken, die Web-Apps unterstützen

Die folgenden Microsoft-Bibliotheken werden verwendet, um eine Web-App (und eine Web-API) zu schützen:

Programmiersprache/Framework Projekt auf
GitHub
Paket Erste Schritte
gestartet
Anmelden von Benutzern Zugriff auf Web-APIs Allgemein verfügbar (Generally Available, GA) oder
Öffentliche Vorschau1
.NET MSAL.NET Microsoft.Identity.Client Library cannot request ID tokens for user sign-in. Library can request access tokens for protected web APIs. Allgemein verfügbar
.NET Microsoft.IdentityModel Microsoft.IdentityModel Library cannot request ID tokens for user sign-in.2 Library cannot request access tokens for protected web APIs.2 Allgemein verfügbar
ASP.NET Core ASP.NET Core Microsoft.AspNetCore.Authentication Schnellstart Library can request ID tokens for user sign-in. Library cannot request access tokens for protected web APIs. Allgemein verfügbar
ASP.NET Core Microsoft.Identity.Web Microsoft.Identity.Web Schnellstart Library can request ID tokens for user sign-in. Library can request access tokens for protected web APIs. Allgemein verfügbar
Java MSAL4J msal4j Schnellstart Library can request ID tokens for user sign-in. Library can request access tokens for protected web APIs. Allgemein verfügbar
Spring spring-cloud-azure-starter-active-directory spring-cloud-azure-starter-active-directory Tutorial Library can request ID tokens for user sign-in. Library can request access tokens for protected web APIs. Allgemein verfügbar
Node.js MSAL Node msal-node Schnellstart Library can request ID tokens for user sign-in. Library can request access tokens for protected web APIs. Allgemein verfügbar
Python MSAL Python msal Library can request ID tokens for user sign-in. Library can request access tokens for protected web APIs. Allgemein verfügbar
Python Identität Identität Schnellstart Library can request ID tokens for user sign-in. Library can request access tokens for protected web APIs. --

(1)Universelle Lizenzbedingungen für Onlinedienste gelten für Bibliotheken in der öffentlichen Vorschau.

(2) Die Bibliothek Microsoft.IdentityModelüberprüft nur Token. Sie kann keine ID- oder Zugriffstoken anfordern.

Wählen Sie die Registerkarte aus, die der gewünschten Plattform entspricht:

Die Codeausschnitte in diesem und den folgenden Artikeln stammen aus Kapitel 1 des inkrementellen Tutorials zu ASP.NET Core-Web-Apps.

In diesem Tutorial finden Sie auch ausführliche Informationen zur Implementierung.

Konfigurationsdateien

Webanwendungen, die Benutzer mithilfe der Microsoft Identity Platform anmelden, werden mithilfe von Konfigurationsdateien konfiguriert. Diese Dateien müssen die folgenden Werte angeben:

  • Die Cloudinstanz, wenn Ihre App beispielsweise in nationalen Clouds ausgeführt werden soll. Die verschiedenen Optionen umfassen:
    • https://login.microsoftonline.com/ für die öffentliche Azure-Cloud
    • https://login.microsoftonline.us/ für Azure US Government
    • https://login.microsoftonline.de/für Microsoft Entra Deutschland
    • https://login.partner.microsoftonline.cn/common für Microsoft Entra China, betrieben von 21Vianet
  • Die Zielgruppe in der Mandanten-ID. Die verfügbaren Optionen hängen davon ab, ob es sich bei Ihrer App um eine einzel- oder mehrinstanzenfähige Anwendung handelt.
    • Die Mandanten-GUID, die vom Azure-Portal zum Anmelden von Benutzern in Ihrer Organisation abgerufen wird. Sie können auch einen Domänennamen verwenden.
    • organizations zum Anmelden von Benutzern in einem Geschäfts-, Schul- oder Unikonto
    • common zum Anmelden von Benutzern mit Geschäfts-, Schul- oder Unikonten oder persönlichen Microsoft-Konten
    • consumers zum Anmelden von Benutzern, die nur ein persönliches Microsoft-Konto haben
  • Die Client-ID für Ihre Anwendung, wie sie aus dem Azure-Portal kopiert wird.

Möglicherweise sehen Sie auch Verweise auf die Autorität, eine Verkettung der Werte von Instanz und Mandanten-ID.

In ASP.NET Core befinden sich diese Einstellungen in der Datei appsettings.json im Abschnitt „Microsoft Entra ID“.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "[Enter the tenantId here]",

    // Client ID (application ID) obtained from the Azure portal
    "ClientId": "[Enter the Client Id here]",
    "CallbackPath": "/signin-oidc",
    "SignedOutCallbackPath": "/signout-oidc"
  }
}

In ASP.NET Core gibt es eine weitere Datei (properties\launchSettings.json), die die URL (applicationUrl) und den TLS-/SSL-Port (sslPort) für Ihre Anwendung und verschiedenen Profile enthält.

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:3110/",
      "sslPort": 44321
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "webApp": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "http://localhost:3110/"
    }
  }
}

Im Azure-Portal müssen die Umleitungs-URIs, die Sie auf der Seite Authentifizierung für Ihre Anwendung registrieren, mit diesen URLs übereinstimmen. Für die beiden obigen Konfigurationsdateien wäre dies https://localhost:44321/signin-oidc. Der Grund hierfür ist, dass applicationUrl zwar http://localhost:3110 ist, aber sslPort angegeben wird (44321). CallbackPath ist /signin-oidc, wie in appsettings.jsondefiniert.

Auf die gleiche Weise wird der Abmelde-URI auf https://localhost:44321/signout-oidc festgelegt.

Hinweis

„SignedOutCallbackPath“ sollte entweder auf das Portal oder die Anwendung festgelegt werden, um Konflikte bei der Behandlung des Ereignisses zu vermeiden.

Initialisierungscode

Die Unterschiede beim Initialisierungscode hängen von der Plattform ab. Für ASP.NET Core und ASP.NET wird die Anmeldung von Benutzern an die OpenID Connect-Middleware delegiert. Die ASP.NET-/ASP.NET Core-Vorlage generiert Webanwendungen für den Azure AD v1.0-Endpunkt. Es müssen Konfigurationsänderungen vorgenommen werden, um diese an Microsoft Identity Platform anzupassen.

In ASP.NET Core-Web-Apps (und Web-APIs) ist die Anwendung geschützt, da es das Attribut Authorize für die Controller bzw. Controlleraktionen gibt. Mit diesem Attribut wird geprüft, ob der Benutzer authentifiziert ist. Vor der Einführung von .NET 6 befand sich die Codeinitialisierung in der Datei Startup.cs. Neue ASP.NET Core-Projekte mit .NET 6 enthalten keine Startup.cs-Datei mehr. An ihre Stelle tritt die Datei Program.cs. Der Rest dieses Tutorials bezieht sich auf .NET 5 oder niedriger.

Hinweis

Wenn Sie direkt mit den neuen ASP.NET Core-Vorlagen für Microsoft Identity Platform, die Microsoft.Identity.Web nutzen, beginnen möchten, können Sie ein NuGet-Vorschaupaket mit Projektvorlagen für .NET 5.0 herunterladen. Nach der Installation können Sie dann direkt ASP.NET Core-Webanwendungen (MVC oder Blazor) instanziieren. Weitere Informationen finden Sie unter Microsoft.Identity.Web – Web-App-Projektvorlage. Dies ist der einfachste Ansatz, da er alle folgenden Schritte für Sie ausführt.

Wenn Sie Ihr Projekt lieber mit dem aktuellen ASP.NET Core-Standardwebprojekt in Visual Studio oder mithilfe von dotnet new mvc --auth SingleOrg oder dotnet new webapp --auth SingleOrg starten möchten, wird Code ähnlich dem folgenden angezeigt:

 services.AddAuthentication(AzureADDefaults.AuthenticationScheme)
         .AddAzureAD(options => Configuration.Bind("AzureAd", options));

In diesem Code wird das ältere NuGet-Paket Microsoft.AspNetCore.Authentication.AzureAD.UI verwendet, das zum Erstellen einer Azure Active Directory v1.0-Anwendung verwendet wird. In diesem Artikel wird erläutert, wie Sie eine Microsoft Identity Platform v2.0-Anwendung erstellen, die diesen Code ersetzt.

  1. Fügen Sie dem Projekt die NuGet-Pakete Microsoft.Identity.Web und Microsoft.Identity.Web.UI hinzu. Entfernen Sie das NuGet-Paket Microsoft.AspNetCore.Authentication.AzureAD.UI, wenn es vorhanden ist.

  2. Aktualisieren Sie den Code in ConfigureServices, sodass er die Methoden AddMicrosoftIdentityWebApp und AddMicrosoftIdentityUI verwendet.

    public class Startup
    {
     ...
     // This method gets called by the runtime. Use this method to add services to the container.
     public void ConfigureServices(IServiceCollection services)
     {
      services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
             .AddMicrosoftIdentityWebApp(Configuration, "AzureAd");
    
      services.AddRazorPages().AddMvcOptions(options =>
      {
       var policy = new AuthorizationPolicyBuilder()
                     .RequireAuthenticatedUser()
                     .Build();
       options.Filters.Add(new AuthorizeFilter(policy));
      }).AddMicrosoftIdentityUI();
    
  3. Aktivieren Sie in der Configure-Methode in der Datei Startup.cs die Authentifizierung mit einem Aufruf von app.UseAuthentication(); und app.MapControllers();.

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
     // more code here
     app.UseAuthentication();
     app.UseAuthorization();
    
     app.MapRazorPages();
     app.MapControllers();
     // more code here
    }
    

Informationen zu diesem Code:

  • Die Erweiterungsmethode AddMicrosoftIdentityWebApp ist definiert in Microsoft.Identity.Web für folgende Aufgaben:

    • Konfigurieren von Optionen zum Lesen der Konfigurationsdatei (hier aus dem Abschnitt „Microsoft Entra ID“)
    • Konfigurieren der OpenID Connect-Optionen, damit Microsoft Identity Platform die verwendete Autorität ist
    • Validieren des Ausstellers des Tokens
    • Sicherstellen der Zuordnung der dem Namen entsprechenden Ansprüche aus dem Anspruch preferred_username im ID-Token
  • Neben dem Konfigurationsobjekt können Sie beim Aufruf von AddMicrosoftIdentityWebApp auch den Namen des Konfigurationsabschnitts angeben. Dieser lautet standardmäßig AzureAd.

  • AddMicrosoftIdentityWebApp weist andere Parameter für erweiterte Szenarien auf. Das Verfolgen von Ereignissen der OpenID Connect-Middleware beispielsweise kann bei der Behebung von Fehlern bei Ihrer Webanwendung helfen, wenn die Authentifizierung nicht funktioniert. Wenn Sie den optionalen Parameter subscribeToOpenIdConnectMiddlewareDiagnosticsEvents auf true festlegen, können Sie sehen, wie Informationen beim Fortschritt von der HTTP-Antwort zur Identität des Benutzers in HttpContext.User von der ASP.NET Core-Middleware verarbeitet werden.

  • Die AddMicrosoftIdentityUI-Erweiterungsmethode ist im Paket Microsoft.Identity.Web.UI definiert. Sie stellt einen Standardcontroller zum Behandeln der An- und Abmeldung bereit.

Weitere Informationen darüber, wie Sie mit Microsoft.Identity.Web Web-Anwendungen erstellen können, finden Sie unter Web Apps in Microsoft.Identity.Web.

Nächste Schritte

Im nächsten Artikel erfahren Sie, wie An- und Abmeldung ausgelöst werden.

Fahren Sie mit dem nächsten Artikel in diesem Szenario fort: Anmelden und Abmelden.