Bagikan melalui

Referensi klaim opsional

  • Artikel

Anda dapat menggunakan klaim opsional untuk:

  • Pilih klaim untuk disertakan dalam token untuk aplikasi Anda.
  • Ubah perilaku klaim tertentu yang dikembalikan platform identitas Microsoft dalam token.
  • Tambahkan dan akses klaim kustom untuk aplikasi Anda.

Meskipun klaim opsional didukung dalam token format v1.0 dan v2.0 dan token SAML, mereka memberikan sebagian besar nilainya saat berpindah dari v1.0 ke v2.0. Di platform identitas Microsoft, ukuran token yang lebih kecil digunakan untuk memastikan performa optimal oleh klien. Akibatnya, beberapa klaim yang sebelumnya disertakan dalam token akses dan ID tidak lagi ada dalam token v2.0 dan harus diminta secara khusus berdasarkan per aplikasi.

Jenis Akun Token v1.0 Token v2.0
Akun Microsoft pribadi N/A Didukung
Akun Microsoft Entra Didukung Didukung

Kumpulan klaim opsional v1.0 dan v2.0

Kumpulan klaim opsional yang tersedia secara default untuk digunakan aplikasi tercantum dalam tabel berikut. Anda dapat menggunakan data kustom dalam atribut ekstensi dan ekstensi direktori untuk menambahkan klaim opsional untuk aplikasi Anda. Saat Anda menambahkan klaim ke token akses, klaim berlaku untuk token akses yang diminta untuk aplikasi (API web), bukan klaim yang diminta dengan aplikasi. Tidak peduli bagaimana klien mengakses API Anda, data yang tepat ada dalam token akses yang digunakan untuk mengautentikasi terhadap API Anda.

Nota

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

Tabel berikut mencantumkan kumpulan klaim opsional v1.0 dan v2.0.

Nama Deskripsi Jenis Token Jenis Pengguna Catatan
acct Status akun pengguna di penyewa JWT, SAML Jika pengguna adalah anggota penyewa, nilainya adalah 0. Jika mereka adalah tamu, nilainya adalah 1.
acrs ID Konteks Autentikasi JWT Microsoft Entra ID Menunjukkan ID Konteks Autentikasi operasi yang memenuhi syarat untuk dilakukan oleh pembawa. ID Konteks Autentikasi dapat digunakan untuk memicu permintaan autentikasi peningkatan dari dalam aplikasi dan layanan Anda. Sering digunakan bersama dengan klaim xms_cc.
auth_time Waktu saat pengguna terakhir diautentikasi. JWT
ctry Negara/wilayah pengguna JWT Klaim ini dikembalikan jika ada dan nilai bidang adalah kode negara/wilayah dua huruf standar, seperti FR, JP, SZ, dan sebagainya.
email Alamat email yang dilaporkan untuk pengguna ini JWT, SAML MSA, Microsoft Entra ID Nilai ini disertakan secara default jika pengguna adalah tamu di penyewa. Untuk pengguna terkelola (pengguna di dalam penyewa), pengguna harus diminta melalui klaim opsional ini atau, hanya pada v2.0, dengan cakupan OpenID. Nilai ini tidak dijamin benar, dan dapat diubah dari waktu ke waktu - jangan pernah menggunakannya untuk otorisasi atau menyimpan data untuk pengguna. Untuk informasi selengkapnya, lihat Memvalidasi pengguna memiliki izin untuk mengakses data ini. Jika Anda menggunakan klaim email untuk otorisasi, sebaiknya melakukan migrasi untuk pindah ke klaim yang lebih aman. Jika Anda memerlukan alamat email yang dapat diatasi di aplikasi Anda, minta data ini dari pengguna secara langsung, menggunakan klaim ini sebagai saran atau awalan di UX Anda.
fwd Alamat IP JWT Menambahkan alamat asli klien yang meminta (saat berada di dalam VNET).
groups Pemformatan opsional untuk klaim grup JWT, SAML Klaim groups digunakan dengan pengaturan GroupMembershipClaims dalam manifes aplikasi , yang harus diatur juga.
idtyp Jenis token Token akses JWT Khusus: hanya dalam token akses khusus aplikasi Nilainya app saat token adalah token khusus aplikasi. Klaim ini adalah cara paling akurat bagi API untuk menentukan apakah token adalah token aplikasi atau token aplikasi+pengguna.
login_hint Petunjuk masuk JWT MSA, Microsoft Entra ID Klaim petunjuk masuk buram dan andal yang dikodekan basis 64. Jangan ubah nilai ini. Klaim ini adalah nilai terbaik untuk digunakan untuk parameter OAuth login_hint di semua alur untuk mendapatkan SSO. Ini dapat diteruskan di antara aplikasi untuk membantu mereka diam-diam SSO juga - aplikasi A dapat memasukkan pengguna, membaca klaim login_hint, lalu mengirim klaim dan konteks penyewa saat ini ke aplikasi B dalam string kueri atau fragmen ketika pengguna memilih tautan yang membawa mereka ke aplikasi B. Untuk menghindari kondisi balapan dan masalah keandalan, klaim login_hinttidak menyertakan penyewa saat ini untuk pengguna, dan default ke penyewa rumah pengguna saat digunakan. Dalam skenario tamu di mana pengguna berasal dari penyewa lain, pengidentifikasi penyewa harus disediakan dalam permintaan masuk. dan teruskan hal yang sama ke aplikasi yang bermitra dengan Anda. Klaim ini ditujukan untuk digunakan dengan fungsionalitas login_hint SDK yang ada, namun terekspos.
tenant_ctry Negara/wilayah penyewa sumber daya JWT Sama seperti ctry kecuali diatur pada tingkat penyewa oleh admin. Juga harus berupa 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 untuk pengguna dan tidak boleh digunakan untuk otorisasi atau untuk identitas informasi pengguna secara unik (misalnya, sebagai kunci database). Sebagai gantinya, gunakan ID objek pengguna (oid) sebagai kunci database. Untuk informasi selengkapnya, lihat Mengamankan aplikasi dan API dengan memvalidasi klaim. Pengguna yang masuk dengan ID masuk alternatif tidak boleh ditampilkan 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 lain untuk memodifikasi perilakunya 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_cc Kemampuan Klien JWT Microsoft Entra ID Menunjukkan apakah aplikasi klien yang memperoleh token mampu menangani tantangan klaim. Ini sering digunakan bersama dengan klaim acrs. Klaim ini umumnya digunakan dalam skenario Akses Bersyariah dan Evaluasi Akses Berkelanjutan. Server sumber daya atau aplikasi layanan yang dikeluarkan token untuk mengontrol keberadaan klaim ini dalam token. Nilai cp1 dalam token akses adalah cara otoritatif untuk mengidentifikasi bahwa aplikasi klien mampu menangani tantangan klaim. Untuk informasi selengkapnya, lihat tantangan Klaim , permintaan klaim, dan kemampuan klien.
xms_edov Nilai Boolean yang menunjukkan apakah pemilik domain email pengguna telah diverifikasi. JWT Email dianggap sebagai domain yang diverifikasi jika milik penyewa tempat akun pengguna berada dan admin penyewa telah melakukan verifikasi domain. Selain itu, email harus berasal dari akun Microsoft (MSA), akun Google, atau digunakan untuk autentikasi menggunakan alur kode akses satu kali (OTP). Akun Facebook dan SAML/WS-Fed tidak memiliki domain terverifikasi. Agar klaim ini dikembalikan dalam token, kehadiran klaim email diperlukan.
xms_pdl Lokasi data pilihan JWT Untuk penyewa Multi-Geo, lokasi data pilihan adalah kode tiga huruf yang menunjukkan wilayah geografis tempat pengguna berada. Untuk informasi selengkapnya, lihat dokumentasi Microsoft Entra Connect tentang lokasi data pilihan.
xms_pl Bahasa pilihan pengguna JWT Bahasa pilihan pengguna, jika diatur. Bersumber dari penyewa rumah mereka, dalam skenario akses tamu. LL-CC yang diformat ("en-us").
xms_tpl Bahasa pilihan penyewa JWT Bahasa pilihan penyewa sumber daya, jika diatur. LL yang diformat ("en").
ztdid ID Penyebaran Tanpa Sentuhan JWT Identitas perangkat yang digunakan untuk Windows AutoPilot.

Peringatan

Jangan pernah menggunakan nilai klaim email atau upn untuk menyimpan atau menentukan apakah pengguna dalam token akses harus memiliki akses ke data. Nilai klaim yang dapat diubah seperti ini dapat berubah dari waktu ke waktu, membuatnya tidak aman dan tidak dapat diandalkan untuk otorisasi.

Kumpulan klaim opsional khusus v2.0

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

Klaim JWT Nama Deskripsi Catatan
ipaddr Alamat IP Alamat IP tempat klien masuk.
onprem_sid Pengidentifikasi Keamanan Lokal
pwd_exp Waktu Kedaluwarsa Kata Sandi Jumlah detik setelah waktu dalam klaim iat di mana kata sandi kedaluwarsa. Klaim ini hanya disertakan ketika kata sandi 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 mereka. Klaim ini hanya disertakan ketika kata sandi segera kedaluwarsa (seperti yang didefinisikan oleh "hari pemberitahuan" dalam kebijakan kata sandi).
in_corp Di 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 Menyediakan nama belakang, nama keluarga, atau nama keluarga pengguna seperti yang didefinisikan dalam objek pengguna. Misalnya, "family_name":"Miller". Didukung di MSA dan ID Microsoft Entra. Memerlukan cakupan profile.
given_name Nama depan Memberikan nama pertama atau "diberikan" pengguna, seperti yang diatur pada objek pengguna. Misalnya, "given_name": "Frank". Didukung di MSA dan ID Microsoft Entra. Memerlukan cakupan profile.
upn Nama Prinsipal Pengguna Pengidentifikasi untuk pengguna yang dapat digunakan dengan parameter username_hint. Bukan pengidentifikasi yang tahan lama untuk pengguna dan tidak boleh digunakan untuk otorisasi atau untuk identitas informasi pengguna secara unik (misalnya, sebagai kunci database). Untuk informasi selengkapnya, lihat Mengamankan aplikasi dan API dengan memvalidasi klaim. Sebagai gantinya, gunakan ID objek pengguna (oid) sebagai kunci database. Pengguna yang masuk dengan ID masuk alternatif tidak boleh ditampilkan Nama Prinsipal Pengguna (UPN) mereka. Sebagai gantinya, gunakan klaim preferred_username berikut untuk menampilkan status masuk kepada pengguna. Memerlukan cakupan profile.

Kumpulan klaim opsional khusus v1.0

Beberapa peningkatan format token v2 tersedia untuk aplikasi yang menggunakan format token v1, karena membantu meningkatkan keamanan dan keandalan. Peningkatan ini hanya berlaku untuk JWT, bukan token SAML.

Klaim JWT Nama Deskripsi Catatan
aud Penonton Selalu ada di JWT, tetapi dalam token akses v1 dapat dipancarkan dengan berbagai cara - URI appID apa pun, dengan atau tanpa garis miring berikutnya, dan ID klien sumber daya. Pengacakan ini bisa sulit dikodekan saat melakukan validasi token. Gunakan additionalProperties untuk klaim ini untuk memastikannya selalu diatur ke ID klien sumber daya dalam token akses v1. Token akses JWT v1 saja
preferred_username Nama pengguna pilihan Menyediakan klaim nama pengguna pilihan dalam token v1. Klaim ini memudahkan aplikasi untuk memberikan petunjuk nama pengguna dan menunjukkan nama tampilan yang dapat dibaca manusia, terlepas dari jenis tokennya. Disarankan agar Anda menggunakan klaim opsional ini alih-alih menggunakan, upn atau unique_name. Token ID v1 dan token akses

additionalProperties klaim opsional

Beberapa klaim opsional dapat dikonfigurasi untuk mengubah cara klaim dikembalikan. additionalProperties 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.

Nama properti nama additionalProperty Deskripsi
upn Dapat digunakan untuk respons SAML dan JWT, dan untuk token v1.0 dan v2.0.
include_externally_authenticated_upn Menyertakan UPN tamu seperti yang disimpan di penyewa sumber daya. Misalnya, foo_hometenant.com#EXT#@resourcetenant.com.
include_externally_authenticated_upn_without_hash Sama seperti yang tercantum sebelumnya, kecuali bahwa tanda hash (#) diganti dengan garis bawah (_), misalnya foo_hometenant.com_EXT_@resourcetenant.com.
aud Dalam token akses v1, klaim ini digunakan untuk mengubah format klaim aud. Klaim ini tidak berpengaruh dalam token v2 atau token ID versi, di mana klaim aud selalu merupakan ID klien. Gunakan konfigurasi ini untuk memastikan bahwa API Anda dapat dengan lebih mudah melakukan validasi audiens. Seperti semua klaim opsional yang memengaruhi token akses, sumber daya dalam permintaan harus mengatur klaim opsional ini, karena sumber daya memiliki token akses.
use_guid Memancarkan ID klien sumber daya (API) dalam format GUID sebagai klaim aud selalu alih-alih menjadi dependen runtime. Misalnya, jika sumber daya menetapkan bendera ini, dan ID kliennya 00001111-aaaa-2222-bbbb-3333cccc4444, aplikasi apa pun yang meminta token akses untuk sumber daya tersebut menerima token akses dengan aud : 00001111-aaaa-2222-bbbb-3333cccc4444. Tanpa kumpulan klaim ini, API bisa mendapatkan token dengan klaim audapi://MyApi.com, api://MyApi.com/, api://myapi.com/AdditionalRegisteredField atau nilai lain yang ditetapkan sebagai URI ID aplikasi untuk API tersebut, dan ID klien sumber daya.
idtyp Klaim ini digunakan untuk mendapatkan jenis token (aplikasi, pengguna, perangkat). Secara default hanya dipancarkan untuk token khusus aplikasi. Seperti semua klaim opsional yang memengaruhi token akses, sumber daya dalam permintaan harus mengatur klaim opsional ini, karena sumber daya memiliki token akses.
include_user_token Memancarkan klaim idtyp untuk token pengguna. Tanpa properti tambahan opsional ini untuk kumpulan klaim idtyp, API hanya mendapatkan klaim untuk token aplikasi.

contoh additionalProperties

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

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

Lihat juga

  • token akses
  • token ID

Langkah berikutnya