Memberikan klaim opsional ke aplikasi Anda

  • Artikel
  • 18 menit untuk membaca

Pengembang aplikasi dapat menggunakan klaim opsional dalam aplikasi Microsoft Azure AD mereka untuk menentukan klaim mana yang mereka inginkan dalam token yang dikirim ke aplikasi mereka.

Anda dapat menggunakan klaim opsional untuk:

  • Memilih klaim tambahan untuk disertakan dalam token aplikasi Anda.
  • Mengubah sifat klaim tertentu yang dihasilkan platform identitas Microsoft dalam token.
  • Menambahkan dan mengakses klaim kustom untuk aplikasi Anda.

Untuk daftar klaim standar, lihat token akses dan dokumentasi klaim id_token.

Meskipun klaim opsional didukung dalam token format v1.0 dan v2.0, dan token SAML, klaim tersebut memberikan sebagian besar nilainya saat berpindah dari v1.0 ke v2.0. Salah satu tujuan platform identitas Microsoft adalah ukuran token yang lebih kecil untuk memastikan performa optimal oleh klien. Akibatnya, beberapa klaim yang sebelumnya termasuk dalam token akses dan ID tidak lagi muncul dalam token v2.0, dan harus diminta secara khusus berdasarkan setiap aplikasi.

Tabel 1: Penerapan

Jenis Akun Token v1.0 Token v2.0
Akun Microsoft pribadi T/A Didukung
Akun Microsoft Azure AD Didukung Didukung

Set klaim opsional v1.0 dan v2.0

Kumpulan klaim opsional yang tersedia secara default untuk digunakan aplikasi tercantum di bawah ini. Anda dapat menggunakan data kustom dalam atribut ekstensi dan ekstensi direktori untuk menambahkan klaim opsional untuk aplikasi Anda. Untuk menggunakan ekstensi direktori, lihat Ekstensi Direktori, di bawah ini. Saat menambahkan klaim ke token akses, klaim berlaku untuk mengakses token yang diminta untuk aplikasi (API web), bukan klaim yang diminta oleh aplikasi. Tidak penting bagaimana klien mengakses API Anda, data yang tepat berada dalam token akses yang digunakan untuk mengautentikasi terhadap API Anda.

Catatan

Sebagian besar klaim ini dapat dimasukkan dalam JWT untuk token v1.0 dan v2.0, tetapi bukan token SAML, kecuali jika terletak di kolom Jenis Token. Akun konsumen mendukung sub rangkaian klaim ini, ditandai di kolom "Jenis Pengguna". Banyak klaim yang tercantum tidak berlaku untuk pengguna konsumen (mereka tidak memiliki penyewa, sehingga tenant_ctry tidak memiliki nilai).

Tabel 2: Set klaim opsional v1.0 dan v2.0

Nama Deskripsi Jenis Token Jenis pengguna Catatan
acct Status akun pengguna dalam penyewa JWT, SAML Jika pengguna adalah anggota penyewa, nilainya adalah 0. Jika mereka adalah tamu, nilainya adalah 1.
auth_time Waktu ketika pengguna terakhir diautentikasi. Lihat spesifikasi OpenID Connect. JWT
ctry Negara/wilayah pengguna JWT Microsoft Azure AD menghasilkan klaim opsional ctry jika ada, dan nilai bidang adalah kode negara/kawasan dua huruf standar, seperti FR, JP, SZ, dan sebagainya.
email Alamat email yang dilaporkan untuk pengguna ini JWT, SAML MSA, Microsoft Azure AD Nilai ini disertakan secara default jika pengguna adalah tamu dalam penyewa. Untuk pengguna terkelola (pengguna di dalam penyewa), harus diminta melalui klaim opsional ini atau, hanya pada v2.0, dengan cakupan OpenID. Nilai ini tidak dijamin benar, dan dapat berubah dari waktu ke waktu - jangan pernah menggunakannya untuk otorisasi atau untuk menyimpan data bagi pengguna. Untuk informasi selengkapnya, lihat Memvalidasi izin pengguna untuk mengakses data ini. Jika Anda memerlukan alamat email yang dapat dialamatkan di aplikasi Anda, minta data ini dari pengguna secara langsung, menggunakan klaim ini sebagai saran atau mengisi UX Anda.
fwd Alamat IP. JWT Menambahkan alamat IPv4 asli klien yang meminta (saat berada di dalam VNET)
groups Pembuatan format opsional untuk klaim grup JWT, SAML Untuk detail lihat Klaim grup berikut. Untuk informasi selengkapnya tentang klaim grup, lihat Cara mengonfigurasi klaim grup. Digunakan dengan pengaturan GroupMembershipClaims dalam manifes aplikasi, yang harus diatur juga.
idtyp Jenis token Token akses JWT Khusus: hanya dalam token akses khusus aplikasi Nilai adalah app ketika token merupakan token khusus aplikasi. Ini adalah cara paling akurat bagi API untuk menentukan jika token adalah token aplikasi atau token pengguna+aplikasi.
login_hint Petunjuk login JWT MSA, Microsoft Azure AD Klaim petunjuk masuk yang buram dan andal yang dikodekan base64. Jangan ubah nilai ini. Klaim ini adalah nilai terbaik yang digunakan untuk parameter OAuth login_hint di semua alur untuk mendapatkan SSO. Klaim ini dapat diteruskan di antara aplikasi untuk membantu melakukan SSO juga secara diam-diam - aplikasi A dapat membuat pengguna masuk, membaca klaim login_hint, lalu mengirim klaim dan konteks penyewa saat ini ke aplikasi B dalam string kueri atau fragmen ketika pengguna mengeklik link yang mengarahkan mereka ke aplikasi B. Untuk menghindari kondisi bersaing dan masalah keandalan, klaim login_hinttidak menyertakan penyewa saat ini untuk pengguna, dan default ke penyewa rumah pengguna saat digunakan. Jika Anda beroperasi dalam skenario tamu, di mana pengguna berasal dari penyewa lain, Anda harus memberikan pengidentifikasi penyewa dalam permintaan kredensial masuk, dan meneruskannya ke aplikasi yang bermitra dengan Anda. Klaim ini dimaksudkan untuk digunakan dengan fungsionalitas SDK login_hint Anda yang sudah ada, meskipun terbuka.
sid ID sesi, digunakan untuk keluar pengguna per sesi. JWT Akun Microsoft Azure AD dan Pribadi.
tenant_ctry Negara/wilayah penyewa sumber daya JWT Sama seperti ctry kecuali diatur pada tingkat penyewa oleh admin. Juga harus merupakan nilai dua huruf standar.
tenant_region_scope Wilayah penyewa sumber daya JWT
upn UserPrincipalName JWT, SAML Pengidentifikasi untuk pengguna yang dapat digunakan dengan parameter username_hint. Bukan pengidentifikasi yang tahan lama bagi pengguna dan tidak boleh digunakan untuk otorisasi atau untuk mengidentifikasi informasi pengguna secara unik (misalnya, sebagai kunci database). Sebagai gantinya, gunakan ID objek pengguna (oid) sebagai kunci database. Untuk informasi selengkapnya, lihat Memvalidasi izin pengguna untuk mengakses data ini. Pengguna yang masuk dengan ID masuk alternatif tidak boleh menunjukkan Nama Prinsipal Pengguna (UPN) mereka. Sebagai gantinya, gunakan klaim token ID berikut untuk menampilkan status masuk kepada pengguna: preferred_username atau unique_name untuk token v1 dan preferred_username untuk token v2. Meskipun klaim ini disertakan secara otomatis, Anda dapat menentukannya sebagai klaim opsional untuk melampirkan properti tambahan guna memodifikasi sifatnya dalam kasus pengguna tamu. Anda harus menggunakan klaim login_hint untuk penggunaan login_hint - pengidentifikasi yang dapat dibaca manusia seperti UPN tidak dapat diandalkan.
verified_primary_email Bersumber dari PrimaryAuthoritativeEmail pengguna JWT
verified_secondary_email Bersumber dari SecondaryAuthoritativeEmail pengguna JWT
vnet Informasi penentu VNET. JWT
xms_pdl Lokasi data pilihan JWT Untuk penyewa Multi-Lokasi, lokasi data pilihan adalah kode tiga huruf yang menunjukkan wilayah geografis tempat pengguna berada. Untuk informasi selengkapnya, lihat dokumentasi Microsoft Azure AD Connect tentang lokasi data pilihan.
Contohnya: APC untuk Asia Pasifik.
xms_pl Bahasa pilihan JWT Bahasa pilihan pengguna, jika diterapkan. Bersumber dari penyewa asal mereka, dalam skenario akses tamu. LL-CC yang diformat ("id-id").
xms_tpl Bahasa pilihan penyewa JWT Bahasa pilihan penyewa sumber daya, jika ditetapkan. LL yang diformat ("id").
ztdid ID Penyebaran Tanpa Sentuhan JWT Identitas perangkat yang digunakan untuk Windows AutoPilot

Kumpulan klaim opsional tertentu v2.0

Klaim ini selalu disertakan dalam token Microsoft Azure AD v1.0, tetapi tidak termasuk dalam token v2.0 kecuali diminta. Klaim ini hanya berlaku untuk JWT (token ID dan Token Akses).

Tabel 3: Klaim opsional v2.0 saja

Klaim JWT Nama Deskripsi Catatan
ipaddr Alamat IP Alamat IP klien tempat masuk.
onprem_sid Pengenal Keamanan Lokal
pwd_exp Kebijakan kedaluwarsa kata sandi Jumlah detik setelah waktu dalam klaim iat di mana kata sandi kedaluwarsa. Klaim ini hanya disertakan ketika kata sandi akan segera kedaluwarsa (seperti yang didefinisikan oleh "hari pemberitahuan" dalam kebijakan kata sandi).
pwd_url Ubah URL kata sandi URL yang dapat dikunjungi pengguna untuk mengubah kata sandi. Klaim ini hanya disertakan ketika kata sandi akan segera kedaluwarsa (seperti yang didefinisikan oleh "hari pemberitahuan" dalam kebijakan kata sandi).
in_corp Dalam Jaringan Perusahaan Memberi sinyal jika klien masuk dari jaringan perusahaan. Jika tidak, klaim tidak disertakan. Berdasarkan pengaturan IP tepercaya di MFA.
family_name Nama Belakang Memberi nama belakang, atau nama keluarga pengguna seperti yang ditentukan pada objek pengguna.
"family_name":"Miller"		 Didukung di MSA dan Microsoft Azure AD. Membutuhkan cakupan profile.
given_name Nama depan Memberi nama pertama pengguna, seperti yang diatur pada objek pengguna.
"given_name": "Frank"		 Didukung di MSA dan Microsoft Azure AD. Membutuhkan cakupan profile.
upn Nama Utama Pengguna Pengidentifikasi untuk pengguna yang dapat digunakan dengan parameter username_hint. Bukan pengidentifikasi yang tahan lama bagi pengguna dan tidak boleh digunakan untuk otorisasi atau untuk mengidentifikasi informasi pengguna secara unik (misalnya, sebagai kunci database). Untuk informasi selengkapnya, lihat Memvalidasi izin pengguna untuk mengakses data ini. Sebagai gantinya, gunakan ID objek pengguna (oid) sebagai kunci database. Pengguna yang masuk dengan ID masuk alternatif tidak boleh menunjukkan Nama Prinsipal Pengguna (UPN) mereka. Sebagai gantinya, gunakan klaim preferred_username berikut untuk menampilkan status masuk kepada pengguna. Lihat properti tambahan berikut untuk konfigurasi klaim. Membutuhkan cakupan profile.

Kumpulan klaim opsional tertentu v1.0

Beberapa peningkatan format token v2 tersedia untuk aplikasi yang menggunakan format token v1, karena mereka membantu meningkatkan keamanan dan keandalan. Peningkatan ini tidak akan berlaku untuk token ID yang diminta dari titik akhir v2, atau token akses untuk API yang menggunakan format token v2. Peningkatan ini hanya berlaku untuk JWT, bukan token SAML.

Tabel 4: Klaim opsional v1.0 saja

Klaim JWT Nama Deskripsi Catatan
aud Audiens Selalu hadir di JWT, tetapi dalam token akses v1 dapat dipancarkan dengan berbagai cara - semua jenis URI appID, dengan atau tanpa garis miring berikutnya, serta ID klien sumber daya. Pengacakan ini bisa sulit untuk dikodekan ketika melakukan validasi token. Gunakan properti tambahan untuk klaim ini guna memastikan properti selalu ditetapkan ke ID klien sumber daya dalam token akses v1. Token akses v1 JWT saja
preferred_username Nama pengguna pilihan Memberikan klaim nama pengguna pilihan dalam token v1. Klaim ini memudahkan aplikasi untuk memberikan petunjuk nama pengguna dan menampilkan nama tampilan yang dapat dibaca manusia, terlepas dari jenis token mereka. Sebaiknya gunakan klaim opsional ini alih-alih menggunakan, misalnya,upn atau unique_name. token ID v1 dan token akses

Properti tambahan dari klaim opsional

Beberapa klaim opsional dapat dikonfigurasi untuk mengubah cara klaim dihasilkan. Properti tambahan ini sebagian besar digunakan untuk membantu migrasi aplikasi lokal dengan harapan data yang berbeda. Misalnya, include_externally_authenticated_upn_without_hash membantu klien yang tidak dapat menangani tanda hash (#) di UPN.

Tabel 4: Nilai untuk mengonfigurasi klaim opsional

Nama properti Nama properti Tambahan Deskripsi
upn Dapat digunakan untuk respons SAML dan JWT, serta untuk token v1.0 dan v2.0.
include_externally_authenticated_upn Termasuk UPN tamu seperti yang disimpan di penyewa sumber daya. Contohnya, foo_hometenant.com#EXT#@resourcetenant.com
include_externally_authenticated_upn_without_hash Sama seperti di atas, kecuali tanda pagar (#) diganti dengan garis bawah (_), contohnya foo_hometenant.com_EXT_@resourcetenant.com
aud Dalam token akses v1, klaim ini digunakan untuk mengubah format klaim aud. Klaim ini tidak berpengaruh pada token v2, atau token ID kedua versi, di mana klaim aud selalu merupakan ID klien. Gunakan konfigurasi ini untuk memastikan bahwa API Anda dapat melakukan validasi audiens dengan lebih mudah. Seperti semua klaim opsional yang memengaruhi token akses, sumber daya dalam permintaan harus menetapkan klaim opsional ini, karena sumber daya memiliki token akses.
use_guid Mengeluarkan ID klien sumber daya (API) dalam format GUID selalu sebagai klaim aud alih-alih tergantung pada runtime. Misalnya, jika sumber daya mengatur tanda ini, dan ID kliennya adalah bb0a297b-6a42-4a55-ac40-09a501456577, aplikasi apa pun yang meminta token akses untuk sumber daya tersebut akan menerima token akses dengan aud : bb0a297b-6a42-4a55-ac40-09a501456577.

Tanpa set klaim ini, API bisa mendapatkan token dengan klaim aud berupa api://MyApi.com, api://MyApi.com/, api://myapi.com/AdditionalRegisteredField atau nilai lain yang ditetapkan sebagai URI ID aplikasi untuk API tersebut, serta ID klien sumber daya.

Contoh properti tambahan

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ]
}

Objek OptionalClaims ini menyebabkan token ID dihasilkan ke klien untuk menyertakan klaim upn dengan penyewa asal tambahan dan informasi penyewa sumber daya. Klaim upn hanya diubah dalam token jika pengguna adalah tamu di penyewa (yang menggunakan IDP yang berbeda untuk autentikasi).

Mengonfigurasi klaim opsional

Penting

Token akses selalu dihasilkan menggunakan manifes sumber daya, bukan klien. Sehingga, dalam ...scope=https://graph.microsoft.com/user.read... permintaan, sumber daya merupakan API Microsoft Graph. Dengan demikian, token akses dibuat menggunakan manifes API Microsoft Graph, bukan manifes klien. Mengubah manifes untuk aplikasi Anda tidak akan menyebabkan token API Microsoft Graph terlihat berbeda. Untuk memvalidasi bahwa perubahan accessToken bekerja, minta token untuk aplikasi Anda, bukan aplikasi lain.

Anda dapat mengonfigurasi klaim opsional untuk aplikasi dengan menyesuaikan manifes aplikasi.

  1. Buka portal Microsoft Azure.
  2. Cari dan pilih Microsoft Azure Active Directory.
  3. Di bagian Kelola, pilih Pendaftaran aplikasi.
  4. Pilih aplikasi dalam daftar tempat Anda ingin mengonfigurasi klaim opsional.

Mengonfigurasi klaim opsional melalui UI:

Mengonfigurasi klaim opsional di UI

  1. Di bagian Kelola, pilih Konfigurasi token.

  2. Pilih Tambahkan klaim opsional.

  3. Pilih jenis token yang ingin Anda konfigurasi.

  4. Pilih klaim opsional untuk ditambahkan.

  5. Pilih Tambahkan.

Mengonfigurasi klaim opsional melalui manifes aplikasi:

Menunjukkan cara mengonfigurasi klaim opsional menggunakan manifes aplikasi

  1. Di bagian Kelola, pilih Manifes. Editor manifes berbasis web terbuka, yang memungkinkan Anda mengedit manifes. Secara opsional, Anda dapat memilih Unduh untuk mengedit manifes secara lokal, lalu gunakan Unggah untuk menerapkannya kembali ke aplikasi Anda. Untuk informasi selengkapnya tentang manifes aplikasi, lihat Artikel memahami aplikasi manifes Microsoft Azure AD.

    Entri manifes aplikasi berikut menambahkan klaim opsional auth_time, ipaddr, dan upn ke ID, akses, dan token SAML.

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

  2. Setelah selesai, pilih Simpan. Sekarang klaim opsional yang ditentukan akan dimasukkan dalam token untuk aplikasi Anda.

Jenis OptionalClaims

Menyatakan klaim opsional yang diminta oleh aplikasi. Aplikasi dapat mengonfigurasi klaim opsional untuk dihasilkan dalam masing-masing dari tiga jenis token (token ID, token akses, token SAML 2) yang dapat diterima olehnya melalui layanan token keamanan. Aplikasi ini dapat mengonfigurasi set klaim opsional yang berbeda untuk dihasilkan dalam setiap jenis token. Properti OptionalClaims dari entitas Aplikasi adalah objek OptionalClaims.

Tabel 5: Properti jenis OptionalClaims

Nama Jenis Deskripsi
idToken Kumpulan (OptionalClaim) Klaim opsional dihasilkan dalam token ID JWT.
accessToken Kumpulan (OptionalClaim) Klaim opsional dihasilkan dalam token akses JWT.
saml2Token Kumpulan (OptionalClaim) Klaim opsional dihasilkan dalam token SAML.

Jenis OptionalClaim

Berisi klaim opsional yang terkait dengan aplikasi atau perwakilan layanan. Properti idToken, accessToken, dan saml2Token dari jenis OptionalClaims adalah kumpulan OptionalClaim. Jika didukung oleh klaim tertentu, Anda juga dapat menyesuaikan perilaku OptionalClaim menggunakan bidang AdditionalProperties.

Tabel 6: Properti jenis OptionalClaim

Nama Jenis Deskripsi
name Edm.String Nama klaim opsional.
source Edm.String Sumber (objek direktori) klaim. Ada klaim yang ditentukan sebelumnya dan klaim yang ditentukan pengguna dari properti ekstensi. Jika nilai sumber null, klaimnya adalah klaim opsional yang ditentukan. Jika nilai sumber adalah pengguna, nilai dalam properti nama adalah properti ekstensi dari objek pengguna.
essential Edm.Boolean Jika nilai tersebut true, klaim yang ditentukan oleh klien diperlukan untuk memastikan pengalaman otorisasi yang lancar dengan tugas tertentu yang diminta oleh pengguna akhir. Nilai defaultnya adalah false.
additionalProperties Kumpulan (Edm.String) Properti tambahan klaim. Jika properti ada dalam kumpulan ini, properti akan menyesuaikan sifat klaim opsional yang ditentukan dalam properti nama.

Mengonfigurasi klaim opsional ekstensi direktori

Selain klaim opsional standar yang ditetapkan, Anda juga dapat mengonfigurasi token untuk menyertakan ekstensi Microsoft Graph. Untuk informasi selengkapnya, lihat Menambahkan data kustom ke sumber daya menggunakan ekstensi.

Skema dan ekstensi terbuka tidak didukung oleh klaim opsional, hanya ekstensi direktori dan atribut ekstensi. Fitur ini berguna untuk melampirkan informasi pengguna tambahan yang dapat digunakan aplikasi Anda – contohnya, pengidentifikasi tambahan atau opsi konfigurasi penting yang telah ditetapkan pengguna. Lihat bagian bawah halaman ini sebagai contoh.

Ekstensi direktori adalah fitur khusus Azure AD. Jika manifes aplikasi Anda meminta ekstensi khusus, dan pengguna MSA masuk ke aplikasi Anda, ekstensi ini tidak akan dikembalikan.

Pembuatan format ekstensi direktori

Saat mengonfigurasi klaim opsional ekstensi direktori menggunakan manifes aplikasi, gunakan nama lengkap ekstensi (dalam format: extension_<appid>_<attributename> ). <appid> adalah versi appId yang dilucuti (atau ID Klien) dari aplikasi yang meminta klaim.

Dalam JWT, klaim ini akan dikeluarkan dengan format nama berikut: extn.<attributename>.

Dalam token SAML, klaim ini akan dikeluarkan dengan format URI berikut: http://schemas.microsoft.com/identity/claims/extn.<attributename>

Mengonfigurasi klaim opsional grup

Bagian ini mencakup opsi konfigurasi di bagian klaim opsional untuk mengubah atribut grup yang digunakan dalam klaim grup dari objectID grup default ke atribut yang disinkronkan dari Direktori Aktif Windows lokal. Anda dapat mengonfigurasi klaim opsional untuk aplikasi dengan menyesuaikan UI atau manifes aplikasi.

Penting

Azure AD membatasi jumlah grup yang akan dikeluarkannya dalam token hingga 150 untuk pernyataan SAML dan 200 untuk JWT, termasuk grup berlapis. Untuk detail selengkapnya tentang batas grup dan peringatan penting untuk klaim grup dari atribut lokal, lihat Mengonfigurasi klaim grup untuk aplikasi dengan Azure AD.

Mengonfigurasi klaim opsional grup melalui UI:

  1. Masuk ke portal Microsoft Azure.
  2. Setelah mengautentikasi, pilih penyewa Microsoft Azure AD Anda dengan memilihnya dari sudut kanan atas halaman.
  3. Cari dan pilih Microsoft Azure Active Directory.
  4. Di bagian Kelola, pilih Pendaftaran aplikasi.
  5. Pilih aplikasi dalam daftar tempat Anda ingin mengonfigurasi klaim opsional.
  6. Di bagian Kelola, pilih Konfigurasi token.
  7. Pilih Tambah klaim grup.
  8. Pilih jenis grup yang akan dihasilkan (Grup keamanan, atau peran Direktori, Semua grup, dan/atau Grup yang ditetapkan ke aplikasi).
    • Opsi Grup yang Ditetapkan ke aplikasi menyertakan hanya grup yang ditetapkan dalam aplikasi. Opsi Grup yang ditetapkan ke aplikasi direkomendasikan untuk organisasi besar karena batas nomor grup dalam token. Untuk mengubah grup yang ditetapkan ke aplikasi, pilih aplikasi dari daftar Aplikasi Enterprise. Pilih Pengguna dan grup, lalu pilih Tambahkan pengguna/grup. Pilih grup yang ingin Anda tambahkan ke aplikasi dari Pengguna dan grup.
    • Opsi Semua Grup mencakup SecurityGroup, DirectoryRole, dan DistributionList, tetapi bukan Grup yang ditetapkan untuk aplikasi.
  9. Opsional: pilih properti jenis token tertentu untuk menyesuaikan nilai klaim grup yang dikandung pada atribut grup lokal atau untuk mengubah jenis klaim menjadi peran.
  10. Pilih Simpan.

Mengonfigurasi klaim opsional grup melalui manifes aplikasi:

  1. Masuk ke portal Microsoft Azure.

  2. Setelah mengautentikasi, pilih penyewa Microsoft Azure AD Anda dengan memilihnya dari sudut kanan atas halaman.

  3. Cari dan pilih Microsoft Azure Active Directory.

  4. Pilih aplikasi dalam daftar tempat Anda ingin mengonfigurasi klaim opsional.

  5. Di bagian Kelola, pilih Manifes.

  6. Tambahkan entri berikut menggunakan editor manifes:

    Nilai yang valid adalah:

    • "Semua" (opsi ini mencakup SecurityGroup, DirectoryRole, dan DistributionList)
    • "SecurityGroup"
    • "DirectoryRole"
    • "ApplicationGroup" (opsi ini hanya mencakup grup yang ditetapkan ke aplikasi)

    Contohnya:

    "groupMembershipClaims": "SecurityGroup"

    Secara default ObjectID Grup akan dikeluarkan dalam nilai klaim grup. Untuk mengubah nilai klaim menjadi berisi atribut grup lokal, atau mengubah jenis klaim menjadi peran, gunakan konfigurasi OptionalClaims sebagai berikut:

  7. Setel klaim opsional konfigurasi nama grup.

    Jika Anda ingin grup dalam token terisi dengan atribut grup AD di bagian klaim opsional, tentukan klaim opsional tempat jenis token diterapkan, nama klaim opsional yang diminta, dan semua jenis properti tambahan yang diinginkan. Beberapa jenis token dapat dicantumkan:

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

    Jenis Saml2Token berlaku untuk token format SAML1.1 dan SAML2.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
    nama: Harus "grup"
    sumber: Tidak digunakan. Hilangkan atau tentukan null
    esensial: 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", "emit_as_roles" dan "cloud_displayname"

    Dalam additionalProperties hanya ada memerlukan satu dari "sam_account_name", “dns_domain_and_sam_account_name”, “netbios_domain_and_sam_account_name”. Jika ada lebih dari satu, yang pertama digunakan dan yang lain diabaikan. Selain itu, Anda dapat menambahkan "cloud_displayname" untuk memancarkan nama tampilan grup cloud. Perhatikan, bahwa opsi ini hanya berfungsi ketika “groupMembershipClaims” diatur ke “ApplicationGroup”.

    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.

    Jika "emit_as_roles" digunakan, semua jenis peran aplikasi yang dikonfigurasi bahwa pengguna ditetapkan tidak akan muncul dalam klaim peran.

Contoh:

  1. Mengeluarkan grup sebagai nama grup dalam token akses OAuth dalam format dnsDomainName\sAMAccountName

    Konfigurasi UI:

    Konfigurasikan klaim opsional

    Entri manifes aplikasi:

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

  2. Mengeluarkan nama grup yang akan dihasilkan dalam format netbiosDomain\sAMAccountName sebagai klaim peran dalam Token ID SAML dan OIDC

    Konfigurasi UI:

    Klaim opsional dalam manifes

    Entri manifes aplikasi:

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

  3. Keluarkan nama grup dalam format samAccountName untuk grup yang disinkronkan lokal dan nama tampilan untuk grup cloud di Saml dan Token ID OIDC untuk grup yang ditetapkan ke aplikasi:

    Entri manifes aplikasi:

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

Contoh klaim opsional

Di bagian ini, Anda dapat menelusuri skenario untuk melihat jika Anda dapat menggunakan fitur klaim opsional untuk aplikasi Anda. Ada beberapa opsi yang tersedia untuk memperbarui properti pada konfigurasi identitas aplikasi untuk mengaktifkan dan mengonfigurasi klaim opsional:

  • Anda dapat menggunakan UI Konfigurasi token (lihat contoh di bawah)
  • Anda dapat menggunakan Manifes (lihat contoh di bawah). Baca Memahami dokumen manifes aplikasi Microsoft Azure AD sebelumnya untuk pengenalan dengan manifes.
  • Anda juga dapat menulis aplikasi yang menggunakan API Microsoft Graph untuk memperbarui aplikasi Anda. Jenis OptionalClaims dalam panduan referensi API Microsoft Graph dapat membantu Anda mengonfigurasi klaim opsional.

Contoh:

Dalam contoh berikut, Anda akan menggunakan UI Konfigurasi token dan Manifes untuk menambahkan klaim opsional ke token akses, ID, dan SAML yang ditujukan untuk aplikasi Anda. Beragam klaim opsional akan ditambahkan ke setiap jenis token yang dapat diterima aplikasi:

  • Token ID sekarang akan berisi UPN untuk pengguna gabungan dalam bentuk lengkap (<upn>_<homedomain>#EXT#@<resourcedomain>).
  • Token akses yang diminta klien lain untuk aplikasi ini sekarang akan mencakup klaim auth_time.
  • Token SAML sekarang akan berisi ekstensi skema direktori skypeId (dalam contoh ini, ID aplikasi untuk aplikasi ini adalah ab603c56068041afb2f6832e2a17e237). Token SAML akan mengekspos ID Skype sebagai extension_ab603c56068041afb2f6832e2a17e237_skypeId.

Konfigurasi UI:

  1. Masuk ke portal Microsoft Azure.

  2. Setelah mengautentikasi, pilih penyewa Microsoft Azure AD Anda dengan memilihnya dari sudut kanan atas halaman.

  3. Cari dan pilih Microsoft Azure Active Directory.

  4. Di bagian Kelola, pilih Pendaftaran aplikasi.

  5. Pilih aplikasi tempat Anda ingin mengonfigurasi klaim opsional dalam daftar.

  6. Di bagian Kelola, pilih Konfigurasi token.

  7. Pilih Tambah klaim opsional, pilih jenis token ID, pilih upn dari daftar klaim, lalu pilih Tambahkan.

  8. Pilih Tambah klaim opsional, pilih jenis token Akses, pilih auth_time dari daftar klaim, lalu pilih Tambahkan.

  9. Dari layar gambaran umum Konfigurasi Token, pilih ikon pensil di samping upn, pilih tombol Diautentikasi secara eksternal, lalu pilih Simpan.

  10. Pilih Tambahkan klaim opsional, pilih jenis token SAML, pilih extn.skypeID dari daftar klaim (hanya berlaku jika Anda telah membuat objek pengguna Microsoft Azure AD yang disebut skypeID), lalu pilih Tambahkan.

    Klaim opsional untuk token SAML

Konfigurasi manifes:

  1. Masuk ke portal Microsoft Azure.

  2. Setelah mengautentikasi, pilih penyewa Microsoft Azure AD Anda dengan memilihnya dari sudut kanan atas halaman.

  3. Cari dan pilih Microsoft Azure Active Directory.

  4. Pilih aplikasi tempat Anda ingin mengonfigurasi klaim opsional dalam daftar.

  5. Di bagian Kelola, pilih Manifes untuk membuka editor manifes sebaris.

  6. Anda dapat langsung mengedit manifes menggunakan editor ini. Manifes mengikuti skema untuk Entitas aplikasi, dan membuat format manifes setelah disimpan secara otomatis. Elemen baru akan ditambahkan ke properti OptionalClaims.

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

  7. Setelah selesai memperbarui manifes, pilih Simpan untuk menyimpan manifes.

Langkah berikutnya

Pelajari selengkapnya tentang klaim standar yang disediakan Microsoft Azure AD.