Mengonfigurasi aplikasi untuk mengekspos API web

Dalam panduan cara ini, Anda akan mendaftarkan API web dengan platform identitas Microsoft dan mengeksposnya ke aplikasi klien dengan menambahkan cakupan. Dengan mendaftarkan API web Anda dan mengeksposnya melalui cakupan, menetapkan peran pemilik dan aplikasi, Anda dapat memberikan akses berbasis izin ke sumber dayanya kepada pengguna dan aplikasi klien yang berwenang yang mengakses API Anda.

Prasyarat

• Sebuah akun Azure dengan langganan aktif. Jika Anda tidak memilikinya, buat akun secara gratis.
• Aplikasi yang terdaftar di pusat admin Microsoft Entra. Jika Anda tidak memilikinya, daftarkan aplikasi sekarang.

Mendaftarkan API web

Akses ke API memerlukan konfigurasi cakupan dan peran akses. Jika Anda ingin mengekspose API web aplikasi sumber daya ke aplikasi klien, konfigurasikan cakupan dan peran akses untuk API. Jika Anda ingin aplikasi klien mengakses API web, konfigurasikan izin untuk mengakses API dalam pendaftaran aplikasi. Untuk menyediakan akses tercakup ke sumber daya di API web Anda, Pertama-tama Anda harus mendaftarkan API dengan platform identitas Microsoft.

1. Masuk ke pusat admin Microsoft Entra sebagai paling tidak Administrator Aplikasi Cloud.
2. Jika Anda memiliki akses ke beberapa penyewa, gunakan ikon Pengaturan di menu atas untuk beralih ke penyewa yang berisi pendaftaran aplikasi dari menu Direktori + langganan.
3. Lakukan langkah-langkah dalam mendaftarkan aplikasi dan lewati bagian URI Pengalihan (opsional). Anda tidak perlu mengonfigurasi URI pengalihan untuk API web karena tidak ada pengguna yang masuk secara interaktif.

Menetapkan pemilik aplikasi

1. Di pendaftaran aplikasi Anda, di bawah Kelola, pilih Pemilik, dan Tambahkan pemilik.
2. Di jendela baru, temukan dan pilih pemilik yang ingin Anda tetapkan ke aplikasi. Pemilik yang dipilih muncul di panel kanan. Setelah selesai, konfirmasi dengan Pilih. Pemilik aplikasi sekarang akan muncul dalam daftar pemilik.

Catatan

Pastikan bahwa pemilik ditetapkan ke aplikasi API dan aplikasi yang ingin Anda tambahkan izinnya, jika tidak, API tidak akan tercantum saat meminta izin API.

Menetapkan peran aplikasi

1. Di pendaftaran aplikasi Anda, di bawah Kelola, pilih Peran aplikasi, dan Buat peran aplikasi.

2. Selanjutnya, tentukan atribut peran aplikasi di panel Buat peran aplikasi. Untuk walk-through ini, Anda dapat menggunakan nilai contoh atau menentukan nilai Anda sendiri.

   Bidang	Deskripsi	Contoh
   Nama tampilan	Nama peran aplikasi Anda	Rekaman Karyawan
   Tipe anggota yang diperbolehkan	Menentukan apakah peran aplikasi dapat ditetapkan ke pengguna/grup dan/atau aplikasi	Aplikasi
   Nilai	Nilai yang ditampilkan dalam klaim "peran" dari token	Employee.Records
   Keterangan	Deskripsi peran aplikasi yang lebih rinci	Aplikasi memiliki akses ke catatan karyawan

3. Pilih kotak centang untuk mengaktifkan peran aplikasi, lalu pilih Terapkan.

Tambah cakupan

Dengan API web terdaftar, diberi peran dan pemilik aplikasi, Anda dapat menambahkan cakupan ke kode API sehingga dapat memberikan izin terperinci kepada konsumen.

Kode dalam aplikasi klien meminta izin untuk melakukan operasi yang ditentukan oleh API web Anda dengan meneruskan token akses bersama dengan permintaannya ke sumber daya yang dilindungi (API web). API web Anda kemudian melakukan operasi yang diminta hanya jika token akses yang diterimanya berisi cakupan yang diperlukan untuk operasi.

Menambahkan cakupan yang memerlukan persetujuan admin dan pengguna

Pertama, ikuti langkah-langkah ini untuk membuat contoh cakupan bernama Employees.Read.All:

1. Pilih Ekspos API.

2. Di bagian atas halaman, pilih Tambahkan di samping URI ID Aplikasi. Pengaturan bawaan ini ke api://<application-client-id>. App ID URI bertindak sebagai awalan untuk cakupan yang akan Anda referensikan dalam kode API Anda, dan itu harus unik secara global. Pilih Simpan.

3. Pilih Tambahkan cakupan:

   

4. Berikutnya, tentukan atribut cakupan di panel Tambahkan cakupan. Untuk walk-through ini, Anda dapat menggunakan nilai contoh atau menentukan nilai Anda sendiri.

   Bidang	Deskripsi	Contoh
   Nama cakupan	Nama cakupan Anda. Konvensi penamaan cakupan umum adalah resource.operation.constraint.	Employees.Read.All
   Siapa yang dapat menyetujui	Apakah cakupan ini dapat disetujui oleh pengguna atau jika persetujuan admin diperlukan. Hanya untuk admin yang memiliki izin dengan hak istimewa yang lebih tinggi.	Admin dan pengguna
   Nama tampilan persetujuan admin	Deskripsi singkat tentang tujuan cakupan yang hanya akan dilihat oleh admin.	Akses lihat-saja ke catatan Karyawan
   Deskripsi persetujuan admin	Deskripsi lebih rinci dari izin yang diberikan oleh cakupan yang hanya dapat dilihat oleh admin.	Izinkan aplikasi memiliki akses baca-saja ke semua data Karyawan.
   Nama tampilan persetujuan pengguna	Deskripsi singkat tentang tujuan cakupan. Diperlihatkan kepada pengguna hanya jika Anda mengatur Siapa yang bisa menyetujui Admin dan pengguna.	Akses baca-saja ke catatan Karyawan Anda
   Deskripsi persetujuan pengguna	Deskripsi yang lebih terperinci tentang izin yang diberikan dalam lingkup ini. Diperlihatkan kepada pengguna hanya jika Anda mengatur Siapa yang bisa menyetujui Admin dan pengguna.	Izinkan aplikasi memiliki akses baca-saja ke data Karyawan Anda.
   Negara	Apakah cakupan diaktifkan atau dinonaktifkan.	Diaktifkan

5. Pilih Tambahkan cakupan.

6. (Opsional) Untuk menekan permintaan persetujuan oleh pengguna aplikasi Anda ke cakupan yang telah Anda tentukan, Anda dapat melakukan pra-otorisasi aplikasi klien untuk mengakses API web Anda. Pra-otorisasi hanya aplikasi klien yang Anda percayai karena pengguna Anda tidak akan memiliki kesempatan untuk menolak persetujuan.

   1. Di bagian Aplikasi klien yang diotorisasi, pilih Tambahkan aplikasi klien.
   2. Masukkan ID Aplikasi (klien) dari aplikasi klien yang ingin Anda pra-otorisasi. Misalnya, aplikasi web yang sebelumnya telah Anda daftarkan.
   3. Di bawah Cakupan yang diotorisasi, pilih cakupan yang ingin Anda tekan permintaan persetujuannya, lalu pilih Tambahkan aplikasi.

   Jika Anda mengikuti langkah opsional ini, aplikasi klien sekarang menjadi aplikasi klien pra-otorisasi (PCA), dan pengguna tidak akan dimintai persetujuan mereka saat masuk ke aplikasi tersebut.

Menambahkan cakupan yang memerlukan persetujuan admin

Selanjutnya, tambahkan contoh cakupan lain yang bernama Employees.Write.All yang hanya dapat disetujui oleh admin. Ruang lingkup yang memerlukan persetujuan admin biasanya digunakan untuk menyediakan akses untuk operasi dengan hak istimewa lebih tinggi, dan seringkali digunakan oleh aplikasi klien yang berjalan sebagai layanan backend atau daemon yang tidak masuk sebagai pengguna secara interaktif.

Untuk menambahkan Employees.Write.All contoh cakupan, ikuti langkah-langkah di bagian Tambahkan cakupan dan tentukan nilai-nilai ini di panel Tambahkan cakupan . Pilih Tambahkan cakupan saat Anda selesai:

Bidang	Contoh nilai
Nama cakupan	Employees.Write.All
Siapa yang dapat menyetujui	Hanya Admin
Nama tampilan persetujuan admin	Akses menulis ke catatan Karyawan
Deskripsi persetujuan admin	Izinkan aplikasi memiliki akses tulis ke semua data Karyawan.
Nama tampilan persetujuan pengguna	Tidak ada (biarkan kosong)
Deskripsi persetujuan pengguna	Tidak ada (biarkan kosong)
Negara	Diaktifkan

Memverifikasi cakupan yang diekspos

Jika Anda berhasil menambahkan kedua contoh cakupan yang dijelaskan di bagian sebelumnya, cakupan tersebut akan muncul di panel Ekspos API pendaftaran aplikasi API web Anda, mirip dengan gambar berikut:

Rangkaian lengkap cakupan adalah perangkaian URI ID Aplikasi API web Anda dan nama cakupan. Misalnya, jika URI ID aplikasi API web Anda https://contoso.com/api dan nama cakupannya adalahEmployees.Read.All, ruang cakupan lengkapnya adalah:

https://contoso.com/api/Employees.Read.All

Menggunakan cakupan yang diekspos

Pada artikel berikutnya dalam seri ini, Anda mengonfigurasi pendaftaran aplikasi klien dengan akses ke API web Anda dan cakupan yang Anda tentukan dengan mengikuti langkah-langkah dalam artikel ini.

Setelah pendaftaran aplikasi klien diberikan izin untuk mengakses API web Anda, klien dapat mengeluarkan token akses OAuth 2.0 oleh platform identitas. Ketika klien memanggil API web, fitur ini menyajikan token akses yang cakupan klaimnya (scp) diatur ke izin yang Anda tentukan dalam pendaftaran aplikasi klien.

Anda dapat mengekspos cakupan tambahan nanti jika diperlukan. Pertimbangkan bahwa API web Anda dapat mengekspos beberapa cakupan yang terkait dengan beberapa operasi. Sumber daya Anda dapat mengontrol akses ke API web saat runtime dengan mengevaluasi klaim cakupan (scp) dalam token akses OAuth 2.0 yang diterimanya.

Langkah selanjutnya

Sekarang setelah Anda mengekspos API web Anda dengan mengonfigurasi cakupannya, konfigurasikan pendaftaran aplikasi klien Anda dengan izin untuk mengakses cakupan.

Mengonfigurasi registrasi aplikasi untuk akses API web