Verwenden Sie geheime Clientschlüssel mit Microsoft. Identity.Web

Ein geheimer Clientschlüssel ist ein Zeichenfolgenwert, den Ihre Anwendung verwendet, um ihre Identität beim Anfordern von Token aus dem Microsoft Identity Platform nachzuweisen. Microsoft. Identity.Web unterstützt geheime Clientschlüssel als einen von mehreren Anmeldeinformationstypen für vertrauliche Clientanwendungen.

Wählen Sie einen Anmeldedatentyp

Vertrauliche Clientanwendungen benötigen eine Anmeldeinformationen, um sich mit dem Microsoft Identity Platform zu authentifizieren. Microsoft. Identity.Web unterstützt die folgenden Anmeldeinformationstypen über den Konfigurationsabschnitt ClientCredentials:

Geheime Clientschlüssel sind einfache Zeichenfolgen, die bei Ihrer App in Microsoft Entra ID registriert sind. Obwohl sie der einfachste Berechtigungstyp sind, der eingerichtet werden kann, haben sie auch erhebliche Sicherheitsbeschränkungen:

• Sie können versehentlich in Quellcode-, Protokoll- oder Konfigurationsdateien verfügbar gemacht werden.
• Sie haben ein Ablaufdatum und müssen manuell gedreht werden.
• Sie stellen keinen kryptografischen Nachweis der Identität des Anrufers bereit, der über den Besitz des Geheimen hinausgeht.

Konfigurieren eines geheimen Clientschlüssels in appsettings.json

Um ein Clientgeheimnis zu konfigurieren, fügen Sie ein ClientCredentials Array zum AzureAd Abschnitt Ihrer appsettings.json Datei hinzu.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "YOUR_SECRET_VALUE"
      }
    ]
  }
}

Das ClientCredentials Array unterstützt mehrere Einträge. Microsoft.Identity.Web versucht die Anmeldeinformationen in der Reihenfolge durch, bis eine erfolgreich ist, was für Szenarien der Geheimnisrotation nützlich ist.

Geheime Schlüssel für die Entwicklung speichern

In diesem Abschnitt wird beschrieben, wie geheime Werte während der lokalen Entwicklung aus dem Quellcode entfernt werden.

.NET Benutzergeheimnisse

Der empfohlene Ansatz zum Speichern geheimer Schlüssel während der lokalen Entwicklung ist das Tool "Geheimer Manager". Benutzergeheimnisse speichern vertrauliche Daten außerhalb Der Projektstruktur, wodurch versehentliche Commits zur Quellcodeverwaltung verhindert werden.

1. Initialisieren Von Benutzergeheimnissen für Ihr Projekt:

   dotnet user-secrets init
   

2. Legen Sie den geheimen Clientschlüsselwert fest:

   dotnet user-secrets set "AzureAd:ClientCredentials:0:ClientSecret" "your-secret-value"
   

3. Überprüfen Sie, ob der geheime Schlüssel gespeichert wurde:

   dotnet user-secrets list
   

Benutzergeheimnisse werden automatisch in die Development Umgebung geladen, wenn Sie verwenden WebApplication.CreateBuilder() oder Host.CreateDefaultBuilder().

Die appsettings.json-Struktur sollte den Aufbau ohne den tatsächlichen geheimen Wert enthalten.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret"
      }
    ]
  }
}

Umgebungsvariablen

Sie können auch Umgebungsvariablen verwenden, um den geheimen Clientschlüssel bereitzustellen. .NET Konfiguration ordnet Umgebungsvariablen, die das Trennzeichen __ (Doppelter Unterstrich) der Konfigurationshierarchie verwenden, automatisch zu. Legen Sie die Variable für die Shell fest:

$env:AzureAd__ClientCredentials__0__ClientSecret = "your-secret-value"

export AzureAd__ClientCredentials__0__ClientSecret="your-secret-value"

Umgebungsvariablen haben Vorrang vor Werten in appsettings.json, sodass der geheime Wert in Ihrer Konfigurationsdatei leer oder weggelassen werden kann.

Geheimnisse für höhere Umgebungen speichern

Verwenden Sie für staging, QA oder eine beliebige freigegebene Umgebung Azure Key Vault als Konfigurationsquelle. Bei diesem Ansatz werden Geheimnisse aus Konfigurationsdateien und Umgebungsvariablen herausgehalten, während Prüfprotokollierung, Zugriffsrichtlinien und Funktionen zur automatischen Rotation bereitgestellt werden.

Hinzufügen von Azure Key Vault als Konfigurationsquelle

1. Installieren Sie das erforderliche NuGet-Paket:

   dotnet add package Azure.Extensions.AspNetCore.Configuration.Secrets
   

2. Speichern Sie den geheimen Clientschlüssel in Azure Key Vault mit einem Namen, der dem Konfigurationspfad zugeordnet ist. Verwenden Sie -- (doppelt gestrichelt) als Trennzeichen:

   az keyvault secret set \
     --vault-name "your-keyvault-name" \
     --name "AzureAd--ClientCredentials--0--ClientSecret" \
     --value "your-secret-value"
   

3. Fügen Sie Key Vault als Konfigurationsquelle in Program.cs hinzu. Der folgende Code registriert Key Vault, sodass die geheimen Schlüssel über die Standardkonfigurations-API verfügbar sind:

   var builder = WebApplication.CreateBuilder(args);
   
   builder.Configuration.AddAzureKeyVault(
       new Uri("https://your-keyvault-name.vault.azure.net/"),
       new DefaultAzureCredential());
   

Der Key Vault geheime Name AzureAd--ClientCredentials--0--ClientSecret wird automatisch dem Konfigurationspfad AzureAd:ClientCredentials:0:ClientSecret zugeordnet.

Erstellen eines geheimen Clientschlüssels im Azure Portal

Führen Sie die folgenden Schritte aus, um einen geheimen Clientschlüssel für Ihre Anwendung in Microsoft Entra ID zu registrieren:

1. Melden Sie sich beim Microsoft Entra Admin Center an.
2. Navigieren Sie zu Identity>Applications>App-Registrierungen.
3. Wählen Sie Ihre Anwendung in der Liste aus.
4. Wählen Sie im linken Menü "Zertifikate und Geheime Schlüssel" aus.
5. Wählen Sie die Registerkarte "Geheime Clientschlüssel " aus.
6. Wählen Sie Neuer Clientschlüssel.
7. Fügen Sie im Bereich "Geheimen Clientschlüssel hinzufügen" folgendes hinzu:
   • Geben Sie eine Beschreibung für den geheimen Schlüssel ein (z. B. "Entwicklungsgeheimnis").
   • Wählen Sie eine Ablaufdauer aus. Verfügbare Optionen umfassen 180 Tage, 365 Tage, 730 Tage oder ein benutzerdefiniertes Datum.
   • Klicken Sie auf Hinzufügen.
8. Kopieren Sie den geheimen Wert sofort. Der Wert wird nur einmal angezeigt und kann nicht abgerufen werden, nachdem Sie von der Seite weg navigieren.

Verwalten des geheimen Ablaufs und der Drehung des geheimen Schlüssels

Geheime Clientschlüssel haben eine maximale Lebensdauer und laufen am datum ab, das während der Erstellung angegeben wurde. Planen Sie den geheimen Wechsel, um Ausfallzeiten zu vermeiden.

Ablauf überwachen

• Überprüfen Sie die Spalte "Ablaufdatum" auf der Seite " Zertifikate und Geheime Schlüssel " Ihrer App-Registrierung.
• Richten Sie Microsoft Entra Empfehlungen ein, um Benachrichtigungen zu erhalten, bevor Anmeldeinformationen ablaufen.

Rotationsstrategie

Verwenden Sie das ClientCredentials Array, um die Drehung ohne Ausfallzeiten zu unterstützen:

1. Erstellen Sie einen neuen geheimen Clientschlüssel im Azure-Portal.

2. Fügen Sie den neuen geheimen Schlüssel als zusätzlichen Eintrag im ClientCredentials Array hinzu. Platzieren Sie zuerst das neue Geheimnis, damit es vor dem alten versucht wird:

   {
     "AzureAd": {
       "ClientCredentials": [
         {
           "SourceType": "ClientSecret",
           "ClientSecret": "[NEW_SECRET_REFERENCE]"
         },
         {
           "SourceType": "ClientSecret",
           "ClientSecret": "[OLD_SECRET_REFERENCE]"
         }
       ]
     }
   }
   

3. Stellen Sie die aktualisierte Konfiguration bereit. Microsoft. Identity.Web versucht die ersten Anmeldeinformationen und greift auf die zweite zurück, wenn der erste Fehler auftritt.

4. Entfernen Sie nach der Bestätigung des neuen geheimen Schlüssels den alten geheimen Schlüssel sowohl aus der Konfiguration als auch aus dem Azure Portal.

Migrieren zu Produktionsanmeldedaten

Migrieren Sie vor der Produktionsbereitstellung von Client Secrets zu einem sichereren Anmeldedatentyp.

Zertifikatbasierte Authentifizierung

Zertifikate stellen einen kryptografischen Identitätsnachweis bereit und sind der empfohlene Authentifizierungsinformationstyp für die Produktionsumgebung. Die folgende Konfiguration ruft ein Zertifikat aus Key Vault ab:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault-name.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      }
    ]
  }
}

Ausführliche Schritte finden Sie unter Use certificates with Microsoft. Identity.Web.

Verwaltete Identität (zertifikatlos)

Bei Anwendungen, die in Azure gehostet werden, vermeiden verwaltete Identitäten die vollständige Verwaltung von Anmeldeinformationen. Die folgende Konfiguration verwendet eine vom Benutzer zugewiesene verwaltete Identität:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "YOUR_MANAGED_IDENTITY_CLIENT_ID"
      }
    ]
  }
}

Ausführliche Schritte finden Sie unter Certificateless-Authentifizierung mit Microsoft. Identity.Web.

Migrationscheckliste

• [ ] Generieren oder Bereitstellen der neuen Anmeldeinformationen (Zertifikat oder verwaltete Identität).
• [ ] Aktualisieren Sie Ihre Anwendungskonfiguration, um den neuen Anmeldeinformationstyp zu verwenden.
• [ ] Testen Sie die neuen Anmeldeinformationen in einer Stagingumgebung.
• [ ] Deployen in die Produktion.
• [ ] Entfernen Sie den alten geheimen Clientschlüssel aus dem Azure Portal.
• [ ] Überprüfen Sie, ob die Anwendung ohne den alten geheimen Schlüssel ordnungsgemäß funktioniert.

Vermeiden häufiger Sicherheitsfehler

Überprüfen Sie die folgenden Antimuster und ihre empfohlenen Alternativen beim Arbeiten mit Client-Geheimnissen.

Häufige Fehler beheben

In diesem Abschnitt werden häufige Fehler behandelt, die beim Konfigurieren von geheimen Clientschlüsseln auftreten können.

Ungültiger geheimer Clientschlüssel

Fehler: AADSTS7000215: Invalid client secret provided.

Mögliche Ursachen:

• Der geheime Wert wurde falsch kopiert. Geheime Werte können Sonderzeichen enthalten, die während Kopier-/Einfügevorgängen abgeschnitten werden.
• Der Geheimnis wurde für eine andere App-Registrierung erstellt als diejenige, die in ClientId konfiguriert ist.
• Der Konfigurationspfad ist falsch, und der geheime Wert wird von der Anwendung nicht gelesen.

Lösung:

1. Erstellen Sie einen neuen geheimen Clientschlüssel im Azure Portal, und kopieren Sie sorgfältig den vollständigen Wert.

2. Überprüfen Sie, ob ClientId und TenantId in Ihrer Konfiguration mit der App-Registrierung übereinstimmen, in der der geheime Schlüssel erstellt wurde.

3. Fügen Sie einen Haltepunkt oder eine Protokollanweisung hinzu, um zu überprüfen, ob die Konfiguration korrekt geladen wurde.

   // For debugging only — remove before committing
   var config = builder.Configuration.GetSection("AzureAd:ClientCredentials:0:ClientSecret").Value;
   Console.WriteLine($"Secret loaded: {!string.IsNullOrEmpty(config)}");
   

Abgelaufener geheimer Clientschlüssel

Fehler: AADSTS7000222: The provided client secret keys for app '{app-id}' are expired.

Lösung:

1. Navigieren Sie zur App-Registrierung im Microsoft Entra Admin Center.
2. Überprüfen Sie das Ablaufdatum unter Zertifikaten und geheimen Clientschlüsseln>.
3. Erstellen Sie einen neuen geheimen Schlüssel, und aktualisieren Sie ihre Anwendungskonfiguration.
4. Löschen Sie das abgelaufene Geheimnis aus dem Portal.

Geheimer Schlüssel wurde in der Konfiguration nicht gefunden

Symptom: Die Anwendung wirft einen Fehler NullReferenceException oder die Authentifizierung schlägt fehl, weil der geheime Wert null ist.

Mögliche Ursachen:

• Geheime Benutzerschlüssel werden für das Projekt nicht initialisiert.
• Der Name der Umgebungsvariable stimmt nicht mit dem erwarteten Konfigurationspfad überein.
• Key Vault ist nicht als Konfigurationsquelle konfiguriert.
• Die Anwendung wird in einer Nicht-Entwicklungsumgebung ausgeführt, in der Benutzergeheimnisse nicht geladen werden.

Lösung:

1. Überprüfen Sie, ob die Benutzergeheimnisse initialisiert sind, indem Sie nach einem UserSecretsId in Ihrer .csproj Datei suchen.
2. Überprüfen Sie, ob das Geheimnis festgelegt ist, indem Sie dotnet user-secrets list ausführen.
3. Überprüfen Sie, ob der Konfigurationspfad exakt übereinstimmt: AzureAd:ClientCredentials:0:ClientSecret.
4. Falls Sie außerhalb der Entwicklungsumgebung arbeiten, stellen Sie sicher, dass die entsprechende Konfigurationsquelle (Umgebungsvariable oder Key Vault) verfügbar ist.

Verwandte Inhalte

• Certificates mit Microsoft.Identity.Web
• Zertifikatlose Authentifizierung
• Übersicht über den Tokencache
• Sichere Speicherung von geheimen App-Daten bei der Entwicklung in ASP.NET Core
• Azure Key Vault-Konfigurationsanbieter in ASP.NET Core