Referensi klaim opsional

  • Artikel

Anda dapat menggunakan klaim opsional untuk:

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

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. Dalam platform identitas Microsoft, ukuran token yang lebih kecil digunakan 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.

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

Set 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 oleh aplikasi. Tidak peduli bagaimana klien mengakses API Anda, data yang tepat ada 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 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 dalam 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 xms_cc klaim.
auth_time Waktu ketika 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 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 menggunakan klaim email untuk otorisasi, sebaiknya lakukan 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 Pembuatan format opsional untuk klaim grup JWT, SAML Klaim groups ini digunakan dengan pengaturan GroupMembershipClaims dalam manifes aplikasi, yang juga harus diatur.
idtyp Jenis token Token akses JWT Khusus: hanya dalam token akses khusus aplikasi Nilainya adalah app ketika token adalah 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 Entra ID Klaim petunjuk masuk buram dan andal yang dikodekan basis 64. 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. 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 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 Pribadi dan Microsoft Entra.
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 username_hint parameter . 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 Mengamankan aplikasi dan API dengan memvalidasi klaim. 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 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 Kapabilitas 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 email klaim diperlukan.
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 Entra Koneksi tentang lokasi data pilihan.
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.

Peringatan

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

Kumpulan klaim opsional tertentu 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 klien tempat masuk.
onprem_sid Pengenal Keamanan Lokal
pwd_exp Kebijakan kedaluwarsa kata sandi Jumlah detik setelah waktu dalam iat klaim 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. Contohnya,"family_name":"Miller". Didukung di MSA dan ID Microsoft Entra. Membutuhkan cakupan profile.
given_name Nama depan Memberi nama pertama pengguna, seperti yang diatur pada objek pengguna. Contohnya,"given_name": "Frank". Didukung di MSA dan ID Microsoft Entra. Membutuhkan cakupan profile.
upn Nama Utama Pengguna Pengidentifikasi untuk pengguna yang dapat digunakan dengan username_hint parameter . 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 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 menunjukkan Nama Prinsipal Pengguna (UPN) mereka. Sebagai gantinya, gunakan klaim preferred_username berikut untuk menampilkan status masuk kepada pengguna. 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 hanya berlaku untuk JWT, bukan token SAML.

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 additionalProperties untuk klaim ini untuk memastikan selalu diatur 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. 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 dihasilkan. Ini additionalProperties 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 additionalProperty nama 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 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 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 menetapkan bendera ini, dan ID kliennya adalah 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 aud klaim api://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 menetapkan klaim opsional ini, karena sumber daya memiliki token akses.
include_user_token Memancarkan idtyp klaim untuk token pengguna. Tanpa properti tambahan opsional ini untuk kumpulan klaim idtyp, API hanya mendapatkan klaim untuk token aplikasi.

additionalProperties contoh

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

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

Lihat juga

Langkah berikutnya