Používejte tajné kódy klienta s Microsoft. Identity.Web

Tajný klíč klienta je řetězcová hodnota, kterou vaše aplikace používá k prokázání identity při vyžádání tokenů z Microsoft identity platform. Microsoft. Identity.Web podporuje tajné kódy klienta jako jeden z několika typů přihlašovacích údajů pro důvěrné klientské aplikace.

Volba typu přihlašovacích údajů

Důvěrné klientské aplikace potřebují přihlašovací údaje k ověření v Microsoft identity platform. Microsoft. Identity.Web podporuje následující typy přihlašovacích údajů prostřednictvím oddílu konfigurace ClientCredentials:

Tajné kódy klienta jsou jednoduché řetězce zaregistrované ve vaší aplikaci v Microsoft Entra ID. I když jsou nejjednodušším typem přihlašovacích údajů, který je potřeba nastavit, mají také významná omezení zabezpečení:

• Můžou být náhodně vystavené ve zdrojovém kódu, protokolech nebo konfiguračních souborech.
• Mají datum vypršení platnosti a musí se ručně otočit.
• Neposkytují kryptografický důkaz o identitě volajícího nad rámec vlastnictví tajného klíče.

Konfigurace tajného klíče klienta v appsettings.json

Pokud chcete nakonfigurovat tajný klíč klienta, přidejte ClientCredentials pole do AzureAd části souboru appsettings.json :

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

Pole ClientCredentials podporuje více položek. Microsoft.Identity.Web zkouší každý ověřovací údaj postupně, dokud jeden neuspěje, což je užitečné pro scénáře obměny tajemství.

Ukládání tajných kódů pro vývoj

Tato část popisuje, jak zachovat tajné hodnoty mimo zdrojový kód během místního vývoje.

.NET uživatelská tajemství

Doporučeným přístupem k ukládání tajných kódů během místního vývoje je nástroj Secret Manager. Uživatelská tajemství ukládají citlivá data mimo strom projektu, což brání náhodnému odeslání do verzíovacího systému.

1. Inicializace tajných kódů uživatele pro váš projekt:

   dotnet user-secrets init
   

2. Nastavte hodnotu tajného klíče klienta:

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

3. Ověřte, že tajný klíč byl uložen:

   dotnet user-secrets list
   

Uživatelské tajemství se automaticky načítají v prostředí Development při použití WebApplication.CreateBuilder() nebo Host.CreateDefaultBuilder().

Vaše appsettings.json by mělo obsahovat strukturu bez skutečné tajné hodnoty:

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

Proměnné prostředí

Proměnné prostředí můžete použít také k poskytnutí tajného klíče klienta. konfigurace .NET automaticky mapuje proměnné prostředí, které používají oddělovač __ (dvojité podtržítko) do hierarchie konfigurace. Nastavte proměnnou pro váš shell:

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

export AzureAd__ClientCredentials__0__ClientSecret="your-secret-value"

Proměnné prostředí mají přednost před hodnotami v appsettings.json, takže tajná hodnota v konfiguračním souboru může být prázdná nebo vynechána.

Ukládání tajných kódů pro vyšší prostředí

Pro přípravu, kontrolu kvality nebo jakékoli sdílené prostředí použijte Azure Key Vault jako zdroj konfigurace. Tento přístup uchovává tajné kódy mimo konfigurační soubory a proměnné prostředí a současně poskytuje možnosti auditování, zásad přístupu a automatické obměny.

Přidání Azure Key Vault jako zdroje konfigurace

1. Nainstalujte požadovaný balíček NuGet:

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

2. Uložte klientský tajný klíč do Azure Key Vault s názvem, který se mapuje na cestu konfigurace. Jako oddělovač použijte -- (dvojitou pomlčku):

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

3. Přidejte Key Vault jako zdroj konfigurace v Program.cs. Následující kód zaregistruje Key Vault, aby jeho tajné kódy byly dostupné prostřednictvím standardního konfiguračního rozhraní API:

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

Název tajného kódu Key Vault AzureAd--ClientCredentials--0--ClientSecret se automaticky mapuje na cestu konfigurace AzureAd:ClientCredentials:0:ClientSecret.

Vytvoření tajného klíče klienta na portálu Azure

Pomocí následujícího postupu zaregistrujte tajný klíč klienta pro vaši aplikaci v Microsoft Entra ID:

1. Přihlaste se k Centrum pro správu Microsoft Entra.
2. Přejděte na Identity>Applications>Registrace aplikací.
3. Ze seznamu vyberte aplikaci.
4. V nabídce vlevo vyberte Certifikáty a tajné kódy.
5. Vyberte kartu Tajné kódy klienta .
6. Vyberte Nový tajný klíč klienta.
7. V podokně Přidat tajný klíč klienta :
   • Zadejte popis tajného klíče (například "Tajný kód pro vývoj").
   • Vyberte dobu trvání vypršení platnosti . Mezi dostupné možnosti patří 180 dní, 365 dní, 730 dní nebo vlastní datum.
   • Vyberte Přidat.
8. Okamžitě zkopírujte hodnotu tajného kódu. Hodnota je zobrazena jen jednou a po opuštění stránky ji nelze znovu zobrazit.

Správa vypršení platnosti a obměně tajných kódů

Tajné kódy klienta mají maximální životnost a vyprší k datu zadanému během vytváření. Naplánujte obměnu tajných kódů, abyste se vyhnuli výpadkům aplikací.

Monitorování vypršení platnosti

• Na stránce Certifikáty a tajné kódy registrace vaší aplikace zkontrolujte sloupec Konec platnosti.
• Nastavte doporučení Microsoft Entra pro příjem upozornění před vypršením platnosti přihlašovacích údajů.

Strategie rotace

Pomocí pole ClientCredentials můžete podporovat rotaci bez výpadku.

1. Na portálu Azure vytvořte nový tajný klíč klienta.

2. Přidejte nový tajný klíč jako další položku v ClientCredentials poli. Nejprve umístěte nové tajemství, aby se vyzkoušelo před starým.

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

3. Nasaďte aktualizovanou konfiguraci. Microsoft. Identity.Web se pokusí o první přihlašovací údaje a vrátí se k druhému, pokud se první nezdaří.

4. Po potvrzení fungování nového tajného kódu odeberte starý tajný klíč z konfigurace i z portálu Azure.

Migrace na produkční autentizační údaje

Před nasazením do produkčního prostředí migrujte z tajných kódů klienta na bezpečnější typ přihlašovacích údajů:

Ověřování pomocí certifikátů

Certifikáty poskytují kryptografickou kontrolu identity a jsou doporučeným typem přihlašovacích údajů pro produkční prostředí. Následující konfigurace načte certifikát z Key Vault:

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

Podrobný postup najdete v tématu Užívání certifikátů pomocí Microsoft. Identity.Web

Spravovaná identita (bez certifikátů)

U aplikací hostovaných v Azure spravované identity eliminují potřebu úplné správy přihlašovacích údajů. Následující konfigurace používá spravovanou identitu přiřazenou uživatelem:

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

Podrobné kroky najdete v tématu Certificateless authentication with Microsoft. Identity.Web

Kontrolní seznam pro migraci

• [ ] Vygenerujte nebo zřiďte nové přihlašovací údaje (certifikát nebo spravovaná identita).
• [ ] Aktualizujte konfiguraci aplikace tak, aby používala nový typ přihlašovacích údajů.
• [ ] Otestujte nové přihlašovací údaje v přípravném prostředí.
• [ ] Nasaďte do produkčního prostředí.
• [ ] Odeberte starý tajný klíč klienta z portálu Azure.
• [ ] Ověřte správné fungování aplikace bez starého tajného kódu.

Vyhněte se běžným chybám zabezpečení

Při práci s klientskými tajemstvími si projděte následující antivzory a doporučené alternativy:

Řešení běžných chyb

Tato část se věnuje častým chybám, ke kterým může dojít při konfiguraci tajných klíčů klienta.

Neplatný tajný klíč klienta

Chyba:AADSTS7000215: Invalid client secret provided.

Možné příčiny:

• Hodnota tajného kódu byla nesprávně zkopírována. Tajné hodnoty můžou obsahovat speciální znaky, které se během operací kopírování a vkládání zkrátí.
• Tajný kód byl vytvořen pro jinou registraci aplikace, než je ten nakonfigurovaný v ClientId.
• Cesta konfigurace je nesprávná a aplikace nečte tajnou hodnotu.

Řešení:

1. Na portálu Azure vytvořte nový tajný klíč klienta a pečlivě zkopírujte celou hodnotu.

2. Ověřte, že ClientId a TenantId v konfiguraci odpovídá registraci aplikace, ve které byl tajný klíč vytvořen.

3. Přidejte zarážku nebo protokolovací příkaz pro ověření, že konfigurace je správně načtena.

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

Tajný klíč klienta s vypršenou platností

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

Řešení:

1. Přejděte do registrace aplikace v Centrum pro správu Microsoft Entra.
2. Zkontrolujte datum vypršení platnosti v části Certifikáty a tajné kódy>klienta.
3. Vytvořte nový tajný klíč a aktualizujte konfiguraci aplikace.
4. Odstraňte tajný kód, jehož platnost vypršela, z portálu.

Tajný klíč nebyl v konfiguraci nalezen.

Příznak: Aplikace NullReferenceException nebo se ji nepodaří ověřit, protože tajná hodnota je null.

Možné příčiny:

• Tajné kódy uživatele nejsou inicializovány pro projekt.
• Název proměnné prostředí neodpovídá očekávané cestě konfigurace.
• Key Vault není nakonfigurovaný jako zdroj konfigurace.
• Aplikace běží v prostředí, které není vývojové, kde se nenačtou tajné kódy uživatelů.

Řešení:

1. Ověřte, zda jsou uživatelská tajemství inicializována kontrolou UserSecretsId ve vašem souboru .csproj.
2. Spuštěním dotnet user-secrets listpříkazu ověřte, že je tajný kód nastavený.
3. Zkontrolujte, jestli cesta konfigurace přesně odpovídá: AzureAd:ClientCredentials:0:ClientSecret.
4. Pokud běží mimo vývojové prostředí, ujistěte se, že je k dispozici příslušný zdroj konfigurace (proměnná prostředí nebo Key Vault).

Související obsah

• Certifikáty s Microsoft.Identity.Web
• Ověřování bez certifikátů
• Přehled mezipaměti tokenů
• Bezpečné úložiště tajných kódů aplikací při vývoji ve ASP.NET Core
• Konfigurační zprostředkovatel služby Azure Key Vault v ASP.NET Core