Mengubah aplikasi penyewa tunggal menjadi penyewa banyak dalam Microsoft Entra ID

Jika Anda menawarkan aplikasi Software as a Service (SaaS) ke banyak organisasi, Anda dapat mengonfigurasi aplikasi untuk menerima masuk dari penyewa Microsoft Entra mana pun dengan mengonversinya menjadi 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 Connect, atau Security Assertion Markup Language (SAML), dan menempatkan tombol "Masuk dengan Microsoft" di aplikasi Anda.

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

  1. Perbarui registrasi aplikasi Anda menjadi multitenan
  2. Memperbarui kode Anda untuk mengirim permintaan ke /common titik akhir
  3. Perbarui kode Anda untuk menangani beberapa nilai penerbit
  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 Connect

Prasyarat

Memperbarui pendaftaran menjadi multipenyewa

Secara bawaan, pendaftaran aplikasi web/API di Microsoft Entra ID adalah tenant tunggal ketika 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 menjadi Akun di direktori organisasi mana 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, 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, penetapan aplikasi sebagai multitenant 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. Untuk aplikasi SAML, ini dapat dikonfigurasi dalam file XML penyedia identitas. Titik akhir ini bukan penyewa atau penerbit itu sendiri. Ketika platform identitas Microsoft menerima permintaan di /common titik akhir, platform identitas Microsoft memasukkan pengguna, menemukan penyewa mana pengguna berasal. Titik akhir ini berfungsi dengan semua protokol autentikasi yang didukung oleh ID Microsoft Entra (OpenID Connect, 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 titik akhir /common, nilai penerbit dalam token sesuai dengan penyewa.

Catatan

Ada 2 otoritas untuk aplikasi multi-tenant pada kenyataannya.

  • https://login.microsoftonline.com/common untuk akun pemrosesan aplikasi di direktori organisasi apa pun (direktori Microsoft Entra apa pun) dan akun Microsoft pribadi (seperti 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 penerbit

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 URL kunci /organizations atau /common. Aplikasi harus memvalidasi bahwa properti issuer dalam metadata yang diterbitkan sesuai dengan klaim iss dalam token, selain pemeriksaan biasa bahwa klaim iss 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. Organisasi kemudian diizinkan untuk melakukan hal-hal seperti menerapkan kebijakan unik saat pengguna dari penyewa mereka masuk ke aplikasi. Untuk aplikasi penyewa tunggal, dapat menggunakan pendaftaran melalui Pusat Admin Microsoft Entra.

Untuk aplikasi multipenyewa, pendaftaran awal aplikasi ditempatkan 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.

Izin yang diminta oleh aplikasi memengaruhi pengalaman persetujuan. 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.

Pengguna reguler dapat menyetujui beberapa izin, sementara yang 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 sebagai pengguna yang masuk memerlukan persetujuan dari 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. Pengembang yang menerbitkan sumber daya menentukan apakah izin memerlukan persetujuan admin, dan Anda dapat menemukan informasi ini dalam dokumentasi 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 persetujuan admin dan perwakilan layanan dibuat di penyewa pelanggan, permintaan masuk berikutnya tidak memerlukan prompt=consent parameter . Karena administrator telah menyetujui izin yang diminta, tidak ada pengguna lain di penyewa yang dimintai persetujuan.

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 >perusahaan, centang opsi Jangan izinkan persetujuan pengguna.

Parameter prompt=consent juga dapat digunakan oleh aplikasi yang meminta izin yang tidak memerlukan persetujuan admin. Contoh kasus penggunaan adalah jika aplikasi memerlukan pengalaman di mana admin penyewa "mendaftar" satu kali, dan tidak ada pengguna lain yang dimintai persetujuan sejak saat itu.

Jika aplikasi memerlukan persetujuan admin dan admin masuk tanpa prompt=consent parameter dikirim, ketika admin berhasil menyetujui aplikasi, aplikasi tersebut hanya berlaku untuk akun pengguna mereka. Pengguna reguler 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

Jika aplikasi logis Anda terdiri dari dua pendaftaran aplikasi atau lebih, misalnya klien dan sumber daya terpisah, Anda dapat mengalami beberapa masalah. Misalnya, bagaimana Anda memasukkan 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"]

Anda dapat merujuk ke contoh aplikasi multi-penyewa untuk demonstrasi. Diagram di bawah ini memberikan ikhtisar persetujuan untuk aplikasi multi-tingkatan yang terdaftar dalam penyewa tunggal.

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 tenant yang berbeda. Misalnya, pertimbangkan kasus membangun aplikasi klien native yang memanggil API Exchange Online. Untuk mengembangkan aplikasi native, dan agar aplikasi native dapat berjalan di tenant pelanggan, principal layanan Exchange Online harus ada. Di sini, pengembang dan pelanggan harus membeli Exchange Online agar prinsipal layanan dapat dibuat di tenant 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. Kamu bisa;

  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, link perwakilan layanan dan delegasi persetujuan dibuat di tenant mereka, dan aplikasi asli dapat memperoleh token untuk API.

Diagram berikut ini memberikan ringkasan izin untuk aplikasi bertingkat yang terdaftar dalam penyewa yang berbeda.

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

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 multi-penyewa dan token akses cache

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 tidak menemukan entri cache, dan pengguna diminta masuk kembali. Untuk menghindari kehilangan cache, pastikan panggilan berikutnya untuk pengguna yang sudah login dilakukan ke endpoint penyewa.

Lihat juga

  • Last updated on