Bagikan melalui

OpenID Connect di platform identitas Microsoft

  • Artikel

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.

Diagram batang menunjukkan alur masuk protokol OpenID Connect.

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:

  1. Masuk ke Pusat Admin Microsoft Entra.
  2. Telusuri ke Aplikasi> Identitas>Pendaftaran aplikasi>< Autentikasi aplikasi>>Anda.
  3. Di bagian Konfigurasi platform, pilih Tambahkan platform.
  4. Di panel yang terbuka, pilih platform yang sesuai untuk aplikasi Anda. Misalnya, pilih Web untuk aplikasi web.
  5. Di bawah URI Pengalihan, tambahkan URI pengalihan aplikasi Anda. Contohnya,https://localhost:8080/.
  6. Di bagian Izin implisit dan alur hibrid, pilih kotak centang Token ID (digunakan untuk alur implisit dan hibrid).

Atau:

  1. Pilih Aplikasi> Identitas>Pendaftaran aplikasi<> Manifestasi aplikasi>>Anda.
  2. Atur oauth2AllowIdTokenImplicitFlow ke true 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:

  1. Telusuri ke Aplikasi> Identitas>Pendaftaran aplikasi>< Titik Akhir aplikasi>>Anda.
  2. 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 parameter scope.
  • Tentukan id_token dalam response_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:

Protokol OpenID Connect: Akuisisi token

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:

  1. Alihkan agen pengguna pengguna ke URI keluar platform identitas Microsoft.
  2. 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:

  1. Hapus sesi apa pun yang mengidentifikasi pengguna.
  2. 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