OpenID Connect di platform identitas Microsoft
OpenID Connect (OIDC) memperluas protokol otorisasi OAuth 2.0 untuk digunakan sebagai protokol autentikasi lain. Anda dapat menggunakan OIDC untuk mengaktifkan akses menyeluruh (SSO) antara aplikasi Anda yang didukung OAuth menggunakan token keamanan yang disebut token ID.
Spesifikasi lengkap untuk OIDC tersedia di situs web OpenID Foundation di spesifikasi OpenID Connect Core 1.0.
Alur protokol: Proses masuk
Diagram berikut menunjukkan alur masuk OpenID Connect dasar. Langkah-langkah dalam alur dijelaskan secara lebih detail di bagian selanjutnya artikel.
Aktifkan token ID
Token ID yang diperkenalkan oleh OpenID Connect dikeluarkan oleh server otorisasi, platform identitas Microsoft, ketika aplikasi klien memintanya selama autentikasi pengguna. Token ID memungkinkan aplikasi klien untuk memverifikasi identitas pengguna dan mendapatkan informasi lain (klaim) tentang mereka.
Token ID tidak dikeluarkan secara default untuk aplikasi yang terdaftar di platform identitas Microsoft. Token ID untuk aplikasi diaktifkan dengan menggunakan salah satu metode berikut:
- Masuk ke Pusat Admin Microsoft Entra.
- Telusuri ke Aplikasi> Identitas>Pendaftaran aplikasi>< Autentikasi aplikasi>>Anda.
- Di bagian Konfigurasi platform, pilih Tambahkan platform.
- Di panel yang terbuka, pilih platform yang sesuai untuk aplikasi Anda. Misalnya, pilih Web untuk aplikasi web.
- Di bawah URI Pengalihan, tambahkan URI pengalihan aplikasi Anda. Contohnya,
https://localhost:8080/
. - Di bagian Izin implisit dan alur hibrid, pilih kotak centang Token ID (digunakan untuk alur implisit dan hibrid).
Atau:
- Pilih Aplikasi> Identitas>Pendaftaran aplikasi<> Manifestasi aplikasi>>Anda.
- Atur
oauth2AllowIdTokenImplicitFlow
ketrue
dalam manifes aplikasi pendaftaran aplikasi.
Jika token ID tidak diaktifkan untuk aplikasi Anda dan token id diminta, platform identitas Microsoft mengembalikan kesalahan yang unsupported_response
mirip dengan:
Nilai yang disediakan untuk parameter input 'response_type' tidak diizinkan untuk klien ini. Nilai yang diharapkan adalah 'kode'.
Meminta token ID dengan menentukan response_type
dari id_token
dijelaskan dalam Mengirim permintaan masuk nanti di artikel ini.
Mengambil dokumen konfigurasi OpenID
Penyedia OpenID seperti platform identitas Microsoft menyediakan Dokumen Konfigurasi Penyedia OpenID di titik akhir yang dapat diakses publik yang berisi titik akhir OIDC penyedia, klaim yang didukung, dan metadata lain. Aplikasi klien dapat menggunakan metadata untuk menemukan URL yang akan digunakan untuk autentikasi dan kunci penandatanganan publik layanan autentikasi.
Pustaka autentikasi adalah konsumen paling umum dokumen konfigurasi OpenID, yang mereka gunakan untuk penemuan URL autentikasi, kunci penandatanganan publik penyedia, dan metadata layanan lain. Jika pustaka autentikasi digunakan di aplikasi, Anda mungkin tidak perlu membuat permintaan kode tangan ke dan respons dari titik akhir dokumen konfigurasi OpenID.
Menemukan URI dokumen konfigurasi OpenID aplikasi Anda
Setiap pendaftaran aplikasi di MICROSOFT Entra ID disediakan titik akhir yang dapat diakses publik yang melayani dokumen konfigurasi OpenID-nya. Untuk menentukan URI titik akhir dokumen konfigurasi bagi aplikasi Anda, tambahkan jalur konfigurasi OpenID terkenal ke URL otoritas pendaftaran aplikasi Anda.
- Jalur dokumen konfigurasi yang terkenal:
/.well-known/openid-configuration
- URL Otoritas:
https://login.microsoftonline.com/{tenant}/v2.0
Nilai {tenant}
bervariasi menurut audiens masuk aplikasi seperti yang ditunjukkan dalam tabel berikut. URL otoritas juga bervariasi menurut instans cloud.
Nilai | Deskripsi |
---|---|
common |
Pengguna dengan akun Microsoft pribadi dan akun kantor atau sekolah dari ID Microsoft Entra dapat masuk ke aplikasi. |
organizations |
Hanya pengguna dengan akun kantor atau sekolah dari ID Microsoft Entra yang dapat masuk ke aplikasi. |
consumers |
Hanya pengguna dengan akun Microsoft personal yang dapat masuk ke aplikasi. |
Directory (tenant) ID atau contoso.onmicrosoft.com |
Hanya pengguna dari penyewa Microsoft Entra tertentu (anggota direktori dengan akun kerja atau sekolah atau tamu direktori dengan akun Microsoft pribadi) yang dapat masuk ke aplikasi. Nilainya bisa menjadi nama domain penyewa Microsoft Entra atau ID penyewa dalam format GUID. |
Tip
Perhatikan bahwa saat menggunakan common
otoritas atau consumers
untuk akun Microsoft pribadi, aplikasi sumber daya yang menggunakan harus dikonfigurasi untuk mendukung jenis akun tersebut sesuai dengan signInAudience.
Untuk menemukan dokumen konfigurasi OIDC di pusat admin Microsoft Entra, masuk ke pusat admin Microsoft Entra lalu:
- Telusuri ke Aplikasi> Identitas>Pendaftaran aplikasi>< Titik Akhir aplikasi>>Anda.
- Temukan URI di bagian dokumen metadata OpenID Connect.
Permintaan sampel
Permintaan berikut mendapatkan metadata konfigurasi OpenID dari common
titik akhir dokumen konfigurasi OpenID otoritas di cloud publik Azure:
GET /common/v2.0/.well-known/openid-configuration
Host: login.microsoftonline.com
Tip
Cobalah! Untuk melihat dokumen konfigurasi OpenID untuk otoritas common
aplikasi, buka https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration.
Respon sampel
Metadata konfigurasi ditampilkan dalam format JSON seperti yang ditunjukkan dalam contoh berikut (dipotong supaya ringkas). Metadata yang ditampilkan dalam respons JSON dijelaskan secara rinci dalam spesifikasi penemuan OpenID Connect 1.0.
{
"authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize",
"token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
"token_endpoint_auth_methods_supported": [
"client_secret_post",
"private_key_jwt"
],
"jwks_uri": "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys",
"userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo",
"subject_types_supported": [
"pairwise"
],
...
}
Mengirim permintaan masuk
Untuk mengautentikasi pengguna dan meminta token ID agar digunakan dalam aplikasi Anda, arahkan agen pengguna mereka ke titik akhir /authorize platform identitas Microsoft. Permintaan ini mirip dengan bagian pertama alur kode otorisasi OAuth 2.0, dengan perbedaan berikut:
- Sertakan cakupan
openid
dalam parameterscope
. - Tentukan
id_token
dalamresponse_type
parameter . - Sertakan parameter
nonce
.
Contoh permintaan masuk (spasi baris disertakan agar mudah dibaca):
GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=form_post
&scope=openid
&state=12345
&nonce=678910
Parameter | Kondisi | Deskripsi |
---|---|---|
tenant |
Wajib diisi | Anda dapat menggunakan nilai {tenant} di jalur permintaan untuk mengontrol siapa yang dapat masuk ke aplikasi. Nilai yang diizinkan adalah common , organizations , consumers , dan pengidentifikasi penyewa. Untuk informasi selengkapnya, lihat dasar-dasar protokol. Sangat penting, untuk skenario tamu di mana Anda memasukkan pengguna dari satu penyewa ke penyewa lain, Anda harus memberikan pengenal penyewa untuk memasukkan mereka ke penyewa sumber daya dengan benar. |
client_id |
Wajib | ID Aplikasi (klien) yang ditetapkan pusat admin Microsoft Entra – pengalaman Pendaftaran aplikasi ke aplikasi Anda. |
response_type |
Wajib | Harus menyertakan id_token untuk masuk OpenID Connect. |
redirect_uri |
Direkomendasikan | URI pengalihan aplikasi Anda, di mana respons autentikasi dapat dikirim dan diterima oleh aplikasi Anda. Ini harus sama persis dengan salah satu URI pengalihan yang Anda daftarkan di portal, kecuali hal itu memang harus dikodekan-URL. Jika tidak ada, titik akhir memilih satu yang terdaftar redirect_uri secara acak untuk mengirim pengguna kembali. |
scope |
Wajib | Daftar cakupan yang dipisahkan spasi. Untuk OpenID Connect, hal ini harus menyertakan cakupan openid , yang diterjemahkan menjadi izin Masukkan Anda di UI persetujuan. Anda mungkin juga menyertakan cakupan lain dalam permintaan ini untuk meminta persetujuan. |
nonce |
Wajib | Nilai yang dihasilkan dan dikirim oleh aplikasi Anda dalam permintaannya untuk token ID. Nilai nonce yang sama disertakan dalam token ID yang ditampilkan ke aplikasi Anda oleh platform identitas Microsoft. Untuk mengurangi serangan replay token, aplikasi Anda harus memverifikasi nilai nonce dalam token ID adalah nilai yang sama dengan yang dikirimnya saat meminta token. Nilai ini biasanya merupakan string acak yang unik. |
response_mode |
Direkomendasikan | Tentukan metode yang harus digunakan untuk mengirim kode otorisasi yang dihasilkan kembali ke aplikasi Anda. Bisa form_post atau fragment . Untuk aplikasi web, sebaiknya gunakan response_mode=form_post untuk memastikan transfer token yang paling aman ke aplikasi Anda. |
state |
Direkomendasikan | Nilai yang disertakan dalam permintaan yang juga dikembalikan dalam respons token. Ini bisa berupa string dari konten apa pun yang Anda inginkan. Nilai unik yang dihasilkan secara acak biasanya digunakan untuk mencegah serangan pemalsuan permintaan antar situs. Status ini juga digunakan untuk mengodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi muncul, seperti halaman atau tampilan tempat pengguna berada. |
prompt |
Opsional | Menunjukkan jenis interaksi pengguna yang diperlukan. Satu-satunya nilai yang valid saat ini adalah login , none , consent dan select_account . Klaim prompt=login memaksa pengguna untuk memasukkan kredensial mereka pada permintaan tersebut, yang meniadakan masuk tunggal. Paramter prompt=none adalah sebaliknya, dan harus dipasangkan dengan login_hint untuk mengindikasikan pengguna mana yang harus masuk. Parameter ini memastikan pengguna tidak disajikan dengan perintah interaktif sama sekali. Jika permintaan tidak dapat diselesaikan secara diam-diam melalui akses menyeluruh, platform identitas Microsoft mengembalikan kesalahan. Penyebabnya termasuk tidak ada pengguna yang masuk, pengguna yang diisyaratkan tidak masuk, atau beberapa pengguna masuk tetapi tidak ada isyarat yang diberikan. Klaim prompt=consent memicu dialog persetujuan OAuth setelah pengguna masuk. Dialog meminta pengguna untuk memberikan izin ke aplikasi. Terakhir, select_account menunjukkan kepada pengguna pemilih akun, meniadakan akses menyeluruh tetapi memungkinkan pengguna untuk memilih akun mana yang ingin mereka masuki, tanpa memerlukan entri kredensial. Anda tidak dapat menggunakan login_hint dan select_account . |
login_hint |
Opsional | Anda dapat menggunakan parameter ini untuk mengisi bidang nama pengguna dan alamat email halaman masuk untuk pengguna, jika Anda mengetahui nama pengguna sebelumnya. Seringkali, aplikasi menggunakan parameter ini selama autentikasi ulang, setelah mengekstrak login_hint klaim opsional dari rincian masuk sebelumnya. |
domain_hint |
Opsional | Realm pengguna dalam direktori gabungan. Ini melewati proses penemuan berbasis email yang dilalui pengguna di halaman masuk, untuk pengalaman pengguna yang sedikit lebih efisien. Untuk penyewa yang digabungkan melalui direktori lokal seperti Layanan Federasi Direktori Aktif, sering kali menghasilkan masuk tanpa gangguan karena sesi masuk yang ada. |
Pada titik ini, pengguna diminta untuk memasukkan kredensial mereka dan menyelesaikan autentikasi. Platform identitas Microsoft memverifikasi bahwa pengguna sudah menyetujui izin yang ditunjukkan dalam parameter kueri scope
. Jika pengguna belum menyetujui salah satu izin tersebut, platform identitas Microsoft meminta pengguna untuk menyetujui izin yang diperlukan. Anda dapat membaca selengkapnya tentang izin, persetujuan, dan aplikasi multipenyewa.
Setelah pengguna mengautentikasi dan memberikan persetujuan, platform identitas Microsoft mengembalikan respons ke aplikasi Anda di URI pengalihan yang ditunjukkan menggunakan metode yang ditentukan dalam parameter response_mode
.
Respons berhasil
Respons yang berhasil saat Anda menggunakan response_mode=form_post
mirip dengan:
POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345
Parameter | Deskripsi |
---|---|
id_token |
Token ID yang diminta aplikasi. Anda dapat menggunakan parameter id_token untuk memverifikasi identitas pengguna dan memulai sesi dengan pengguna. Untuk informasi lebih lanjut tentang token ID dan kontennya, lihat referensi token ID. |
state |
Jika parameter state disertakan dalam permintaan, maka nilai yang sama akan muncul dalam respons. Aplikasi harus memverifikasi bahwa nilai status dalam permintaan dan respons adalah identik. |
Respons kesalahan
Respons kesalahan juga dapat dikirim ke URI pengalihan sehingga aplikasi dapat menanganinya, contoh:
POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
error=access_denied&error_description=the+user+canceled+the+authentication
Parameter | Deskripsi |
---|---|
error |
String kode galat yang dapat digunakan untuk mengklasifikasikan jenis kesalahan yang terjadi, dan untuk menanggapi kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi akar penyebab kesalahan autentikasi. |
Kode galat untuk kesalahan titik akhir otorisasi
Tabel berikut menjelaskan kode galat yang dapat dikembalikan dalam parameter error
respons kesalahan:
Kode kesalahan | Deskripsi | Tindakan klien |
---|---|---|
invalid_request |
Kesalahan protokol, seperti kehilangan parameter yang diperlukan. | Perbaiki dan kirim ulang permintaan. Kesalahan pengembangan ini harus dikenali selama pengujian aplikasi. |
unauthorized_client |
Aplikasi klien tidak dapat meminta kode otorisasi. | Kesalahan ini dapat terjadi ketika aplikasi klien tidak terdaftar di ID Microsoft Entra atau tidak ditambahkan ke penyewa Microsoft Entra pengguna. Aplikasi dapat meminta pengguna dengan instruksi untuk menginstal aplikasi dan menambahkannya ke ID Microsoft Entra. |
access_denied |
Pemilik sumber daya menolak persetujuan. | Aplikasi klien dapat memberi tahu pengguna bahwa ini tidak dapat dilanjutkan kecuali pengguna menyetujui. |
unsupported_response_type |
Server perizinan tidak mendukung jenis respons dalam permintaan. | Perbaiki dan kirim ulang permintaan. Kesalahan pengembangan ini harus dikenali selama pengujian aplikasi. |
server_error |
Server mengalami kesalahan tidak terduga. | Coba lagi permintaannya. Kesalahan ini dapat diakibatkan oleh kondisi sementara. Aplikasi klien mungkin menjelaskan kepada pengguna bahwa responsnya tertunda karena kesalahan sementara. |
temporarily_unavailable |
Server terlalu sibuk untuk menangani permintaan tersebut untuk sementara waktu. | Coba lagi permintaannya. Aplikasi klien mungkin menjelaskan kepada pengguna bahwa responsnya tertunda karena kondisi sementara. |
invalid_resource |
Sumber daya target tidak valid karena tidak ada, ID Microsoft Entra tidak dapat menemukannya, atau dikonfigurasi dengan tidak benar. | Kesalahan ini menunjukkan bahwa sumber daya, jika ada, belum dikonfigurasi di penyewa. Aplikasi dapat meminta pengguna dengan instruksi untuk menginstal aplikasi dan menambahkannya ke ID Microsoft Entra. |
Memvalidasi token ID
Menerima token ID di aplikasi Anda mungkin tidak selalu cukup untuk sepenuhnya mengautentikasi pengguna. Anda mungkin juga perlu memvalidasi tanda tangan token ID dan memverifikasi klaimnya sesuai persyaratan aplikasi Anda. Seperti semua penyedia OpenID, token ID platform identitas Microsoft adalah JSON Web Tokens (JWT) yang ditandatangani menggunakan kriptografi kunci publik.
Aplikasi web dan API web yang menggunakan token ID untuk otorisasi harus memvalidasinya karena aplikasi tersebut mendapatkan akses ke data. Namun, jenis aplikasi lain mungkin tidak mendapat manfaat dari validasi token ID. Aplikasi asli dan satu halaman (SPA), misalnya, jarang mendapat manfaat dari validasi token ID karena entitas apa pun dengan akses fisik ke perangkat atau browser berpotensi melewati validasi.
Dua contoh melewati validasi token adalah:
- Menyediakan token atau kunci palsu dengan memodifikasi lalu lintas jaringan ke perangkat
- Menelusuri kesalahan aplikasi dan melangkahi logika validasi selama eksekusi program.
Jika Anda memvalidasi token ID di aplikasi Anda, sebaiknya jangan melakukannya secara manual. Sebagai gantinya, gunakan pustaka validasi token untuk mengurai dan memvalidasi token. Pustaka validasi token tersedia untuk sebagian besar bahasa pengembangan, kerangka kerja, dan platform.
Yang harus divalidasi dalam token ID
Selain memvalidasi tanda tangan token ID, Anda harus memvalidasi beberapa klaimnya seperti yang dijelaskan dalam Memvalidasi token ID. Lihat juga Informasi penting tentang penandatanganan rollover kunci.
Beberapa validasi lainnya bersifat umum dan bervariasi menurut skenario aplikasi, termasuk:
- Memastikan pengguna/organisasi sudah mendaftar untuk aplikasi.
- Memastikan pengguna memiliki otorisasi/hak istimewa yang sesuai
- Memastikan kekuatan autentikasi tertentu telah terjadi, seperti autentikasi multifaktor.
Setelah memvalidasi token ID, Anda dapat memulai sesi dengan pengguna dan menggunakan informasi dalam klaim token untuk personalisasi aplikasi, tampilan, atau untuk menyimpan data mereka.
Diagram protokol: Akuisisi token akses
Banyak aplikasi tidak hanya perlu memasukkan pengguna, tetapi juga mengakses sumber daya yang dilindungi seperti API web atas nama pengguna. Skenario ini menggabungkan OpenID Connect untuk mendapatkan token ID untuk mengautentikasi pengguna dan OAuth 2.0 untuk mendapatkan token akses untuk sumber daya yang dilindungi.
Alur akuisisi token dan masuk OpenID Connect lengkap terlihat mirip dengan diagram berikut:
Mendapatkan token akses untuk titik akhir UserInfo
Selain token ID, informasi pengguna yang diautentikasi juga tersedia di titik akhir UserInfo OIDC.
Untuk mendapatkan token akses bagi titik akhir UserInfo OIDC, ubah permintaan masuk seperti yang dijelaskan berikut:
// Line breaks are for legibility only.
GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444 // Your app registration's Application (client) ID
&response_type=id_token%20token // Requests both an ID token and access token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F // Your application's redirect URI (URL-encoded)
&response_mode=form_post // 'form_post' or 'fragment'
&scope=openid+profile+email // 'openid' is required; 'profile' and 'email' provide information in the UserInfo endpoint as they do in an ID token.
&state=12345 // Any value - provided by your app
&nonce=678910 // Any value - provided by your app
Anda juga dapat menggunakan alur kode otorisasi, alur kode perangkat, atau token refresh sebagai ganti response_type=token
untuk mendapatkan token akses bagi aplikasi Anda.
Respons token yang berhasil
Respons yang berhasil dari menggunakan response_mode=form_post
:
POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
access_token=eyJ0eXAiOiJKV1QiLCJub25jZSI6I....
&token_type=Bearer
&expires_in=3598
&scope=email+openid+profile
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI....
&state=12345
Parameter respons berarti hal yang sama terlepas dari alur yang digunakan untuk memperolehnya.
Parameter | Deskripsi |
---|---|
access_token |
Token yang digunakan untuk memanggil titik akhir UserInfo. |
token_type |
Selalu "Token pembawa" |
expires_in |
Berapa lama hingga token akses berakhir, dalam hitungan detik. |
scope |
Izin yang diberikan pada token akses. Karena titik akhir UserInfo dihosting di Microsoft Graph, scope dapat memuat pengguna lain yang sebelumnya diberikan izin ke aplikasi (misalnya User.Read ). |
id_token |
Token ID yang diminta aplikasi. Anda dapat menggunakan token ID untuk memverifikasi identitas pengguna dan memulai sesi dengan pengguna. Anda akan menemukan detail lebih lanjut tentang token ID dan kontennya referensi token ID. |
state |
Jika parameter status disertakan dalam permintaan, nilai yang sama akan muncul dalam respons. Aplikasi harus memverifikasi bahwa nilai status dalam permintaan dan respons adalah identik. |
Peringatan
Jangan mencoba memvalidasi atau membaca token untuk API apa pun yang tidak Anda miliki, termasuk token dalam contoh ini, dalam kode Anda. Token untuk layanan Microsoft dapat menggunakan format khusus yang tidak akan divalidasi sebagai JWT, dan juga dapat dienkripsi untuk pengguna konsumen (akun Microsoft). Meskipun membaca token adalah alat penelusuran kesalahan dan pembelajaran yang berguna, jangan mengambil dependensi terhadapnya dalam kode Anda atau asumsikan hal-hal yang spesifik tentang token yang bukan untuk API yang Anda kontrol.
Respons kesalahan
Respons kesalahan juga dapat dikirim ke URI pengalihan agar aplikasi dapat menanganinya dengan tepat:
POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
error=access_denied&error_description=the+user+canceled+the+authentication
Parameter | Deskripsi |
---|---|
error |
String kode galat yang dapat digunakan untuk mengklasifikasikan jenis kesalahan yang terjadi, dan untuk menanggapi kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi akar penyebab kesalahan autentikasi. |
Untuk deskripsi kemungkinan kode galat dan respons klien yang direkomendasikan, lihat Kode galat untuk kesalahan titik akhir otorisasi.
Ketika memiliki kode otorisasi dan token ID, Anda dapat memasukkan pengguna dan mendapatkan token akses atas nama mereka. Untuk memasukkan pengguna, Anda harus memvalidasi token ID seperti yang dijelaskan dalam token validasi. Untuk mendapatkan token akses, ikuti langkah-langkah yang dijelaskan dalam dokumentasi alur kode OAuth.
Memanggil titik akhir UserInfo
Baca dokumentasi UserInfo untuk melihat cara memanggil titik akhir UserInfo dengan token ini.
Mengirim permintaan keluar
Untuk mengeluarkan pengguna, lakukan kedua operasi berikut:
- Alihkan agen pengguna pengguna ke URI keluar platform identitas Microsoft.
- Hapus cookie aplikasi Anda atau akhiri sesi pengguna di aplikasi Anda.
Jika Anda gagal melakukan salah satu operasi ini, pengguna mungkin tetap diautentikasi dan tidak diminta untuk masuk saat berikutnya mereka menggunakan aplikasi Anda.
Alihkan agen pengguna ke end_session_endpoint
seperti yang ditunjukkan dalam dokumen konfigurasi OpenID Connect ini. end_session_endpoint
mendukung permintaan GET dan POST.
GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
Parameter | Kondisi | Deskripsi |
---|---|---|
post_logout_redirect_uri |
Direkomendasikan | URL yang dialihkan pengguna setelah berhasil keluar. Jika parameter tidak disertakan, pengguna akan ditampilkan pesan umum yang dihasilkan oleh platform identitas Microsoft. URL ini harus cocok dengan salah satu URI pengalihan yang terdaftar untuk aplikasi Anda di portal pendaftaran aplikasi. |
logout_hint |
Opsional | Memungkinkan keluar untuk terjadi tanpa meminta pengguna untuk memilih akun. Untuk menggunakan logout_hint , aktifkan login_hint klaim opsional di aplikasi klien Anda dan gunakan nilai login_hint klaim opsional sebagai logout_hint parameter . Jangan gunakan UPN atau nomor telepon sebagai nilai parameter logout_hint . |
Catatan
Setelah berhasil keluar, sesi aktif akan diatur ke tidak aktif. Jika Token Refresh Utama (PRT) yang valid ada untuk pengguna yang keluar dan rincian masuk baru dijalankan, akses menyeluruh akan terganggu dan pengguna akan melihat permintaan dengan pemilih akun. Jika opsi yang dipilih adalah akun tersambung yang mengacu pada PRT, masuk akan dilanjutkan secara otomatis tanpa perlu menyisipkan kredensial baru.
Single sign-out
Saat Anda mengalihkan pengguna ke end_session_endpoint
dalam aplikasi, platform identitas Microsoft mengakhiri sesi pengguna untuk aplikasi ini. Namun, pengguna mungkin masih masuk ke aplikasi lain yang menggunakan akun Microsoft yang sama untuk autentikasi.
Ketika pengguna telah masuk ke beberapa aplikasi web atau SPA yang terdaftar di direktori ini (juga dikenal sebagai penyewa) akses menyeluruh memungkinkan pengguna ini untuk keluar dari semua aplikasi secara instan dengan keluar di salah satu aplikasi.
Untuk mengaktifkan akses menyeluruh untuk aplikasi Entra, Anda harus menggunakan fitur keluar saluran depan OpenID Connect. Fitur ini memungkinkan aplikasi untuk memberi tahu aplikasi lain bahwa pengguna telah keluar. Ketika pengguna keluar dari satu aplikasi, platform identitas Microsoft mengirim permintaan HTTP GET ke URL keluar saluran depan dari setiap aplikasi tempat pengguna saat ini masuk.
Aplikasi ini harus menanggapi permintaan ini dengan melakukan dua tindakan berikut agar akses menyeluruh berhasil:
- Hapus sesi apa pun yang mengidentifikasi pengguna.
- Aplikasi harus menanggapi permintaan ini dengan menghapus sesi apa pun yang mengidentifikasi pengguna dan mengembalikan respons
200
.
Apa itu URL keluar saluran depan?
URL keluar saluran depan adalah tempat aplikasi web atau SPA Anda menerima permintaan keluar dari server autentikasi Entra dan melakukan fungsionalitas akses menyeluruh. Setiap aplikasi memiliki satu URL keluar saluran depan.
Kapan Anda harus mengatur URL keluar saluran depan?
Jika Anda atau pengembang Anda telah menentukan akses menyeluruh diperlukan untuk aplikasi, Anda harus mengatur URL keluar saluran depan untuk pendaftaran aplikasi ini. Setelah URL keluar saluran depan diatur untuk pendaftaran aplikasi aplikasi ini, platform identitas Microsoft mengirim permintaan HTTP GET ke URL keluar saluran depan aplikasi ini ketika pengguna yang masuk telah keluar dari aplikasi lain.
Cara menyiapkan akses menyeluruh menggunakan fitur keluar saluran depan
Untuk menggunakan fitur keluar saluran depan untuk sekumpulan aplikasi, Anda harus menyelesaikan dua tugas berikut:
- Atur URL keluar saluran depan di pusat admin Microsoft Entra untuk semua aplikasi yang harus keluar secara bersamaan. Setiap aplikasi biasanya memiliki URL keluar saluran depan khusus sendiri.
- Edit kode aplikasi sehingga mereka mendengarkan permintaan HTTP GET yang dikirim oleh platform identitas Microsoft ke URL keluar saluran depan, dan menanggapi permintaan ini dengan menghapus sesi apa pun yang mengidentifikasi pengguna dan mengembalikan respons 200.
Cara memilih URL keluar saluran depan
URL keluar saluran depan harus berupa URL yang mampu menerima dan menanggapi permintaan HTTP GET dan harus dapat menghapus sesi apa pun yang mengidentifikasi pengguna. Contoh URL keluar saluran depan bisa jadi, tetapi tidak terbatas pada, berikut ini:
https://example.com/frontchannel_logout
https://example.com/signout
https://example.com/logout
Langkah berikutnya
- Pelajari dokumentasi titik akhir UserInfo.
- Mengisi nilai klaim di token dengan data dari sistem lokal.
- Menyertakan klaim Anda sendiri dalam token.