Skonfiguruj odszyfrowywanie tokenu w Microsoft. Identity.Web

W tym artykule wyjaśniono, jak skonfigurować certyfikaty odszyfrowywania tokenów w Microsoft. Identity.Web, aby aplikacja mogła odszyfrować zaszyfrowane tokeny z Platforma tożsamości Microsoft.

Domyślnie Platforma tożsamości Microsoft wystawia tokeny (tokeny identyfikatorów, tokeny SAML) jako podpisane, ale niezaszyfrowane JWTs. Każdy pośrednik, który przechwytuje token, może odczytać jego oświadczenia. W przypadku aplikacji obsługujących poufne oświadczenia lub działających w ścisłych środowiskach zgodności Platforma tożsamości Microsoft obsługuje szyfrowanie token. Po włączeniu platforma tożsamości szyfruje ładunek tokenu przy użyciu klucza publicznego zarejestrowanego w aplikacji. Tylko aplikacja , która przechowuje odpowiedni klucz prywatny, może odszyfrować i odczytać token.

Jak działa szyfrowanie tokenów

  1. Certyfikat jest generowany z parą kluczy publicznych/prywatnych.
  2. Przekażesz klucz public (plik .cer) do rejestracji aplikacji w Microsoft Entra ID.
  3. Gdy Platforma tożsamości Microsoft wystawia token dla aplikacji, szyfruje token przy użyciu klucza publicznego.
  4. Aplikacja używa klucza prywatnego do odszyfrowywania tokenu przed przetworzeniem oświadczeń.

Szyfrowanie używa schematu dwuwarstwowego: ładunek tokenu jest szyfrowany przy użyciu symetrycznego klucza szyfrowania zawartości, który jest opakowany (zaszyfrowany) przy użyciu klucza publicznego. Microsoft Entra obsługuje algorytmy opakowujące klucze RSA-OAEP i RSA-OAEP-256.

Określanie, kiedy skonfigurować odszyfrowywanie tokenu

Skonfiguruj odszyfrowywanie tokenów, gdy aplikacja spełnia jeden z następujących warunków:

  • Odbiera zaszyfrowane tokeny SAML — aplikacje dla przedsiębiorstw korzystające z logowania jednokrotnego opartego na protokole SAML i wymagają zaszyfrowanych asercji SAML ze względów zgodności lub przepisów.
  • Odbiera zaszyfrowane tokeny identyfikatorów — aplikacje internetowe, które decydują się na szyfrowanie tokenów identyfikatorów w celu ochrony poufnych oświadczeń (członkostwa w grupach, oświadczeń niestandardowych) przed odczytem podczas przesyłania.
  • Działa w środowiskach o wysokim poziomie zabezpieczeń — aplikacje w scenariuszach instytucji rządowych, finansowych lub opieki zdrowotnej, w których poufność tokenu jest wymagana przez zasady.

Uwaga / Notatka

Szyfrowanie tokenu jest opcjonalne. Większość aplikacji jej nie potrzebuje. Włącz szyfrowanie tokenów tylko wtedy, gdy masz określone wymaganie, ponieważ zwiększa złożoność operacyjną (zarządzanie certyfikatami, rotacja) i utrudnia rozwiązywanie problemów.

Spełnianie wymagań wstępnych

Przed skonfigurowaniem odszyfrowywania tokenu sprawdź następujące wymagania:

  • Certyfikat X.509 z kluczem prywatnym — potrzebujesz certyfikatu w formacie .pfx (PKCS#12) lub przechowywanego w lokalizacji dostępnej dla Twojej aplikacji (Azure Key Vault, magazyn certyfikatów lub system plików). Klucz prywatny jest wymagany do odszyfrowywania tokenów.
  • Rejestracja aplikacji skonfigurowana na potrzeby szyfrowania tokenu — przekaż klucz publiczny certyfikatu do rejestracji aplikacji w Microsoft Entra ID. Zobacz Rejestrowanie certyfikatu odszyfrowywania w dalszej części tego artykułu.
  • Microsoft. Identity.Web 2.1.0 lub nowszy — właściwość konfiguracji TokenDecryptionCredentials jest dostępna w Microsoft. Identity.Web 2.1.0 i nowsze.

Konfigurowanie odszyfrowywania tokenów w appsettings.json

Microsoft.Identity.Web używa tablicy TokenDecryptionCredentials w sekcji konfiguracji AzureAd. Ta tablica jest zgodna z tym samym formatem opisu poświadczeń co ClientCredentials, dzięki czemu można załadować certyfikaty odszyfrowywania z Azure Key Vault, magazynu certyfikatów, ścieżki pliku lub ciągu zakodowanego w formacie Base64.

Konfigurowanie podstawowej konfiguracji

W poniższym przykładzie przedstawiono minimalną konfigurację ładowania certyfikatu odszyfrowywania z Azure Key Vault:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "CallbackPath": "/signin-oidc",

    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "MyCertificate"
      }
    ]
  }
}

Nie jest wymagany dodatkowy kod. Gdy Microsoft. Identity.Web wykrywa konfigurację TokenDecryptionCredentials, automatycznie ładuje określony certyfikat i rejestruje go w procedurze obsługi uwierzytelniania OpenID Connect na potrzeby odszyfrowywania tokenów.

Wybieranie źródła poświadczeń

Tablica TokenDecryptionCredentials obsługuje te same typy źródłowe co ClientCredentials. Poniższa tabela zawiera podsumowanie każdej opcji:

Typ źródła Opis Wymagane właściwości
KeyVault Załaduj certyfikat z Azure Key Vault. Zalecane do użycia produkcyjnego. KeyVaultUrl, KeyVaultCertificateName
StoreWithThumbprint Załaduj z lokalnego magazynu certyfikatów za pomocą odcisku palca. CertificateStorePath, CertificateThumbprint
StoreWithDistinguishedName Załaduj z lokalnego magazynu certyfikatów według nazwy wyróżniającej podmiotu. CertificateStorePath, CertificateDistinguishedName
Path Załaduj z pliku .pfx w systemie plików. CertificateDiskPath, CertificatePassword
Kodowanie Base64 Ładowanie z ciągu zakodowanego .pfx w formacie Base64 (przydatne w przypadku zmiennych środowiskowych). Base64EncodedValue

Następująca konfiguracja ładuje certyfikat odszyfrowywania z Azure Key Vault:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert"
    }
  ]
}

Tożsamość zarządzana aplikacji lub jednostka usługi musi mieć uprawnienia Get i List na certyfikatach Key Vault.

Magazyn certyfikatów (Windows)

Następująca konfiguracja ładuje certyfikat z magazynu certyfikatów Windows za pomocą odcisku palca:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "StoreWithThumbprint",
      "CertificateStorePath": "CurrentUser/My",
      "CertificateThumbprint": "A1B2C3D4E5F6..."
    }
  ]
}

Ścieżka pliku

Następująca konfiguracja ładuje certyfikat z .pfx pliku na dysku:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Path",
      "CertificateDiskPath": "/var/ssl/private/decrypt-cert.pfx",
      "CertificatePassword": "your-certificate-password"
    }
  ]
}

Ostrzeżenie

Unikaj przechowywania haseł certyfikatów w appsettings.json środowisku produkcyjnym. Zamiast tego użyj zmiennych środowiskowych, odwołań do Azure Key Vault lub menedżera sekretów.

Kodowane w formacie Base64

Następująca konfiguracja ładuje certyfikat z ciągu zakodowanego w formacie Base64:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Base64Encoded",
      "Base64EncodedValue": "MIIJ..."
    }
  ]
}

Ta opcja jest przydatna podczas używania certyfikatu za pośrednictwem zmiennej środowiskowej lub tajnego klucza w potokach CI/CD.

Konfigurowanie wielu certyfikatów odszyfrowywania

W tablicy TokenDecryptionCredentials można określić wiele certyfikatów. Microsoft.Identity.Web próbuje każdego certyfikatu w kolejności do momentu pomyślnego rozszyfrowania tokenu. Ta funkcja jest niezbędna do rotacji certyfikatów (zobacz Rotacja certyfikatów).

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-New"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-Old"
    }
  ]
}

Rejestrowanie certyfikatu odszyfrowywania w Microsoft Entra ID

Aby platforma tożsamości Microsoft mogła szyfrować tokeny dla Twojej aplikacji, musisz przekazać publiczny klucz do rejestracji aplikacji:

  1. Zaloguj się do centrum administracyjne Microsoft Entra.
  2. Przejdź do Identity>Applications>Rejestracje aplikacji i wybierz aplikację.
  3. Wybierz pozycję Certyfikaty i wpisy tajne>Certyfikaty>Przekaż certyfikat.
  4. .cer Przekaż plik (tylko klucz publiczny) certyfikatu odszyfrowywania.
  5. Po przesłaniu zanotuj wartość odcisku palca — musi być zgodna z certyfikatem używanym przez aplikację.

Włączanie szyfrowania tokenów dla aplikacji

Po przekazaniu certyfikatu należy skonfigurować aplikację do odbierania zaszyfrowanych tokenów. Ta konfiguracja jest obecnie dostępna za pośrednictwem interfejs Graph API Microsoft lub programu PowerShell:

Using Microsoft Graph PowerShell:

# Get the key credential ID of the uploaded certificate
$app = Get-MgApplication -Filter "appId eq 'your-client-id'"
$keyId = ($app.KeyCredentials | Where-Object { $_.DisplayName -eq "CN=TokenDecryptionCert" }).KeyId

# Set the token encryption key ID
Update-MgApplication -ApplicationId $app.Id -BodyParameter @{
    "tokenEncryptionKeyId" = $keyId
}

Ważna

Właściwość tokenEncryptionKeyId w obiekcie aplikacji identyfikuje, które przekazane certyfikaty Microsoft Entra używa do szyfrowania tokenów. Jednocześnie może być aktywny tylko jeden klucz szyfrowania.

Obracanie certyfikatów odszyfrowywania

Rotacja certyfikatów na potrzeby odszyfrowywania tokenów wymaga starannego, etapowego podejścia, aby uniknąć przestoju:

Kroki rotacji

  1. Wygeneruj nowy certyfikat — utwórz nowy certyfikat X.509 z kluczem prywatnym.
  2. Dodaj nowy certyfikat do konfiguracji aplikacji — dodaj nowy certyfikat do TokenDecryptionCredentials tablicy wraz z istniejącym certyfikatem. Najpierw umieść nowy certyfikat w tablicy.
  3. Uładuj nowy klucz publiczny — przekaż plik .cer nowego certyfikatu do rejestracji aplikacji w Microsoft Entra.
  4. Wdróż aplikację — wdróż zaktualizowaną konfigurację, aby aplikacja mogła odszyfrować tokeny przy użyciu dowolnego certyfikatu.
  5. Przełącz aktywny klucz szyfrowania — zaktualizuj tokenEncryptionKeyId na obiekcie aplikacji, aby wskazać atrybut keyId nowego certyfikatu.
  6. Sprawdź — upewnij się, że aplikacja pomyślnie odszyfrowuje tokeny zaszyfrowane przy użyciu nowego certyfikatu.
  7. Usuń stary certyfikat — po okresie prolongaty (co najmniej 24 godziny, aby zezwolić na wygaśnięcie buforowanych tokenów), usuń stary certyfikat zarówno z rejestracji aplikacji, jak i konfiguracji aplikacji.

Konfiguracja podczas rotacji

Podczas okna rotacji, twoje TokenDecryptionCredentials powinno zawierać oba certyfikaty:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2026"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2025"
    }
  ]
}

Wskazówka

Automatyzacja rotacji certyfikatów przy użyciu funkcji automatycznej rotacji usługi Azure Key Vault, w połączeniu z powiadomieniami o zdarzeniach w Key Vault, aby inicjować ponowne wdrażanie aplikacji.

Rozwiązywanie problemów z odszyfrowywaniem tokenów

Skorzystaj z poniższych wskazówek, aby zdiagnozować i rozwiązać typowe problemy z odszyfrowywaniem tokenów.

Błędy odszyfrowywania tokenów

Objaw: Aplikacja zgłasza błąd SecurityTokenDecryptionFailedException lub zwraca błąd 401/500 podczas przetwarzania tokenów.

Typowe przyczyny:

Przyczyna Rozwiązanie
Nie znaleziono certyfikatu Sprawdź, czy certyfikat istnieje w skonfigurowanej lokalizacji (Key Vault, przechowywanie lub ścieżka pliku). Sprawdź, czy aplikacja ma wymagane uprawnienia, aby uzyskać do niej dostęp.
Nieprawidłowy certyfikat Sprawdź, czy odcisk palca certyfikatu w konfiguracji aplikacji jest zgodny z certyfikatem przekazanym do rejestracji aplikacji.
tokenEncryptionKeyId nie ustawiono Ustaw właściwość tokenEncryptionKeyId obiektu aplikacji w Microsoft Entra. Bez tej właściwości platforma tożsamości nie szyfruje tokenów.

Brak klucza prywatnego

Objawem:CryptographicException: The certificate key is not accessible lub InvalidOperationException: Certificate does not have a private key.

Przyczyny i rozwiązania:

  • Certyfikat wyeksportowany bez klucza prywatnego — ponownie wyeksportuj certyfikat w .pfx formacie i upewnij się, że podczas eksportowania dołączono klucz prywatny.
  • Key Vault zasady dostępu do zasobów — Korzystając z Azure Key Vault, upewnij się, że tożsamość aplikacji ma uprawnienie Get dla obu elementów: Certificates i Secrets. Klucz prywatny jest przechowywany jako sekret w Key Vault.
  • Uprawnienia magazynu certyfikatów — W systemie Windows sprawdź, czy tożsamość puli aplikacji lub konto usługi ma dostęp do odczytu do klucza prywatnego. Użyj opcji Zarządzaj kluczami prywatnymi w przystawce MMC magazynu certyfikatów.

Niezgodność algorytmu

Objaw:SecurityTokenDecryptionFailedException komunikat wskazujący na nieobsługiwany algorytm.

Przyczyny i rozwiązania:

  • Nieobsługiwany typ klucza — Microsoft Entra obsługuje certyfikaty RSA na potrzeby szyfrowania tokenów. Upewnij się, że certyfikat używa pary kluczy RSA (nie EC/ECDSA).
  • Rozmiar klucza jest za mały — użyj rozmiaru klucza co najmniej 2048 bitów. Klucze RSA mniejsze niż 2048 bitów mogą zostać odrzucone.
  • Algorithm nie jest obsługiwany — Microsoft Entra używa RSA-OAEP do zawijania kluczy. Upewnij się, że certyfikat i infrastruktura aplikacji obsługują ten algorytm.

Zaszyfrowane tokeny nie są wystawiane

Objawem: Aplikacja odbiera niezaszyfrowane tokeny, mimo że skonfigurowano odszyfrowywanie tokenów.

Przyczyny i rozwiązania:

  • tokenEncryptionKeyId nie skonfigurowano — należy jawnie ustawić tę właściwość za pomocą Microsoft Graph. Przesłanie samego certyfikatu nie wystarczy.
  • Certyfikat wygasł w rejestracji aplikacji — sprawdź, czy certyfikat przekazany do rejestracji aplikacji nie wygasł. W razie potrzeby przekaż nowy certyfikat.
  • Tokeny dostępu nie są szyfrowane — szyfrowanie tokenów dotyczy tylko tokenów identyfikatorów i tokenów SAML . Tokeny dostępu z Microsoft Entra nie są szyfrowane przy użyciu certyfikatu.

Porównanie odszyfrowywania tokenów i poświadczeń klienta

Poświadczenia odszyfrowywania tokenu mają inny cel niż poświadczenia klienta. Aplikacja może używać tego samego certyfikatu dla obu tych certyfikatów lub używać oddzielnych certyfikatów.

W poniższym przykładzie przedstawiono konfigurację, która używa tego samego certyfikatu Key Vault na potrzeby uwierzytelniania i odszyfrowywania tokenu:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ],
    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ]
  }
}

Uwaga / Notatka

Jeśli używasz tego samego certyfikatu w obu celach, certyfikat musi mieć użycia klucza KeyEncipherment i specyfikację klucza KeyExchange (nie Signature). Certyfikaty wygenerowane z KeySpec = Signature działają dla poświadczeń klienta, ale nie działają przy odszyfrowaniu tokenu.

Postępuj zgodnie z najlepszymi rozwiązaniami

Zastosuj te zalecenia podczas implementowania odszyfrowywania tokenów.

Użyj certyfikaty odszyfrowywania Azure Key Vault — przechowuj certyfikaty odszyfrowywania w Key Vault na potrzeby scentralizowanego zarządzania, kontroli dostępu i rejestrowania inspekcji.

Planowanie rotacji — zawsze mają strategię rotacji przed wdrożeniem szyfrowania tokenu. Dołącz zarówno nowe, jak i stare certyfikaty w przedziale czasowym rotacji.

Użyj kluczy RSA 2048-bitowych lub większych — upewnij się, że certyfikaty używają kluczy RSA co najmniej 2048 bitów w celu zapewnienia odpowiednich zabezpieczeń.

Monitorowanie wygaśnięcia certyfikatu — skonfiguruj alerty w Azure Key Vault lub systemie monitorowania, aby powiadomić Cię przed wygaśnięciem certyfikatów.

Testowanie w środowisku przejściowym — przed włączeniem go w środowisku produkcyjnym zweryfikuj szyfrowanie i odszyfrowywanie tokenu w środowisku nieprodukcyjnym.

Nie przechowuj kluczy prywatnych w systemie kontroli wersji — użyj sejfu na klucze, zmiennych środowiskowych lub menedżera zarządzania tajnymi danymi do przechowywania certyfikatów.

Nie usuwaj starego certyfikatu zbyt wcześnie podczas rotacji — zachowaj aktywne oba certyfikaty przez co najmniej 24 godziny, aby zezwolić na wygaśnięcie buforowanych tokenów.

Nie włączaj szyfrowania tokenu bez skonfigurowanego certyfikatu odszyfrowywania — aplikacja nie będzie mogła przetworzyć tokenów, jeśli nie będzie mogła ich odszyfrować.

Treści powiązane

  • Last updated on