Mengonfigurasi klaim grup untuk aplikasi dengan menggunakan Azure Active Directory

Azure Active Directory (Azure AD) 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 (OID) Azure Active Directory 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 (Pratinjau)

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 tempat pengguna menjadi anggota mungkin melebihi batas yang akan ditambahkan Azure AD ke token. Melebihi batas dapat menyebabkan hasil yang tidak dapat diprediksi. 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 Azure AD tidak berisi atribut yang diperlukan untuk mengeluarkan 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 dipancarkan untuk aplikasi tempat klaim dan pemfilteran grup dikonfigurasi di bilah aplikasi Enterprise di portal.

  • 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 Azure AD mungkin berisi sAMAccountName atribut yang memenuhi syarat domain atau GroupSID atribut yang disinkronkan dari Active Directory, alih-alih objectID atribut Azure AD grup.

Format yang didukung untuk klaim grup adalah:

  • ObjectId grup Azure AD: 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 pada grup yang dibuat di Azure AD atau Office 365. Aplikasi yang dikonfigurasi di Azure AD untuk mendapatkan atribut grup lokal yang disinkronkan membuatnya 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 mengkonsumsi informasi grup melalui klaim, Anda dapat mengonfigurasi Azure AD 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 berubah dan unik di Azure AD. 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 Active Directory, tetapi jika lebih dari satu domain Active Directory disinkronkan dengan penyewa Azure AD, ada kemungkinan lebih dari satu grup 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. Azure AD membatasi jumlah grup yang akan dikeluarkannya 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 Active Directory melalui Azure AD Connect.

Untuk mengonfigurasi Azure AD untuk mengeluarkan nama grup untuk grup Active Directory:

  1. Menyinkronkan nama grup dari Active Directory

    Sebelum Azure AD dapat mengeluarkan nama grup atau SID grup lokal dalam klaim grup atau peran, Anda perlu menyinkronkan atribut yang diperlukan dari Active Directory. Anda harus menjalankan Azure AD Connect versi 1.2.70 atau yang lebih baru. Versi Azure AD Connect yang lebih lama dari 1.2.70 akan menyinkronkan objek grup dari Active Directory, tetapi mereka tidak akan menyertakan atribut nama grup yang diperlukan.

  2. Mengonfigurasi pendaftaran aplikasi di Azure AD 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 Azure AD 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 Enterprise, pilih aplikasi dalam daftar, pilih Konfigurasi Akses Menyeluruh, lalu pilih Klaim &Atribut Pengguna.

  2. Pilih Tambahkan klaim grup.

    Cuplikan layar yang menampilkan halaman untuk atribut dan klaim pengguna, dengan tombol untuk menambahkan klaim grup dipilih.

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

    Cuplikan layar yang menampilkan jendela Klaim Grup dengan opsi grup.

    Pilihan Deskripsi
    Semua grup Mengeluarkan grup keamanan serta daftar dan peran distribusi.
    Kelompok keamanan Mengeluarkan kelompok keamanan tempat pengguna menjadi anggota dalam klaim grup.
    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.

      Cuplikan layar yang menampilkan jendela Klaim Grup, dengan opsi untuk grup keamanan dipilih.

      Untuk mengeluarkan grup dengan menggunakan atribut Active Directory yang disinkronkan dari Active Directory alih-alih atribut objectID Azure AD, pilih format yang diperlukan dari daftar turun Atribut sumber. Hanya grup yang disinkronkan dari Direktori Aktif yang akan disertakan dalam klaim.

      Cuplikan layar yang menampikan menu drop-down untuk atribut sumber.

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

      Cuplikan layar yang menampilkan jendela Klaim Grup, dengan opsi untuk grup yang ditetapkan ke aplikasi dipilih.

      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.

Mengeluarkan nama tampilan grup khusus cloud dalam token (Pratinjau)

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

  1. Buka Aplikasi Enterprise, pilih aplikasi dalam daftar, pilih Konfigurasi Akses Menyeluruh, lalu pilih Klaim &Atribut 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 dalam langkah-langkah sebelumnya.

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

    Cuplikan layar yang menampilkan jendela Klaim Grup, dengan opsi untuk grup yang ditetapkan ke aplikasi dipilih.

  4. Untuk memancarkan nama tampilan grup hanya untuk grup cloud, di menu drop-down Atribut sumber pilih nama tampilan grup khusus Cloud (Pratinjau):

    Cuplikan layar yang memperlihatkan menu dropdown atribut sumber Klaim Grup, dengan opsi untuk mengonfigurasi nama grup hanya cloud yang dipilih.

  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 (Pratinjau):

    Cuplikan layar yang memperlihatkan konfigurasi untuk memancarkan atribut grup lokal untuk grup yang disinkronkan dan nama tampilan untuk grup cloud.

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.

Cuplikan layar yang menampilkan opsi tingkat lanjut, dengan opsi penyesuaian nama klaim grup dipilih dan nilai nama dan namespace dimasukkan.

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.

Cuplikan layar yang menampilkan opsi tingkat lanjut, dengan kotak centang dipilih untuk opsi penyesuaian nama klaim grup dan penghapusan 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.

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.

Cuplikan layar yang menampilkan opsi pemfilteran.

Transformasi grup

Beberapa aplikasi mungkin memerlukan grup dalam format yang berbeda dengan cara mereka diwakilkan dalam Azure AD. 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.

Cuplikan layar transformasi grup, dengan informasi regex ditambahkan.\

  • 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 Azure AD, 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.

Cuplikan layar area untuk atribut dan klaim pengguna, dengan nama klaim grup disorot.

Mengonfigurasi pendaftaran aplikasi Azure AD untuk atribut grup

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

  1. Di portal, pilih Azure Active Directory>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 Mengeluarkan kelompok keamanan tempat pengguna menjadi 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 menjadi 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