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

İ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.

• Erişim belirteci
• Kimlik belirteci

Sonraki adımlar

• İsteğe bağlı talepleri yapılandırma hakkında daha fazla bilgi edinin.