Mengonfigurasi klaim grup untuk aplikasi dengan menggunakan ID Microsoft Entra

ID Microsoft Entra dapat memberikan informasi keanggotaan grup pengguna dalam token untuk digunakan dalam aplikasi. Fitur ini mendukung tiga pola utama:

• Grup yang diidentifikasi oleh atribut pengidentifikasi objek Microsoft Entra (OID) mereka
• Grup yang diidentifikasi oleh atribut sAMAccountName atau GroupSID untuk grup dan pengguna yang disinkronkan dengan Active Directory
• Grup yang diidentifikasi oleh atribut Nama Tampilan mereka untuk grup khusus cloud

Penting

Jumlah grup yang dikeluarkan dalam token dibatasi hingga 150 untuk pernyataan SAML dan 200 untuk JWT, termasuk grup berlapis. Di organisasi yang lebih besar, jumlah grup di mana pengguna adalah anggota mungkin melebihi batas yang diterapkan ID Microsoft Entra sebelum memancarkan klaim grup dalam token. Melebihi batas ini akan menyebabkan ID Microsoft Entra sepenuhnya menghilangkan pengiriman klaim grup dalam token. Untuk solusi batas ini, baca selengkapnya di Peringatan penting untuk fungsionalitas ini.

Peringatan penting untuk fungsionalitas ini

• Dukungan untuk penggunaan sAMAccountName dan atribut pengidentifikasi keamanan (SID) yang disinkronkan dari lokal dirancang untuk memungkinkan pemindahan aplikasi yang ada dari Active Directory Federation Services (AD FS) dan IdP lainnya. Grup yang dikelola di MICROSOFT Entra ID tidak berisi atribut yang diperlukan untuk memancarkan klaim ini.

• Untuk menghindari jumlah batas grup jika pengguna Anda memiliki keanggotaan grup dalam jumlah besar, Anda dapat membatasi grup yang dikeluarkan dalam klaim ke grup yang relevan untuk aplikasi. Baca selengkapnya tentang memancarkan grup yang ditetapkan ke aplikasi untuk token JWT dan token SAML. Jika menetapkan grup ke aplikasi Anda tidak dimungkinkan, Anda dapat mengkonfigurasi filter grup untuk mengurangi jumlah grup yang muncul dalam klaim. Pemfilteran grup berlaku untuk token yang dikeluarkan untuk aplikasi tempat klaim dan pemfilteran grup dikonfigurasi di bilah aplikasi Enterprise di portal. Perlu diingat bahwa di organisasi yang lebih besar, jumlah grup di mana pengguna adalah anggota mungkin melebihi batas yang diterapkan ID Microsoft Entra sebelum mengeluarkan klaim grup dalam token. Melebihi batas ini akan menyebabkan ID Microsoft Entra sepenuhnya menghilangkan pengiriman klaim grup dalam token.

• Klaim grup memiliki batas lima grup jika token dikeluarkan melalui aliran implisit. Token yang diminta melalui aliran implisit akan memiliki "hasgroups":true klaim hanya jika pengguna berada di lebih dari lima grup.

• Sebaiknya mendasarkan otorisasi dalam aplikasi pada peran aplikasi alih-alih grup saat:

  • Anda sedang mengembangkan aplikasi baru, atau aplikasi yang ada dapat dikonfigurasi untuk itu.
  • Dukungan untuk grup berlapis tidak diperlukan.

  Menggunakan peran aplikasi membatasi jumlah informasi yang perlu masuk ke token, lebih aman, dan memisahkan penugasan pengguna dari konfigurasi aplikasi.

Klaim grup untuk aplikasi yang bermigrasi dari AD FS dan penyedia identitas lain

Banyak aplikasi yang dikonfigurasi untuk mengautentikasi dengan Active Directory Federation Services mengandalkan informasi keanggotaan grup dalam bentuk atribut grup Active Directory lokal. Atribut ini adalah grup sAMAccountName, yang mungkin dikualifikasikan menurut nama domain, atau pengidentifikasi keamanan grup Windows (GroupSID). Ketika aplikasi disalurkan dengan Active Directory Federation Services, Active Directory Federation Services menggunakan fungsi TokenGroups untuk mengambil keanggotaan grup bagi pengguna.

Aplikasi yang telah dipindahkan dari AD FS memerlukan klaim dalam format yang sama. Klaim grup dan peran yang dikeluarkan dari MICROSOFT Entra ID mungkin berisi atribut yang memenuhi syarat sAMAccountName domain atau atribut yang GroupSID disinkronkan dari Direktori Aktif, bukan atribut ID objectID Microsoft Entra grup.

Format yang didukung untuk klaim grup adalah:

• ObjectId grup Microsoft Entra: Tersedia untuk semua grup.
• sAMAccountName: Tersedia untuk grup yang disinkronkan dari Active Directory
• NetbiosDomain\sAMAccountName: Tersedia untuk grup yang disinkronkan dari Active Directory.
• DNSDomainName\sAMAccountName: Tersedia untuk grup yang disinkronkan dari Active Directory.
• Pengidentifikasi Keamanan Grup Lokal Tersedia untuk grup yang disinkronkan dari Active Directory.

Catatan

sAMAccountName dan atribut lokal GroupSID atribut hanya tersedia pada objek grup yang disinkronkan dari Active Directory. Mereka tidak tersedia di grup yang dibuat di MICROSOFT Entra ID atau Office 365. Aplikasi yang dikonfigurasi di ID Microsoft Entra untuk mendapatkan atribut grup lokal yang disinkronkan mendapatkannya hanya untuk grup yang disinkronkan.

Opsi untuk aplikasi untuk menggunakan informasi grup

Aplikasi dapat memanggil titik akhir grup Microsoft Graph guna mendapatkan informasi grup untuk pengguna yang diautentikasi. Panggilan ini memastikan bahwa semua grup tempat pengguna menjadi anggota tersedia, bahkan ketika ada sejumlah besar grup yang terlibat. Enumerasi grup kemudian independen dari keterbatasan ukuran token.

Namun, jika aplikasi yang ada mengharapkan untuk menggunakan informasi grup melalui klaim, Anda dapat mengonfigurasi ID Microsoft Entra dengan berbagai format klaim. Pertimbangkan opsi berikut:

• Saat Anda menggunakan keanggotaan grup untuk otorisasi dalam aplikasi, sebaiknya gunakan atribut grup ObjectID. Atribut grup ObjectID tidak dapat diubah dan unik di MICROSOFT Entra ID. Ini tersedia untuk semua grup.

• Jika Anda menggunakan atribut grup sAMAccountName lokal untuk otorisasi, gunakan nama yang memenuhi syarat domain. Ini mengurangi kemungkinan bentrokan nama. sAMAccountName mungkin unik dalam domain Direktori Aktif, tetapi jika lebih dari satu domain Direktori Aktif disinkronkan dengan penyewa Microsoft Entra, ada kemungkinan bagi lebih dari satu grup untuk memiliki nama yang sama.

• Pertimbangkan untuk menggunakan peran aplikasi untuk memberikan lapisan tidak langsung antara keanggotaan grup dan aplikasi. Aplikasi kemudian membuat keputusan otorisasi internal berdasarkan klaim peran dalam token.

• Jika aplikasi dikonfigurasi untuk mendapatkan atribut grup yang disinkronkan dari Active Directory dan grup tidak berisi atribut tersebut, maka aplikasi tersebut tidak akan disertakan dalam klaim.

• Klaim grup dalam token menyertakan grup bertumpuk, kecuali saat menggunakan opsi untuk membatasi klaim grup ke grup yang ditetapkan untuk aplikasi.

  Jika pengguna adalah anggota GroupB, dan GroupB adalah anggota GroupA, maka klaim grup untuk pengguna akan berisi GroupA dan GroupB. Saat pengguna organisasi memiliki sejumlah besar keanggotaan grup, jumlah grup yang tercantum dalam token dapat menambah ukuran token. MICROSOFT Entra ID membatasi jumlah grup yang akan dikeluarkan dalam token hingga 150 untuk pernyataan SAML dan 200 untuk JWT. Jika pengguna adalah anggota dari jumlah grup yang lebih besar, grup dihilangkan. Tautan ke titik akhir Microsoft Graph untuk mendapatkan informasi grup disertakan sebagai gantinya.

Prasyarat untuk menggunakan atribut Grup yang disinkronkan dari Active Directory

Klaim keanggotaan grup dapat dikeluarkan dalam token untuk grup mana pun jika Anda menggunakan format ObjectId. Untuk menggunakan klaim grup dalam format selain grup ObjectId, grup harus disinkronkan dari Direktori Aktif melalui Microsoft Entra Connect.

Untuk mengonfigurasi ID Microsoft Entra untuk memancarkan nama grup untuk grup Direktori Aktif:

1. Menyinkronkan nama grup dari Active Directory

   Sebelum MICROSOFT Entra ID dapat memancarkan nama grup atau SID grup lokal dalam klaim grup atau peran, Anda perlu menyinkronkan atribut yang diperlukan dari Direktori Aktif. Anda harus menjalankan Microsoft Entra Connect versi 1.2.70 atau yang lebih baru. Versi Microsoft Entra Connect yang lebih lama dari 1.2.70 akan menyinkronkan objek grup dari Direktori Aktif, tetapi tidak akan menyertakan atribut nama grup yang diperlukan.

2. Mengonfigurasi pendaftaran aplikasi di ID Microsoft Entra untuk menyertakan klaim grup dalam token

   Anda dapat mengonfigurasi klaim grup di bagian Aplikasi Enterprise di portal, atau dengan menggunakan manifes aplikasi di bagian Pendaftaran Aplikasi. Untuk mengonfigurasi klaim grup dalam manifes aplikasi, lihat Mengonfigurasi pendaftaran aplikasi Microsoft Entra untuk atribut grup nanti di artikel ini.

Menambahkan klaim grup ke token untuk aplikasi SAML menggunakan konfigurasi SSO

Untuk mengonfigurasi klaim grup untuk aplikasi SAML galeri atau non-galeri melalui SSO:

1. Buka Aplikasi Perusahaan, pilih aplikasi dalam daftar, pilih konfigurasi Akses Menyeluruh, lalu pilih Atribut & Klaim Pengguna.

2. Pilih Tambahkan klaim grup.

   

3. Gunakan opsi untuk memilih grup mana yang harus dimasukkan dalam token.

   

   Pilihan	Deskripsi
   Semua grup	Mengeluarkan grup keamanan serta daftar dan peran distribusi.
   Kelompok keamanan	Mengeluarkan kelompok keamanan tempat pengguna menjadi anggota dalam klaim grup. Jika pengguna diberi peran direktori, mereka dipancarkan sebagai ID objek.
   Peran direktori	Jika pengguna ditetapkan peran direktori, peran tersebut akan dikeluarkan sebagai klaim wids. (Klaim grup tidak akan dikeluarkan.)
   Group yang ditetapkan ke aplikasi	Hanya mengeluarkan grup yang secara eksplisit ditetapkan ke aplikasi dan pengguna adalah anggota. Direkomendasikan untuk organisasi besar karena batas nomor grup dalam token.

   • Misalnya, untuk mengeluarkan semua kelompok keamanan tempat pengguna menjadi anggota, pilih Grup keamanan.

     

     Untuk memancarkan grup dengan menggunakan atribut Direktori Aktif yang disinkronkan dari Direktori Aktif alih-alih atribut ID objectID Microsoft Entra, pilih format yang diperlukan dari daftar drop-down Atribut sumber. Hanya grup yang disinkronkan dari Direktori Aktif yang akan disertakan dalam klaim.

     

   • Untuk hanya mengeluarkan grup yang ditetapkan ke aplikasi, pilih Grup yang Ditetapkan ke aplikasi.

     

     Grup yang ditetapkan ke aplikasi akan disertakan dalam token. Grup lain yang merupakan tempat pengguna menjadi anggota akan dihilangkan. Dengan opsi ini, grup bertumpuk tidak disertakan dan pengguna harus menjadi anggota langsung dari grup yang ditetapkan ke aplikasi.

     Untuk mengubah grup yang ditetapkan ke aplikasi, pilih aplikasi dari daftar Aplikasi Enterprise. Kemudian pilih Pengguna dan Grup dari menu kiri aplikasi.

     Untuk informasi selengkapnya tentang mengelola penugasan grup ke aplikasi, lihat Menetapkan pengguna atau grup ke aplikasi perusahaan.

Memancarkan nama tampilan grup khusus cloud dalam token

Anda dapat mengonfigurasi klaim grup untuk menyertakan nama tampilan grup untuk grup khusus cloud.

1. Buka Aplikasi Perusahaan, pilih aplikasi dalam daftar, pilih konfigurasi Akses Menyeluruh, lalu pilih Atribut & Klaim Pengguna.

2. Jika Anda sudah memiliki klaim grup yang dikonfigurasi, pilih dari bagian Klaim tambahan. Jika tidak, Anda dapat menambahkan klaim grup seperti yang dijelaskan di langkah-langkah sebelumnya.

3. Untuk jenis grup yang dipancarkan dalam token, pilih Grup yang ditetapkan ke aplikasi:

   

4. Untuk memancarkan nama tampilan grup hanya untuk grup cloud, di menu dropdown Atribut sumber pilih nama tampilan grup khusus Cloud:

   

5. Untuk penyiapan hibrid, untuk memancarkan atribut grup lokal untuk grup yang disinkronkan dan nama tampilan untuk grup cloud, Anda dapat memilih atribut sumber lokal yang diinginkan dan memeriksa kotak centang Keluarkan nama grup untuk grup khusus cloud:

   

Catatan

Anda hanya dapat menambahkan nama grup cloud dari grup yang ditetapkan ke aplikasi. Pembatasan groups assigned to the application untuk adalah karena nama grup tidak unik, dan nama tampilan hanya dapat dipancarkan untuk grup yang secara eksplisit ditetapkan ke aplikasi untuk mengurangi risiko keamanan. Jika tidak, setiap pengguna dapat membuat grup dengan nama duplikat dan mendapatkan akses di sisi aplikasi.

Set opsi lanjutan

Mengkustomisasi nama klaim grup

Anda dapat mengubah cara klaim grup dikeluarkan dengan menggunakan pengaturan di bawah Opsi lanjutan.

Jika memilih Kustomisasi nama klaim grup, Anda dapat menentukan jenis klaim yang berbeda untuk klaim grup. Masukkan jenis klaim di kotak Nama dan namespace layanan opsional untuk klaim di kotak Namespace layanan.

Beberapa aplikasi mengharuskan informasi keanggotaan grup muncul dalam klaim peran. Anda dapat secara opsional memancarkan grup pengguna sebagai peran dengan mencentang kotak Keluarkan grup sebagai klaim peran.

Catatan

Jika Anda menggunakan opsi untuk mengeluarkan data grup sebagai peran, hanya grup yang akan muncul dalam klaim peran. Peran aplikasi yang ditetapkan kepada pengguna tidak akan muncul dalam klaim peran.

Pemfilteran grup

Pemfilteran grup memungkinkan kontrol terperinci daftar grup yang disertakan sebagai bagian dari klaim grup. Ketika filter dikonfigurasi, hanya grup yang cocok dengan filter yang akan disertakan dalam klaim grup yang dikirim ke aplikasi tersebut. Filter akan diterapkan terhadap semua kelompok terlepas dari hierarki grup.

Catatan

Pemfilteran grup berlaku unruk permintaan token untuk aplikasi tempat claim dan pemfilteran dikonfigurasi di bilah Aplikasi Enterprise portal.
Pemfilteran grup tidak berlaku untuk peran Microsoft Entra.

Anda dapat mengonfigurasi filter untuk diterapkan ke nama tampilan atau SAMAccountName atribut grup. Operasi pemfilteran berikut didukung:

• Prefiks: Mencocokkan awal atribut yang dipilih.
• Sufiks: Mencocokkan akhir atribut yang dipilih.
• Berisi: Cocok dengan lokasi mana pun di atribut yang dipilih.

Transformasi grup

Beberapa aplikasi mungkin memerlukan grup dalam format yang berbeda dari bagaimana mereka diwakili dalam ID Microsoft Entra. Untuk mendukung hal ini, Anda dapat menerapkan transformasi untuk setiap grup yang akan dikeluarkan dalam klaim grup. Hal ini dicapai dengan memungkinkan konfigurasi regex dan nilai pengganti pada klaim grup kustom.

\

• Pola Regex: Gunakan regex untuk mengurai string teks sesuai dengan pola yang Anda atur dalam kotak ini. Jika pola ekspresi reguler yang Anda uraikan bernilai true, pola penggantian regex akan berjalan.
• Pola penggantian regex: Uraikan dalam notasi regex bagaimana Anda ingin mengganti string Anda jika pola regex yang Anda uraikan bernilai true. Gunakan grup ambil untuk mencocokkan subekspresi dalam regex pengganti ini.

Untuk informasi selengkapnya tentang penggantian regex dan grup ambil, lihat Model Objek Regex: Grup yang Diambil.

Catatan

Seperti yang dijelaskan dalam dokumentasi Microsoft Entra, Anda tidak dapat mengubah klaim terbatas dengan menggunakan kebijakan. Sumber data tidak dapat diubah, serta tidak ada transformasi yang diterapkan saat Anda membuat klaim ini. Klaim grup masih merupakan klaim terbatas, jadi Anda perlu menyesuaikan grup dengan mengubah nama. Jika Anda memilih nama terbatas untuk nama klaim grup kustom Anda, klaim akan diabaikan saat runtime.

Fitur transformasi regex juga dapat digunakan sebagai filter, karena setiap grup yang tidak sesuai dengan pola regex tidak akan dikeluarkan dalam klaim yang dihasilkan.

Jika transformasi yang diterapkan ke klaim grup asli menghasilkan klaim kustom baru, maka klaim grup asli akan dihilangkan dari token. Namun, jika regex yang dikonfigurasi tidak cocok dengan nilai apa pun dalam daftar asli, maka klaim kustom tidak akan ada dan klaim grup asli akan disertakan dalam token.

Edit konfigurasi klaim grup

Setelah Anda menambahkan konfigurasi klaim grup ke konfigurasi Atribut Pengguna & Klaim , opsi untuk menambahkan klaim grup tidak akan tersedia. Untuk mengubah konfigurasi klaim grup, pilih klaim grup di daftar Klaim tambahan.

Mengonfigurasi pendaftaran aplikasi Microsoft Entra untuk atribut grup

Anda juga dapat mengonfigurasi klaim grup di bagian klaim opsional dari manifes aplikasi.

1. Di portal, pilih Aplikasi> Identitas>Pendaftaran aplikasi> Pilih Manifes Aplikasi.>

2. Aktifkan klaim keanggotaan grup dengan mengubah groupMembershipClaims.

   Nilai yang valid adalah:

   Pilihan	Deskripsi
   All	Mengeluarkan grup keamanan, peran, dan daftar distribusi.
   SecurityGroup	Memancarkan grup keamanan dan peran Microsoft Entra bahwa pengguna adalah anggota dalam klaim grup.
   DirectoryRole	Jika pengguna ditetapkan peran direktori, peran tersebut akan dikeluarkan sebagai klaim wids. (Klaim grup tidak akan dikeluarkan.)
   ApplicationGroup	Hanya mengeluarkan grup yang secara eksplisit ditetapkan ke aplikasi dan pengguna adalah anggota.
   None	Tidak ada grup yang dikembalikan. (Hal ini tidak peka huruf besar/kecil, sehingga none juga dimungkinkan. Ia dapat diatur langsung dalam manifes aplikasi.)

   Contohnya:

   "groupMembershipClaims": "SecurityGroup"
   

   Secara default, atribut grup ObjectID akan ditampilkan dalam nilai klaim grup. Untuk mengubah nilai klaim agar berisi atribut grup lokal, atau untuk mengubah jenis klaim menjadi peran, gunakan konfigurasi optionalClaims yang dijelaskan di langkah berikutnya.

3. Atur klaim opsional untuk konfigurasi nama grup.

   Jika Anda ingin grup dalam token berisi atribut grup Active Directory lokal, tentukan klaim opsional jenis token mana yang harus diterapkan di bagian optionalClaims. Anda dapat mencantumkan beberapa jenis token:

   • idToken untuk token ID OIDC
   • accessToken untuk token akses OAuth/OIDC
   • Saml2Token untuk token SAML

   Catatan

   Jenis Saml2Token berlaku untuk token dalam format SAML 1.1 dan SAML 2.0.

   Untuk setiap jenis token yang relevan, ubah klaim grup untuk menggunakan bagian optionalClaims dalam manifes. Skema optionalClaims adalah sebagai berikut:

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

   Skema klaim opsional	Nilai
   name	Harus berupa "groups" .
   source	Tidak digunakan. Hilangkan atau tentukan null.
   essential	Tidak digunakan. Hilangkan atau tentukan false.
   additionalProperties	Daftar properti tambahan. Opsi yang valid adalah "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name", "cloud_displayname", dan "emit_as_roles".

   Di additionalProperties, hanya satu dari "sam_account_name", "dns_domain_and_sam_account_name", atau "netbios_domain_and_sam_account_name" yang diperlukan. Jika ada lebih dari satu, yang pertama digunakan dan yang lainnya diabaikan.

   Beberapa aplikasi memerlukan informasi grup tentang pengguna dalam klaim peran. Untuk mengubah jenis klaim dari klaim grup menjadi klaim peran, tambahkan "emit_as_roles" ke properti tambahan. Nilai grup akan dikeluarkan dalam klaim peran.

   Untuk memancarkan nama tampilan grup untuk grup khusus cloud, Anda dapat menambahkan "cloud_displayname" ke additional properties. Opsi ini hanya akan berfungsi ketika “groupMembershipClaims” diatur ke ApplicationGroup

   Catatan

   Jika Anda menggunakan "emit_as_roles", peran aplikasi yang dikonfigurasi yang ditetapkan pengguna tidak akan muncul dalam klaim peran.

Contoh

Keluarkan grup sebagai nama grup dalam token akses OAuth dalam format DNSDomainName\sAMAccountName:

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

Keluarkan nama grup untuk ditampilkan dalam format NetbiosDomain\sAMAccountName sebagai klaim peran dalam token SAML dan ID OIDC:

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

Langkah berikutnya

• Menambahkan otorisasi menggunakan grup & klaim grup ke aplikasi web ASP.NET Core (sampel kode)
• Menetapkan pengguna atau grup ke aplikasi perusahaan
• Mengonfigurasi klaim peran