Użyj tajemnic klienta z Microsoft.Identity.Web

Sekret klienta to ciąg znaków, którego aplikacja używa do potwierdzenia swojej tożsamości podczas żądania tokenów z Platforma tożsamości Microsoft. Microsoft.Identity.Web obsługuje tajne klucze klienta jako jeden z kilku typów poświadczeń dla poufnych aplikacji klienckich.

Ważna

Wpisy tajne klienta powinny być używane tylko w środowiskach deweloperskich i testowych. W przypadku obciążeń produkcyjnych użyj certyfikatów lub poświadczeń bez certyfikatów , takich jak tożsamości zarządzane lub poświadczenia tożsamości federacyjnej. Wpisy tajne klienta są łatwiejsze do naruszenia niż poświadczenia oparte na certyfikatach i nie mogą być ograniczone do określonych operacji.

Wybierz typ poświadczeń

Poufne aplikacje klienckie muszą uwierzytelniać się przy użyciu Platforma tożsamości Microsoft. Microsoft.Identity.Web obsługuje następujące typy poświadczeń poprzez sekcję konfiguracji ClientCredentials:

Typ poświadczeń Zalecane środowisko Poziom zabezpieczeń
Klucz tajny klienta Programowanie, testowanie Low
Certyfikat Środowisko testowe, produkcyjne High
Tożsamość zarządzana środowisko produkcyjne hostowane Azure Najwyższa
Tożsamość federacyjna Ciągła integracja/ciągłe wdrażanie, Kubernetes High

W Microsoft Entra ID "sekrety klienta" to proste ciągi znaków zarejestrowane w Twojej aplikacji. Chociaż są one najprostszym typem poświadczeń do skonfigurowania, mają również istotne ograniczenia zabezpieczeń:

  • Mogą one być przypadkowo uwidocznione w kodzie źródłowym, dziennikach lub plikach konfiguracji.
  • Mają datę wygaśnięcia i muszą zostać ręcznie obrócone.
  • Nie zapewniają kryptograficznego dowodu tożsamości dzwoniącego poza posiadaniem hasła.

Skonfiguruj tajemnicę klienta w appsettings.json

Aby skonfigurować tajemnicę klienta, dodaj tablicę ClientCredentials do sekcji AzureAd w pliku appsettings.json.

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

Tablica ClientCredentials obsługuje wiele wpisów. Microsoft.Identity.Web próbuje każdego poświadczenia po kolei, dopóki jedno się nie powiedzie, co jest przydatne przy rotacji tajnych kluczy.

Ostrzeżenie

Nigdy nie zatwierdzaj rzeczywistych wartości poufnych do systemu kontroli wersji. Symbol YOUR_SECRET_VALUE zastępczy w poprzednim przykładzie musi zostać zastąpiony odwołaniem do bezpiecznego magazynu, zgodnie z opisem w poniższych sekcjach.

Przechowywanie sekretów do programowania

W tej sekcji opisano, jak chronić wartości tajne przed umieszczeniem ich w kodzie źródłowym podczas lokalnego rozwoju oprogramowania.

.NET sekrety użytkownika

Zalecaną metodą przechowywania wpisów tajnych podczas programowania lokalnego jest narzędzie Secret Manager. Sekrety Użytkownika przechowują poufne dane poza strukturą projektu, co zapobiega przypadkowemu zatwierdzaniu ich do kontroli wersji.

  1. Zainicjuj sekrety użytkownika dla projektu:

    dotnet user-secrets init

  2. Ustaw wartość sekretu klienta:

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

  3. Sprawdź, czy wpis tajny został zapisany:

    dotnet user-secrets list

Sekrety użytkownika są automatycznie ładowane w Development środowisku podczas korzystania z WebApplication.CreateBuilder() lub Host.CreateDefaultBuilder().

Element appsettings.json powinien zawierać strukturę bez rzeczywistej wartości sekretnej:

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

Zmienne środowiskowe

Możesz również użyć zmiennych środowiskowych, aby podać klucz tajny klienta. .NET konfiguracja automatycznie mapuje zmienne środowiskowe, które używają separatora __ (podwójne podkreślenie) do hierarchii konfiguracji. Ustaw zmienną dla powłoki:

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

Zmienne środowiskowe mają pierwszeństwo przed wartościami w appsettings.json, więc wartość sekretu w pliku konfiguracji może być pusta lub pominięta.

Przechowywanie tajemnic dla bardziej zaawansowanych środowisk

W przypadku środowiska przejściowego, kontroli jakości lub dowolnego środowiska udostępnionego użyj Azure Key Vault jako źródła konfiguracji. Takie podejście przechowuje tajne informacje poza plikami konfiguracji i zmiennymi środowiskowymi, zapewniając jednocześnie funkcje inspekcji, polityk dostępu i automatyczną rotację.

Dodaj Azure Key Vault jako źródło konfiguracji

  1. Zainstaluj wymagany pakiet NuGet:

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

  2. Zapisz sekret klienta w Azure Key Vault z nazwą odpowiadającą ścieżce konfiguracji. Użyj -- znaku (podwójna kreska) jako separatora:

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

  3. Dodaj Key Vault jako źródło konfiguracji w Program.cs. Poniższy kod rejestruje Key Vault, aby jego sekrety były dostępne za pośrednictwem standardowego interfejsu API konfiguracji.

    var builder = WebApplication.CreateBuilder(args);

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

Nazwa wpisu tajnego Key Vault AzureAd--ClientCredentials--0--ClientSecret jest automatycznie mapowana na ścieżkę konfiguracji AzureAd:ClientCredentials:0:ClientSecret.

Wskazówka

Nawet gdy używasz Key Vault do przechowywania tajemnicy klienta, warto rozważyć, czy obciążenie produkcyjne byłoby lepiej obsługiwane przez certyfikaty czy zarządzane tożsamości. Key Vault jest przydatna w przypadku współużytkowanych środowisk programistycznych lub przejściowych, ale aplikacje produkcyjne powinny używać silniejszych typów poświadczeń.

Utwórz tajny klucz klienta w portalu Azure

Wykonaj następujące kroki, aby zarejestrować klucz tajny klienta dla aplikacji w Microsoft Entra ID:

  1. Zaloguj się do centrum administracyjne Microsoft Entra.
  2. Przejdź do Identity>Applications>Rejestracje aplikacji.
  3. Wybierz aplikację z listy.
  4. W menu po lewej stronie wybierz pozycję Certyfikaty i wpisy tajne.
  5. Wybierz kartę Tajny klienta.
  6. Wybierz Nowy klucz tajny klienta.
  7. W okienku Dodaj tajny klucz klienta:
    • Wprowadź opis dla tajemnicy (na przykład "Tajemnica rozwojowa").
    • Wybierz czas wygaśnięcia . Dostępne opcje obejmują 180 dni, 365 dni, 730 dni lub datę niestandardową.
    • Wybierz opcję Dodaj.
  8. Skopiuj wartość sekretu natychmiast. Wartość jest wyświetlana tylko raz i nie można jej pobrać po opuszczeniu strony.

Ważna

Zapisz wartość tajną w bezpiecznej lokalizacji natychmiast po utworzeniu. Microsoft Entra ID wyświetla tylko wartość w czasie tworzenia. Jeśli utracisz tajny klucz, musisz utworzyć nowy tajny klucz.

Zarządzanie wygaśnięciem i rotacją tajemnic

Wpisy tajne klienta mają maksymalny okres istnienia i wygasają w dniu określonym podczas tworzenia. Zaplanuj rotację danych poufnych, aby uniknąć przestojów aplikacji.

Monitorowanie wygaśnięcia

  • Sprawdź kolumnę Wygasa na stronie Certyfikaty i sekrety rejestracji aplikacji.
  • Skonfiguruj zalecenia Microsoft Entra aby otrzymywać alerty przed wygaśnięciem poświadczeń.

Strategia rotacji

Użyj tablicy ClientCredentials, aby obsługiwać rotację bez przestojów.

  1. Utwórz nowy tajny klucz klienta w portalu Azure.

  2. Dodaj nowy sekret jako dodatkowy element w tablicy ClientCredentials. Najpierw umieść nowy sekret, aby był wypróbowany przed starym.

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

  3. Wdróż zaktualizowaną konfigurację. Microsoft.Identity.Web próbuje wykonać pierwsze poświadczenie i przełącza się na drugie, jeśli pierwsze nie powiedzie się.

  4. Po potwierdzeniu, że nowy wpis tajny działa, usuń stary wpis tajny zarówno z konfiguracji, jak i z portalu Azure.

Migrowanie do poświadczeń produkcyjnych

Przed wdrożeniem w środowisku produkcyjnym przeprowadź migrację z tajnych kluczy klienta do bezpieczniejszego typu poświadczeń:

Uwierzytelnianie oparte na certyfikatach

Certyfikaty zapewniają kryptograficzny dowód tożsamości i są zalecanym typem poświadczeń dla środowiska produkcyjnego. Poniższa konfiguracja pobiera certyfikat z Key Vault:

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

Aby uzyskać szczegółowe instrukcje, zobacz Użyj certyfikaty za pomocą Microsoft. Identity.Web.

Tożsamość zarządzana (bez certyfikatów)

W przypadku aplikacji hostowanych w Azure tożsamości zarządzane eliminują konieczność całkowitego zarządzania poświadczeniami. Poniższa konfiguracja używa tożsamości zarządzanej przypisanej przez użytkownika:

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

Aby uzyskać szczegółowe instrukcje, zobacz Certificateless authentication with Microsoft (Uwierzytelnianie bez certyfikatów za pomocą Microsoft). Identity.Web.

Lista kontrolna migracji

  • [ ] Generuj lub uzyskaj nowe poświadczenie (certyfikat lub tożsamość zarządzana).
  • [ ] Zaktualizuj konfigurację aplikacji, aby użyć nowego typu poświadczeń.
  • [ ] Przetestuj nowe poświadczenie w środowisku testowym.
  • [ ] Wdrażanie w środowisku produkcyjnym.
  • [ ] Usuń stary klucz tajny klienta z portalu Azure.
  • [ ] Sprawdź, czy aplikacja działa poprawnie bez starego klucza tajnego.

Unikaj typowych błędów zabezpieczeń

Podczas pracy z tajemnicami klienta zapoznaj się z następującymi antywzorcami i ich zalecanymi alternatywami:

Antywzorzec Ryzyko Zalecenie
Twarde kodowanie tajnych danych w kodzie źródłowym Wpis tajny uwidoczniony w kontroli wersji Użyj User Secrets, zmiennych środowiska lub Key Vault
Zatwierdzanie appsettings.Development.json z tajnymi danymi Wpis tajny udostępniany wszystkim osobom z dostępem do repozytorium Dodaj plik do .gitignore i wykorzystaj zamiast tego User Secrets
Udostępnianie sekretów w różnych środowiskach Naruszony tajny klucz dewelopera ujawnia środowisko produkcyjne Używaj unikatowych sekretów dla każdego środowiska
Używanie sekretów w środowisku produkcyjnym Większe ryzyko kradzieży poświadczeń Migrowanie do certyfikatów lub tożsamości zarządzanych
Tworzenie sekretów bez planu wygaśnięcia Awaria aplikacji, gdy wygaśnie tajny klucz Ustawianie przypomnień o wygaśnięciu i implementowanie rotacji
Rejestrowanie wartości tajnych Wpis tajny uwidoczniony w plikach dziennika Nigdy nie rejestruj wartości poświadczeń; rejestruj tylko typ źródła poświadczeń.
Przechowywanie wpisów tajnych w plikach zwykłego tekstu na serwerach Wpis tajny udostępniany wszystkim osobom z dostępem do serwera Użyj zmiennych środowiskowych lub Key Vault

Rozwiązywanie typowych błędów

W tej sekcji opisano częste błędy, które mogą wystąpić podczas konfigurowania tajemnic klientów.

Nieprawidłowy klucz tajny klienta

Błąd:AADSTS7000215: Invalid client secret provided.

Możliwe przyczyny:

  • Tajna wartość została skopiowana niepoprawnie. Wartości wpisów tajnych mogą zawierać znaki specjalne, które są obcinane podczas operacji kopiowania/wklejania.
  • Tajny klucz został utworzony dla innej rejestracji aplikacji niż ta skonfigurowana w ClientId.
  • Ścieżka konfiguracji jest niepoprawna, a tajna wartość nie jest odczytywana przez aplikację.

Rozwiązanie:

  1. Utwórz nowy klucz tajny klienta w portalu Azure i dokładnie skopiuj pełną wartość.

  2. Sprawdź, czy elementy ClientId i TenantId w konfiguracji są zgodne z rejestracją aplikacji, w której utworzono sekret.

  3. Dodaj punkt przerwania lub instrukcję logowania, aby sprawdzić, czy konfiguracja jest poprawnie załadowana.

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

Wygasły klucz tajny klienta

Błąd:AADSTS7000222: The provided client secret keys for app '{app-id}' are expired.

Rozwiązanie:

  1. Przejdź do rejestracji aplikacji w centrum administracyjne Microsoft Entra.
  2. Sprawdź datę wygaśnięcia w obszarze Certyfikaty i wpisy tajne> klienta.
  3. Utwórz nową tajemnicę i zaktualizuj ustawienia konfiguracyjne aplikacji.
  4. Usuń wygasły tajny klucz z portalu.

Nie znaleziono sekretu w konfiguracji

Objaw: Aplikacja zgłasza błąd NullReferenceException lub nie uwierzytelnia się, ponieważ wartość sekretu to null.

Możliwe przyczyny:

  • Wpisy tajne użytkownika nie są inicjowane dla projektu.
  • Nazwa zmiennej środowiskowej nie jest zgodna z oczekiwaną ścieżką konfiguracji.
  • Key Vault nie jest skonfigurowany jako źródło konfiguracji.
  • Aplikacja jest uruchomiona w środowisku innym niż developerskie, w którym nie są ładowane tajne dane użytkownika.

Rozwiązanie:

  1. Sprawdź, czy tajne użytkownika są zainicjowane, sprawdzając obecność UserSecretsId w pliku .csproj.
  2. Sprawdź, czy sekret został ustawiony, uruchamiając dotnet user-secrets list.
  3. Sprawdź, czy ścieżka konfiguracji dokładnie odpowiada: AzureAd:ClientCredentials:0:ClientSecret.
  4. Jeśli działa poza środowiskiem programistycznym, upewnij się, że jest dostępne odpowiednie źródło konfiguracji (zmienna środowiskowa lub Key Vault).

Treści powiązane

  • Last updated on