Microsoft kimlik platformu'nde belirteçlere erişme

Erişim belirteçleri yetkilendirme için tasarlanmış bir güvenlik belirteci türüdür ve kimliği doğrulanmış bir kullanıcı adına belirli kaynaklara erişim verir. Erişim belirteçlerindeki bilgiler, bir kullanıcının bir binadaki belirli kapıların kilidini açan anahtarlara benzer şekilde belirli bir kaynağa erişme hakkına sahip olup olmadığını belirler. Belirteçleri oluşturan bu tek tek bilgi parçaları talep olarak adlandırılır. Bu nedenle, bunlar hassas kimlik bilgileridir ve doğru işlenmediği takdirde güvenlik riski oluşturur. Erişim belirteçleri kimlik doğrulaması kanıtı görevi görecek kimlik belirteçlerinden farklıdır.

Erişim belirteçleri istemcilerin korumalı web API'lerini güvenli bir şekilde çağırmasını sağlar. İstemci uygulamaları erişim belirteçlerini alıp kullanasa da, bunları opak dizeler olarak kabul etmelidir. İstemci uygulaması erişim belirteçlerini doğrulamayı denememelidir. Kaynak sunucusu, yetkilendirme kanıtı olarak kabul etmeden önce erişim belirtecini doğrulamalıdır. Belirtecin içeriği yalnızca API'ye yöneliktir; bu da erişim belirteçlerinin opak dizeler olarak ele alınması gerektiği anlamına gelir. Yalnızca doğrulama ve hata ayıklama amacıyla geliştiriciler JWT'lerin kodunu jwt.ms gibi bir site kullanarak çözebilir. Microsoft API'lerinin aldığı belirteçler her zaman çözülebilen bir JWT olmayabilir.

İstemciler, belirtecin içeriği hakkında ayrıntılı bilgi için erişim belirteciyle birlikte döndürülen belirteç yanıtı verilerini kullanmalıdır. İstemci bir erişim belirteci istediğinde, Microsoft kimlik platformu uygulamanın kullanımı için erişim belirteci hakkında bazı meta veriler de döndürür. Bu bilgiler, erişim belirtecinin süre sonu süresini ve geçerli olduğu kapsamları içerir. Bu veriler, uygulamanın erişim belirtecinin kendisini ayrıştırmak zorunda kalmadan erişim belirteçlerinin akıllı önbelleğe alınmasını sağlar. Bu makalede, biçimler, sahiplik, yaşam süreleri ve API'lerin erişim belirtecinin içindeki talepleri nasıl doğrulayıp kullanabileceği gibi erişim belirteçleri hakkında temel bilgiler açıklanmaktadır.

Not

Bu sayfadaki tüm belgeler, not edilenler dışında yalnızca kayıtlı API'ler için verilen belirteçler için geçerlidir. Microsoft'a ait API'ler için verilen belirteçler için geçerli değildir ve bu belirteçler, Microsoft kimlik platformu kayıtlı api için belirteçleri nasıl dağıtacağını doğrulamak için kullanılamaz.

Belirteç biçimleri

Microsoft kimlik platformu iki erişim belirteci sürümü vardır: v1.0 ve v2.0. Bu sürümler, belirteçteki talepleri belirler ve bir web API'sinin belirtecin içeriğini denetleyebildiğinden emin olur.

Web API'lerinde kayıt sırasında varsayılan olarak seçilen aşağıdaki sürümlerden biri vardır:

Yalnızca Microsoft Entra uygulamaları için v1.0. Aşağıdaki örnekte bir v1.0 belirteci gösterilmektedir (anahtarlar değiştirilir ve kişisel bilgiler kaldırılır ve bu da belirteç doğrulamasını engeller):

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd

Tüketici hesaplarını destekleyen uygulamalar için v2.0. Aşağıdaki örnekte bir v2.0 belirteci gösterilmektedir (anahtarlar değiştirilir ve kişisel bilgiler kaldırılır ve bu da belirteç doğrulamasını engeller):

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt

Uygulama bildirimindeki ayara requestedAccessTokenVersionuygun değeri sağlayarak uygulamalar için sürümü ayarlayın. null ve 1 değerleri v1.0 belirteçleri üretir ve 2 değeri v2.0 belirteçleri üretir.

Belirteç sahipliği

Erişim belirteci isteği iki taraf içerir: belirteci isteyen istemci ve belirteci kabul eden kaynak (Web API'si). Belirtecin hedeflediği kaynak (hedef kitlesi) belirteçteki aud talepte tanımlanır. İstemciler belirteci kullanır, ancak bunu anlamamalı veya ayrıştırmaya çalışmamalıdır. Kaynaklar token'ı kabul eder.

Microsoft kimlik platformu, herhangi bir sürüm uç noktasından belirteç sürümünün verilmesini destekler. Örneğin, requestedAccessTokenVersion değerinin 2 olduğu durumda, bu kaynak için bir belirteç almak üzere v1.0 uç noktasını çağıran bir istemci v2.0 erişim belirteci alır.

Kaynaklar, aud talebini kullanarak her zaman kendi belirteçlerinin sahibi olur ve belirteç ayrıntılarını değiştirebilen tek uygulamalardır.

Belirteç süresi

Erişim belirtecinin varsayılan ömrü değişkendir. verildiğinde, Microsoft kimlik platformu erişim belirtecinin varsayılan ömrü olarak 60-90 dakika (ortalama 75 dakika) arasında rastgele bir değer atar. Değişim, erişim belirteci talebini bir zamana yayarak hizmet dayanıklılığını artırır ve bu sayede Microsoft Entra Id trafiğinde saatlik ani artışlar önlenir.

Koşullu Erişim kullanmayan kiracılar, Microsoft Teams ve Microsoft 365 gibi istemciler için iki saatlik varsayılan erişim belirteci ömrüne sahiptir.

İstemci uygulamasının uygulama oturumunun ne sıklıkta sona ereceğini ve kullanıcının ne sıklıkta yeniden kimlik doğrulaması (sessiz veya etkileşimli) gerektirdiğini denetlemek için erişim belirtecinin ömrünü ayarlayın. Varsayılan erişim belirteci yaşam süresi varyasyonunu geçersiz kılmak için Yapılandırılabilir belirteç ömrü (CTL) kullanın.

Sürekli Erişim Değerlendirmesi (CAE) etkinleştirilmiş kuruluşlara varsayılan belirteç yaşam süresi varyasyonu uygulayın. Kuruluşlar CTL ilkelerini kullansa bile varsayılan belirteç ömrü varyasyonunu uygulayın. Uzun ömürlü belirteç ömrü için varsayılan belirteç ömrü 20 ila 28 saat arasında değişir. Erişim belirtecinin süresi dolduğunda istemci, yeni bir yenileme belirteci ve erişim belirtecini sessizce almak için yenileme belirtecini kullanmalıdır.

Oturum açma sıklığını zorlamak için Koşullu Erişim oturum açma sıklığı (SIF) kullanan kuruluşlar, varsayılan erişim belirteci yaşam süresi varyasyonunu geçersiz kılamaz. Kuruluşlar SIF kullandığında, istemci için kimlik bilgisi istemleri arasındaki süre, oturum açma sıklığı aralığından başlayarak 60 ila 90 dakika arasındaki belirteç ömrü süresine kadar değişebilir.

Burada, varsayılan belirteç ömrü varyasyonunun oturum açma sıklığıyla nasıl çalıştığına dair bir örnek verilmiştir. Bir kuruluşun oturum açma sıklığını saatte bir gerçekleşecek şekilde ayarlı olduğunu düşünelim. Belirteç yaşam süresi varyasyonu nedeniyle belirtecin ömrü 60-90 dakika arasında olduğunda, gerçek oturum açma aralığı 1 saat ile 2,5 saat arasında herhangi bir yerde gerçekleşir.

Bir saatlik ömrü olan belirteci olan bir kullanıcı 59 dakikada etkileşimli oturum açma işlemi gerçekleştiriyorsa, oturum açma SIF eşiğinin altında olduğundan kimlik bilgisi istemi yoktur. Yeni bir belirtecin ömrü 90 dakikaysa, kullanıcı bir buçuk saat daha kimlik bilgisi istemi görmez. Sessiz yenileme girişimi sırasında, toplam oturum uzunluğu 1 saatlik oturum açma sıklığı ayarını aştığı için Microsoft Entra Id kimlik bilgisi istem gerektirir. Bu örnekte, SIF aralığı ve belirteç ömrü varyasyonu nedeniyle kimlik bilgisi istemleri arasındaki zaman farkı 2,5 saat olacaktır.

Belirteçleri doğrulama

Tüm uygulamalar belirteçleri doğrulamamalıdır. Yalnızca belirli senaryolarda uygulamalar bir belirteci doğrulamalıdır:

Web API'leri, bir istemci tarafından kendilerine gönderilen erişim belirteçlerini doğrulamalıdır. aud talebi olarak AppId URI'lerinden birini içeren belirteçleri yalnızca kabul etmelidirler.
Web uygulamaları, bir kullanıcının verilerine erişime izin vermeden veya oturum oluşturmadan önce karma akışta kullanıcının tarayıcısını kullanarak kendilerine gönderilen kimlik belirteçlerini doğrulamalıdır.

Daha önce açıklanan senaryolardan hiçbiri geçerli değilse belirteci doğrulamaya gerek yoktur. Yerel, masaüstü veya tek sayfalı uygulamalar gibi genel istemciler kimlik belirteçlerini doğrulama avantajından yararlanmaz çünkü uygulama, SSL korumasının kimlik belirteçlerinin geçerli olmasını sağladığı IDP ile doğrudan iletişim kurar. Erişim belirteçlerini doğrulamamalıdırlar; çünkü bunları doğrulaması gereken istemci değil, web API'sidir.

API'ler ve web uygulamaları yalnızca uygulamayla eşleşen bir aud talebi olan belirteçleri doğrulamalıdır. Diğer kaynakların özel belirteç doğrulama kuralları olabilir. Örneğin, Microsoft Graph belirteçlerini özel biçimleri nedeniyle bu kurallara göre doğrulayamazsınız. Başka bir kaynağa yönelik belirteçlerin doğrulanması ve kabul edilmesi, confused deputy probleminin bir örneğidir.

Uygulamanın bir kimlik belirtecini veya erişim belirtecini doğrulaması gerekiyorsa, önce belirtecin imzasını ve vereni OpenID bulma belgesindeki değerlerle karşılaştırarak doğrulamalıdır.

Microsoft Entra ara yazılımının erişim belirteçlerini doğrulamaya yönelik yerleşik özellikleri vardır. Uygun dilde bir örnek bulmak için örneklere bakın. Ayrıca, JWT doğrulaması için kullanılabilecek birkaç üçüncü taraf açık kaynak kitaplığı vardır. Kimlik doğrulama kitaplıkları ve kod örnekleri hakkında daha fazla bilgi için bkz . kimlik doğrulama kitaplıkları. Web uygulamanız veya web API'niz ASP.NET veya ASP.NET Core'daysa, doğrulamayı sizin yerinize gerçekleştiren Microsoft.Identity.Web'i kullanın.

v1.0 ve v2.0 belirteçleri

Web uygulamanız/API'niz bir v1.0 belirtecini (ver talep ="1.0") doğrularken, web API'niz için yapılandırılan yetkili bir v2.0 yetkilisi olsa bile, v1.0 uç noktasından (https://login.microsoftonline.com/{example-tenant-id}/.well-known/openid-configuration) OpenID Connect meta veri belgesini okuması gerekir.
Web uygulamanız/API'niz bir v2.0 belirtecini (ver talep ="2.0") doğrularken, web API'niz için yapılandırılan yetkili bir v1.0 yetkilisi olsa bile, v2.0 uç noktasından (https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration) OpenID Connect meta veri belgesini okuması gerekir.

Aşağıdaki örneklerde uygulamanızın bir v2.0 erişim belirtecini doğruladığını varsayalım (ve bu nedenle OIDC meta veri belgelerinin ve anahtarlarının v2.0 sürümlerine başvurun). v1.0 belirteçlerini doğrularsanız URL'deki "/v2.0" öğesini kaldırmanız yeter.

Vereni doğrulama

OpenID Connect Core şöyle diyor: "Veren Tanımlayıcı [...] ISS (veren) Talebi değeriyle tam olarak eşleşmelidir." Kiracıya özgü meta veri uç noktasını (veya https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/.well-known/openid-configurationgibihttps://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration) kullanan uygulamalar için gereken tek şey budur.

Microsoft Entra Id, adresinde https://login.microsoftonline.com/common/v2.0/.well-known/openid-configurationbulunan belgenin kiracıdan bağımsız bir sürümüne sahiptir. Bu uç nokta bir veren değeri https://login.microsoftonline.com/{tenantid}/v2.0döndürür. Uygulamalar, aşağıdaki değişikliklerle her kiracıdan belirteçleri doğrulamak için bu kiracıdan bağımsız uç noktayı kullanabilir:

Belirteçteki düzenleyici talebinin meta verilerdeki düzenleyici değeriyle tam olarak eşleşmesini beklemek yerine, uygulama düzenleyici meta verilerindeki {tenantid} değerini geçerli isteğin hedefi olan kiracı kimliğiyle değiştirmeli ve ardından tam eşleşmeyi kontrol etmelidir.

Uygulama, anahtarların kapsamını kısıtlamak için keys uç noktasından döndürülen issuer özelliğini kullanmalıdır.

gibi https://login.microsoftonline.com/{tenantid}/v2.0 bir veren değerine sahip anahtarlar, eşleşen belirteç verenlerle birlikte kullanılabilir.
Gibi https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 bir veren değerine sahip anahtarlar yalnızca tam eşleşme ile kullanılmalıdır.

Microsoft Entra kiracıdan bağımsız anahtar uç noktası (https://login.microsoftonline.com/common/discovery/v2.0/keys) aşağıdaki gibi bir belge döndürür:

{
  "keys":[
    {"kty":"RSA","use":"sig","kid":"A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u","x5t":"A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w","x5t":"C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"E3fH4iJ5kL6mN7oP8qR9sT0uV1wX2y","x5t":"E3fH4iJ5kL6mN7oP8qR9sT0uV1wX2y","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

Standart veren talebi yerine güven sınırı olarak Microsoft Entra kiracı kimliği (tid) talebini kullanan uygulamalar, kiracı kimliği talebinin GUID olduğundan ve veren ile kiracı kimliğinin birbiriyle eşleştiğinden emin olmalıdır.

Kiracıdan bağımsız meta verilerin kullanılması, birçok kiracının belirteçlerini kabul eden uygulamalar için daha verimlidir.

Not

Microsoft Entra kiracıdan bağımsız meta verilerle talepler kiracı içinde yorumlanmalıdır, standart OpenID Connect altında olduğu gibi, talepler verenin içinde yorumlanır. Yani, {"sub":"ABC123","iss":"https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0","tid":"aaaabbbb-0000-cccc-1111-dddd2222eeee"} ve {"sub":"ABC123","iss":"https://login.microsoftonline.com/bbbbcccc-1111-dddd-2222-eeee3333ffff/v2.0","tid":"bbbbcccc-1111-dddd-2222-eeee3333ffff"}, sub aynı olsa da farklı kullanıcıları tanımlar; çünkü sub gibi claim’ler veren/tenant bağlamında yorumlanır.

İmzayı doğrulama

JWT, karakterle . ayrılmış üç segment içerir. İlk segment üst bilgidir, ikincisi gövde, üçüncüsü ise imzadır. Belirtecin orijinalliğini değerlendirmek için imza kesimini kullanın.

Microsoft Entra ID, RS256 gibi endüstri standardı asimetrik şifreleme algoritmaları kullanılarak imzalanan belirteçleri verir. JWT üst bilgisi, belirteci imzalamak için kullanılan anahtar ve şifreleme yöntemi hakkında bilgi içerir:

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "H4iJ5kL6mN7oP8qR9sT0uV1wX2yZ3a",
  "kid": "H4iJ5kL6mN7oP8qR9sT0uV1wX2yZ3a"
}

Talep alg , belirteci imzalamak için kullanılan algoritmayı, talep ise kid belirteci doğrulamak için kullanılan belirli bir ortak anahtarı gösterir.

Belirli bir zamanda, Microsoft Entra Id belirli bir ortak-özel anahtar çifti kümesinden herhangi birini kullanarak bir kimlik belirtecini imzalar. Microsoft Entra Id olası anahtar kümesini düzenli aralıklarla döndürür, bu nedenle uygulamayı bu anahtar değişikliklerini otomatik olarak işleyecek şekilde yazın. Microsoft Entra Id tarafından kullanılan ortak anahtar güncelleştirmelerini denetlemek için makul bir sıklık 24 saatte bir yapılır.

Aşağıdaki konumda bulunan OpenID Connect meta veri belgesini kullanarak imzayı doğrulamak için gereken imzalama anahtarı verilerini alın:

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

İpucu

Bunu tarayıcıda deneyin: URL

Aşağıdaki bilgiler meta veri belgesini açıklar:

OpenID Connect kimlik doğrulaması yapmak için gereken çeşitli uç noktaların konumu gibi birkaç yararlı bilgi parçası içeren bir JSON nesnesidir.
belirteçleri imzalamak için kullanılan özel anahtarlara karşılık gelen ortak anahtar kümesinin konumunu veren bir jwks_uriiçerir. konumunda jwks_uri bulunan JSON Web Anahtarı (JWK), o anda kullanımda olan tüm ortak anahtar bilgilerini içerir. RFC 7517 , JWK biçimini açıklar. Uygulama, belirli bir belirteci imzalamak için kullanılmış özel anahtara karşılık gelen ortak anahtarı bu belgede yer alan anahtarlar arasından seçmek için JWT üst bilgisindeki kid claim’ini kullanabilir. Ardından doğru ortak anahtarı ve belirtilen algoritmayı kullanarak imza doğrulaması yapabilir.

Not

Belirteci doğrulamak için kid claim’ini kullanın. v1.0 belirteçleri hem x5t hem de kid istemlerini içerse de v2.0 belirteçleri yalnızca kid istemini içerir.

İmza doğrulaması yapmak bu belgenin kapsamı dışındadır. Gerekirse imza doğrulamasına yardımcı olmak için kullanılabilecek birçok açık kaynak kitaplık vardır. Ancak Microsoft kimlik platformu, standartlara ek olarak özel imzalama anahtarları biçiminde bir belirteç imzalama uzantısına sahiptir.

Uygulamanın, talep eşleme özelliğini kullanmanın bir sonucu olarak özel imzalama anahtarları varsa, uygulama kimliğini içeren bir appid sorgu parametresi ekleyin. Doğrulama için, uygulamanın imzalama anahtarı bilgilerini gösteren öğesini kullanın jwks_uri . Örneğin: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=00001111-aaaa-2222-bbbb-3333cccc4444, https://login.microsoftonline.com/{tenant}/discovery/keys?appid=00001111-aaaa-2222-bbbb-3333cccc4444 öğesinden bir jwks_uri içerir.

Vereni doğrulama

Kimlik belirteçlerini doğrulayan web uygulamaları ve erişim belirteçlerini doğrulayan web API'lerinin belirtecin verenini (iss talebi) şu şekilde doğrulamaları gerekir:

uygulama yapılandırması (yetkili) ile ilişkili OpenID connect meta veri belgesinde bulunan veren. Doğrulanması gereken meta veri belgesi aşağıdakilere bağlıdır:
- belirtecin sürümü
- uygulamanızın desteklediği hesaplar.
belirtecin kiracı kimliği (tid talep)
imzalama anahtarını veren.

Tek müşterili uygulamalar

OpenID Connect Core şöyle der: "Yayımlayıcı Tanımlayıcısı [...] iss (issuer) iddiasının değeriyle tam olarak eşleşmelidir." https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration veya https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration gibi kiracıya özgü meta veri uç noktası kullanan uygulamalar için.

Tek kiracılı uygulamalar, şu desteği sağlayan uygulamalardır:

Bir kuruluş dizinindeki hesaplar (yalnızca example-tenant-id ): https://login.microsoftonline.com/{example-tenant-id}
Yalnızca kişisel Microsoft hesapları: https://login.microsoftonline.com/consumers (“consumers”, 9188040d-6c67-4c5b-b112-36a304b66dad kiracısının takma adıdır)

Çok kiracılı uygulamalar

Microsoft Entra ID, çok kiracılı uygulamaları da destekler. Bu uygulamalar şunları destekler:

Herhangi bir kuruluş dizinindeki hesaplar (herhangi bir Microsoft Entra dizini): https://login.microsoftonline.com/organizations
Herhangi bir kuruluş dizinindeki hesaplar (herhangi bir Microsoft Entra dizini) ve kişisel Microsoft hesapları (örneğin, Skype, XBox): https://login.microsoftonline.com/common

Bu uygulamalar için Microsoft Entra ID, OIDC belgesinin kiracıdan bağımsız sürümlerini sırasıyla https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration ve https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration konumlarında sunar. Bu uç noktalar, tenantid tarafından parametreleştirilmiş bir şablon olan bir issuer değeri döndürür: https://login.microsoftonline.com/{tenantid}/v2.0. Uygulamalar, aşağıdaki koşullara tabi olarak her kiracıdan gelen belirteçleri doğrulamak için bu kiracıdan bağımsız uç noktaları kullanabilir:

İmzalama anahtarı vereni doğrulama
Belirteçteki veren isteminin meta verilerdeki veren değeriyle tam olarak eşleşmesini beklemek yerine, uygulama veren meta verilerindeki {tenantid} değerini geçerli isteğin hedefi olan kiracı kimliğiyle değiştirmeli ve ardından belirtecin tid isteminin tam olarak eşleşip eşleşmediğini denetlemelidir.
tid claim’inin bir GUID olduğunu ve iss claim’inin, {tid}’ün tam olarak tid claim’i olduğu https://login.microsoftonline.com/{tid}/v2.0 biçiminde olduğunu doğrulayın. Bu doğrulama, kiracıyı verene ve bir güven zinciri oluşturan imzalama anahtarının kapsamına geri bağlar.
Talebin konusuyla ilişkili verileri bulduklarında tid talebini kullanın. Başka bir deyişle talep, tid kullanıcının verilerine erişmek için kullanılan anahtarın bir parçası olmalıdır.

İmzalama anahtarı vereni doğrulama

v2.0 kiracıdan bağımsız meta verileri kullanan uygulamaların imzalama anahtarı vereni doğrulaması gerekir.

Anahtarlar belgesi ve imzalama anahtarı yayımcısı

Açıklandığı gibi, OpenID Connect belgesinden uygulamanız belirteçleri imzalamak için kullanılan anahtarlara erişir. OpenIdConnect belgesinin jwks_uri özelliğinde gösterilen URL'ye erişerek ilgili anahtarlar belgesini alır.

 "jwks_uri": "https://login.microsoftonline.com/{example-tenant-id}/discovery/v2.0/keys",

Değerin {example-tenant-id} yerini GUID, etki alanı adı veya yaygın **kuruluşlar ve tüketiciler alabilir.

keys Azure AD v2.0 tarafından kullanıma sunulan belgeler, her anahtar için bu imzalama anahtarını kullanan vereni içerir. Örneğin kiracıdan bağımsız "ortak" anahtar uç noktası https://login.microsoftonline.com/common/discovery/v2.0/keys aşağıdaki gibi bir belge döndürür:

{
  "keys":[
    {"kty":"RSA","use":"sig","kid":"A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u","x5t":"A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w","x5t":"C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"E3fH4iJ5kL6mN7oP8qR9sT0uV1wX2y","x5t":"E3fH4iJ5kL6mN7oP8qR9sT0uV1wX2y","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

İmzalama anahtarı verenin doğrulanması

Uygulama, anahtarların kapsamını sınırlamak amacıyla, belirteci imzalamak için kullanılan anahtarla ilişkili anahtarlar belgesinin issuer özelliğini kullanmalıdır:

https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 gibi bir GUID içeren yayımcı değerine sahip anahtarlar, yalnızca belirteçteki iss claim’i bu değerle tam olarak eşleştiğinde kullanılmalıdır.
https://login.microsoftonline.com/{tenantid}/v2.0 gibi şablonlu bir düzenleyici değerine sahip anahtarlar, yalnızca belirteçteki iss talebi, belirteçteki tid talebi {tenantid} yer tutucusunun yerine konulduktan sonra bu değerle eşleşiyorsa kullanılmalıdır.

Kiracıdan bağımsız meta verilerin kullanılması, birçok kiracıdan belirteç kabul eden uygulamalar için daha verimlidir.

Not

Microsoft Entra kiracıdan bağımsız meta verilerle talepler kiracı içinde yorumlanmalıdır, standart OpenID Connect altında olduğu gibi, talepler verenin içinde yorumlanır. Yani, {"sub":"ABC123","iss":"https://login.microsoftonline.com/{example-tenant-id}/v2.0","tid":"{example-tenant-id}"} ve {"sub":"ABC123","iss":"https://login.microsoftonline.com/{another-tenand-id}/v2.0","tid":"{another-tenant-id}"}, sub aynı olsa da farklı kullanıcıları tanımlar; çünkü sub gibi claim’ler veren/tenant bağlamında yorumlanır.

Özet

Aşağıda, verenin ve imzalama anahtarı vereninin nasıl doğrulanacağını özetleyen bir sözde kod yer almaktadır:

Yapılandırılmış meta veri URL'sinden anahtarları getirme
Belirteci, yayımlanmış anahtarlardan biriyle imzalanmışsa denetleyin; değilse başarısız sayın.

kid başlığına göre meta verilerdeki anahtarı belirleyin. Meta veri belgesindeki anahtara eklenen "veren" özelliğini denetleyin:

var issuer = metadata["kid"].issuer;
if (issuer.contains("{tenantId}", CaseInvariant)) issuer = issuer.Replace("{tenantid}", token["tid"], CaseInvariant);
if (issuer != token["iss"]) throw validationException;
if (configuration.allowedIssuer != "*" && configuration.allowedIssuer != issuer) throw validationException;
var issUri = new Uri(token["iss"]);
if (issUri.Segments.Count < 1) throw validationException;
if (issUri.Segments[1] != token["tid"]) throw validationException;

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-05-14

Microsoft kimlik platformu'nde belirteçlere erişme

Belirteç biçimleri

Belirteç sahipliği

Belirteç süresi

Belirteçleri doğrulama

v1.0 ve v2.0 belirteçleri

Vereni doğrulama

İmzayı doğrulama

Vereni doğrulama

Tek müşterili uygulamalar

Çok kiracılı uygulamalar

İmzalama anahtarı vereni doğrulama

Anahtarlar belgesi ve imzalama anahtarı yayımcısı

İmzalama anahtarı verenin doğrulanması

Özet

İlgili içerik

Geri Bildirim

Ek kaynaklar