Initialisieren von Clientanwendungen mit MSAL.NET

In diesem Artikel werden die Initialisierung öffentlicher Clients und vertraulicher Clientanwendungen mithilfe der Microsoft Authentication Library (MSAL) für .NET (MSAL.NET) beschrieben. Weitere Informationen zu den Clientanwendungstypen finden Sie unter Öffentliche Client- und vertrauliche Clientanwendungen.

Mit MSAL.NET 3.x wird empfohlen, eine Anwendung mithilfe der Anwendungs-Generatoren zu instanziieren: PublicClientApplicationBuilder und ConfidentialClientApplicationBuilder. Sie bieten einen leistungsfähigen Mechanismus zum Konfigurieren der Anwendung aus dem Code, einer Konfigurationsdatei oder sogar durch Mischen beider Ansätze.

Voraussetzungen

Bevor Sie eine Anwendung initialisieren, müssen Sie sie zuerst registrieren, damit Ihre App in die Microsoft Identity Platform integriert werden kann. Weitere Informationen finden Sie in der Schnellstartanleitung: Registrieren einer Anwendung mit dem Microsoft Identity Platform. Nach der Registrierung benötigen Sie die folgenden Informationen, die auf der App-Registrierungsseite im Microsoft Entra Admin Center zu finden sind.

Anwendungs-ID (Client-ID) – Dies ist eine Zeichenfolge, die eine GUID darstellt.
Verzeichnis-ID (Mandant): Bietet Identitäts- und Zugriffsverwaltungsfunktionen (Identity and Access Management, IAM) für Anwendungen und Ressourcen, die von der Organisation verwendet werden. Sie kann angeben, ob Sie eine Branchenanwendung ausschließlich für Ihre Organisation schreiben (auch als Einzelmandantenanwendung bezeichnet).
Die URL des Identitätsanbieters (die Instanz genannt) und die Anmeldegruppe für Ihre Anwendung. Diese beiden Parameter werden gemeinsam als Autorität bezeichnet.
Clientanmeldeinformationen – die Form eines geheimen Anwendungsschlüssels (clientschlüssele Zeichenfolge) oder eines Zertifikats (vom Typ X509Certificate2) annehmen können, wenn es sich um eine vertrauliche Client-App handelt.
Für Web-Apps und manchmal auch für öffentliche Client-Apps (insbesondere wenn Ihre App einen Broker verwenden muss) müssen Sie den Umleitungs-URI festlegen, an den der Identitätsanbieter Ihre Anwendung mit den Sicherheitstoken zurückleitet.

Initialisieren von Anwendungen

Es gibt viele verschiedene Möglichkeiten zum Instanziieren von Clientanwendungen.

Initialisieren einer öffentlichen Clientanwendung aus Code

Der folgende Code instanziiert eine öffentliche Clientanwendung, anmeldet Benutzer in der Microsoft Azure öffentlichen Cloud mit ihren Geschäfts-, Schul- oder persönlichen Microsoft-Konten.

IPublicClientApplication app = PublicClientApplicationBuilder.Create(clientId)
    .Build();

Initialisieren einer vertraulichen Clientanwendung aus Code

Auf dieselbe Weise instanziiert der folgende Code eine vertrauliche Anwendung (eine Web-App unter https://myapp.azurewebsites.net), indem Token von Benutzern in der öffentlichen Microsoft Azure-Cloud über deren Geschäfts-, Schul- oder Unikonto oder deren persönliches Microsoft-Konto verarbeitet werden. Die Anwendung wird mit dem Identitätsanbieter identifiziert, indem ein geheimer Clientschlüssel freigegeben wird:

string redirectUri = "https://myapp.azurewebsites.net";
IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithClientSecret(clientSecret)
    .WithRedirectUri(redirectUri )
    .Build();

In der Produktion werden zertifikate jedoch empfohlen, da sie sicherer sind als geheime Clientschlüssel. Sie können erstellt und in die Microsoft Entra Admin Center hochgeladen werden. Der Code würde dann wie folgt aussehen:

IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithCertificate(certificate)
    .WithRedirectUri(redirectUri )
    .Build();

Initialisieren einer öffentlichen Clientanwendung über Konfigurationsoptionen

Der folgende Code instanziiert eine öffentliche Clientanwendung aus einem Konfigurationsobjekt, das programmgesteuert ausgefüllt oder aus einer Konfigurationsdatei gelesen werden kann:

PublicClientApplicationOptions options = GetOptions(); // your own method
IPublicClientApplication app = PublicClientApplicationBuilder.CreateWithApplicationOptions(options)
    .Build();

Initialisieren einer vertraulichen Clientanwendung über Konfigurationsoptionen

Die gleiche Art von Muster gilt für vertrauliche Clientanwendungen. Sie können auch andere Parameter mithilfe von .WithXXX Modifizierern hinzufügen. In diesem Beispiel wird .WithCertificate verwendet.

ConfidentialClientApplicationOptions options = GetOptions(); // your own method
IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.CreateWithApplicationOptions(options)
    .WithCertificate(certificate)
    .Build();

Builder-Modifikatoren

In den Codeausschnitten mit Anwendungs-Buildern können viele .With-Methoden als Modifier verwendet werden (zum Beispiel .WithCertificate und .WithRedirectUri).

Modifizierer, die für öffentliche und vertrauliche Clientanwendungen üblich sind

Die Modifizierer, die Sie auf einem öffentlichen Client oder einem vertraulichen Clientanwendungs-Generator festlegen können, finden Sie in der AbstractApplicationBuilder<T> Klasse. Die verschiedenen Methoden finden Sie in der Azure SDK für .NET Dokumentation.

Modifizierer speziell für Xamarin.iOS-Anwendungen

Die Modifizierer, die Sie für einen öffentlichen Clientanwendungs-Generator auf Xamarin.iOS festlegen können, sind:

Modifikator	Description
`.WithIosKeychainSecurityGroup()`	nur Xamarin.iOS: Legt die Sicherheitsgruppe der iOS-Schlüsselkette (für die Cachepersistenz) fest.

Modifizierer, die für vertrauliche Clientanwendungen spezifisch sind

Die für einen vertraulichen Clientanwendungs-Generator spezifischen Modifizierer finden Sie in der ConfidentialClientApplicationBuilder Klasse. Die verschiedenen Methoden finden Sie in der Azure SDK für .NET Dokumentation.

Modifizierer wie .WithCertificate(X509Certificate2 certificate) und .WithClientSecret(string clientSecret) schließen sich gegenseitig aus. Wenn Sie beides angeben, löst MSAL eine aussagekräftige Ausnahme aus.

Beispiel für die Verwendung von Modifizierern

Angenommen, Ihre Anwendung ist eine Branchenanwendung, die nur für Ihre Organisation gilt. Anschließend können Sie Folgendes schreiben:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
        .Build();

Die Programmierung für nationale Clouds wurde vereinfacht. Wenn Ihre Anwendung also eine mehrinstanzenfähige Anwendung in einer nationalen Cloud sein soll, könnten Sie beispielsweise Folgendes schreiben:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAuthority(AzureCloudInstance.AzureUsGovernment, AadAuthorityAudience.AzureAdMultipleOrgs)
        .Build();

Es gibt auch eine Außerkraftsetzung für AD FS (MSAL.NET unterstützt nur AD FS 2019 oder höher):

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAdfsAuthority("https://consoso.com/adfs")
        .Build();

Wenn Sie ein Azure AD B2C-Entwickler sind, können Sie ihren Mandanten wie folgt angeben:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithB2CAuthority("https://fabrikamb2c.b2clogin.com/tfp/{tenant}/{PolicySignInSignUp}")
        .Build();

Siehe auch

API-Referenzdokumentation

Paket auf NuGet

Quellcode der Bibliothek

Codebeispiele

Nächste Schritte

Nachdem Sie die Clientanwendung initialisiert haben, besteht die nächste Aufgabe darin, Unterstützung für die Benutzeranmeldung, autorisierten API-Zugriff oder beides hinzuzufügen.

Unsere Anwendungsszenariodokumentation enthält Anleitungen zum Anmelden eines Benutzers und zum Abrufen eines Zugriffstokens für den Zugriff auf eine API im Namen dieses Benutzers:

Last updated on 2026-07-02