Använd klienthemligheter med Microsoft. Identity.Web

En klienthemlighet är ett strängvärde som programmet använder för att bevisa sin identitet när du begär token från Microsofts identitetsplattform. Microsoft. Identity.Web stöder klienthemligheter som en av flera typer av autentiseringsuppgifter för konfidentiella klientprogram.

Välj en typ av autentiseringsuppgifter

Konfidentiella klientprogram behöver en autentiseringsuppgift för att autentisera med Microsofts identitetsplattform. Microsoft. Identity.Web stöder följande typer av autentiseringsuppgifter via konfigurationsavsnittet ClientCredentials:

Klienthemligheter är enkla strängar som registrerats med din app i Microsoft Entra ID. De är den enklaste typen av autentiseringsuppgifter att konfigurera, men de har också betydande säkerhetsbegränsningar:

• De kan oavsiktligt exponeras i källkod, loggar eller konfigurationsfiler.
• De har ett utgångsdatum och måste roteras manuellt.
• De ger inga kryptografiska bevis på uppringarens identitet utöver hemlighetens innehav.

Konfigurera en klienthemlighet i appsettings.json

Om du vill konfigurera en klienthemlighet lägger du till en ClientCredentials matris i AzureAd avsnittet i appsettings.json filen:

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

Matrisen ClientCredentials stöder flera poster. Microsoft. Identity.Web försöker varje autentiseringsuppgift i ordning tills den lyckas, vilket är användbart för scenarier med hemlig rotation.

Lagra hemligheter för utveckling

I det här avsnittet beskrivs hur du håller hemliga värden borta från källkoden under den lokala utvecklingen.

.NET användarhemligheter

Den rekommenderade metoden för att lagra hemligheter under lokal utveckling är Secret Manager-verktyget. Användarhemligheter lagrar känsliga data utanför projektträdet, vilket förhindrar oavsiktliga incheckningar till källkontrollen.

1. Initiera användarhemligheter för projektet:

   dotnet user-secrets init
   

2. Ange värdet för klienthemlighet:

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

3. Kontrollera att hemligheten har lagrats:

   dotnet user-secrets list
   

Användarhemligheter läses in automatiskt i Development miljön när du använder WebApplication.CreateBuilder() eller Host.CreateDefaultBuilder().

Din appsettings.json ska innehålla strukturen utan det faktiska hemliga värdet:

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

Miljövariabler

Du kan också använda miljövariabler för att ange klienthemligheten. .NET konfiguration mappar automatiskt miljövariabler som använder avgränsaren __ (dubbelt understreck) till konfigurationshierarkin. Ställ in variabeln för ditt skal:

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

export AzureAd__ClientCredentials__0__ClientSecret="your-secret-value"

Miljövariabler har företräde framför värden i appsettings.json, så det hemliga värdet i konfigurationsfilen kan vara tomt eller utelämnat.

Lagra hemligheter för avancerade miljöer

För mellanlagring, QA eller en delad miljö använder du Azure Key Vault som konfigurationskälla. Den här metoden håller hemligheter borta från konfigurationsfiler och miljövariabler samtidigt som du tillhandahåller gransknings-, åtkomstprinciper och automatiska rotationsfunktioner.

Lägg till Azure Key Vault som en konfigurationskälla

1. Installera det nödvändiga NuGet-paketet:

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

2. Lagra klientens hemlighet i Azure Key Vault med ett namn som motsvarar konfigurationssökvägen. Använd -- (dubbel bindestreck) som avgränsare:

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

3. Lägg till Key Vault som en konfigurationskälla i Program.cs. Följande kod registrerar Key Vault så att dess hemligheter är tillgängliga via standardkonfigurations-API:et:

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

Det Key Vault hemliga namnet AzureAd--ClientCredentials--0--ClientSecret mappas automatiskt till konfigurationssökvägen AzureAd:ClientCredentials:0:ClientSecret.

Skapa en klienthemlighet i Azure-portalen

Följ dessa steg för att registrera en klienthemlighet för ditt program i Microsoft Entra ID:

1. Logga in på Microsoft Entra administrationscenter.
2. Gå till Identity>Applications>App registrations.
3. Välj ditt program i listan.
4. I den vänstra menyn väljer du Certifikat och hemligheter.
5. Välj fliken Klienthemligheter .
6. Välj Ny klienthemlighet.
7. I fönstret Lägg till en klienthemlighet :
   • Ange en Beskrivning för hemligheten (till exempel "Utvecklingshemlighet").
   • Välj en utgångstid. Tillgängliga alternativ omfattar 180 dagar, 365 dagar, 730 dagar eller ett anpassat datum.
   • Välj Lägg till.
8. Kopiera det hemliga värdet omedelbart. Värdet visas bara en gång och kan inte hämtas när du har navigerat bort från sidan.

Hantera hemlighetens förfallodatum och rotation

Klienthemligheter har en maximal livslängd och upphör att gälla det datum som angavs när de skapades. Planera för hemlig rotation för att undvika programfel.

Utgångsdatum för övervakning

• Kontrollera kolumnen Upphör att gälla på sidan Certifikat och hemligheter i din appregistrering.
• Konfigurera Microsoft Entra rekommendationer för att ta emot aviseringar innan autentiseringsuppgifterna upphör att gälla.

Rotationsstrategi

Använd matrisen ClientCredentials för att stödja noll stilleståndstidsrotation:

1. Skapa en ny klienthemlighet i Azure portalen.

2. Lägg till den nya hemligheten som en ytterligare post i matrisen ClientCredentials . Placera den nya hemligheten först så att den provas före den gamla:

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

3. Distribuera den uppdaterade konfigurationen. Microsoft. Identity.Web försöker med den första autentiseringsuppgiften och återgår till den andra om den första misslyckas.

4. När du har bekräftat att den nya hemligheten fungerar tar du bort den gamla hemligheten från både konfigurationen och Azure-portalen.

Migrera till autentiseringsuppgifter för produktion

Innan du distribuerar till produktion migrerar du från klienthemligheter till en säkrare typ av autentiseringsuppgifter:

Certifikatbaserad autentisering

Certifikat ger kryptografiskt identitetsbevis och är den rekommenderade typen av autentiseringsuppgifter för produktion. Följande konfiguration hämtar ett certifikat från Key Vault:

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

Detaljerade steg finns i Använd certifikat med Microsoft. Identity.Web.

Hanterad identitet (utan certifikat)

För program som finns i Azure eliminerar hanterade identiteter behovet av att hantera autentiseringsuppgifter helt. Följande konfiguration använder en användartilldelad hanterad identitet:

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

Detaljerade steg finns i Certifikatlös autentisering med Microsoft. Identity.Web.

Checklista för migrering

• [ ] Generera eller etablera den nya autentiseringsuppgiften (certifikat eller hanterad identitet).
• [ ] Uppdatera programkonfigurationen så att den nya autentiseringstypen används.
• [ ] Testa de nya autentiseringsuppgifterna i en mellanlagringsmiljö.
• [ ] Lägg upp i produktion.
• [ ] Ta bort den gamla klienthemligheten från Azure-portalen.
• [ ] Kontrollera att programmet fungerar korrekt utan den gamla hemligheten.

Undvik vanliga säkerhetsmisstag

Granska följande antimönster och deras rekommenderade alternativ när du arbetar med klienthemligheter:

Felsök vanliga fel

Det här avsnittet beskriver vanliga fel som kan uppstå när du konfigurerar klienthemligheter.

Ogiltig klienthemlighet

Fel:AADSTS7000215: Invalid client secret provided.

Möjliga orsaker:

• Det hemliga värdet kopierades felaktigt. Hemliga värden kan innehålla specialtecken som trunkeras under kopierings-/inklistringsåtgärder.
• Hemligheten skapades för en annan appregistrering än den som konfigurerades i ClientId.
• Konfigurationssökvägen är felaktig och det hemliga värdet läss inte av programmet.

Upplösning:

1. Skapa en ny klienthemlighet i Azure-portalen och kopiera noggrant det fullständiga värdet.

2. Kontrollera att ClientId och TenantId i konfigurationen matchar appregistreringen där hemligheten skapades.

3. Lägg till en brytpunkt eller logginstruktion för att kontrollera att konfigurationen har lästs in korrekt:

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

Klienthemlighet har upphört att gälla

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

Upplösning:

1. Gå till appregistreringen i Microsoft Entra administrationscenter.
2. Kontrollera förfallodatumet under Certifikat och hemligheter>Klienthemligheter.
3. Skapa en ny hemlighet och uppdatera programkonfigurationen.
4. Ta bort den utgångna hemligheten från portalen.

Hemligheten hittades inte i konfigurationen

Symptom: Programmet genererar en NullReferenceException eller misslyckas med att autentisera eftersom det hemliga värdet är null.

Möjliga orsaker:

• Användarhemligheter initieras inte för projektet.
• Miljövariabelnamnet matchar inte den förväntade konfigurationssökvägen.
• Key Vault har inte konfigurerats som en konfigurationskälla.
• Programmet körs i en icke-utvecklingsmiljö där användarhemligheter inte läses in.

Upplösning:

1. Kontrollera att användarhemligheter initieras genom att söka efter en UserSecretsId i filen .csproj.
2. Kontrollera att hemligheten har angetts genom att köra dotnet user-secrets list.
3. Kontrollera att konfigurationssökvägen matchar exakt: AzureAd:ClientCredentials:0:ClientSecret.
4. Om du kör utanför utvecklingsmiljön kontrollerar du att rätt konfigurationskälla (miljövariabel eller Key Vault) är tillgänglig.

Relaterat innehåll

• Certifikat med Microsoft. Identity.Web
• Certifikatfri autentisering
• Översikt över tokencache
• Säkerhetslagring av apphemligheter under utveckling i ASP.NET Core
• Azure Key Vault konfigurationsleverantör i ASP.NET Core