Microsoft.Identity.Web'de belirteç şifre çözmeyi yapılandırın.

Bu makale, Microsoft.Identity.Web'de belirteç şifre çözme sertifikalarının nasıl yapılandırılacağını açıklar, böylece uygulamanız Microsoft kimlik platformundan şifrelenmiş belirteçlerin şifresini çözebilir.

varsayılan olarak, Microsoft kimlik platformu belirteçleri (KIMLIK belirteçleri, SAML belirteçleri) imzalı ancak şifrelenmemiş JWT'ler olarak verir. Bir belirteci yakalayan herhangi bir aracı, onun iddialarını okuyabilir. Hassas talepleri işleyen veya katı uyumluluk ortamlarında çalışan uygulamalar için Microsoft kimlik platformu token şifreleme destekler. Kimlik platformu etkinleştirildiğinde, uygulamanıza kayıtlı bir ortak anahtar kullanarak belirteç yükünü şifreler. Yalnızca karşılık gelen özel anahtarı barındıran uygulamanız belirtecin şifresini çözebilir ve okuyabilir.

Belirteç şifrelemesi nasıl çalışır?

Ortak/özel anahtar çifti olan bir sertifika oluşturursunuz.
public anahtarını (.cer dosyası) Microsoft Entra ID uygulama kaydınıza yüklersiniz.
Microsoft kimlik platformu uygulamanız için bir belirteç yayındığında, belirteci ortak anahtarınızı kullanarak şifreler.
Uygulamanız, talepleri işlemeden önce belirtecin şifresini çözmek için özel anahtarı kullanır.

Şifreleme, iki katmanlı bir şema kullanır: Belirteç yükü, simetrik bir içerik şifreleme anahtarı ile şifrelenir ve bu anahtar, sizin ortak anahtarınız kullanılarak sarmalanır (şifrelenir). Microsoft Entra RSA-OAEP ve RSA-OAEP-256 anahtar sarmalama algoritmalarını destekler.

Token çözme işleminin ne zaman yapılandırılacağını belirleme

Uygulamanız aşağıdaki koşullardan birini karşıladığında belirteçlerin şifre çözümünü yapılandırın.

Şifrelenmiş SAML belirteçleri alır: SAML tabanlı çoklu oturum açma kullanan ve uyumluluk veya mevzuat nedeniyle şifrelenmiş SAML onayları gerektiren kurumsal uygulamalar.
Şifrelenmiş kimlik belirteçleri alır : Hassas taleplerin (grup üyelikleri, özel talepler) aktarım sırasında okunmasını korumak için kimlik belirteci şifrelemesini kabul eden web uygulamaları.
Yüksek güvenlikli ortamlarda çalışır : Belirteç gizliliğinin ilke tarafından zorunlu kılındığı kamu, finansal veya sağlık senaryolarındaki uygulamalar.

Uyarı

Jeton şifrelemesi isteğe bağlıdır. Çoğu uygulamanın buna ihtiyacı yoktur. Belirteç şifrelemesini yalnızca belirli bir gereksiniminiz varsa etkinleştirin çünkü işlem karmaşıklığını (sertifika yönetimi, döndürme) ekler ve sorun gidermeyi daha zor hale getirir.

Önkoşulları karşılama

Token şifre çözmeyi yapılandırmadan önce aşağıdaki gereksinimleri kontrol edin.

Özel anahtara sahip X.509 sertifikası — .pfx (PKCS#12) biçiminde bir sertifikaya ihtiyacınız vardır veya uygulamanız (Azure Key Vault, sertifika deposu veya dosya sistemi) tarafından erişilebilen bir konumda depolanmalıdır. Belirteçlerin şifresini çözmek için özel anahtar gereklidir.
Belirteç şifrelemesi için yapılandırılan uygulama kaydı — Sertifikanın ortak anahtarını Microsoft Entra ID uygulama kaydınıza yükleyin. Bu makalenin devamında şifre çözme sertifikasını kaydetme bölümüne bakın.
Microsoft.Identity.Web 2.1.0 veya üzeri — TokenDecryptionCredentials yapılandırma özelliği Microsoft.Identity.Web 2.1.0 ve üzeri sürümlerde kullanılabilir.

appsettings.json dosyasında belirteç şifre çözmeyi yapılandırın

Microsoft. Identity.Web, TokenDecryptionCredentials yapılandırma bölümünüzde AzureAd dizisini kullanır. Bu dizi, ClientCredentials ile aynı kimlik bilgisi açıklama biçimini izler, böylece şifre çözme sertifikalarını Azure Key Vault, sertifika deposundan, dosya yolundan veya Base64 ile kodlanmış bir dizeden yükleyebilirsiniz.

Temel yapılandırmayı ayarlama

Aşağıdaki örnek, Azure Key Vault bir şifre çözme sertifikası yüklemek için en düşük yapılandırmayı gösterir:

{
  "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"
      }
    ]
  }
}

Ek kod gerekmez. Microsoft.Identity.Web, TokenDecryptionCredentials yapılandırmasını algıladığında, belirtilen sertifikayı otomatik olarak yükler ve belirteci çözmesi için OpenID Connect kimlik doğrulama işlevine kaydeder.

Kimlik bilgisi kaynağı seçme

Dizi, TokenDecryptionCredentials ile aynı kaynak türlerini ClientCredentialsdestekler. Aşağıdaki tabloda her seçenek özetlemektedir:

KaynakTürü	Açıklama	Gerekli özellikler
KeyVault	sertifikayı Azure Key Vault yükleyin. Üretim için tavsiye edilir.	`KeyVaultUrl`, `KeyVaultCertificateName`
Parmak İziyle Mağaza	Parmak iziyle yerel sertifika deposundan yükleyin.	`CertificateStorePath`, `CertificateThumbprint`
StoreWithDistinguishedName	Konu ayırt edici adına göre yerel sertifika deposundan yükleyin.	`CertificateStorePath`, `CertificateDistinguishedName`
Path	Dosya sistemindeki bir `.pfx` dosyadan yükleyin.	`CertificateDiskPath`, `CertificatePassword`
Base64Encoded	Base64 ile kodlanmış `.pfx` bir dizeden yükleme (ortam değişkenleri için kullanışlıdır).	`Base64EncodedValue`

Key Vault (üretim için önerilir)

Aşağıdaki yapılandırma, Azure Key Vault bir şifre çözme sertifikası yükler:

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

Uygulamanızın yönetilen kimliği veya hizmet sorumlusunun Key Vault sertifikalarında Get ve List izinleri olmalıdır.

Sertifika deposu (Windows)

Aşağıdaki yapılandırma, parmak iziyle Windows sertifika deposundan bir sertifika yükler:

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

Dosya yolu

Aşağıdaki yapılandırma, disk üzerindeki bir dosyadan sertifika .pfx yükler:

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

Uyarı

Sertifika parolalarını üretim ortamında appsettings.json depolamaktan kaçının. Bunun yerine ortam değişkenlerini, Azure Key Vault başvurularını veya gizli dizi yöneticisini kullanın.

Base64 ile kodlanmış

Aşağıdaki yapılandırma, Base64 ile kodlanmış bir dizeden sertifika yükler:

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

Bu seçenek, sertifikayı bir ortam değişkeni veya CI/CD işlem hattı gizli dizisi aracılığıyla eklediğinizde kullanışlıdır.

Birden çok şifre çözme sertifikası yapılandırma

Dizide TokenDecryptionCredentials birden çok sertifika belirtebilirsiniz. Microsoft.Identity.Web, belirtecin şifresini başarıyla çözene kadar her sertifikayı sırayla dener. Bu özellik sertifika döndürme için gereklidir (bkz. Sertifika döndürme).

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

Şifre çözme sertifikasını Microsoft Entra ID'ye kaydedin.

Microsoft kimlik platformu uygulamanızın belirteçlerini şifrelemesi için sertifikanın public anahtarını uygulama kaydınıza yüklemeniz gerekir:

Microsoft Entra yönetici merkezine oturum açın.
Identity>Applications>Uygulama kayıtları adresine gidin ve uygulamanızı seçin.
Sertifikalar & gizli anahtarlarSertifikalarSertifika yükle.
.cer Şifre çözme sertifikanızın dosyasını (yalnızca ortak anahtar) karşıya yükleyin.
Karşıya yükledikten sonra Parmak İzi değerini not edin; bu değerin uygulamanızın kullandığı sertifikayla eşleşmesi gerekir.

Uygulama için belirteç şifrelemesini etkinleştirme

Sertifikayı karşıya yükledikten sonra, uygulamanızı şifrelenmiş belirteçleri alacak şekilde yapılandırmanız gerekir. Bu yapılandırma şu anda Microsoft Graph API veya PowerShell aracılığıyla kullanılabilir:

Microsoft Graph PowerShell Kullanımı:

# 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
}

Önemli

Microsoft Entra, uygulama nesnesindeki tokenEncryptionKeyId özelliği ile hangi karşıya yüklenen sertifikayı belirteçleri şifrelemek için kullandığını tanımlar. Aynı anda yalnızca bir şifreleme anahtarı etkin olabilir.

Şifre çözme sertifikalarını döndürme

Belirteç şifre çözme için sertifika yenileme, kesintiyi önlemek için dikkatli ve aşamalı bir süreç gerektirir.

Döndürme adımları

Yeni sertifika oluşturma — Özel anahtarla yeni bir X.509 sertifikası oluşturun.
Yeni sertifikayı uygulama yapılandırmanıza ekleyin — Yeni sertifikayı var olan sertifikayla TokenDecryptionCredentials birlikte diziye ekleyin. Yeni sertifikayı diziye önce yerleştirin.
Yeni ortak anahtarı yükleyin — Yeni sertifikanın .cer dosyasını Microsoft Entra'daki uygulama kaydınıza yükleyin.
Uygulamanızı dağıtma — Uygulamanızın iki sertifikayla da belirteçlerin şifresini çözebilmesi için güncelleştirilmiş yapılandırmayı dağıtın.
Etkin şifreleme anahtarını değiştirin — Uygulama nesnesindeki tokenEncryptionKeyId öğesini, yeni sertifikanın keyId öğesine işaret edecek şekilde güncelleyin.
Doğrulama — Uygulamanızın yeni sertifikayla şifrelenmiş belirteçlerin şifresini başarıyla çözdüğünü onaylayın.
Eski sertifikayı kaldırma — Yetkisiz kullanım süresinden (önbelleğe alınmış belirteçlerin süresinin dolmasına izin vermek için en az 24 saat) sonra, eski sertifikayı hem uygulama kaydınızdan hem de uygulama yapılandırmanızdan kaldırın.

Döndürme sırasında yapılandırma

Döndürme penceresi sırasında, TokenDecryptionCredentials iki sertifikayı da içermelidir.

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

Tip

Uygulama yeniden dağıtımlarını tetikleme amacıyla Azure Key Vault otomatik döndürme özelliğini Key Vault olay bildirimleriyle birleştirerek sertifika döndürmeyi otomatikleştirin.

Belirteç şifre çözme sorunlarını giderme

Yaygın token şifre çözme sorunlarını tanımlamak ve çözmek için aşağıdaki kılavuzu kullanın.

Jeton şifre çözme hataları

Belirti: Uygulamanız belirteçleri işlerken bir SecurityTokenDecryptionFailedException veya 401/500 hatası döndürür.

Yaygın nedenler:

Nedeni	Çözüm
Sertifika bulunamadı	Sertifikanın yapılandırılan konumda (Key Vault, depo veya dosya yolunda) var olduğunu doğrulayın. Uygulamanızın erişim için gerekli izinlere sahip olup olmadığını denetleyin.
Yanlış sertifika	Uygulama yapılandırmanızdaki sertifika parmak izinin uygulama kaydına yüklenen sertifikayla eşleştiğinden emin olun.
`tokenEncryptionKeyId` ayarlanmadı	Microsoft Entra'daki uygulama nesnesinde `tokenEncryptionKeyId` özelliğini ayarlayın. Bu özellik olmadan kimlik platformu belirteçleri şifrelemez.

Eksik özel anahtar

Belirti:CryptographicException: The certificate key is not accessible veya .InvalidOperationException: Certificate does not have a private key

Nedenler ve çözümler:

Özel anahtar olmadan dışarı aktarılan sertifika — Sertifikayı .pfx biçimde yeniden dışarı aktarın ve dışarı aktarma sırasında özel anahtarı eklediğinizden emin olun.
Key Vault erişim ilkesi — Azure Key Vault kullanırken, Uygulamanızın kimliğinin hem Certificates hem de Secrets üzerinde Get iznine sahip olduğundan emin olun. Özel anahtar, Key Vault'ta gizli bir bilgi olarak depolanır.
Sertifika deposu izinleri — Windows'da, uygulama havuzu kimliği veya hizmet hesabının özel anahtara okuma erişimine sahip olduğunu doğrulayın. Sertifika deposu MMC ek bileşenindeki Özel Anahtarları Yönet seçeneğini kullanın.

Algoritma uyuşmazlığı

Belirti:SecurityTokenDecryptionFailedException desteklenmeyen bir algoritmaya işaret eden bir ileti.

Nedenler ve çözümler:

Desteklenmeyen anahtar türü — Microsoft Entra belirteç şifrelemesi için RSA sertifikalarını destekler. Sertifikanızın bir RSA anahtar çifti (EC/ECDSA değil) kullandığına emin olun.
Anahtar boyutu çok küçük — En az 2048 bit anahtar boyutu kullanın. 2048 bitten küçük RSA anahtarları reddedilebilir.
Algorithm desteklenmez — Microsoft Entra anahtar sarmalama için RSA-OAEP kullanır. Sertifikanızın ve uygulama altyapınızın bu algoritmayı desteklediğine emin olun.

Şifrelenmiş jetonlar verilmiyor

Belirti: Jeton şifre çözmeyi yapılandırdığınız halde uygulamanız şifresiz jetonlar alıyor.

Nedenler ve çözümler:

tokenEncryptionKeyId yapılandırılmadı — Bu özelliği açıkça Microsoft Graph aracılığıyla ayarlamanız gerekir. Sertifikayı tek başına karşıya yüklemek yeterli değildir.
Uygulama kaydında sertifikanın süresi doldu — Uygulama kaydınıza yüklenen sertifikanın süresinin dolmadığını doğrulayın. Gerekirse yeni bir sertifika yükleyin.
Erişim belirteçleri şifrelenmez — Belirteç şifrelemesi yalnızca kimlik belirteçleri ve SAML belirteçleri için geçerlidir. Microsoft Entra erişim belirteçleri sertifikanızla şifrelenmez.

Token decryption ve istemci kimlik bilgileri karşılaştırma

Belirteç şifre çözme kimlik bilgileri, istemci kimlik bilgileriyle farklı bir amaca hizmet eder. Uygulamanız her ikisi için de aynı sertifikayı kullanabilir veya ayrı sertifikalar kullanabilir.

Aşağıdaki örnekte, hem kimlik doğrulaması hem de belirteç şifre çözme için aynı Key Vault sertifikasını kullanan bir yapılandırma gösterilmektedir:

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

Uyarı

Aynı sertifikayı her iki amaçla da kullandığınızda, sertifikanın KeyEncipherment anahtar kullanımına sahip olması ve anahtar belirtimini KeyExchange (değil Signature) kullanması gerekir. KeySpec = Signature ile oluşturulan sertifikalar istemci kimlik bilgileri için çalışır ancak token çözme için başarısız olur.

En iyi yöntemleri izleyin

Token şifre çözmeyi uygularken bu önerileri dikkate alın.

Azure Key Vault kullanın — Merkezi yönetim, erişim denetimi ve denetim günlüğü için şifre çözme sertifikalarını Key Vault'de depolayın.

Döndürme planı — Belirteç şifrelemesini dağıtmadan önce her zaman bir döndürme stratejisine sahip olun. Döndürme penceresi sırasında hem yeni hem de eski sertifikaları ekleyin.

RSA 2048 bit veya daha büyük anahtarlar kullanın — Sertifikalarınızın yeterli güvenlik için en az 2048 bit RSA anahtarlarını kullandığından emin olun.

Monitor sertifikası süre sonu — sertifikaların süresi dolmadan önce sizi bilgilendirmek için Azure Key Vault veya izleme sisteminizde uyarılar ayarlayın.

Hazırlama ortamında test etme — Üretim ortamında etkinleştirmeden önce üretim dışı bir ortamda belirteç şifrelemesini ve şifre çözmeyi doğrulayın.

Özel anahtarları kaynak denetiminde depolama — Sertifika depolama için Key Vault, ortam değişkenleri veya gizli dizi yöneticisi kullanın.

Döndürme sırasında eski sertifikayı çok erken kaldırmayın — Önbelleğe alınan belirteçlerin süresinin dolmasına izin vermek için her iki sertifikayı da en az 24 saat etkin tutun.

Şifre çözme sertifikası yapılandırılmadan belirteç şifrelemesini etkinleştirme — Uygulamanız şifrelerini çözemezse belirteçleri işleyemez.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-04-29

Microsoft.Identity.Web'de belirteç şifre çözmeyi yapılandırın.

Belirteç şifrelemesi nasıl çalışır?

Token çözme işleminin ne zaman yapılandırılacağını belirleme

Önkoşulları karşılama

appsettings.json dosyasında belirteç şifre çözmeyi yapılandırın

Temel yapılandırmayı ayarlama

Kimlik bilgisi kaynağı seçme

Key Vault (üretim için önerilir)

Sertifika deposu (Windows)

Dosya yolu

Base64 ile kodlanmış

Birden çok şifre çözme sertifikası yapılandırma

Şifre çözme sertifikasını Microsoft Entra ID'ye kaydedin.

Uygulama için belirteç şifrelemesini etkinleştirme

Şifre çözme sertifikalarını döndürme

Döndürme adımları

Döndürme sırasında yapılandırma

Belirteç şifre çözme sorunlarını giderme

Jeton şifre çözme hataları

Eksik özel anahtar

Algoritma uyuşmazlığı

Şifrelenmiş jetonlar verilmiyor

Token decryption ve istemci kimlik bilgileri karşılaştırma

En iyi yöntemleri izleyin

İlgili içerik

Geri Bildirim

Ek kaynaklar