API web yang dilindungi: Pendaftaran aplikasi

  • Artikel

Artikel ini menjelaskan secara spesifik pendaftaran aplikasi untuk API web yang dilindungi.

Untuk langkah-langkah umum untuk mendaftarkan aplikasi, lihat Mulai Cepat: Mendaftarkan aplikasi dengan platform identitas Microsoft.

Versi token yang diterima

Platform identitas Microsoft dapat mengeluarkan token v1.0 dan token v2.0. Untuk informasi selengkapnya tentang token ini, lihat Token akses.

Versi token yang mungkin diterima API Anda bergantung pada pilihan Jenis akun yang didukung saat Anda membuat pendaftaran aplikasi API web di portal Microsoft Azure.

  • Jika nilai Jenis akun yang didukung adalah Akun di direktori organisasi dan akun Microsoft pribadi apa pun(misalnya Skype, Xbox, Outlook.com), versi token yang diterima harus v2.0.
  • Jika tidak, versi token yang diterima dapat v1.0.

Setelah membuat aplikasi, Anda dapat menentukan atau mengubah versi token yang diterima dengan mengikuti langkah-langkah berikut:

  1. Di portal Microsoft Azure, pilih aplikasi Anda lalu pilih Manifes.
  2. Temukan properti accessTokenAcceptedVersion dalam manifes.
  3. Nilai menentukan microsoft Entra versi token mana yang diterima API web.
    • Jika nilainya adalah 2, API web akan menerima token v2.0.
    • Jika nilainya adalah null, API web akan menerima token v1.0.
  4. Jika Anda mengubah versi token, pilih Simpan.

API web menentukan versi token mana yang diterimanya. Ketika klien meminta token untuk API web Anda dari platform identitas Microsoft, klien mendapatkan token yang menunjukkan versi token mana yang diterima API web.

Jangan alihkan URI

API Web tidak perlu mendaftarkan URI pengalihan karena tidak ada pengguna yang masuk secara interaktif.

API Yang Terekspos

Pengaturan lain khusus untuk API web adalah API yang diekspos dan cakupan atau peran aplikasi yang diekspos.

Cakupan dan URI ID Aplikasi

Cakupan biasanya memiliki formulir resourceURI/scopeName. Untuk Microsoft Graph, cakupannya memiliki pintasan. Misalnya, User.Read adalah pintasan untuk https://graph.microsoft.com/user.read.

Selama pendaftaran aplikasi, tentukan parameter berikut:

  • URI Sumber Daya
  • Satu atau beberapa cakupan
  • Satu atau beberapa peran aplikasi

Secara default, portal pendaftaran aplikasi merekomendasikan agar Anda menggunakan sumber daya URI api://{clientId}. URI ini unik tetapi tidak dapat dibaca manusia. Jika Anda mengubah URI, pastikan nilai baru unik. Portal pendaftaran aplikasi akan memastikan bahwa Anda menggunakan domain penerbit yang dikonfigurasi.

Untuk aplikasi klien, cakupan muncul sebagai izin yang didelegasikan dan peran aplikasi muncul sebagai izin aplikasi untuk API web Anda.

Cakupan juga muncul di jendela persetujuan yang disajikan kepada pengguna aplikasi Anda. Oleh karena itu, berikan string yang sesuai yang menjelaskan cakupan:

  • Seperti yang terlihat oleh pengguna.
  • Seperti yang terlihat oleh admin penyewa, yang dapat memberikan persetujuan admin.

Peran aplikasi tidak dapat disetujui oleh pengguna (karena digunakan oleh aplikasi yang memanggil API web atas namanya sendiri). Administrator penyewa harus menyetujui aplikasi klien dari API web Anda yang mengekspos peran aplikasi. Lihat Persetujuan admin untuk detailnya.

Memperlihatkan izin yang didelegasikan (cakupan)

Untuk memperlihatkan izin yang didelegasikan, atau cakupan, ikuti langkah-langkah di Mengonfigurasi aplikasi untuk memperlihatkan API web.

Jika Anda mengikuti skenario API web yang dijelaskan dalam kumpulan artikel ini, gunakan pengaturan ini:

  • URI ID Aplikasi: Menerima URI ID aplikasi yang diusulkan (api://<clientId>) (jika diminta)
  • Nama cakupan: access_as_user
  • Siapa yang dapat menyetujui: Admin dan pengguna
  • Nama tampilan persetujuan admin: Mengakses TodoListService sebagai pengguna
  • Deskripsi persetujuan admin: Mengakses API web TodoListService sebagai pengguna
  • Nama tampilan persetujuan pengguna: Mengakses TodoListService sebagai pengguna
  • Deskripsi persetujuan pengguna: Mengakses API web TodoListService sebagai pengguna
  • Status: Diaktifkan

Tip

Untuk URI ID Aplikasi, Anda memiliki opsi untuk mengaturnya ke otoritas fisik API, misalnya https://graph.microsoft.com. Ini dapat berguna jika URL API yang perlu dipanggil diketahui.

Jika API web Anda dipanggil oleh layanan atau aplikasi daemon

Buka izin aplikasi, bukan izin yang didelegasikan jika API Anda harus diakses oleh daemon, layanan, atau aplikasi non-interaktif lainnya (oleh manusia). Karena aplikasi jenis daemon dan layanan berjalan tanpa pengawasan dan mengautentikasi dengan identitasnya sendiri, tidak ada pengguna yang "mendelegasikan" izinnya.

Memperlihatkan izin aplikasi (peran aplikasi)

Untuk memperlihatkan izin aplikasi, ikuti langkah-langkah di Menambahkan peran aplikasi ke aplikasi Anda.

Di panel Buat peran aplikasi di bawah Jenis anggota yang diizinkan, pilih Aplikasi. Atau, tambahkan peran dengan menggunakan Penyunting manifes aplikasi seperti yang dijelaskan dalam artikel.

Membatasi token akses ke aplikasi klien tertentu

Peran aplikasi adalah mekanisme yang digunakan pengembang aplikasi untuk memperlihatkan izin aplikasi mereka. Kode API web Anda harus memeriksa peran aplikasi dalam token akses yang diterima kode API web dari pemanggil.

Untuk menambahkan lapisan keamanan lain, administrator penyewa Microsoft Entra dapat mengonfigurasi penyewa mereka sehingga platform identitas Microsoft mengeluarkan token keamanan hanya ke aplikasi klien yang telah mereka setujui untuk akses API.

Untuk meningkatkan keamanan dengan membatasi pengeluaran token hanya untuk aplikasi klien yang telah ditetapkan peran aplikasinya:

  1. Di pusat admin Microsoft Entra, pilih aplikasi Anda di bawah Aplikasi> Identitas>Pendaftaran aplikasi.
  2. Pada halaman gambaran umum aplikasi, pilih tautan Aplikasi terkelola di direktori lokal untuk menavigasi ke halaman Gambaran Umum Aplikasi Enterprise.
  3. Di bawah Kelola, pilih Properti.
  4. Tetapkan Penugasan diperlukan? ke Ya.
  5. Pilih Simpan.

ID Microsoft Entra sekarang akan memeriksa penetapan peran aplikasi aplikasi klien yang meminta token akses untuk API web Anda. Jika aplikasi klien belum diberi peran aplikasi apa pun, ID Microsoft Entra mengembalikan pesan kesalahan ke klien yang mirip dengan invalid_client: AADSTS501051: <Nama> aplikasi aplikasi tidak ditetapkan ke peran untuk <API> web.

Peringatan

JANGAN gunakan kode galat AADSTS atau string pesan kode galat AADSTS sebagai harfiah dalam kode aplikasi Anda. Kode kesalahan "AADSTS" dan string pesan kesalahan yang dikembalikan oleh ID Microsoft Entra tidak dapat diubah, dan dapat diubah oleh Microsoft kapan saja dan tanpa sepengetahuan Anda. Jika Anda membuat keputusan pencabangan dalam kode Anda berdasarkan nilai kode AADSTS atau string pesannya, Anda membahayakan fungsionalitas dan stabilitas aplikasi Anda.

Langkah berikutnya

Artikel berikutnya dalam seri ini adalah Konfigurasi kode aplikasi.