Aracılığıyla paylaş

İsteğe bağlı talep başvurusu

  • Makale

İsteğe bağlı beyanları kullanarak:

  • Uygulamanız için belirteçlere eklenecek talepleri seçin.
  • Microsoft kimlik platformunun belirteçlerde döndürdüğü bazı beyanların davranışını değiştirebilirsiniz.
  • Uygulamanız için özel beyanlar ekleyebilir ve bunlara erişebilirsiniz.

İsteğe bağlı talepler hem v1.0 hem de v2.0 biçim belirteçlerinde ve SAML belirteçlerinde destekleniyor olsa da, v1.0'dan v2.0'a geçerken değerlerinin çoğunu sağlar. Microsoft kimlik platformu, istemciler tarafından en iyi performansı sağlamak için daha küçük belirteç boyutları kullanılır. Sonuç olarak, daha önce erişim ve kimlik belirteçlerine dahil edilen çeşitli talepler artık v2.0 belirteçlerinde mevcut değildir ve uygulama başına özel olarak istenmelidir.

Hesap Türü v1.0 belirteçleri v2.0 belirteçleri
Kişisel Microsoft hesabı Yok Desteklenir
Microsoft Entra hesabı Desteklenir Desteklenir

v1.0 ve v2.0 isteğe bağlı talep kümesi

Uygulamaların kullanması için varsayılan olarak kullanılabilen isteğe bağlı talepler kümesi aşağıdaki tabloda listelenmiştir. Uygulamanız için isteğe bağlı talepler eklemek için uzantı özniteliklerinde ve dizin uzantılarında özel veriler kullanabilirsiniz. Erişim belirtecine talep eklediğinizde, talepler uygulama tarafından istenen taleplere değil uygulama için istenen erişim belirteçlerine (bir web API'si) uygulanır. İstemci API'nize nasıl erişirse erişsin, API'nizde kimlik doğrulaması yapmak için kullanılan erişim belirtecinde doğru veriler bulunur.

Not

Bu taleplerin çoğu v1.0 ve v2.0 belirteçleri için JWT'lere dahil edilebilir, ancak Belirteç Türü sütununda belirtilen durumlar dışında SAML belirteçlerine dahil edilemez. Tüketici hesapları, bu taleplerin Kullanıcı Türü sütununda işaretlenmiş bir alt kümesini destekler. Listelenen taleplerin çoğu tüketici kullanıcıları için geçerli değildir (kiracıları yoktur, bu nedenle tenant_ctry değeri yoktur).

Aşağıdaki tabloda v1.0 ve v2.0 isteğe bağlı talep kümesi listelenir.

Veri Akışı Adı Açıklama Belirteç Türü Kullanıcı Türü Notlar
acct Kiracıdaki kullanıcı hesabı durumu JWT, SAML Kullanıcı kiracının bir üyesiyse, değeri olur 0. Konuksa, değeri olur 1.
acrs Kimlik Doğrulama Bağlam Kimlikleri JWT Microsoft Entra Kimlik Taşıyıcının gerçekleştirmeye uygun olduğu işlemlerin Kimlik Doğrulama Bağlam kimliklerini gösterir. Kimlik Doğrulama Bağlam Kimlikleri, uygulamanızın ve hizmetlerinizin içinden adım adım kimlik doğrulaması talebini tetikleme amacıyla kullanılabilir. Genellikle taleple xms_cc birlikte kullanılır.
auth_time Kullanıcının son kimlik doğrulamasından geçtiği zaman. JWT
ctry Kullanıcının ülkesi/bölgesi JWT Bu talep mevcutsa ve alanın değeri FR, JP, SZ gibi standart iki harfli bir ülke/bölge koduysa döndürülür.
email Bu kullanıcının bildirilen e-posta adresi JWT, SAML MSA, Microsoft Entra ID Kullanıcı kiracıda bir konuksa bu değer varsayılan olarak eklenir. Yönetilen kullanıcılar için (kiracıdaki kullanıcılar), bu isteğe bağlı talep aracılığıyla veya yalnızca v2.0'da OpenID kapsamıyla istenmelidir. Bu değerin doğru olduğu garanti edilmediğinden ve zaman içinde değiştirilebilir olduğundan, hiçbir zaman yetkilendirme için veya bir kullanıcının verilerini kaydetmek için kullanmayın. Daha fazla bilgi için bkz . Kullanıcının bu verilere erişme izni olduğunu doğrulama. Yetkilendirme için e-posta talebi kullanıyorsanız, daha güvenli bir beyana geçmek için bir geçiş gerçekleştirmenizi öneririz. Uygulamanızda adreslenebilir bir e-posta adresi gerekiyorsa, bu talebi öneri olarak kullanarak veya UX'inizde önceden doldurarak doğrudan kullanıcıdan bu verileri isteyin.
fwd IP Adresi JWT İstekte bulunan istemcinin özgün adresini ekler (bir sanal ağın içindeyken).
groups Grup talepleri için isteğe bağlı biçimlendirme JWT, SAML Talepgroups, uygulama bildiriminde GroupMembershipClaims ayarıyla birlikte kullanılır ve bu ayarın da ayarlanması gerekir.
idtyp Belirteç türü JWT erişim belirteçleri Özel: yalnızca uygulama erişim belirteçlerinde Değer, app belirteç yalnızca uygulama belirteci olduğunda kullanılır. Bu talep, bir API'nin belirtecin uygulama belirteci mi yoksa uygulama+kullanıcı belirteci mi olduğunu belirlemesinin en doğru yoludur.
login_hint Oturum açma ipucu JWT MSA, Microsoft Entra ID 64 tabanında kodlanmış, opak, güvenilir bir oturum açma ipucu talebi. Bu değeri değiştirmeyin. Bu talep, SSO almak için tüm akışlarda OAuth parametresi için login_hint kullanılacak en iyi değerdir. Uygulamalar arasında da sessizce SSO'ya yardımcı olmak için geçirilebilir - A uygulaması bir kullanıcıda oturum açabilir, talebi okuyabilir login_hint ve kullanıcı B uygulamasına götüren bir bağlantıyı seçtiğinde sorgu dizesinde veya parçasında talebi ve geçerli kiracı bağlamını B uygulamasına gönderebilir. Yarış koşullarından ve güvenilirlik sorunlarından kaçınmak için talep, login_hint kullanıcının geçerli kiracısını içermez ve kullanıldığında varsayılan olarak kullanıcının ev kiracısını kullanır. Kullanıcının başka bir kiracıdan geldiği konuk senaryosunda, oturum açma isteğinde bir kiracı tanımlayıcısı sağlanmalıdır. ve aynı bilgileri iş ortağı olduğunuz uygulamalara geçirin. Bu talep, SDK'nızın mevcut login_hint işlevselliğiyle birlikte kullanıma sunulmak üzere tasarlanmıştır.
sid Oturum başına kullanıcı oturumu kapatma için kullanılan oturum kimliği JWT Kişisel ve Microsoft Entra hesapları.
tenant_ctry Kaynak kiracının ülkesi/bölgesi JWT ctry Yönetici tarafından kiracı düzeyinde ayarlanması dışında aynı. Standart iki harfli bir değer de olmalıdır.
tenant_region_scope Kaynak kiracısının bölgesi JWT
upn UserPrincipalName JWT, SAML Kullanıcı için parametresiyle username_hint kullanılabilecek bir tanımlayıcı. Kullanıcı için dayanıklı bir tanımlayıcı değildir ve yetkilendirme için veya kullanıcı bilgilerini benzersiz olarak tanımlamak için (örneğin, veritabanı anahtarı olarak) kullanılmamalıdır. Bunun yerine, veritabanı anahtarı olarak kullanıcı nesne kimliğini (oid) kullanın. Daha fazla bilgi için bkz . Talepleri doğrulayarak uygulamaların ve API'lerin güvenliğini sağlama. Alternatif oturum açma kimliğiyle oturum açan kullanıcılara Kullanıcı Asıl Adları (UPN) gösterilmemelidir. Bunun yerine, kullanıcıya oturum açma durumunu görüntülemek için aşağıdaki kimlik belirteci taleplerini kullanın: preferred_username veya unique_name v1 belirteçleri ve preferred_username v2 belirteçleri için. Bu talep otomatik olarak dahil olsa da, konuk kullanıcı durumunda davranışını değiştirmek için diğer özellikleri eklemek için isteğe bağlı bir talep olarak belirtebilirsiniz. Talebi kullanım için login_hint kullanmalısınızlogin_hint. UPN gibi insan tarafından okunabilen tanımlayıcılar güvenilir değildir.
verified_primary_email Kullanıcının PrimaryAuthoritativeEmail kaynağı JWT
verified_secondary_email Kullanıcının SecondaryAuthoritativeEmail kaynağı JWT
vnet Sanal ağ tanımlayıcı bilgileri. JWT
xms_cc İstemci Özellikleri JWT Microsoft Entra Kimlik Belirteci alan istemci uygulamasının talep sınamalarını işleyip işleyemeyeceğini gösterir. Genellikle talep acrsile birlikte kullanılır. Bu talep, Koşullu Erişim ve Sürekli Erişim Değerlendirme senaryolarında yaygın olarak kullanılır. Belirtecin verildiği kaynak sunucusu veya hizmet uygulaması, belirteçte bu talebin varlığını denetler. Erişim belirtecindeki değeri cp1 , bir istemci uygulamasının talep sınamasını işleyebilme becerisini belirlemenin yetkili yoludur. Daha fazla bilgi için bkz . Talep sınamaları, talep istekleri ve istemci özellikleri.
xms_edov Kullanıcının e-posta etki alanı sahibinin doğrulanıp doğrulanmadığını gösteren Boole değeri. JWT E-postanın, kullanıcı hesabının bulunduğu kiracıya ait olması ve kiracı yöneticisinin etki alanı doğrulamasını yapmış olması durumunda etki alanının doğrulandığı kabul edilir. Ayrıca, e-posta bir Microsoft hesabından (MSA), google hesabından veya tek seferlik geçiş kodu (OTP) akışı kullanılarak kimlik doğrulaması için kullanılmalıdır. Facebook ve SAML/WS-Fed hesaplarının doğrulanmış etki alanları yoktur . Bu talebin belirteçte döndürülecek olması için talebin email varlığı gereklidir.
xms_pdl Tercih edilen veri konumu JWT Multi-Geo kiracıları için tercih edilen veri konumu, kullanıcının bulunduğu coğrafi bölgeyi gösteren üç harfli koddur. Daha fazla bilgi için tercih edilen veri konumu hakkında Microsoft Entra Bağlan belgelerine bakın.
xms_pl Kullanıcı tarafından tercih edilen dil JWT Ayarlandıysa kullanıcının tercih ettiği dil. Konuk erişim senaryolarında kendi ev kiracısından kaynaklanmıştır. Biçimlendirilmiş LL-CC ("en-us").
xms_tpl Kiracı tercih edilen dili JWT Kaynak kiracısının tercih edilen dili (ayarlandıysa). Biçimlendirilmiş LL ("en").
ztdid Sıfır dokunma dağıtım kimliği JWT için Windows AutoPilotkullanılan cihaz kimliği.

Uyarı

Erişim belirtecindeki kullanıcının verilere erişimi olup olmadığını depolamak veya belirlemek için hiçbir zaman değerleri kullanmayın emailupn veya talep etmeyin. Bunlar gibi değiştirilebilir talep değerleri zaman içinde değişebilir ve bu da güvenli olmalarını ve yetkilendirme için güvenilir olmalarını sağlamaz.

v2.0'a özgü isteğe bağlı talep kümesi

Bu talepler her zaman v1.0 belirteçlerine dahil edilir, ancak istenmediği sürece v2.0 belirteçlerine dahil değildir. Bu talepler yalnızca JWT'ler (kimlik belirteçleri ve erişim belirteçleri) için geçerlidir.

JWT Talebi Veri Akışı Adı Açıklama Notlar
ipaddr IP Adresi İstemcinin oturum açtığı IP adresi.
onprem_sid Şirket İçi Güvenlik Tanımlayıcısı
pwd_exp Parola Son Kullanma Tarihi Parolanın süresinin dolduğu talepteki iat süreden sonraki saniye sayısı. Bu talep yalnızca parolanın süresi yakında dolduğunda (parola ilkesinde "bildirim günleri" ile tanımlandığı şekilde) dahil edilir.
pwd_url Parola URL'sini Değiştir Kullanıcının parolasını değiştirmek için ziyaretebileceği bir URL. Bu talep yalnızca parolanın süresi yakında dolduğunda (parola ilkesinde "bildirim günleri" ile tanımlandığı şekilde) dahil edilir.
in_corp İç Şirket Ağı İstemcinin şirket ağından oturum açması durumunda sinyal gönderir. Bunlar dahil değilse, talep dahil değildir. MFA'daki güvenilen IP ayarlarını temel alır.
family_name Soyadı Kullanıcı nesnesinde tanımlandığı gibi kullanıcının soyadını, soyadını veya aile adını sağlar. Örneğin, "family_name":"Miller". MSA ve Microsoft Entra Id'de desteklenir. Kapsamı gerektirir profile .
given_name Ad Kullanıcı nesnesinde ayarlandığı gibi kullanıcının ilk veya "verilen" adını sağlar. Örneğin, "given_name": "Frank". MSA ve Microsoft Entra Id'de desteklenir. Kapsamı gerektirir profile .
upn Kullanıcı Asıl Adı Kullanıcı için parametresiyle username_hint kullanılabilecek bir tanımlayıcı. Kullanıcı için dayanıklı bir tanımlayıcı değildir ve yetkilendirme için veya kullanıcı bilgilerini benzersiz olarak tanımlamak için (örneğin, veritabanı anahtarı olarak) kullanılmamalıdır. Daha fazla bilgi için bkz . Talepleri doğrulayarak uygulamaların ve API'lerin güvenliğini sağlama. Bunun yerine, veritabanı anahtarı olarak kullanıcı nesne kimliğini (oid) kullanın. Alternatif oturum açma kimliğiyle oturum açan kullanıcılara Kullanıcı Asıl Adları (UPN) gösterilmemelidir. Bunun yerine, kullanıcıya oturum açma durumunu görüntülemek için aşağıdaki preferred_username talebi kullanın. Kapsamı gerektirir profile .

v1.0'a özgü isteğe bağlı talep kümesi

v2 belirteç biçiminin bazı geliştirmeleri, güvenliği ve güvenilirliği artırmaya yardımcı olduğundan v1 belirteç biçimini kullanan uygulamalar tarafından kullanılabilir. Bu geliştirmeler SAML belirteçleri için değil yalnızca JWT'ler için geçerlidir.

JWT Talebi Veri Akışı Adı Açıklama Notlar
aud Hedef Kitle Her zaman JWT'lerde bulunur, ancak v1 erişim belirteçlerinde çeşitli yollarla yayılabilir: herhangi bir appID URI'si, sondaki eğik çizgiyle veya eğik çizgi olmadan ve kaynağın istemci kimliği. Belirteç doğrulaması yapılırken bu rastgeleye karşı kodlanması zor olabilir. Her zaman v1 erişim belirteçlerinde kaynağın istemci kimliğine ayarlandığından emin olmak için bu talep için kullanın additionalProperties . Yalnızca v1 JWT erişim belirteçleri
preferred_username Tercih edilen kullanıcı adı v1 belirteçleri içinde tercih edilen kullanıcı adı talebi sağlar. Bu talep, belirteç türünden bağımsız olarak uygulamaların kullanıcı adı ipuçları sağlamasını ve okunabilir görünen adları göstermesini kolaylaştırır. veya yerine bu isteğe bağlı talebi kullanmanız upnunique_nameönerilir. v1 kimlik belirteçleri ve erişim belirteçleri

additionalProperties isteğe bağlı talepler

İsteğe bağlı bazı talepler, talebin döndürülürken nasıl döndürüleceğini değiştirmek için yapılandırılabilir. Bunlar additionalProperties çoğunlukla farklı veri beklentilerine sahip şirket içi uygulamaların geçişine yardımcı olmak için kullanılır. Örneğin, include_externally_authenticated_upn_without_hash UPN'de karma işaretleri (#) işleyebilen istemcilere yardımcı olur.

Özellik adı additionalProperty Adı Açıklama
upn Hem SAML hem de JWT yanıtları ve v1.0 ve v2.0 belirteçleri için kullanılabilir.
include_externally_authenticated_upn Kaynak kiracısında depolandığı şekilde konuk UPN'sini içerir. Örneğin, foo_hometenant.com#EXT#@resourcetenant.com.
include_externally_authenticated_upn_without_hash Daha önce listelendiği gibi, örneğin karma işaretlerinin (#) alt çizgilerle ()_foo_hometenant.com_EXT_@resourcetenant.com değiştirilmesi dışında.
aud v1 erişim belirteçlerinde bu talep, talebin aud biçimini değiştirmek için kullanılır. Bu talebin v2 belirteçlerinde veya sürümün kimlik belirteçlerinde hiçbir etkisi yoktur; burada aud talep her zaman istemci kimliğidir. API'nizin hedef kitle doğrulamasını daha kolay gerçekleştirebilmesini sağlamak için bu yapılandırmayı kullanın. Erişim belirtecini etkileyen tüm isteğe bağlı talepler gibi, erişim belirtecinin sahibi kaynaklar olduğundan istekteki kaynağın da bu isteğe bağlı talebi ayarlaması gerekir.
use_guid Kaynağın (API) istemci kimliğini, çalışma zamanına bağımlı olmak yerine her zaman talep olarak aud GUID biçiminde yayar. Örneğin, bir kaynak bu bayrağı ayarlarsa ve istemci kimliği ise 00001111-aaaa-2222-bbbb-3333cccc4444, bu kaynak için erişim belirteci isteyen tüm uygulamalar ile aud bir erişim belirteci alır: 00001111-aaaa-2222-bbbb-3333cccc4444. Bu talep kümesi olmadan, bir API , veya api://MyApi.comapi://MyApi.com/api://myapi.com/AdditionalRegisteredField bu API için uygulama kimliği URI'si olarak ayarlanmış başka bir değere sahip belirteçleri aud ve kaynağın istemci kimliğini alabilir.
idtyp Bu talep, belirteç türünü (uygulama, kullanıcı, cihaz) almak için kullanılır. Varsayılan olarak yalnızca uygulama belirteçleri için gönderilir. Erişim belirtecini etkileyen tüm isteğe bağlı talepler gibi, erişim belirtecinin sahibi kaynaklar olduğundan istekteki kaynağın da bu isteğe bağlı talebi ayarlaması gerekir.
include_user_token Kullanıcı belirteci idtyp için talebi yayar. Idtyp talep kümesi için bu isteğe bağlı ek özellik olmadan, API yalnızca uygulama belirteçleri için talebi alır.

additionalProperties Örnek

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ]
}

Bu optionalClaims nesne, istemciye döndürülen kimlik belirtecinin diğer ev kiracısı ve kaynak kiracı bilgileriyle bir upn talep içermesine neden olur. Talep upn yalnızca kullanıcı kiracıda konuksa (kimlik doğrulaması için farklı bir IDP kullanan) belirteçte değiştirilir.

Ayrıca bkz.

Sonraki adımlar