Gebruik clientgeheimen met Microsoft. Identity.Web

Een clientgeheim is een tekenreekswaarde die uw toepassing gebruikt om de identiteit te bewijzen bij het aanvragen van tokens van de Microsoft identity platform. Microsoft. Identity.Web ondersteunt clientgeheimen als een van de verschillende referentietypen voor vertrouwelijke clienttoepassingen.

Kies een referentietype

Vertrouwelijke clienttoepassingen hebben een referentie nodig om te verifiëren met de Microsoft identity platform. Microsoft. Identity.Web ondersteunt de volgende referentietypen via de ClientCredentials configuratiesectie:

Clientgeheimen zijn eenvoudige tekenreeksen die zijn geregistreerd bij uw app in Microsoft Entra ID. Hoewel ze het eenvoudigste referentietype zijn om in te stellen, hebben ze ook aanzienlijke beveiligingsbeperkingen:

• Ze kunnen per ongeluk worden weergegeven in broncode, logboeken of configuratiebestanden.
• Ze hebben een vervaldatum en moeten handmatig worden gedraaid.
• Ze bieden geen cryptografisch bewijs van de identiteit van de beller buiten het bezit van het geheim.

Een clientgeheim configureren in appsettings.json

Als u een clientgeheim wilt configureren, voegt u een ClientCredentials matrix toe aan de AzureAd sectie van uw appsettings.json bestand:

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

De ClientCredentials matrix ondersteunt meerdere vermeldingen. Microsoft.Identity.Web probeert elke aanmeldgegevens op volgorde totdat één slaagt, wat handig is voor scenario's voor het rouleren van geheimen.

Geheimen opslaan voor ontwikkeling

In deze sectie wordt beschreven hoe u geheime waarden buiten uw broncode kunt houden tijdens lokale ontwikkeling.

.NET gebruikersgeheimen

De aanbevolen methode voor het opslaan van geheimen tijdens lokale ontwikkeling is het hulpprogramma Secret Manager. Met gebruikersgeheimen worden gevoelige gegevens buiten uw projectstructuur opgeslagen, waardoor onbedoelde doorvoeringen naar broncodebeheer worden voorkomen.

1. Gebruikersgeheimen voor uw project initialiseren:

   dotnet user-secrets init
   

2. Stel de waarde voor het clientgeheim in:

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

3. Controleer of het geheim is opgeslagen:

   dotnet user-secrets list
   

Gebruikersgeheimen worden automatisch geladen in de Development-omgeving bij gebruik van WebApplication.CreateBuilder() of Host.CreateDefaultBuilder().

Uw appsettings.json moet de structuur bevatten zonder de werkelijke geheime waarde:

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

Omgevingsvariabelen

U kunt ook omgevingsvariabelen gebruiken om het clientgeheim op te geven. .NET configuratie wijst omgevingsvariabelen die gebruikmaken van het scheidingsteken __ (dubbele onderstrepingsteken) automatisch toe aan de configuratiehiërarchie. Stel de variabele voor uw shell in:

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

export AzureAd__ClientCredentials__0__ClientSecret="your-secret-value"

Omgevingsvariabelen hebben voorrang op waarden in appsettings.json, zodat de geheime waarde in uw configuratiebestand leeg of weggelaten kan worden.

Geheimen opslaan voor hogere omgevingen

Gebruik voor fasering, QA of een gedeelde omgeving Azure Key Vault als configuratiebron. Deze aanpak houdt geheimen buiten configuratiebestanden en omgevingsvariabelen en biedt tegelijkertijd controle- en toegangsbeleid en mogelijkheden voor automatische rotatie.

Azure Key Vault toevoegen als een configuratiebron

1. Installeer het vereiste NuGet-pakket:

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

2. Sla het clientgeheim op in Azure Key Vault met een naam die is toegewezen aan het configuratiepad. Gebruik -- (dubbel streepje) als scheidingsteken:

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

3. Voeg Key Vault toe als een configuratiebron in Program.cs. De volgende code registreert Key Vault zodat de geheimen beschikbaar zijn via de standaardconfiguratie-API:

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

De Key Vault geheime naam AzureAd--ClientCredentials--0--ClientSecret wordt automatisch toegewezen aan het configuratiepad AzureAd:ClientCredentials:0:ClientSecret.

Een clientgeheim maken in de Azure-portal

Volg deze stappen om een clientgeheim voor uw toepassing te registreren in Microsoft Entra ID:

1. Meld u aan bij de Microsoft Entra-beheercentrum.
2. Navigeer naar Identity>Applications>App-registraties.
3. Selecteer uw toepassing in de lijst.
4. Selecteer certificaten en geheimen in het linkermenu.
5. Selecteer het tabblad Clientgeheimen .
6. Selecteer nieuwe clientsleutel.
7. In het deelvenster Een clientgeheim toevoegen :
   • Voer een beschrijving in voor het geheim (bijvoorbeeld 'Ontwikkelingsgeheim').
   • Selecteer een verlooptijd. Beschikbare opties zijn 180 dagen, 365 dagen, 730 dagen of een aangepaste datum.
   • Selecteer Toevoegen.
8. Kopieer de geheime waarde onmiddellijk. De waarde wordt slechts eenmaal weergegeven en kan niet worden opgehaald nadat u van de pagina bent verwijderd.

Verloop en rotatie van geheimen beheren

Clientgeheimen hebben een maximale levensduur en verlopen op de datum die is opgegeven tijdens het maken. Plan voor geheimrotatie om onderbrekingen van toepassingen te voorkomen.

Verlooptijd bewaken

• Controleer de kolom Verloopt op de pagina Certificaten en geheimen van uw app-registratie.
• Stel Microsoft Entra aanbevelingen in om waarschuwingen te ontvangen voordat referenties verlopen.

Rotatiestrategie

Gebruik de ClientCredentials matrix ter ondersteuning van rotatie zonder downtime:

1. Maak een nieuw clientgeheim in de Azure-portal.

2. Voeg het nieuwe geheim toe als extra vermelding in de ClientCredentials matrix. Plaats het nieuwe geheim eerst, zodat het wordt geprobeerd vóór de oude:

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

3. Implementeer de bijgewerkte configuratie. Microsoft. Identity.Web probeert de eerste referentie en valt terug op de tweede als de eerste mislukt.

4. Nadat u hebt bevestigd dat het nieuwe geheim werkt, verwijdert u het oude geheim uit zowel de configuratie als de Azure-portal.

Migreren naar productie-inloggegevens

Voordat u naar productie implementeert, migreert u van clientgeheimen naar een veiliger referentietype:

Verificatie op basis van certificaat

Certificaten bieden cryptografisch bewijs van identiteit en zijn het aanbevolen referentietype voor productie. Met de volgende configuratie wordt een certificaat opgehaald uit Key Vault:

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

Zie Certificaten gebruiken met Microsoft voor gedetailleerde stappen. Identity.Web.

Beheerde identiteit (certificaatloos)

Voor toepassingen die worden gehost in Azure, elimineren beheerde identiteiten de noodzaak om referenties te beheren. De volgende configuratie maakt gebruik van een door de gebruiker toegewezen beheerde identiteit:

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

Zie Certificateless-authenticatie met Microsoft.Identity.Web voor gedetailleerde stappen.

Migratiecontrolelijst

• [ ] Genereer of richt de nieuwe referentie (certificaat of beheerde identiteit) in.
• [ ] Werk uw toepassingsconfiguratie bij om het nieuwe referentietype te gebruiken.
• [ ] Test de nieuwe inloggegevens in een testomgeving.
• [ ] Implementeer in productie.
• [ ] Verwijder het oude clientgeheim uit de Azure-portal.
• [ ] Controleer of de toepassing correct werkt zonder het oude geheim.

Veelvoorkomende beveiligingsfouten voorkomen

Bekijk de volgende antipatronen en hun aanbevolen alternatieven bij het werken met clientgeheimen:

Veelvoorkomende fouten oplossen

In deze sectie worden veelvoorkomende fouten behandeld die kunnen optreden bij het configureren van clientgeheimen.

Ongeldig clientgeheim

Fout:AADSTS7000215: Invalid client secret provided.

Mogelijke oorzaken:

• De geheime waarde is onjuist gekopieerd. Geheime waarden kunnen speciale tekens bevatten die worden afgekapt tijdens kopieer-/plakbewerkingen.
• Het geheim is gemaakt voor een andere app-registratie dan het geheim dat is geconfigureerd in ClientId.
• Het configuratiepad is onjuist en de geheime waarde wordt niet gelezen door de toepassing.

Resolutie:

1. Maak een nieuw clientgeheim in de Azure-portal en kopieer de volledige waarde zorgvuldig.

2. Controleer of de ClientId en TenantId in uw configuratie overeenkomen met de app-registratie waar het geheim is gemaakt.

3. Voeg een onderbrekingspunt of logboekinstructie toe om te controleren of de configuratie correct is geladen:

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

Verlopen client secret

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

Resolutie:

1. Navigeer naar de app-registratie in de Microsoft Entra-beheercentrum.
2. Controleer de vervaldatum onder Certificaten en geheimen Clientgeheimen>.
3. Maak een nieuw geheim en werk de toepassingsconfiguratie bij.
4. Verwijder het verlopen geheim uit de portal.

Geheim niet gevonden in configuratie

Symptoom: De toepassing genereert een NullReferenceException of mislukte verificatie omdat de geheime waarde is null.

Mogelijke oorzaken:

• Gebruikersgeheimen worden niet geïnitialiseerd voor het project.
• De naam van de omgevingsvariabele komt niet overeen met het verwachte configuratiepad.
• Key Vault is niet geconfigureerd als een configuratiebron.
• De toepassing wordt uitgevoerd in een niet-ontwikkelomgeving waarin gebruikersgeheimen niet worden geladen.

Resolutie:

1. Controleer of gebruikersgeheimen zijn geïnitialiseerd door te controleren op een UserSecretsId in uw .csproj bestand.
2. Controleer of het geheim is ingesteld door uit te voeren dotnet user-secrets list.
3. Controleer of het configuratiepad exact overeenkomt met: AzureAd:ClientCredentials:0:ClientSecret.
4. Als deze buiten de ontwikkelomgeving wordt uitgevoerd, moet u ervoor zorgen dat de juiste configuratiebron (omgevingsvariabele of Key Vault) beschikbaar is.

Verwante inhoud

• Certificaten met Microsoft.Identity.Web
• Verificatie zonder certificaat
• Overzicht van tokencache
• Veilige opslag van app-geheimen tijdens ontwikkeling in ASP.NET Core
• Azure Key Vault configuratieprovider in ASP.NET Core