Integrieren Sie MSAL.NET in Microsoft. Identity.Web in .NET Framework

In diesem Handbuch erfahren Sie, wie Sie Microsoft.Identity.Web-Tokencache und Zertifikatpakete mit MSAL.NET in .NET Framework, .NET Standard 2.0 und klassischen .NET-Anwendungen (.NET 4.7.2+) verwenden.

Überblick verstehen

Beginnend mit Microsoft.Identity.Web 1.17+ können Sie Microsoft.Identity.Web-Hilfsprogrammpakete mit MSAL.NET in Umgebungen außerhalb von ASP.NET Core verwenden.

Identifizieren von Paketvorteilen

Überprüfen unterstützter Szenarien

Die folgenden Szenarien werden mit den zielbezogenen Hilfsprogrammpaketen unterstützt.

• .NET Framework-Konsolenanwendungen (Daemonszenarien)
• Desktop Applications (.NET Framework)
• Worker Services (.NET Framework)
• .NET Standard 2.0 Libraries (plattformübergreifende Kompatibilität)
• Nicht-Web MSAL.NET Anwendungen

Auswählen von Paketen

Wählen Sie das Paket aus, das Ihrem Szenario entspricht.

Identifizieren von Kernpaketen für MSAL.NET

Pakete installieren

Verwenden Sie eine der folgenden Methoden, um dem Projekt die Pakete hinzuzufügen.

Paket-Manager Console:

# Token cache serialization
Install-Package Microsoft.Identity.Web.TokenCache

# Certificate management
Install-Package Microsoft.Identity.Web.Certificate

.NET CLI:

dotnet add package Microsoft.Identity.Web.TokenCache
dotnet add package Microsoft.Identity.Web.Certificate

Grundlegende Paketbeschränkungen verstehen

Das Kernpaket Microsoft.Identity.Web umfasst ASP.NET Core Abhängigkeiten (Microsoft.AspNetCore.*), die:

• Nicht kompatibel mit ASP.NET Framework
• Unnötiges Erhöhen der Paketgröße
• Erzeugen Sie Abhängigkeitskonflikte

Verwenden Sie stattdessen gezielte Pakete für .NET Framework- und .NET Standard-Szenarien.

Konfigurieren der Serialisierung des Tokencaches

Grundlegendes zu Tokencacheadaptern

Microsoft. Identity.Web stellt Tokencacheadapter bereit, die nahtlos mit MSAL.NET IConfidentialClientApplication funktionieren.

Erstellen eines vertraulichen Clients mit Tokencache

Im folgenden Beispiel wird eine vertrauliche Clientanwendung erstellt und ein Speichertokencache angefügt.

using Microsoft.Identity.Client;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.TokenCacheProviders;

public class MsalAppBuilder
{
    private static IConfidentialClientApplication _app;

    public static IConfidentialClientApplication BuildConfidentialClientApplication()
    {
        if (_app == null)
        {
            string clientId = ConfigurationManager.AppSettings["AzureAd:ClientId"];
            string clientSecret = ConfigurationManager.AppSettings["AzureAd:ClientSecret"];
            string tenantId = ConfigurationManager.AppSettings["AzureAd:TenantId"];

            // Create the confidential client application
            _app = ConfidentialClientApplicationBuilder.Create(clientId)
                .WithClientSecret(clientSecret)
                .WithTenantId(tenantId)
                .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
                .Build();

            // Add token cache serialization (choose one option below)
            _app.AddInMemoryTokenCache();
        }

        return _app;
    }
}

Auswählen von Tokencacheoptionen

Wählen Sie den Cacheanbieter aus, der am besten zu Ihrem Bereitstellungsszenario passt.

Konfigurieren des In-Memory-Token-Caches

Im folgenden Beispiel wird ein einfacher Speichercache hinzugefügt:

using Microsoft.Identity.Web.TokenCacheProviders;

_app.AddInMemoryTokenCache();

In-Memory-Cache mit Größenbeschränkungen (Microsoft). Identity.Web 1.20+):

using Microsoft.Extensions.Caching.Memory;

_app.AddInMemoryTokenCache(services =>
{
    // Configure memory cache options
    services.Configure<MemoryCacheOptions>(options =>
    {
        options.SizeLimit = 5000000;  // 5 MB limit
    });
});

Merkmale:

• Schneller Zugriff
• Keine externen Abhängigkeiten
• Nicht über Prozesse hinweg freigegeben
• Beim Neustart der App verloren

Anwendungsfall: Einzelinstanz-Konsolen-Apps, Desktopanwendungen

Konfigurieren des verteilten Caches für Speichertoken

Verwenden Sie den folgenden Code, um einen verteilten Speichercache für Umgebungen mit mehreren Instanzen hinzuzufügen:

_app.AddDistributedTokenCaches(services =>
{
    // Requires: Microsoft.Extensions.Caching.Memory (NuGet)
    services.AddDistributedMemoryCache();
});

Merkmale:

• Für alle App-Instanzen freigegeben
• Besser für Szenarien mit Lastenausgleich
• Erfordert zusätzliches NuGet-Paket
• Beim Neustart der App noch verloren

Anwendungsfall: Dienstleistungen mit mehreren Instanzen mit akzeptabler Token-Wiedererlangung

Konfigurieren SQL Server Tokencache

Verwenden Sie den folgenden Code, um einen persistenten, verteilten SQL Server Cache hinzuzufügen:

using Microsoft.Extensions.Caching.SqlServer;

_app.AddDistributedTokenCaches(services =>
{
    // Requires: Microsoft.Extensions.Caching.SqlServer (NuGet)
    services.AddDistributedSqlServerCache(options =>
    {
        options.ConnectionString = ConfigurationManager.ConnectionStrings["TokenCache"].ConnectionString;
        options.SchemaName = "dbo";
        options.TableName = "TokenCache";

        // IMPORTANT: Set expiration above token lifetime
        // Access tokens typically expire after 1 hour
        options.DefaultSlidingExpiration = TimeSpan.FromMinutes(90);
    });
});

Führen Sie die folgende SQL-Datei aus, um die erforderliche Cachetabelle zu erstellen:

-- Create the cache table
CREATE TABLE [dbo].[TokenCache] (
    [Id] NVARCHAR(449) NOT NULL,
    [Value] VARBINARY(MAX) NOT NULL,
    [ExpiresAtTime] DATETIMEOFFSET NOT NULL,
    [SlidingExpirationInSeconds] BIGINT NULL,
    [AbsoluteExpiration] DATETIMEOFFSET NULL,
    PRIMARY KEY ([Id])
);

-- Create index for performance
CREATE INDEX [Index_ExpiresAtTime] ON [dbo].[TokenCache] ([ExpiresAtTime]);

Merkmale:

• Dauerhaft über Neustarts hinweg
• Gemeinsam von mehreren Instanzen genutzt
• Zuverlässig und skalierbar
• Erfordert Installation von SQL Server

Anwendungsfall: Produktionsdaemondienste, geplante Aufgaben, Mitarbeiter mit mehreren Instanzen

Konfigurieren des Redis-Tokencaches

Verwenden Sie den folgenden Code, um einen leistungsfähigen redis verteilten Cache hinzuzufügen:

using StackExchange.Redis;
using Microsoft.Extensions.Caching.StackExchangeRedis;

_app.AddDistributedTokenCaches(services =>
{
    // Requires: Microsoft.Extensions.Caching.StackExchangeRedis (NuGet)
    services.AddStackExchangeRedisCache(options =>
    {
        options.Configuration = ConfigurationManager.AppSettings["Redis:ConnectionString"];
        options.InstanceName = "TokenCache_";
    });
});

Das folgende Beispiel zeigt eine produktionsfähige Redis-Konfiguration:

services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = ConfigurationManager.AppSettings["Redis:ConnectionString"];
    options.InstanceName = "MyDaemonApp_";

    // Optional: Configure Redis options
    options.ConfigurationOptions = new ConfigurationOptions
    {
        AbortOnConnectFail = false,
        ConnectTimeout = 5000,
        SyncTimeout = 5000
    };
});

Merkmale:

• Extrem schnell
• Gemeinsame Nutzung über Instanzen hinweg
• Persistent (mit aktivierter Redis-Persistenz)
• Erfordert Redis-Server

Anwendungsfall: Daemon-Apps mit hohem Volumen, verteilte Systeme, Microservices

Konfigurieren des Cosmos DB-Tokencaches

Verwenden Sie den folgenden Code, um einen global verteilten Cosmos DB-Cache hinzuzufügen:

using Microsoft.Extensions.Caching.Cosmos;

_app.AddDistributedTokenCaches(services =>
{
    // Requires: Microsoft.Extensions.Caching.Cosmos (preview)
    services.AddCosmosCache(options =>
    {
        options.ContainerName = "TokenCache";
        options.DatabaseName = "IdentityCache";
        options.ClientBuilder = new CosmosClientBuilder(
            ConfigurationManager.AppSettings["CosmosConnectionString"]);
        options.CreateIfNotExists = true;
    });
});

Merkmale:

• Weltweit verteilt
• Hoch verfügbar
• Autoskalierung
• Höhere Latenz als Redis
• Höhere Kosten

Anwendungsfall: Globale Daemon-Dienste, geoverteilte Anwendungen

Konfigurieren des PostgreSQL-Tokencaches

Verwenden Sie den folgenden Code, um einen verteilten PostgreSQL-Cache hinzuzufügen:

_app.AddDistributedTokenCaches(services =>
{
    // Requires: Microsoft.Extensions.Caching.Postgres (NuGet)
    services.AddDistributedPostgresCache(options =>
    {
        options.ConnectionString = ConfigurationManager.ConnectionStrings["PostgresCache"].ConnectionString;
        options.SchemaName = ConfigurationManager.AppSettings["PostgresCache:SchemaName"];
        options.TableName = ConfigurationManager.AppSettings["PostgresCache:TableName"];
        options.CreateIfNotExists = bool.Parse(
            ConfigurationManager.AppSettings["PostgresCache:CreateIfNotExists"] ?? "true");

        // Set expiration above token lifetime.
        // Access tokens typically expire after 1 hour.
        options.DefaultSlidingExpiration = TimeSpan.FromMinutes(90);
    });
});

Merkmale:

• Dauerhaft über Neustarts hinweg
• Gemeinsam von mehreren Instanzen genutzt
• Vertraute SQL-Semantik
• Funktioniert mit Azure Database for PostgreSQL
• Erfordert einen PostgreSQL-Server

Anwendungsfall: Anwendungen verwenden bereits PostgreSQL als primäre Datenbank oder Azure gehostete Dienste mit Azure Database for PostgreSQL

Erstellen einer vollständigen Daemon-Anwendung

Das folgende Beispiel zeigt eine vollständige Daemonanwendung, die Token mithilfe von Clientanmeldeinformationen und einem SQL Server Tokencache erwirbt.

using Microsoft.Identity.Client;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.TokenCacheProviders;
using System;
using System.Threading.Tasks;

namespace DaemonApp
{
    class Program
    {
        private static IConfidentialClientApplication _app;

        static async Task Main(string[] args)
        {
            // Build confidential client with token cache
            _app = BuildConfidentialClient();

            // Acquire token for app-only access
            string[] scopes = new[] { "https://graph.microsoft.com/.default" };

            try
            {
                var result = await _app.AcquireTokenForClient(scopes)
                    .ExecuteAsync();

                Console.WriteLine($"Token acquired successfully!");
                Console.WriteLine($"Token source: {result.AuthenticationResultMetadata.TokenSource}");
                Console.WriteLine($"Expires on: {result.ExpiresOn}");

                // Use token to call API
                await CallProtectedApi(result.AccessToken);
            }
            catch (MsalServiceException ex)
            {
                Console.WriteLine($"Error acquiring token: {ex.ErrorCode}");
                Console.WriteLine($"CorrelationId: {ex.CorrelationId}");
            }
        }

        private static IConfidentialClientApplication BuildConfidentialClient()
        {
            var app = ConfidentialClientApplicationBuilder
                .Create(ConfigurationManager.AppSettings["ClientId"])
                .WithClientSecret(ConfigurationManager.AppSettings["ClientSecret"])
                .WithTenantId(ConfigurationManager.AppSettings["TenantId"])
                .Build();

            // Add SQL Server token cache for persistence
            app.AddDistributedTokenCaches(services =>
            {
                services.AddDistributedSqlServerCache(options =>
                {
                    options.ConnectionString = ConfigurationManager
                        .ConnectionStrings["TokenCache"].ConnectionString;
                    options.SchemaName = "dbo";
                    options.TableName = "TokenCache";
                    options.DefaultSlidingExpiration = TimeSpan.FromMinutes(90);
                });
            });

            return app;
        }

        private static async Task CallProtectedApi(string accessToken)
        {
            // Your API call logic
        }
    }
}

Verwalten von Zertifikaten

Grundlegendes zum Laden von Zertifikaten

Microsoft. Identity.Web vereinfacht das Laden von Zertifikaten aus verschiedenen Quellen für Clientanmeldeinformationsflüsse.

Laden von Zertifikaten mit DefaultCertificateLoader

Im folgenden Beispiel wird veranschaulicht, wie ein Zertifikat aus Azure Key Vault geladen und eine vertrauliche Clientanwendung erstellt wird.

using Microsoft.Identity.Web;
using Microsoft.Identity.Client;

public class CertificateHelper
{
    public static IConfidentialClientApplication CreateAppWithCertificate()
    {
        string clientId = ConfigurationManager.AppSettings["AzureAd:ClientId"];
        string tenantId = ConfigurationManager.AppSettings["AzureAd:TenantId"];

        // Define certificate source
        var certDescription = CertificateDescription.FromKeyVault(
            keyVaultUrl: "https://my-keyvault.vault.azure.net",
            keyVaultCertificateName: "MyCertificate"
        );

        // Load certificate
        ICertificateLoader certificateLoader = new DefaultCertificateLoader();
        certificateLoader.LoadIfNeeded(certDescription);

        // Create confidential client with certificate
        var app = ConfidentialClientApplicationBuilder.Create(clientId)
            .WithCertificate(certDescription.Certificate)
            .WithTenantId(tenantId)
            .Build();

        // Add token cache
        app.AddInMemoryTokenCache();

        return app;
    }
}

Zertifikatquellen auswählen

Laden von Azure Key Vault

Laden Sie ein in Azure Key Vault gespeichertes Zertifikat, indem Sie die Tresor-URL und den Zertifikatnamen angeben.

var certDescription = CertificateDescription.FromKeyVault(
    keyVaultUrl: "https://my-keyvault.vault.azure.net",
    keyVaultCertificateName: "MyApplicationCert"
);

ICertificateLoader loader = new DefaultCertificateLoader();
loader.LoadIfNeeded(certDescription);

var app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithCertificate(certDescription.Certificate)
    .WithTenantId(tenantId)
    .Build();

Voraussetzungen:

• Verwaltete Identität oder Dienstprinzipal mit Zugriff auf Key Vault
• Azure.Identity NuGet-Paket
• Berechtigungen für Key Vault: Get in Bezug auf Zertifikate

Laden aus dem Zertifikatspeicher

Laden Sie ein Zertifikat aus dem Windows-Zertifikatsspeicher per Distinguished Name.

var certDescription = CertificateDescription.FromStoreWithDistinguishedName(
    distinguishedName: "CN=MyApp.contoso.com",
    storeName: StoreName.My,
    storeLocation: StoreLocation.CurrentUser
);

ICertificateLoader loader = new DefaultCertificateLoader();
loader.LoadIfNeeded(certDescription);

var app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithCertificate(certDescription.Certificate)
    .WithTenantId(tenantId)
    .Build();

Sie können auch ein Zertifikat per Fingerabdruck finden:

var certDescription = CertificateDescription.FromStoreWithThumbprint(
    thumbprint: "ABCDEF1234567890ABCDEF1234567890ABCDEF12",
    storeName: StoreName.My,
    storeLocation: StoreLocation.LocalMachine
);

Laden aus dem Dateisystem

Laden Sie ein Zertifikat aus einer PFX-Datei im lokalen Dateisystem.

var certDescription = CertificateDescription.FromPath(
    path: @"C:\Certificates\MyAppCert.pfx",
    password: ConfigurationManager.AppSettings["Certificate:Password"]
);

ICertificateLoader loader = new DefaultCertificateLoader();
loader.LoadIfNeeded(certDescription);

var app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithCertificate(certDescription.Certificate)
    .WithTenantId(tenantId)
    .Build();

Sicherheitshinweis: Niemals hartcodieren Sie Kennwörter. Verwenden Sie die sichere Konfiguration.

Laden aus base64-codierter Zeichenfolge

Laden eines Zertifikats aus einer base64-codierten Zeichenfolge, die in der Konfiguration gespeichert ist.

string base64Cert = ConfigurationManager.AppSettings["Certificate:Base64"];

var certDescription = CertificateDescription.FromBase64Encoded(
    base64EncodedValue: base64Cert,
    password: ConfigurationManager.AppSettings["Certificate:Password"]  // Optional
);

ICertificateLoader loader = new DefaultCertificateLoader();
loader.LoadIfNeeded(certDescription);

Konfigurieren des Ladens von Zertifikaten aus App.config

Definieren Sie die Zertifikateinstellungen in Ihrer App.config Datei, und laden Sie sie zur Laufzeit.

App.config:

<appSettings>
  <add key="AzureAd:ClientId" value="your-client-id" />
  <add key="AzureAd:TenantId" value="your-tenant-id" />

  <!-- Option 1: KeyVault -->
  <add key="Certificate:SourceType" value="KeyVault" />
  <add key="Certificate:KeyVaultUrl" value="https://my-vault.vault.azure.net" />
  <add key="Certificate:KeyVaultCertificateName" value="MyCert" />

  <!-- Option 2: Store -->
  <!--
  <add key="Certificate:SourceType" value="StoreWithThumbprint" />
  <add key="Certificate:CertificateThumbprint" value="ABCD..." />
  <add key="Certificate:CertificateStorePath" value="CurrentUser/My" />
  -->
</appSettings>

<connectionStrings>
  <add name="TokenCache"
       connectionString="Data Source=(localdb)\MSSQLLocalDB;Initial Catalog=TokenCache;Integrated Security=True;" />
</connectionStrings>

Verwenden Sie die folgende Hilfsmethode, um das Zertifikat basierend auf der Konfiguration zu laden:

public static CertificateDescription GetCertificateFromConfig()
{
    string sourceType = ConfigurationManager.AppSettings["Certificate:SourceType"];

    return sourceType switch
    {
        "KeyVault" => CertificateDescription.FromKeyVault(
            ConfigurationManager.AppSettings["Certificate:KeyVaultUrl"],
            ConfigurationManager.AppSettings["Certificate:KeyVaultCertificateName"]
        ),

        "StoreWithThumbprint" => CertificateDescription.FromStoreWithThumbprint(
            ConfigurationManager.AppSettings["Certificate:CertificateThumbprint"],
            StoreName.My,
            StoreLocation.CurrentUser
        ),

        _ => throw new ConfigurationErrorsException("Invalid certificate source type")
    };
}

Erkunden von Beispielanwendungen

Überprüfen Sie diese Beispiele, um funktionierende Implementierungen zu sehen.

Überprüfen der offiziellen Microsoft Beispiele

In der folgenden Tabelle sind offizielle Beispiele aufgeführt, die das Zwischenspeichern von Token und das Laden von Zertifikaten veranschaulichen.

Bewährte Methoden befolgen

Wenden Sie diese Muster an, um zuverlässige und sichere Anwendungen zu erstellen.

Befolgen empfohlener Muster

1. Verwenden Sie das Singleton-Muster für IConfidentialClientApplication:

Erstellen Sie eine einzelne Instanz, und verwenden Sie sie in Ihrer Gesamten Anwendung wieder.

private static IConfidentialClientApplication _app;

public static IConfidentialClientApplication GetApp()
{
    if (_app == null)
    {
        _app = ConfidentialClientApplicationBuilder.Create(clientId)
            .WithClientSecret(clientSecret)
            .WithTenantId(tenantId)
            .Build();

        _app.AddDistributedTokenCaches(/* ... */);
    }

    return _app;
}

2. Festlegung des Ablaufdatums des Tokencaches:

Konfigurieren Sie das gleitende Ablaufdatum über die Lebensdauer des Tokens hinaus, um unnötiges erneutes Erwerben zu verhindern.

// Access tokens typically expire after 1 hour
// Set cache expiration ABOVE token lifetime
options.DefaultSlidingExpiration = TimeSpan.FromMinutes(90);

3. Sichere Zertifikatspeicherung verwenden:

Speichern Sie Zertifikate in Azure Key Vault oder einem ordnungsgemäß gesicherten Zertifikatspeicher.

// Azure Key Vault (production)
var cert = CertificateDescription.FromKeyVault(keyVaultUrl, certName);

// Certificate store with proper permissions
var cert = CertificateDescription.FromStoreWithThumbprint(
    thumbprint, StoreName.My, StoreLocation.LocalMachine);

4. Implementieren Sie die richtige Fehlerbehandlung:

Erfassen Sie MSAL-Ausnahmen, und protokollieren Sie die Korrelations-ID für die Problembehandlung.

try
{
    var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();
}
catch (MsalServiceException ex)
{
    logger.Error($"Token acquisition failed. CorrelationId: {ex.CorrelationId}, ErrorCode: {ex.ErrorCode}");
    throw;
}

5. Verwenden Sie einen verteilten Cache für die Produktion:

Ein verteilter Cache teilt Tokens über Instanzen hinweg und bleibt über Neustarts hinweg bestehen.

// Correct for daemon services
app.AddDistributedTokenCaches(services =>
{
    services.AddDistributedSqlServerCache(/* ... */);
});

Vermeiden häufiger Fehler

1. Erstellen Sie keine neuen IConfidentialClientApplication-Instanzen wiederholt:

// Wrong - creates new instance every time
public void AcquireToken()
{
    var app = ConfidentialClientApplicationBuilder.Create(clientId).Build();
    // ...
}

// Correct - use singleton
private static readonly IConfidentialClientApplication _app = BuildApp();

2. Keine geheimen Schlüssel hartcodieren:

// Wrong
.WithClientSecret("supersecretvalue123")

// Correct
.WithClientSecret(ConfigurationManager.AppSettings["AzureAd:ClientSecret"])

3. Verwenden Sie keinen Speichercache für Dienste mit mehreren Instanzen:

// Wrong for services with multiple instances
app.AddInMemoryTokenCache();

// Correct - use distributed cache
app.AddDistributedTokenCaches(services =>
{
    services.AddDistributedSqlServerCache(/* ... */);
});

4. Ignorieren Sie die Zertifikatüberprüfung nicht:

// Wrong - skips validation
ServicePointManager.ServerCertificateValidationCallback = (sender, cert, chain, errors) => true;

// Correct - validate certificates properly

Migrieren von ADAL.NET

Überprüfen Sie die wichtigsten Unterschiede und aktualisieren Sie Ihren Code, um MSAL.NET mit Microsoft.Identity.Web zu verwenden.

Grundlegende Unterschiede verstehen

Vergleich von Migrationsbeispielen

ADAL.NET (Altversion):

AuthenticationContext authContext = new AuthenticationContext(authority);
ClientCredential credential = new ClientCredential(clientId, clientSecret);
AuthenticationResult result = await authContext.AcquireTokenAsync(resource, credential);

MSAL.NET mit Microsoft. Identity.Web (Neu):

var app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithClientSecret(clientSecret)
    .WithTenantId(tenantId)
    .Build();

app.AddInMemoryTokenCache();  // Add token cache

string[] scopes = new[] { "https://graph.microsoft.com/.default" };
AuthenticationResult result = await app.AcquireTokenForClient(scopes).ExecuteAsync();

Durchsuchen verwandter Inhalte

Verwenden Sie diese Ressourcen, um mehr über verwandte Szenarien zu erfahren.

• Daemon-Anwendungen
• OWIN-Integration
• übersicht über ASP.NET Framework
• Übersicht über Anmeldeinformationen