Microsoft kimlik platformu'nde belirteçlere erişme

Erişim belirteçleri istemcilerin korumalı web API'lerini güvenli bir şekilde çağırmasını sağlar. Web API'leri, kimlik doğrulaması ve yetkilendirme gerçekleştirmek için erişim belirteçlerini kullanır.

OAuth belirtimine göre erişim belirteçleri, ayarlanmış biçimi olmayan opak dizelerdir. Bazı kimlik sağlayıcıları (IDP' ler) GUID'leri, bazıları ise şifrelenmiş blobları kullanır. Erişim belirtecinin biçimi, bunu kabul eden API'nin yapılandırmasına bağlı olabilir.

Microsoft kimlik platformu geliştiriciler tarafından kaydedilen özel API'ler ve v2.0adlı v1.0 iki farklı JSON Web Belirteci (JWT) biçimi arasından seçim yapabilir. Microsoft Graph gibi Microsoft tarafından geliştirilen API'ler veya Azure'daki API'ler başka özel belirteç biçimlerine sahiptir. Doğrulanabilen bu özel biçimler şifrelenmiş belirteçler, JWT'ler veya özel JWT benzeri olabilir.

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, içindekiler hakkında ayrıntılı bilgi için erişim belirteci ile 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.

BIR API'nin erişim belirtecinin içindeki talepleri nasıl doğrulayıp kullanabileceğini öğrenmek için aşağıdaki bölümlere bakın.

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 accessTokenAcceptedVersionuygun değeri sağlayarak uygulamalar için sürümü ayarlayın. ve değerleri null1 v1.0 belirteçleriyle sonuçlanır 2 ve v2.0 belirteçleriyle sonuçlanır.

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 belirteci kabul etti.

Microsoft kimlik platformu, herhangi bir sürüm uç noktasından belirteç sürümünün verilmesini destekler. Örneğin değeri olduğunda accessTokenAcceptedVersion2, v1.0 uç noktasını çağırarak bu kaynak için belirteç alan bir istemci v2.0 erişim belirteci alır.

Kaynaklar her zaman talebi kullanarak aud belirteçlerine sahip olur ve belirteç ayrıntılarını değiştirebilen tek uygulamalardır.

Belirteç ömrü

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 istemcinin yeni bir yenileme belirtecini ve erişim belirtecini sessizce almak için yenileme belirtecini kullanması gerekir.

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, 60 ile 90 dakika arasındaki belirteç ömrü ve oturum açma sıklığı aralığıdır.

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. Talep olarak aud yalnızca AppId URI'lerinden birini içeren belirteçleri kabul etmelidir.
  • 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, KIMLIK belirteçlerinin geçerli olmasını sağladığı IDP ile doğrudan iletişim kurar. Erişim belirteçlerini, istemci değil web API'sinin doğrulaması için olduğu gibi doğrulamamalıdır.

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 kaynak için amaçlanan belirteçlerin doğrulanması ve kabullenmesi, karışık yardımcı sorununa bir örnektir.

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 tane 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 Bağlan 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 Bağlan 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 Bağlan Core "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/contoso.onmicrosoft.com/v2.0/.well-known/openid-configurationgibihttps://login.microsoftonline.com/8eaef023-2b34-4da1-9baa-8bc8c9d6a490/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:

  1. Belirteçteki veren talebinin meta verilerdeki veren değeriyle tam olarak eşleşmesini beklemek yerine, uygulamanın veren meta verilerindeki değeri geçerli isteğin hedefi olan tenantid değeriyle değiştirmesi {tenantid} ve ardından tam eşleşmeyi denetlemesi gerekir.

  2. Uygulama, anahtarların issuer kapsamını kısıtlamak için anahtarlar uç noktasından döndürülen ö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":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
        {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
        {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
      ]
    }
    
  3. Standart veren talebi yerine güven sınırı olarak Microsoft Entra tenantid (tid) talebi kullanan uygulamalar, kiracı kimliği talebin bir guid olduğundan ve veren ile kiracı kimliği eşleşmesini sağlamalı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 Bağlan altında olduğu gibi, talepler veren içinde yorumlanır. Diğer bir ifadeyle {"sub":"ABC123","iss":"https://login.microsoftonline.com/8eaef023-2b34-4da1-9baa-8bc8c9d6a490/v2.0","tid":"8eaef023-2b34-4da1-9baa-8bc8c9d6a490"}{"sub":"ABC123","iss":"https://login.microsoftonline.com/82229342-1101-4ab6-817b-70c0747630f3/v2.0","tid":"82229342-1101-4ab6-817b-70c0747630f3"}, gibi talepler sub veren/kiracı bağlamında yorumlandığından, aynı olsa sub da farklı kullanıcıları açıklayın.

İmzayı doğrulama

JWT, karakterle . ayrılmış üç segment içerir. İlk segment üst bilgi, ikinci bölüm 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": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk",
  "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"
}

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 Bağlan 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 Bağlan 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ılan özel anahtara karşılık gelen bu belgeden ortak anahtarı seçmek için JWT üst bilgisindeki talebi kullanabilir kid . Ardından doğru ortak anahtarı ve belirtilen algoritmayı kullanarak imza doğrulaması yapabilir.

Not

Belirteci kid doğrulamak için talebi kullanın. v1.0 belirteçleri hem hem kid de taleplerini içerse de x5t v2.0 belirteçleri yalnızca kid talebi 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, standartlarda özel imzalama anahtarları olan 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=535fb089-9ff3-47b6-9bfb-4f1264799865 bir jwks_uri içerir https://login.microsoftonline.com/{tenant}/discovery/keys?appid=535fb089-9ff3-47b6-9bfb-4f1264799865.

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:

  1. 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.
  2. belirtecin kiracı kimliği (tid talep)
  3. imzalama anahtarını veren.

Tek kiracılı uygulamalar

OpenID Bağlan Core "Veren Tanımlayıcı [...] (Veren) Talebin değeriyle iss tam olarak eşleşmelidir." veya https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configurationgibi https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration 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 (9188040d-6c67-4c5b-b112-36a304b66dad kiracısı için takma ad olan tüketiciler )

Ç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 ve https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration konumunda https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration kullanıma sunar. Bu uç noktalar bir veren değeri döndürür. Bu değer, tarafından parametrized bir tenantidşablondur: https://login.microsoftonline.com/{tenantid}/v2.0. Uygulamalar, her kiracıdaki belirteçleri doğrulamak için aşağıdaki ipuçlarıyla bu kiracıdan bağımsız uç noktaları kullanabilir:

  • İmzalama anahtarı vereni doğrulama
  • Belirteçteki veren talebinin meta verilerdeki veren değeriyle tam olarak eşleşmesini beklemek yerine, uygulamanın veren meta verilerindeki değeri geçerli isteğin hedefi olan kiracı kimliğiyle değiştirmesi {tenantid} ve ardından tam eşleşmeyi (tid belirtecin talebi) denetlemesi gerekir.
  • Talebin tid GUID olduğunu ve talebin iss tam tid talep olduğu {tid} biçimde https://login.microsoftonline.com/{tid}/v2.0 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ı zaman talebi kullanın tid . 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ı veren

Açıklandığı gibi, OpenID Bağlan belgesinden uygulamanız belirteçleri imzalamak için kullanılan anahtarlara erişir. OpenId Bağlan 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ğer {example-tenant-id} bir GUID, etki alanı adı veya ortak kuruluşlar ve tüketicilerle değiştirilebilir

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":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","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ı kısıtlamak için belirteci imzalamak için kullanılan anahtarla ilişkili anahtarlar belgesinin özelliğini kullanmalıdır issuer :

  • Guid değerine https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 sahip veren değeri olan anahtarlar yalnızca belirteçteki iss talep değerle tam olarak eşleştiğinde kullanılmalıdır.
  • gibi https://login.microsoftonline.com/{tenantid}/v2.0 bir şablonlu veren değerine sahip anahtarlar, yalnızca yer tutucunun belirtecindeki talep değiştirildikten tid sonra belirteçteki {tenantid} talep bu değerle eşleştiğinde iss 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 Bağlan altında olduğu gibi, talepler veren içinde yorumlanır. Diğer bir ifadeyle {"sub":"ABC123","iss":"https://login.microsoftonline.com/{example-tenant-id}/v2.0","tid":"{example-tenant-id}"}{"sub":"ABC123","iss":"https://login.microsoftonline.com/{another-tenand-id}/v2.0","tid":"{another-tenant-id}"}, gibi talepler sub veren/kiracı bağlamında yorumlandığından, aynı olsa sub da farklı kullanıcıları açıklayın.

Özet

Vereni ve imzalama anahtarı vereni doğrulamayı yeniden özetleyen bazı sahte kodlar aşağıda verilmiştir:

  1. Yapılandırılmış meta veri URL'sinden anahtarları getirme
  2. Yayımlanan anahtarlardan biriyle imzalanmışsa belirteci denetleyin, aksi takdirde başarısız olur
  3. Alt üst bilgisine göre meta verilerdeki anahtarı tanımlayın. 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;
    

Ayrıca bkz.

Sonraki adımlar

  • Microsoft Entra Id'de kullanılan güvenlik belirteçleri hakkında daha fazla bilgi edinin.