Kimlik belirteçleri, erişim belirteçleri ve SAML belirteçlerinde isteğe bağlı talepleri yapılandırma ve yönetme

Microsoft Entra'nın döndürdüğü belirteçler, bunları isteyen istemcilerin en iyi performansı elde etmesini sağlamak için daha küçük tutulur. Sonuç olarak, bazı claim’ler artık belirteçte varsayılan olarak yer almaz ve uygulama bazında açıkça talep edilmeleri gerekir.

Microsoft Entra yönetim merkezinin uygulama kullanıcı arabirimi veya bildirimi aracılığıyla uygulamanız için isteğe bağlı talepler yapılandırabilirsiniz.

Önkoşullar

Etkin aboneliği olan bir Azure hesabı. Ücretsiz bir hesap oluşturun.
Hızlı Başlangıcı Tamamlama: Uygulamayı kaydetme

Uygulamanızda isteğe bağlı talepleri yapılandırma

Microsoft Entra yönetim merkezinde en az Bir Bulut Uygulaması Yöneticisi olarak oturum açın.
Entra ID>Uygulama kayıtları'na göz atın.
Senaryonuza ve istediğiniz sonuca göre isteğe bağlı talepleri yapılandırmak istediğiniz uygulamayı seçin.

Uygulama kullanıcı arabirimiyle devam edin
Manifesto ile devam edin

Yönet'in altında Belirteç yapılandırması'nı seçin.
İsteğe bağlı talep ekle'yi seçin.
Yapılandırmak istediğiniz belirteç türünü seçin, örneğin Access.
Eklenecek isteğe bağlı talepleri seçin.
Ekle'yi seçin.

Yönet'in altında Bildirim'i seçin. Bildirimi düzenlemenize olanak sağlayan web tabanlı bir bildirim düzenleyicisi açılır. İsteğe bağlı olarak, Bildirimi yerel olarak indir ve düzenle'yi seçip Karşıya Yükle'yi kullanarak uygulamanıza yeniden uygulayın. Dosya özellik içermiyorsa optionalClaims , ekleyebilirsiniz.

Aşağıdaki uygulama bildirimindeki giriş, auth_timekimlik, ipaddrerişim ve upnSAML belirteçlerine isteğe bağlı talepleri ekler.

"optionalClaims": {
    "idToken": [
        {
            "name": "auth_time",
            "essential": false
        }
    ],
    "accessToken": [
        {
            "name": "ipaddr",
            "essential": false
        }
    ],
    "saml2Token": [
        {
            "name": "upn",
            "essential": false
        },
        {
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "source": "user",
            "essential": false
        }
    ]
}

İşiniz bittiğinde Kaydet'i seçin. Artık belirtilen isteğe bağlı talepler uygulamanızın belirteçlerine dahil edilir.

nesnesi, optionalClaims bir uygulama tarafından istenen isteğe bağlı talepleri bildirir. Bir uygulama kimlik belirteçleri, erişim belirteçleri ve SAML 2 belirteçlerinde döndürülen isteğe bağlı talepleri yapılandırabilir. Uygulama, her belirteç türünde döndürülecek farklı bir isteğe bağlı talep kümesi yapılandırabilir.

Adı	Tip	Açıklama
`idToken`	Koleksiyon	JWT ID belirtecinde döndürülen isteğe bağlı talepler.
`accessToken`	Koleksiyon	JWT erişim belirtecinde döndürülen isteğe bağlı talepler.
`saml2Token`	Koleksiyon	SAML belirtecinde döndürülen isteğe bağlı talepler.

Belirli bir talep tarafından destekleniyorsa, alanını kullanarak additionalProperties isteğe bağlı talebin davranışını da değiştirebilirsiniz.

Adı	Tip	Açıklama
`name`	Edm.String	İsteğe bağlı talebin adı.
`source`	Edm.String	Talebin kaynağı (dizin nesnesi). Uzantı özelliklerinden önceden tanımlanmış talepler ve kullanıcı tanımlı talepler vardır. Kaynak değer null ise, talep önceden tanımlanmış isteğe bağlı bir taleptir. Kaynak değer kullanıcıysa, ad özelliğindeki değer kullanıcı nesnesinden uzantı özelliğidir.
`essential`	Edm.Boolean	Değer true ise, istemcinin belirttiği istem, son kullanıcının talep ettiği belirli görev için sorunsuz bir yetkilendirme deneyimi sağlamak açısından gereklidir. Varsayılan değer false'tur.
`additionalProperties`	Koleksiyon (Edm.String)	Talebin diğer özellikleri. Bu koleksiyonda bir özellik varsa, name özelliğinde belirtilen isteğe bağlı talebin davranışını değiştirir.

Dizin uzantıları için isteğe bağlı talepleri yapılandırın

Standart isteğe bağlı talep kümesine ek olarak, belirteçleri Microsoft Graph uzantılarını içerecek şekilde de yapılandırabilirsiniz. Daha fazla bilgi için bkz. Uzantıları kullanarak kaynaklara özel veri ekleme.

Önemli

Erişim belirteçleri her zaman istemci değil kaynağın bildirimi kullanılarak oluşturulur. ...scope=https://graph.microsoft.com/user.read... isteğinde kaynak Microsoft Graph API’sidir. Erişim belirteci, istemcinin bildirimi değil Microsoft Graph API bildirimi kullanılarak oluşturulur. Uygulamanızın bildirimini değiştirmek hiçbir zaman Microsoft Graph API'sinin belirteçlerinin farklı görünmesine neden olmaz. accessToken değişikliklerinizin geçerli olduğunu doğrulamak için, başka bir uygulama için değil, kendi uygulamanız için bir belirteç isteyin.

İsteğe bağlı talepler uzantı özniteliklerini ve dizin uzantılarını destekler. Bu özellik, uygulamanızın kullanabileceği daha fazla kullanıcı bilgisi eklemek için kullanışlıdır. Örneğin, kullanıcının ayardığı diğer tanımlayıcılar veya önemli yapılandırma seçenekleri. Uygulama bildiriminiz özel bir uzantı isterse ve bir MSA kullanıcısı uygulamanızda oturum açarsa, bu uzantılar döndürülmüyor.

Dizin uzantısı biçimlendirmesi

Uygulama bildirimini kullanarak dizin uzantısı isteğe bağlı beyanlarını yapılandırırken uzantının tam adını kullanın (biçiminde: extension_<appid>_<attributename>). <appid>, talebi isteyen uygulamanın appId 'sinin (veya İstemci Kimliği)'nin kaldırılmış sürümüdür.

JWT’de bu claim’ler aşağıdaki ad biçiminde iletilir: extn.<attributename>. SAML belirteçleri içinde, bu talepler aşağıdaki URI biçimiyle gösterilir: http://schemas.microsoft.com/identity/claims/extn.<attributename>

Gruplar için isteğe bağlı istemleri yapılandırın

Bu bölüm, varsayılan grup objectID'sinden grup taleplerinde kullanılan grup özniteliklerini şirket içi Windows Active Directory'den eşitlenen özniteliklere değiştirmek için isteğe bağlı talepler altındaki yapılandırma seçeneklerini kapsar. Azure portalı veya uygulama bildirimi aracılığıyla uygulamanız için isteğe bağlı grupları yapılandırabilirsiniz. Grup için isteğe bağlı talepler, JWT'de yalnızca kullanıcı asılları için gönderilir. Hizmet sorumluları JWT'de yayılan isteğe bağlı grup taleplerine dahil edilmez.

Önemli

İç içe yerleştirilmiş gruplar da dahil olmak üzere belirteçte yayılan grupların sayısı SAML onayları için 150 ve JWT için 200 ile sınırlanmıştır. Şirket içi özniteliklerden grup talepleri için grup sınırları ve önemli uyarılar hakkında daha fazla bilgi için bkz. Uygulamalar için grup taleplerini yapılandırma.

Azure portalını kullanarak grup isteğe bağlı taleplerini yapılandırmak için aşağıdaki adımları tamamlayın:

İsteğe bağlı talepleri yapılandırmak istediğiniz uygulamayı seçin.
Yönet'in altında Belirteç yapılandırması'nı seçin.
Grup talebi ekle'yi seçin.
Döndürülecek grup türlerini seçin (Güvenlik grupları veya Dizin rolleri, Tüm gruplar ve/veya Uygulamaya atanan gruplar):
- Uygulamaya atanan gruplar seçeneği yalnızca uygulamaya atanmış grupları içerir. Jetondaki grup sayısı sınırı nedeniyle büyük kuruluşlar için uygulamaya atanan Gruplar seçeneği önerilmektedir. Uygulamaya atanan grupları değiştirmek için Kurumsal uygulamalar listesinden uygulamayı seçin. Kullanıcılar ve gruplar'ı ve ardından Kullanıcı/grup ekle'yi seçin. Kullanıcılar ve gruplar'dan uygulamaya eklemek istediğiniz grupları seçin.
- Tüm Gruplar seçeneği SecurityGroup, DirectoryRole ve DistributionList'i içerir ancak uygulamaya atanan Grupları içermez.
İsteğe bağlı: Grup talep değerini şirket içi grup özniteliklerini içerecek şekilde değiştirmek veya talep türünü bir rol olarak değiştirmek için belirli belirteç türü özelliklerini seçin.
Kaydet'i seçin.

Grup isteğe bağlı taleplerini uygulama bildirimi aracılığıyla yapılandırmak için aşağıdaki adımları izleyin:

İsteğe bağlı talepleri yapılandırmak istediğiniz uygulamayı seçin.
Yönet'in altında Bildirim'i seçin.
Bildirim düzenleyicisini kullanarak aşağıdaki girdiyi ekleyin:

Geçerli değerler şunlardır:
- "Tümü" (bu seçenek SecurityGroup, DirectoryRole ve DistributionList'i içerir)
- Güvenlik Grubu
- "DirectoryRole" (Dizin Rolü)
- "ApplicationGroup" (bu seçenek yalnızca uygulamaya atanmış grupları içerir)
Örneğin:
```
"groupMembershipClaims": "SecurityGroup"
```
Varsayılan olarak grup nesne kimlikleri, grup talebi değerinde gönderilir. Talep değerini şirket içi grup özniteliklerini içerecek şekilde değiştirmek veya talep türünü rol olarak değiştirmek için yapılandırmayı optionalClaims aşağıdaki gibi kullanın:

Grup adı yapılandırması için isteğe bağlı talepleri ayarlayın.

Belirteçteki grupların isteğe bağlı talepler bölümünde şirket içi grup özniteliklerini içermesini istiyorsanız, hangi belirteç türüne isteğe bağlı talebin uygulanacağını belirtin. ayrıca istenen isteğe bağlı talebin adını ve istenen diğer özellikleri de belirtirsiniz.

Birden çok belirteç türü listelenebilir:

idToken OIDC Kimlik belirteci için
accessToken OAuth erişim belirteci için
Saml2Token SAML belirteçleri için.

Türü Saml2Token hem SAML1.1 hem de SAML2.0 biçim belirteçleri için geçerlidir.

İlgili her belirteç türü için, grup iddiasını bildirim dosyasındaki optionalClaims bölümünü kullanacak şekilde değiştirin. Şema optionalClaims aşağıdaki gibidir:

{
    "name": "groups",
    "source": null,
    "essential": false,
    "additionalProperties": []
}

İsteğe bağlı talep şeması	Değer
`name`	Olması gerekir `groups`
`source`	Kullanılmadı. Null değerini atla veya belirt.
`essential`	Kullanılmadı. Atla veya false değerini belirt.
`additionalProperties`	Diğer özelliklerin listesi. Geçerli seçenekler : `sam_account_name`, `dns_domain_and_sam_account_name`, `netbios_domain_and_sam_account_name`ve `emit_as_rolescloud_displayname`.

additionalProperties içinde sam_account_name, dns_domain_and_sam_account_name ve netbios_domain_and_sam_account_name öğelerinden yalnızca biri gereklidir. Birden fazla varsa, ilk kullanılır ve diğerleri yoksayılır. Bulut grubunun görünen adını çıktılamak için cloud_displayname etiketini ayrıca ekleyebilirsiniz. Bu seçenek yalnızca groupMembershipClaims olarak ayarlandığında ApplicationGroupçalışır.

Bazı uygulamalar, rol talebindeki kullanıcı hakkında grup bilgileri gerektirir. Talep türünü bir grup talebi yerine rol talebi olarak değiştirmek için emit_as_rolesöğesine ekleyinadditionalProperties. Grup değerleri rol isteminde gönderilir.

emit_as_roles kullanılırsa, kullanıcının (veya bir kaynak uygulamasının) atandığı herhangi bir yapılandırılmış uygulama rolü rol talebinde yer almaz.

Aşağıdaki örneklerde grup talepleri için bildirim yapılandırması gösterilmektedir:

Grupları, OAuth erişim belirteçlerine dnsDomainName\sAMAccountName biçiminde grup adları olarak ekleyin.

"optionalClaims": {
    "accessToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "dns_domain_and_sam_account_name"
            ]
        }
    ]
}

Grup adlarını, SAML ve OIDC kimlik belirteçlerinde roller talebi olarak netbiosDomain\sAMAccountName biçiminde döndür.

"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ]
}

Uygulamaya atanan gruplar için, şirket içi ile eşitlenen grupların grup adlarını SAML ve OIDC kimlik belirteçlerinde sam_account_name biçiminde, bulut gruplarının adlarını ise cloud_display ad biçiminde yayınlayın.

"groupMembershipClaims": "ApplicationGroup",
"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ]
}

İsteğe bağlı talep örneği

İsteğe bağlı talepleri etkinleştirmek ve yapılandırmak için uygulamanın kimlik yapılandırmasındaki özellikleri güncelleştirmek için kullanabileceğiniz birden çok seçenek vardır:

Azure portalını kullanabilirsiniz
Manifesti kullanabilirsiniz.
Uygulamanızı güncelleştirmek için Microsoft Graph API'sini kullanan bir uygulama da yazabilirsiniz. Microsoft Graph API başvuru kılavuzundaki OptionalClaims türü, isteğe bağlı talepleri yapılandırmanıza yardımcı olabilir.

Aşağıdaki örnekte Azure portalı ve bildirimi, uygulamanız için hedeflenen erişim, kimlik ve SAML belirteçlerine isteğe bağlı talepler eklemek için kullanılır. Uygulamanın alabileceği her belirteç türüne farklı isteğe bağlı talepler eklenir:

Kimlik belirteçleri, federasyon kullanıcıları için UPN'yi tam biçiminde (<upn>_<homedomain>#EXT#@<resourcedomain> ) içerir.
Diğer istemcilerin bu uygulama için istediği erişim belirteçleri auth_time claim’ini içerir.
SAML belirteçleri dizin şeması uzantısını skypeId içerir (bu örnekte, bu uygulamanın uygulama kimliği şeklindedir ab603c56068041afb2f6832e2a17e237). SAML belirteci Skype kimliğini extension_ab603c56068041afb2f6832e2a17e237_skypeId olarak sunar.

Azure portalında talepleri yapılandırın:

İsteğe bağlı talepleri yapılandırmak istediğiniz uygulamayı seçin.
Yönet'in altında Belirteç yapılandırması'nı seçin.
İsteğe bağlı talep ekle'yi seçin, kimlik belirteci türünü seçin, talep listesinden upn seçeneğini belirleyin ve ardından Ekle'yi seçin.
İsteğe bağlı talep ekle'yi seçin, Erişim belirteci türünü seçin, talep listesinden auth_time seçin ve ardından Ekle'yi seçin.
Belirteç Yapılandırmasına genel bakış ekranında upn öğesinin yanındaki kalem simgesine tıklayın, Dışarıdan kimliği doğrulanmış seçeneğini etkinleştirin ve ardından Kaydet'i seçin.
İsteğe bağlı talep ekle'yi seçin, SAML belirteci türünü seçin, talep listesinden extn.skypeID'yi seçin (yalnızca skypeID adlı bir Microsoft Entra kullanıcı nesnesi oluşturduysanız geçerlidir) ve ardından Ekle'yi seçin.

Bildirimde talepleri yapılandırın:

İsteğe bağlı talepleri yapılandırmak istediğiniz uygulamayı seçin.
Yönet'in altında Bildirim'i seçerek satır içi bildirim düzenleyicisini açın.

Bu düzenleyiciyi kullanarak bildirimi doğrudan düzenleyebilirsiniz. Bildirim, Uygulama varlığının şemasını izler ve kaydedildikten sonra bildirimi otomatik olarak biçimlendirır. Özelliğine optionalClaims yeni öğeler eklenir.

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ],
    "accessToken": [
        {
            "name": "auth_time",
            "essential": false
        }
    ],
    "saml2Token": [
        {
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "source": "user",
            "essential": true
        }
    ]
}

Bildirimi güncelleştirmeyi bitirdiğinizde, bildirimi kaydetmek için Kaydet'i seçin.

AMR talebi

amr (kimlik doğrulama yöntemi başvuruları) talebi, kullanıcının kimliğinin nasıl doğrulanmış olduğunu tanımlar. Talep amr Salesforce uygulamaları için varsayılan olarak gönderilir, bu nedenle bu uygulamalar için yapılandırma değişikliği gerekmez. Diğer tüm SAML uygulamaları için uygulama yöneticisinin, AMR taleplerini istemek üzere, isteğe bağlı amr talebini include_granular_amr ek özelliğiyle birlikte uygulama kaydına eklemesi gerekir. multipleauthn ve mfa değerleri yalnızca kullanıcı MFA'yi tamamladığında gönderilir.

SAML uygulaması için ayrıntılı AMR değerlerini yapılandırma

Microsoft Entra yönetim merkezi şu anda için include_granular_amrbir kullanıcı arabirimi seçeneği sağlamaz. Bu özelliği uygulama bildiriminde veya Microsoft Graph kullanarak yapılandırın. özelliği, include_granular_amr SAML belirteçlerinde amr ayrıntılı kimlik doğrulama yöntemi değerleri yaymak için talebi değiştirir.

Uygulama bildirimini yapılandırmak için:

Microsoft Entra yönetim merkeziEntra ID>Uygulama kayıtları adresine gidin.
Uygulama kaydını seçin.
Yönet'in altında Bildirim'i seçin.

Özelliğini aşağıdaki yapılandırmayla ekleyin veya güncelleştirin optionalClaims . Uygulamanızın gerektirdiği tüm isteğe bağlı talepleri koruyun.

"optionalClaims": {
    "saml2Token": [
        {
            "name": "amr",
            "essential": false,
            "additionalProperties": [
                "include_granular_amr"
            ]
        }
    ]
}

Kaydet'i seçin.

Alternatif olarak, Microsoft Graph Update uygulama API'sini kullanın. değerini uygulama kaydının nesne kimliğiyle değiştirin {applicationObjectId} . İstek gövdesinde tutmak istediğiniz mevcut isteğe bağlı talep yapılandırmasını ekleyin.

PATCH https://graph.microsoft.com/v1.0/applications/{applicationObjectId}
Content-Type: application/json

{
    "optionalClaims": {
        "saml2Token": [
            {
                "name": "amr",
                "essential": false,
                "additionalProperties": [
                    "include_granular_amr"
                ]
            }
        ]
    }
}

SAML talebi hakkında daha fazla bilgi için bkz. authnmethodreferences.

OIDC uygulaması için AMR talebi yapılandırma

OpenID Connect (OIDC) v2.0 uygulaması için isteğe bağlı talebi uygulamanızın gerektirdiği belirteç türlerine ekleyin amr . include_granular_amr özelliği yalnızca SAML uygulamaları için geçerlidir ve OIDC uygulamaları için gerekli değildir. Aşağıdaki uygulama bildirimi, talebi hem kimlik hem de erişim belirteçlerinde istemektedir amr :

"optionalClaims": {
    "idToken": [
        {
            "name": "amr",
            "essential": false
        }
    ],
    "accessToken": [
        {
            "name": "amr",
            "essential": false
        }
    ]
}

Sınırlama

Bir uygulama isteğe bağlı talep olarak en fazla 10 uzantı özniteliği verebilir.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-08-13