Mulai cepat: Mengonfigurasi aplikasi untuk mengekspos API web

Dalam mulai cepat 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

• Akun Azure dengan langganan aktif - buat akun secara gratis
• Penyelesaian Mulai Cepat: Menyiapkan penyewa

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.

Lakukan langkah-langkah di bagian Daftarkan aplikasi dari Mulai Cepat: Daftarkan aplikasi dengan platform identitas Microsoft.

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 aplikasi API dan aplikasi yang ingin Anda tambahkan izinnya ke keduanya memiliki pemilik, jika tidak, API tidak akan dicantumkan 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	Description	Contoh
   Nama tampilan	Nama peran aplikasi Anda	Catatan 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.

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

Menambahkan cakupan

Tip

Langkah-langkah dalam artikel ini mungkin sedikit berbeda berdasarkan portal tempat Anda memulai.

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.

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

1. Masuk ke pusat admin Microsoft Entra sebagai setidaknya 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. Telusuri Aplikasi >Identitas>Pendaftaran aplikasi, lalu pilih pendaftaran aplikasi API Anda.

4. Pilih Ekspos API

5. Pilih Tambahkan di samping URI ID Aplikasi jika Anda belum mengonfigurasinya.

   Anda dapat menggunakan nilai default api://<application-client-id> atau pola URI ID Aplikasi yang didukung lainnya. App ID URI bertindak sebagai awalan untuk cakupan yang akan Anda referensikan dalam kode API Anda, dan itu harus unik secara global.

6. Pilih Tambahkan cakupan:

   

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

   Bidang	Description	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. Pilih Hanya Admin untuk 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.	Read-only access to Employee records
   Deskripsi persetujuan admin	Deskripsi lebih rinci tentang izin yang diberikan oleh cakupan yang hanya akan dilihat oleh admin.	Allow the application to have read-only access to all Employee data.
   Nama tampilan persetujuan pengguna	Deskripsi singkat tentang tujuan cakupan. Diperlihatkan kepada pengguna hanya jika Anda mengatur Siapa yang bisa menyetujui Admin dan pengguna.	Read-only access to your Employee records
   Deskripsi persetujuan pengguna	Deskripsi yang lebih rinci tentang izin yang diberikan oleh cakupan. Diperlihatkan kepada pengguna hanya jika Anda mengatur Siapa yang bisa menyetujui Admin dan pengguna.	Allow the application to have read-only access to your Employee data.

8. Atur Status ke Aktifkan, lalu pilih Tambahkan cakupan.

9. (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 bawah 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. Cakupan yang memerlukan persetujuan admin biasanya digunakan untuk menyediakan akses ke operasi dengan hak istimewa yang lebih tinggi, dan seringkali oleh aplikasi klien yang berjalan sebagai layanan backend atau daemon yang tidak masuk ke pengguna secara interaktif.

Untuk menambahkan Employees.Write.All contoh cakupan, ikuti langkah-langkah di bagianTambahkan cakupan dan tentukan nilainya di panel Tambahkan satu cakupan :

Bidang	Contoh nilai
Nama cakupan	Employees.Write.All
Siapa yang dapat menyetujui	Hanya Admin
Nama tampilan persetujuan admin	Write access to Employee records
Deskripsi persetujuan admin	Allow the application to have write access to all Employee data.
Nama tampilan persetujuan pengguna	Tidak ada (biarkan kosong)
Deskripsi persetujuan pengguna	Tidak ada (biarkan kosong)

Atur Status ke Aktifkan, lalu pilih Tambahkan cakupan.

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:

Seperti yang ditunjukkan pada gambar, string lengkap cakupan adalah penggabungan URI ID Aplikasi API web Anda dan cakupan 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 berikutnya

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