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

İsteğe bağlı talepleri kullanarak:

Uygulamanız için belirteçlere eklenecek talepleri seçin.
Microsoft kimlik platformunun belirteçlerde döndürdüğü belirli taleplerin davranışını değiştirin.
Uygulamanız için özel talepler ekleyin ve bu taleplere erişin.

İ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 platformunda, istemcilerin en iyi performansı elde etmesini 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	Destekli
Microsoft Entra hesabı	Destekli	Destekli

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 uygulamayı tarafından istenen talepler değil, uygulama (web API'si) için istenen erişim belirteçlerine 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.

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ğer `0`olur. Konuksa, değeri `1`olur.
`acrs`	Kimlik Doğrulama Bağlam Kimlikleri	JWT	Microsoft Entra Kimliği	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 `xms_cc` talebiyle 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ınbu verilere erişme izni olduğunu doğrulama. Yetkilendirme için e-posta talebi kullanıyorsanız,daha güvenli bir talepe geçmek için 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		`groups` talebi, uygulama bildirimide ayarlanması gereken GroupMembershipClaims ayarıyla birlikte kullanılır.
`idtyp`	Belirteç türü	JWT erişim belirteçleri	Özel: yalnızca uygulama erişim belirteçlerinde	Belirteç yalnızca uygulama belirteci olduğunda değer `app`. 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 `login_hint` OAuth parametresi için kullanılacak en iyi değerdir. Uygulamalar arasında geçirilip sessizce SSO ile de geçirilebilir- A uygulaması bir kullanıcıda oturum açabilir, `login_hint` talebi okuyabilir ve kullanıcı B uygulamasına götüren bir bağlantıyı seçtiğinde sorgu dizesindeki veya parçadaki talebi ve geçerli kiracı bağlamını B uygulamasına gönderebilir. Yarış koşulları ve güvenilirlik sorunlarını önlemek için `login_hint` talep kullanıcı için geçerli kiracıyı ve kullanıldığında varsayılan olarak kullanıcının ev kiracısını içerir. 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 kullanıma sunulmak üzere tasarlanmıştır.
`tenant_ctry`	Kaynak kiracının ülkesi/bölgesi	JWT		Yönetici tarafından kiracı düzeyinde ayarlanan `ctry` ile aynıdır. Standart iki harfli bir değer de olmalıdır.
`tenant_region_scope`	Kaynak kiracısının bölgesi	JWT
`upn`	KullanıcıTemelAdı	JWT, SAML		`username_hint` parametresiyle kullanılabilen kullanıcının tanımlayıcısı. 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ği 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: v1 belirteçleri için `preferred_username` veya `unique_name` ve v2 belirteçleri için `preferred_username`. 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. `login_hint` kullanımı için `login_hint` talebi kullanmalısınız. UPN gibi insan tarafından okunabilir 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 Kimliği	Belirteci alan istemci uygulamasının talep sınamalarını işleyip işleyemeyeceğini gösterir. Genellikle talep `acrs`ile 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 `cp1` değeri, 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ı doğrulanmış etki alanları yoktur. Bu talebin belirteçte döndürülecek olması için `email` talebin 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çintercih edilen veri konumu hakkında Microsoft Entra Connect 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		`Windows AutoPilot`için kullanı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 email veya upn talep değerlerini kullanmayın. 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	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 Süre Sonu Süresi	`iat` talebindeki parolanın süresinin dolmasına neden olan 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ğı İçinde	İstemcinin şirket ağından oturum açması durumunda sinyal gönderir. Bunlar dahil değilse, talep dahil değildir.	MFA'daki güvenilen IP'ler ayarlarına göre.
`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. `profile` kapsamını gerektirir.
`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. `profile` kapsamını gerektirir.
`upn`	Kullanıcı Asıl Adı	`username_hint` parametresiyle kullanılabilen kullanıcının tanımlayıcısı. 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ği 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.	`profile` kapsamını gerektirir.

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	Ad	Açıklama	Notlar
`aud`	Seyirci	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 `additionalProperties` kullanın.	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. kullanmak, `upn` veya `unique_name`yerine bu isteğe bağlı talebi kullanmanız önerilir.	v1 kimlik belirteçleri ve erişim belirteçleri

İsteğe bağlı taleplerin `additionalProperties`

İ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. Bu additionalProperties çoğunlukla farklı veri beklentilerine sahip şirket içi uygulamaların geçirilmesine yardımcı olmak için kullanılır. Örneğin include_externally_authenticated_upn_without_hash, UPN'de karma işaretleri (#) işleyememe istemcilerine 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, karma işaretlerinin (`#`) alt çizgilerle (`_`) değiştirilmesi dışında, örneğin `foo_hometenant.com_EXT_@resourcetenant.com`.
`aud`		v1 erişim belirteçlerinde bu talep, `aud` talebin biçimini değiştirmek için kullanılır. Bu talebin v2 belirteçlerinde veya sürüm kimlik belirteçlerinde hiçbir etkisi yoktur; burada `aud` talebi 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 `aud` talebi olarak GUID biçiminde gösterir. Örneğin, bir kaynak bu bayrağı ayarlarsa ve istemci kimliği `00001111-aaaa-2222-bbbb-3333cccc4444`ise, bu kaynak için erişim belirteci isteyen tüm uygulamalar `aud` : `00001111-aaaa-2222-bbbb-3333cccc4444`ile bir erişim belirteci alır. Bu talep kümesi olmadan, API `aud`, `api://MyApi.com`, `api://MyApi.com/api://myapi.com/AdditionalRegisteredField` talebine veya bu API için uygulama kimliği URI'si olarak ayarlanan başka bir değere ve kaynağın istemci kimliğine sahip belirteçler 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 için `idtyp` 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 nesnesi, istemciye döndürülen kimlik belirtecinin diğer ev kiracısı ve kaynak kiracı bilgileriyle bir upn talebi içermesine neden olur. upn talebi 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

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

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-01-23