Web-App für Benutzeranmeldungen: Codekonfiguration

Artikel
08/06/2024

Dieser Artikel beschreibt, wie Sie Code für eine Web-App konfigurieren, die Benutzende anmeldet.

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 Vorschau¹
.NET	MSAL.NET	Microsoft.Identity.Client	—			Allgemein verfügbar
.NET	Microsoft.IdentityModel	Microsoft.IdentityModel	—	²	²	Allgemein verfügbar
ASP.NET Core	ASP.NET Core	Microsoft.AspNetCore.Authentication	Schnellstart			Allgemein verfügbar
ASP.NET Core	Microsoft.Identity.Web	Microsoft.Identity.Web	Schnellstart			Allgemein verfügbar
Java	MSAL4J	msal4j	Schnellstart			Allgemein verfügbar
Spring	spring-cloud-azure-starter-active-directory	spring-cloud-azure-starter-active-directory	Tutorial			Allgemein verfügbar
Node.js	MSAL Node	msal-node	Schnellstart			Allgemein verfügbar
Python	MSAL Python	msal				Allgemein verfügbar
Python	Identität	Identität	Schnellstart			--

⁽¹⁾ Universelle Lizenzbedingungen für Onlinedienste gelten für Bibliotheken in der öffentlichen Vorschauversion.

⁽²⁾ 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.

In ASP.NET wird die Anwendung über die Zeilen 12 bis 15 der Datei appsettings.json konfiguriert.

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

Im Azure-Portal müssen die Antwort-URIs, die Sie auf der Seite Authentifizierung für Ihre Anwendung registrieren, mit diesen URLs übereinstimmen. Das heißt, sie sollten https://localhost:44326/ sein.

In Java befindet sich die Konfiguration in der Datei application.properties unter src/main/resources.

aad.clientId=Enter_the_Application_Id_here
aad.authority=https://login.microsoftonline.com/Enter_the_Tenant_Info_Here/
aad.secretKey=Enter_the_Client_Secret_Here
aad.redirectUriSignin=http://localhost:8080/msal4jsample/secure/aad
aad.redirectUriGraph=http://localhost:8080/msal4jsample/graph/me

Im Azure-Portal müssen die Antwort-URIs, die Sie auf der Seite Authentifizierung für Ihre Anwendung registrieren, mit den redirectUri-Instanzen übereinstimmen, die von der Anwendung definiert werden. Das heißt, sie sollten http://localhost:8080/msal4jsample/secure/aad und http://localhost:8080/msal4jsample/graph/me sein.

Hier befinden sich die Konfigurationsparameter in .env.dev als Umgebungsvariablen:

CLOUD_INSTANCE="Enter_the_Cloud_Instance_Id_Here" # cloud instance string should end with a trailing slash
TENANT_ID="Enter_the_Tenant_Info_Here"
CLIENT_ID="Enter_the_Application_Id_Here"
CLIENT_SECRET="Enter_the_Client_Secret_Here"

REDIRECT_URI="http://localhost:3000/auth/redirect"
POST_LOGOUT_REDIRECT_URI="http://localhost:3000"

GRAPH_API_ENDPOINT="Enter_the_Graph_Endpoint_Here" # graph api endpoint string should end with a trailing slash

EXPRESS_SESSION_SECRET="Enter_the_Express_Session_Secret_Here"

Diese Parameter werden verwendet, um ein Konfigurationsobjekt in der Datei authConfig.js zu erstellen, das schließlich zum Initialisieren von MSAL Node verwendet wird:

/*
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */

require('dotenv').config({ path: '.env.dev' });

/**
 * Configuration object to be passed to MSAL instance on creation.
 * For a full list of MSAL Node configuration parameters, visit:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/configuration.md
 */
const msalConfig = {
    auth: {
        clientId: process.env.CLIENT_ID, // 'Application (client) ID' of app registration in Azure portal - this value is a GUID
        authority: process.env.CLOUD_INSTANCE + process.env.TENANT_ID, // Full directory URL, in the form of https://login.microsoftonline.com/<tenant>
        clientSecret: process.env.CLIENT_SECRET // Client secret generated from the app registration in Azure portal
    },
    system: {
        loggerOptions: {
            loggerCallback(loglevel, message, containsPii) {
                console.log(message);
            },
            piiLoggingEnabled: false,
            logLevel: 3,
        }
    }
}

const REDIRECT_URI = process.env.REDIRECT_URI;
const POST_LOGOUT_REDIRECT_URI = process.env.POST_LOGOUT_REDIRECT_URI;
const GRAPH_ME_ENDPOINT = process.env.GRAPH_API_ENDPOINT + "v1.0/me";

module.exports = {
    msalConfig,
    REDIRECT_URI,
    POST_LOGOUT_REDIRECT_URI,
    GRAPH_ME_ENDPOINT
};

Im Azure-Portal müssen die Antwort-URIs, die Sie auf der Seite „Authentifizierung“ für Ihre Anwendung registrieren, mit den redirectUri-Instanzen übereinstimmen, die von der Anwendung definiert werden (http://localhost:3000/auth/redirect).

Der Einfachheit halber wird in diesem Artikel der geheime Clientschlüssel in der Konfigurationsdatei gespeichert. Erwägen Sie in der Produktions-App die Verwendung eines Schlüsseltresors oder einer Umgebungsvariablen. Die Verwendung eines Zertifikats ist eine noch bessere Möglichkeit.

Die Konfigurationsparameter werden in der .env-Datei als Umgebungsvariablen festgelegt:

# Note: If you are using Azure App Service, go to your app's Configuration,
# and then set the following values into your app's "Application settings".

CLIENT_ID=<client id>
CLIENT_SECRET=<client secret>

# Expects a full authority URL such as "https://login.microsoftonline.com/TENANT_GUID"
# or "https://login.microsoftonline.com/contoso.onmicrosoft.com".
# Alternatively, leave it undefined if you are building a multi-tenant app in world-wide cloud
#AUTHORITY=<authority url>

Auf diese Umgebungsvariablen wird in app_config.py verwiesen:

import os

# Application (client) ID of app registration
CLIENT_ID = os.getenv("CLIENT_ID")
# Application's generated client secret: never check this into source control!
CLIENT_SECRET = os.getenv("CLIENT_SECRET")

# You can configure your authority via environment variable
# Defaults to a multi-tenant app in world-wide cloud
AUTHORITY = os.getenv("AUTHORITY", "https://login.microsoftonline.com/common")

REDIRECT_PATH = "/getAToken"  # Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set
# in the app's registration in the Azure portal.

# You can find more Microsoft Graph API endpoints from Graph Explorer
# https://developer.microsoft.com/en-us/graph/graph-explorer
ENDPOINT = 'https://graph.microsoft.com/v1.0/users'  # This resource requires no admin consent

# You can find the proper permission names from this document
# https://docs.microsoft.com/en-us/graph/permissions-reference
SCOPE = ["User.ReadBasic.All"]

# Tells the Flask-session extension to store sessions in the filesystem
SESSION_TYPE = "filesystem"
# Using the file system will not work in most production systems,
# it's better to use a database-backed session store instead.

Die .env-Datei sollte nie in die Quellcodeverwaltung eingecheckt werden, da sie Geheimnisse enthält. Das Schnellstartbeispiel enthält eine .gitignore-Datei, die das Einchecken der .env-Datei verhindert.

# Environments
.env

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.

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.

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

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.

Der Code für die Authentifizierung in ASP.NET-Web-Apps und -Web-APIs befindet sich in der Datei App_Start/Startup.Auth.cs.

 public void ConfigureAuth(IAppBuilder app)
 {
  app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

  app.UseCookieAuthentication(new CookieAuthenticationOptions());

  OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();
  factory.Build();
  app.AddMicrosoftIdentityWebApi(factory);
 }

Das Java-Beispiel verwendet das Spring-Framework. Die Anwendung ist geschützt, da Sie einen Filter implementieren, der jede HTTP-Antwort abfängt. Im Schnellstart für Java-Web-Apps handelt es sich dabei um den Filter AuthFilter in src/main/java/com/microsoft/azure/msalwebsample/AuthFilter.java.

Der Filter verarbeitet den OAuth 2.0-Autorisierungscodeflow und überprüft, ob der Benutzer authentifiziert ist (isAuthenticated()-Methode). Wenn der Benutzer nicht authentifiziert ist, wird die URL der Microsoft Entra-Autorisierungsendpunkte berechnet und der Browser zu diesem URI umgeleitet.

Wenn die Antwort mit dem Autorisierungscode eingeht, wird mit MSAL für Java das Token abgerufen. Wenn das Token schließlich vom Tokenendpunkt (im Umleitungs-URI) empfangen wird, erfolgt die Benutzeranmeldung.

Weitere Informationen finden Sie unter der doFilter()-Methode in AuthFilter.java.

Hinweis

Der Code von doFilter() wird in einer etwas anderen Reihenfolge geschrieben, aber der Flow entspricht dem beschriebenen.

Unter Microsoft Identity Platform und der OAuth 2.0-Autorisierungscodeflow finden Sie Einzelheiten zu dem durch diese Methode ausgelösten Autorisierungscodeflow.

Im Knotenbeispiel wird das Express-Framework verwendet. MSAL wird im auth-Routenhandler initialisiert:

var express = require('express');

const authProvider = require('../auth/AuthProvider');
const { REDIRECT_URI, POST_LOGOUT_REDIRECT_URI } = require('../authConfig');

const router = express.Router();

router.get('/signin', authProvider.login({
    scopes: [],
    redirectUri: REDIRECT_URI,
    successRedirect: '/'

Das Python-Beispiel wird mit dem Flask-Framework erstellt, obwohl auch andere Frameworks wie Django verwendet werden können. Die Flask-App wird mit der App-Konfiguration am Anfang in app.py initialisiert:

import identity
import identity.web
import requests
from flask import Flask, redirect, render_template, request, session, url_for
from flask_session import Session

import app_config

app = Flask(__name__)
app.config.from_object(app_config)
Session(app)

Anschließend erstellt der Code mithilfe des Identitätspakets ein auth-Objekt.

auth = identity.web.Auth(
    session=session,
    authority=app.config["AUTHORITY"],
    client_id=app.config["CLIENT_ID"],
    client_credential=app.config["CLIENT_SECRET"],
)

Nächster Schritt

An- und Abmelden

Freigeben über

Web-App für Benutzeranmeldungen: Codekonfiguration

Microsoft-Bibliotheken, die Web-Apps unterstützen

Konfigurationsdateien

Initialisierungscode

Nächster Schritt

Feedback

Zusätzliche Ressourcen