Mengonversi aplikasi penyewa tunggal ke multipenyewa di ID Microsoft Entra

  • Artikel

Jika Anda menawarkan aplikasi Software as a Service (SaaS) ke banyak organisasi, Anda dapat mengonfigurasi aplikasi untuk menerima rincian masuk dari penyewa Microsoft Entra mana pun dengan mengonversinya ke multipenyewa. Pengguna di penyewa Microsoft Entra mana pun akan dapat masuk ke aplikasi Anda setelah menyetujui untuk menggunakan akun mereka dengan aplikasi Anda.

Untuk aplikasi yang ada dengan sistem akunnya sendiri (atau rincian masuk lainnya dari penyedia cloud lain), Anda harus menambahkan kode masuk melalui OAuth2, OpenID Koneksi, atau SAML, dan menempatkan tombol "Masuk dengan Microsoft" di aplikasi Anda.

Dalam panduan cara ini, Anda akan melakukan empat langkah yang diperlukan untuk mengonversi satu aplikasi penyewa menjadi aplikasi multipenyewa Microsoft Entra:

  1. Perbarui pendaftaran aplikasi Anda menjadi multipenyewa
  2. Memperbarui kode Anda untuk mengirim permintaan ke /common titik akhir
  3. Perbarui kode Anda untuk menangani beberapa nilai pengeluar sertifikat
  4. Memahami persetujuan pengguna dan admin dan membuat perubahan kode yang sesuai

Jika Anda ingin mencoba menggunakan salah satu sampel kami, lihat Membangun aplikasi web SaaS multipenyewa yang memanggil Microsoft Graph menggunakan MICROSOFT Entra ID dan OpenID Koneksi

Prasyarat

Memperbarui pendaftaran menjadi multipenyewa

Secara default, pendaftaran aplikasi web/API di MICROSOFT Entra ID adalah penyewa tunggal saat dibuat. Untuk membuat pendaftaran multipenyewa, masuk ke pusat admin Microsoft Entra dan pilih pendaftaran aplikasi yang ingin Anda perbarui. Dengan pendaftaran aplikasi terbuka, pilih panel Autentikasi dan navigasikan ke bagian Jenis akun yang didukung. Ubah pengaturan ke Akun di direktori organisasi apa pun.

Saat aplikasi penyewa tunggal dibuat di pusat admin Microsoft Entra, salah satu item yang tercantum di halaman Gambaran Umum adalah URI ID Aplikasi. Ini adalah salah satu cara aplikasi diidentifikasi dalam pesan protokol, dan dapat ditambahkan kapan saja. URI ID Aplikasi untuk aplikasi penyewa tunggal dapat unik secara global dalam penyewa tersebut. Sebaliknya, untuk aplikasi multipenyewa, aplikasi harus unik secara global di semua penyewa, yang memastikan bahwa ID Microsoft Entra dapat menemukan aplikasi di semua penyewa.

Misalnya, jika nama penyewa Anda adalah contoso.onmicrosoft.com URI ID Aplikasi yang valid adalah https://contoso.onmicrosoft.com/myapp. Jika URI ID Aplikasi tidak mengikuti pola ini, pengaturan aplikasi sebagai multipenyewa gagal.

Perbarui kode Anda untuk mengirim permintaan ke /common

Dengan aplikasi multipenyewa, aplikasi tidak dapat segera mengetahui dari penyewa mana pengguna berasal, sehingga permintaan tidak dapat dikirim ke titik akhir penyewa. Sebagai gantinya, permintaan dikirim ke titik akhir umum (https://login.microsoftonline.com/common) yang berfungsi di semua penyewa Microsoft Entra, bertindak sebagai hub pusat yang menangani permintaan.

Buka aplikasi Anda di IDE Anda dan edit kode Anda dan ubah nilai untuk ID penyewa Anda menjadi /common. Titik akhir ini bukan penyewa atau penerbit itu sendiri. Ketika platform identitas Microsoft menerima permintaan di /common titik akhir, platform identitas Microsoft memasukkan pengguna, sehingga menemukan penyewa mana pengguna berasal. Titik akhir ini berfungsi dengan semua protokol autentikasi yang didukung oleh MICROSOFT Entra ID (OpenID Koneksi, OAuth 2.0, SAML 2.0, WS-Federation).

Respons masuk ke aplikasi akan berisi token yang mewakili pengguna. Nilai pengeluar sertifikat dalam token akan memberi tahu aplikasi dari penyewa mana pengguna berasal. Saat respons kembali dari /common titik akhir, nilai pengeluar sertifikat dalam token sesuai dengan penyewa pengguna.

Catatan

Ada, pada kenyataannya 2 otoritas untuk aplikasi multipenyewa:

  • https://login.microsoftonline.com/common untuk akun pemrosesan aplikasi di direktori organisasi apa pun (direktori Microsoft Entra apa pun) dan akun Microsoft pribadi (misalnya Skype, XBox).
  • https://login.microsoftonline.com/organizations untuk akun pemrosesan aplikasi di direktori organisasi apa pun (direktori Microsoft Entra apa pun):

Penjelasan dalam dokumen ini menggunakan common. Tetapi Anda dapat menggantinya dengan organizations jika aplikasi Anda tidak mendukung akun pribadi Microsoft.

Perbarui kode Anda untuk menangani beberapa nilai pengeluar sertifikat

Aplikasi web dan API web menerima dan memvalidasi token dari platform identitas Microsoft. Aplikasi klien asli tidak memvalidasi token akses dan harus memperlakukannya sebagai buram. Sebagai gantinya, mereka meminta dan menerima token dari platform identitas Microsoft, dan melakukannya untuk mengirimnya ke API, tempat token tersebut kemudian divalidasi.

Aplikasi multipenyewa harus melakukan lebih banyak pemeriksaan saat memvalidasi token. Aplikasi multipenyewa dikonfigurasi untuk menggunakan metadata kunci dari /organizations ATAU /common URL kunci. Aplikasi harus memvalidasi bahwa properti dalam metadata yang issuer diterbitkan cocok iss dengan klaim dalam token, selain pemeriksaan biasa bahwa iss klaim dalam token berisi klaim ID penyewa (tid). Untuk informasi selengkapnya, lihat Memvalidasi token.

Agar pengguna dapat masuk ke aplikasi di ID Microsoft Entra, aplikasi harus diwakili di penyewa pengguna. Ini memungkinkan organisasi untuk melakukan hal-hal seperti menerapkan kebijakan unik, ketika pengguna dari penyewa mereka masuk ke aplikasi. Untuk aplikasi penyewa tunggal, seseorang dapat menggunakan pendaftaran melalui pusat admin Microsoft Entra.

Untuk aplikasi multipenyewa, pendaftaran awal untuk aplikasi berada di penyewa Microsoft Entra yang digunakan oleh pengembang. Ketika pengguna dari penyewa yang berbeda masuk ke aplikasi untuk pertama kalinya, ID Microsoft Entra meminta mereka untuk menyetujui izin yang diminta oleh aplikasi. Jika mereka menyetujuinya, maka representasi aplikasi yang disebut perwakilan layanan dibuat dalam penyewa pengguna, dan proses masuk dapat dilanjutkan. Delegasi juga dibuat dalam direktori yang mencatat persetujuan pengguna untuk aplikasi. Untuk detail tentang objek Aplikasi dan ServicePrincipal dari aplikasi, dan bagaimana mereka berhubungan satu sama lain, lihat Objek aplikasi dan objek perwakilan layanan.

Diagram yang mengilustrasikan persetujuan pengguna untuk aplikasi tingkat tunggal.

Pengalaman persetujuan ini dipengaruhi oleh izin yang diminta oleh aplikasi. platform identitas Microsoft mendukung dua jenis izin;

  • Didelegasikan: Izin ini memberi aplikasi kemampuan untuk bertindak sebagai pengguna yang masuk untuk subset hal yang dapat dilakukan pengguna. Misalnya, Anda dapat memberikan izin kepada aplikasi yang didelegasikan untuk membaca kalender pengguna yang masuk.
  • Khusus aplikasi: Izin ini diberikan langsung ke identitas aplikasi. Misalnya, Anda dapat memberikan izin khusus aplikasi untuk membaca daftar pengguna dalam penyewa, terlepas dari siapa yang masuk ke aplikasi.

Beberapa izin dapat disetujui oleh pengguna biasa, sementara izin lain memerlukan persetujuan administrator penyewa.

Untuk mempelajari selengkapnya tentang persetujuan pengguna dan admin, lihat Mengonfigurasi alur kerja persetujuan admin.

Izin khusus aplikasi selalu memerlukan persetujuan administrator penyewa. Jika aplikasi Anda meminta izin khusus aplikasi dan pengguna mencoba masuk ke aplikasi, pesan kesalahan akan menampilkan bahwa pengguna tidak dapat menyetujuinya.

Izin delegasi tertentu juga memerlukan persetujuan administrator penyewa. Misalnya, kemampuan untuk menulis kembali ke MICROSOFT Entra ID karena pengguna yang masuk memerlukan persetujuan administrator penyewa. Seperti izin khusus aplikasi, jika pengguna biasa mencoba masuk ke aplikasi yang meminta izin yang didelegasikan yang memerlukan persetujuan administrator, aplikasi menerima kesalahan. Apakah izin memerlukan persetujuan admin ditentukan oleh pengembang yang menerbitkan sumber daya, dan dapat ditemukan dalam dokumentasi untuk sumber daya. Dokumentasi izin untuk API Microsoft Graph API menunjukkan izin mana yang memerlukan persetujuan admin.

Jika aplikasi Anda menggunakan izin yang memerlukan persetujuan admin, pertimbangkan untuk menambahkan tombol atau tautan tempat admin dapat memulai tindakan. Permintaan yang dikirim aplikasi Anda untuk tindakan ini adalah permintaan otorisasi OAuth2/OpenID Connect biasa yang juga menyertakan parameter untai kueri prompt=consent. Setelah admin menyetujui dan perwakilan layanan dibuat di penyewa pelanggan, permintaan masuk berikutnya tidak memerlukan prompt=consent parameter . Karena administrator telah memutuskan izin yang diminta dapat diterima, tidak ada pengguna lain dalam penyewa yang dimintai persetujuan dari titik tersebut ke depannya.

Administrator penyewa dapat menonaktifkan kemampuan pengguna biasa untuk menyetujui aplikasi. Jika kemampuan ini dinonaktifkan, persetujuan admin selalu diperlukan agar aplikasi dapat digunakan di penyewa. Anda dapat menguji aplikasi Anda dengan persetujuan pengguna akhir dinonaktifkan, di pusat admin Microsoft Entra. Di Persetujuan dan izin aplikasi>perusahaan, centang opsi Jangan izinkan persetujuan pengguna.

Parameter prompt=consent juga dapat digunakan oleh aplikasi yang meminta izin yang tidak memerlukan persetujuan admin. Sebuah contoh kapan ini akan digunakan, adalah jika aplikasi memerlukan pengalaman di mana admin penyewa "mendaftar" satu kali, dan tidak ada pengguna lain yang dimintai persetujuan ke depannya.

Jika aplikasi memerlukan persetujuan admin dan admin masuk tanpa parameter prompt=consent yang dikirim, ketika admin berhasil menyetujui aplikasi, ini akan berlaku hanya untuk akun pengguna mereka. Pengguna biasa masih tidak akan dapat masuk atau menyetujui aplikasi. Fitur ini berguna jika Anda ingin memberikan kemampuan kepada administrator penyewa untuk menjelajahi aplikasi Anda sebelum mengizinkan pengguna lain untuk mengakses.

Aplikasi Anda mungkin memiliki beberapa tingkatan, dengan masing-masing diwakili oleh pendaftarannya sendiri di ID Microsoft Entra. Misalnya, aplikasi native yang memanggil API web, atau aplikasi web yang memanggil API web. Dalam kedua kasus ini, klien (aplikasi native atau aplikasi web) meminta izin untuk memanggil sumber daya (web API). Agar klien berhasil disetujui menjadi penyewa pelanggan, semua sumber daya yang meminta izin harus sudah tercantum di penyewa pelanggan. Jika kondisi ini tidak terpenuhi, ID Microsoft Entra mengembalikan kesalahan bahwa sumber daya harus ditambahkan terlebih dahulu.

Beberapa tingkatan dalam satu penyewa

Ini bisa menjadi masalah jika aplikasi logis Anda terdiri dari dua atau beberapa pendaftaran aplikasi, misalnya klien dan sumber daya yang terpisah. Bagaimana Anda mendapatkan sumber daya ke penyewa eksternal terlebih dahulu? MICROSOFT Entra ID mencakup kasus ini dengan memungkinkan klien dan sumber daya untuk disetujui dalam satu langkah. Pengguna melihat jumlah total izin yang diminta oleh klien dan sumber daya di halaman persetujuan. Untuk mengaktifkan perilaku ini, pendaftaran aplikasi sumber daya harus menyertakan ID Aplikasi klien sebagai knownClientApplications dalam manifes aplikasinya. Contohnya:

"knownClientApplications": ["12ab34cd-56ef-78gh-90ij11kl12mn"]

Ini ditunjukkan dalam sampel aplikasi multipenyewa. Diagram berikut ini memberikan ikhtisar persetujuan untuk aplikasi multi-tingkatan yang terdaftar dalam satu penyewa.

Diagram yang mengilustrasikan persetujuan untuk aplikasi klien multi-tingkat yang diketahui.

Beberapa tingkatan dalam beberapa penyewa

Kasus serupa terjadi jika berbagai tingkatan aplikasi terdaftar di penyewa yang berbeda. Misalnya, pertimbangkan kasus membangun aplikasi klien native yang memanggil API Exchange Online. Untuk mengembangkan aplikasi native, dan nantinya aplikasi native berjalan di penyewa pelanggan, perwakilan layanan Exchange Online harus tersedia. Dalam hal ini, pengembang dan pelanggan harus membeli Exchange Online untuk perwakilan layanan yang akan dibuat di penyewa mereka.

Jika ini adalah API yang dibangun oleh organisasi selain dari Microsoft, pengembang API harus menyediakan cara bagi pelanggan mereka untuk menyetujui aplikasi ke penyewa pelanggan mereka. Desain yang direkomendasikan adalah pengembang pihak ketiga untuk membangun API sedemikian rupa sehingga dapat berfungsi juga sebagai klien web untuk menerapkan pendaftaran. Untuk melakukan ini:

  1. Ikuti bagian sebelumnya untuk memastikan API menerapkan persyaratan pendaftaran/kode aplikasi multipenyewa.
  2. Selain memaparkan cakupan/peran API, pastikan pendaftaran menyertakan izin "Masuk dan baca untuk profil pengguna" (disediakan secara default).
  3. Menerapkan halaman masuk/pendaftaran di klien web, dan ikuti panduan persetujuan admin.
  4. Setelah pengguna menyetujui aplikasi, tautan perwakilan layanan dan delegasi persetujuan dibuat di penyewa mereka, dan aplikasi native bisa mendapatkan token untuk API.

Diagram berikut ini memberikan ikhtisar persetujuan untuk aplikasi multi-tingkatan yang terdaftar dalam penyewa yang berbeda.

Diagram yang mengilustrasikan persetujuan untuk aplikasi multi-pihak multi-tingkat.

Pengguna dan administrator dapat mencabut persetujuan untuk aplikasi Anda kapan saja:

  • Pengguna mencabut akses ke aplikasi individual dengan menghapusnya dari daftar Aplikasi Panel Akses.
  • Administrator mencabut akses ke aplikasi dengan menghapusnya menggunakan bagian Aplikasi perusahaan di pusat admin Microsoft Entra. Pilih aplikasi dan navigasikan ke tab Izin untuk mencabut akses.

Jika administrator menyetujui aplikasi untuk semua pengguna dalam penyewa, pengguna tidak dapat mencabut akses satu per satu. Hanya administrator yang dapat mencabut akses, dan hanya untuk seluruh aplikasi.

Aplikasi multipenyewa dan token akses penembolokan

Aplikasi multipenyewa juga bisa mendapatkan token akses untuk memanggil API yang dilindungi oleh ID Microsoft Entra. Kesalahan umum saat menggunakan Microsoft Authentication Library (MSAL) dengan aplikasi multipenyewa adalah pada awalnya meminta token untuk pengguna menggunakan /common, menerima respons, lalu meminta token berikutnya untuk pengguna yang sama juga menggunakan /common. Karena respons dari MICROSOFT Entra ID berasal dari penyewa, bukan /common, MSAL menyimpan token sebagai berasal dari penyewa. Panggilan berikutnya untuk /common mendapatkan token akses bagi pengguna melewatkan entri cache, dan pengguna diminta untuk masuk lagi. Untuk menghindari kehilangan cache, pastikan panggilan berikutnya untuk pengguna yang sudah masuk dilakukan ke titik akhir penyewa.

Lihat juga