İsteğe bağlı beyanları yapılandırma

Makale
06/10/2024

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, belirteçte varsayılan olarak birkaç talep artık yoktur ve uygulama başına özel olarak istenmelidir.

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 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.
Kimlik>Uygulamaları'na> göz atın Uygulama kayıtları.
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
Bildirimle devam edin

Yönet'in altında Belirteç yapılandırması'nı seçin.
İsteğe bağlı talep ekle öğesini seçin.
Yapılandırmak istediğiniz belirteç türünü (access gibi) seçin.
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 İndir seçeneğini belirleyip bildirimi yerel ortamda düzenledikten sonra Yükle seçeneğiyle uygulamanıza yeniden uygulayabilirsiniz. Dosya özellik içermiyorsa optionalClaims , ekleyebilirsiniz.

Aşağıdaki uygulama bildirim girdisi auth_timekimlik, erişim ve upn SAML belirteçlerine , ipaddrve 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
        }
    ]
}

İşlem tamamlandığında 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ı	Tür	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ı	Tür	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, istemci tarafından belirtilen talep, son kullanıcı tarafından istenen belirli bir görev için sorunsuz bir yetkilendirme deneyimi sağlamak için gereklidir. Varsayılan değer olarak yanlış kullanılır.
`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ısı isteğe bağlı beyanlarını yapılandırma

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. isteğinde ...scope=https://graph.microsoft.com/user.read...kaynak, Microsoft Graph API'sini oluşturur. 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. Değişikliklerinizin accessToken geçerli olduğunu doğrulamak için, başka bir uygulama için değil, 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 içinde, bu talepler şu ad biçimiyle gösterilir: 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ı isteğe bağlı talepleri yapılandırma

İpucu

Bu makaledeki adımlar, başladığınız portala göre biraz değişiklik gösterebilir.

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 isteğe bağlı talepleri yalnızca kullanıcı sorumluları için JWT'de yayılır. 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 isteğe bağlı grupları 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. Belirteçteki grup numarası sınırı nedeniyle büyük kuruluşlar için uygulamaya atanan Gruplar seçeneği önerilir. 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.

Uygulama bildirimi aracılığıyla isteğe bağlı grupları 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 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)
- "SecurityGroup"
- "DirectoryRole"
- "ApplicationGroup" (bu seçenek yalnızca uygulamaya atanmış grupları içerir)
Örneğin:
```
"groupMembershipClaims": "SecurityGroup"
```
Varsayılan olarak grup nesnesi kimlikleri grup talep değerinde yayılır. 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ı 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ı bildirimdeki bölümü kullanacak optionalClaims ş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`	Olmalıdır `groups`
`source`	Kullanılmadı. Null değerini atla veya belirt.
`essential`	Kullanılmadı. Yanlış değerini atla veya 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_roles` `cloud_displayname`.

yalnızca additionalProperties birinde sam_account_name, dns_domain_and_sam_account_namenetbios_domain_and_sam_account_name gereklidir. Birden fazla varsa, ilk kullanılır ve diğerleri yoksayılır. Bulut grubunun görünen adını yaymak için de ekleyebilirsiniz cloud_displayname . 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 additionalPropertiesöğesine ekleyinemit_as_roles. Grup değerleri rol talebine eklenir.

Kullanılırsa emit_as_roles , kullanıcının (veya kaynak uygulamasının) atandığı yapılandırılan uygulama rolleri rol taleplerinde yer almaz.

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

Grupları OAuth erişim belirteçlerinde biçim olarak dnsDomainName\sAMAccountName grup adları olarak yayma.

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

SAML ve OIDC Kimlik belirteçlerinde netbiosDomain\sAMAccountName rollerin talep olduğu biçimde döndürülecek grup adlarını yayın.

"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"
            ]
        }
    ]
}

Şirket içi eşitlenmiş grupların sam_account_name biçiminde grup adlarını ve cloud_display uygulamaya atanan gruplar için SAML ve OIDC Kimlik belirteçlerindeki bulut gruplarının adını yayı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
Bildirimi 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 talebi içerir auth_time .
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 olarak extension_ab603c56068041afb2f6832e2a17e237_skypeIdkullanıma 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 ve ardından Ekle'yi seçin.
Belirteç Yapılandırmasına genel bakış ekranında upn öğesinin yanındaki kalem simgesini seçin, Dışarıdan kimliği doğrulanmış iki durumlu düğmeyi 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.

Aracılığıyla paylaş

İsteğe bağlı beyanları yapılandırma

Önkoşullar

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

Dizin uzantısı isteğe bağlı beyanlarını yapılandırma

Dizin uzantısı biçimlendirmesi

grupları isteğe bağlı talepleri yapılandırma

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

Geri Bildirim

Ek kaynaklar

Aracılığıyla paylaş

İsteğe bağlı beyanları yapılandırma

Önkoşullar

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

Dizin uzantısı isteğe bağlı beyanlarını yapılandırma

Dizin uzantısı biçimlendirmesi

grupları isteğe bağlı talepleri yapılandırma

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

İlgili içerik

Geri Bildirim

Ek kaynaklar