Cara mengotorisasi konsol pengujian portal pengembang dengan mengonfigurasi otorisasi pengguna OAuth 2.0

Artikel
04/01/2024

Banyak API mendukung OAuth 2.0 untuk mengamankan API dan memastikan bahwa hanya pengguna yang valid yang memiliki akses, dan mereka hanya dapat mengakses sumber daya yang berhak mereka dapatkan. Untuk menggunakan konsol pengembang interaktif Azure API Management dengan API tersebut, layanan ini memungkinkan Anda mengonfigurasi penyedia eksternal untuk otorisasi pengguna OAuth 2.0.

Mengonfigurasi otorisasi pengguna OAuth 2.0 dalam konsol pengujian portal pengembang memberi pengembang cara yang mudah untuk memperoleh token akses OAuth 2.0. Dari konsol pengujian, token hanya diteruskan ke backend dengan panggilan API. Validasi token harus dikonfigurasi secara terpisah - baik menggunakan kebijakan validasi JWT, atau di layanan backend.

Prasyarat

Artikel ini menunjukkan cara mengonfigurasi instans layanan API Management Anda untuk menggunakan otorisasi OAuth 2.0 di konsol pengujian portal pengembang, tetapi tidak menunjukkan cara mengonfigurasi penyedia OAuth 2.0.

Jika Anda belum membuat instans layanan API Management, lihat Membuat instans layanan API Management.

Gambaran umum skenario

Mengonfigurasi otorisasi pengguna OAuth 2.0 di API Management hanya memungkinkan konsol pengujian portal pengembang (dan konsol pengujian di portal Azure) sebagai klien untuk memperoleh token dari server otorisasi. Konfigurasi untuk setiap penyedia OAuth 2.0 berbeda, meskipun langkahnya serupa dan bagian yang diperlukan dari informasi yang digunakan dalam mengonfigurasi OAuth 2.0 di instans layanan API Management Anda sama. Artikel ini memperlihatkan contoh menggunakan ID Microsoft Entra sebagai penyedia OAuth 2.0.

Berikut ini adalah langkah-langkah konfigurasi penting:

Daftarkan aplikasi (aplikasi backend) di Microsoft Entra ID untuk mewakili API.
Daftarkan aplikasi lain (client-app) di MICROSOFT Entra ID untuk mewakili aplikasi klien yang perlu memanggil API - dalam hal ini, konsol pengujian portal pengembang.

Di Microsoft Entra ID, berikan izin untuk mengizinkan aplikasi klien memanggil aplikasi backend.
Konfigurasikan konsol pengujian di portal pengembang untuk memanggil API menggunakan otorisasi pengguna OAuth 2.0.
Konfigurasikan API untuk menggunakan otorisasi pengguna OAuth 2.0.
Tambahkan kebijakan untuk melakukan pra-otorisasi token OAuth 2.0 untuk setiap permintaan yang masuk. Anda dapat menggunakan validate-jwt kebijakan untuk penyedia OAuth 2.0 mana pun.

Konfigurasi ini mendukung alur OAuth berikut:

Gambaran umum grafis untuk secara visual mengonseptualisasikan aliran berikut.

Portal pengembang meminta token dari ID Microsoft Entra menggunakan kredensial aplikasi klien.
Setelah validasi berhasil, ID Microsoft Entra mengeluarkan token akses/refresh.
Pengembang (pengguna portal pengembang) melakukan panggilan API dengan header otorisasi.
Token divalidasi dengan menggunakan validate-jwt kebijakan dalam API Management oleh ID Microsoft Entra.
Berdasarkan hasil validasi, pengembang akan menerima respons di portal pengembang.

Jenis pemberian otorisasi

Azure API Management mendukung jenis pemberian OAuth 2.0 berikut (alur). Jenis pemberian mengacu pada cara aplikasi klien (dalam konteks ini, konsol pengujian di portal pengembang) untuk mendapatkan token akses ke API backend Anda. Anda dapat mengonfigurasi satu atau beberapa jenis pemberian tergantung penyedia dan skenario OAuth 2.0 Anda.

Berikut adalah ringkasan tingkat tinggi. Untuk informasi selengkapnya tentang jenis pemberian, lihat Kerangka Kerja Otorisasi OAuth 2.0 dan Jenis pemberian OAuth.

Jenis hibah	Deskripsi	Skenario
Kode otorisasi	Kode otorisasi pertukaran untuk token	Aplikasi sisi server seperti aplikasi web
Kode otorisasi + PKCE	Peningkatan ke alur kode otorisasi yang membuat tantangan kode yang dikirim dengan permintaan otorisasi	Klien seluler dan publik yang tidak dapat melindungi rahasia atau token
Implisit (tidak digunakan lagi)	Mengembalikan token akses dengan segera tanpa langkah pertukaran kode otorisasi tambahan	Klien yang tidak dapat melindungi rahasia atau token sepeti aplikasi ponsel dan aplikasi satu halaman Secara garis besar tidak disarankan karena risiko inheren mengembalikan token akses dalam pengalihan HTTP tanpa konfirmasi yang menyatakan telah diterima oleh klien
Kata sandi pemilik sumber daya	Meminta kredensial pengguna (nama pengguna dan kata sandi), biasanya menggunakan formulir interaktif	Untuk digunakan dengan aplikasi yang sangat tepercaya Hanya boleh digunakan ketika alur lain yang lebih aman tidak dapat digunakan
Informasi masuk klien	Mengautentikasi dan mengotorisasi aplikasi daripada pengguna	Aplikasi mesin-ke-mesin yang tidak memerlukan izin pengguna tertentu untuk mengakses data, seperti CLI, daemon, atau layanan yang berjalan di backend Anda

Pertimbangan keamanan

Pertimbangkan cara jenis pemberian menghasilkan token, cakupan token, dan cara token dapat diekspos. Token yang disusupi dapat digunakan oleh pelaku jahat untuk mengakses sumber daya tambahan dalam cakupan token.

Saat mengonfigurasi otorisasi pengguna OAuth 2.0 di konsol pengujian portal pengembang:

Membatasi cakupan token hingga minimum diperlukan pengembang untuk menguji API. Batasi cakupan ke konsol pengujian, atau ke API yang terpengaruh. Langkah-langkah untuk mengonfigurasi cakupan token bergantung pada penyedia OAuth 2.0 Anda.

Bergantung pada skenario Anda, Anda dapat mengonfigurasi cakupan token yang kurang lebih ketat untuk aplikasi klien lain yang Anda buat untuk mengakses API backend.
Berhati-hatilah jika Anda mengaktifkan alur Kredensial Klien. Konsol pengujian di portal pengembang, saat bekerja dengan alur Kredensial Klien, tidak meminta kredensial. Token akses dapat secara tidak sengaja diekspos ke pengembang atau pengguna anonim konsol pengembang.

Melacak informasi kunci

Sepanjang tutorial ini, Anda akan diminta untuk mencatat informasi kunci untuk direferensikan nanti:

ID Aplikasi Backend (klien): GUID aplikasi yang mewakili API backend
Cakupan Aplikasi Backend: Satu atau beberapa cakupan yang dapat Anda buat untuk mengakses API. Format cakupannya adalah api://<Backend Application (client) ID>/<Scope Name> (misalnya, api://1764e900-1827-4a0b-9182-b2c1841864c2/Read)
ID Aplikasi Klien (klien): GUID aplikasi yang mewakili portal pengembang
Nilai Rahasia Aplikasi Klien: GUID yang berfungsi sebagai rahasia untuk interaksi dengan aplikasi klien di ID Microsoft Entra

Mendaftarkan aplikasi dengan server OAuth

Anda harus mendaftarkan dua aplikasi dengan penyedia OAuth 2.0 Anda: satu mewakili API backend yang akan dilindungi, dan satu detik mewakili aplikasi klien yang memanggil API - dalam hal ini, konsol pengujian portal pengembang.

Berikut ini adalah contoh langkah-langkah menggunakan ID Microsoft Entra sebagai penyedia OAuth 2.0. Untuk detail tentang pendaftaran aplikasi, lihat Mulai Cepat: Mengonfigurasi aplikasi untuk mengekspos API web.

Mendaftarkan aplikasi di ID Microsoft Entra untuk mewakili API

Di portal Microsoft Azure, cari dan pilih pendaftaran Aplikasi.
Pilih Pendaftaran baru.
Saat Halaman daftarkan aplikasi muncul, masukkan informasi pendaftaran aplikasi Anda:
- Di bagian Nama, masukkan nama aplikasi bermakna yang akan ditampilkan kepada pengguna aplikasi, seperti backend-app.
- Di bagian Tipe akun yang didukung, pilih opsi yang sesuai dengan skenario Anda.
Biarkan bagian URI Pengalihan kosong. Nantinya, Anda akan menambahkan URI pengalihan yang dihasilkan dalam konfigurasi OAuth 2.0 di API Management.
Pilih Daftar untuk membuat aplikasi.
Di halaman Gambaran Umum aplikasi, temukan nilai ID Aplikasi (klien) dan catat untuk digunakan nanti.
Di bawah bagian Kelola menu samping, pilih Ekspos API dan atur URI ID Aplikasi dengan nilai default. Catat nilai ini untuk digunakan nanti.
Pilih tombol Tambahkan cakupan untuk menampilkan halaman Tambahkan cakupan:
1. Masukkan Nama cakupan untuk cakupan yang didukung oleh API (misalnya, Files.Read).
2. Dalam Siapa dapat menyetujui?, buat pilihan untuk skenario Anda, seperti Admin dan pengguna. Pilih Admin hanya untuk skenario istimewa yang lebih tinggi.
3. Masukkan Nama tampilan persetujuan admin dan deskripsi persetujuan Admin.
4. Pastikan status lingkup diaktifkan dipilih.
Pilih tombol Tambahkan cakupan untuk membuat cakupan.
Ulangi dua langkah sebelumnya untuk menambahkan semua ruang lingkup yang didukung oleh API Anda.
Saat cakupan dibuat, buat catatan dari cakupan itu untuk digunakan dalam langkah berikutnya.

Mendaftarkan aplikasi lain di ID Microsoft Entra untuk mewakili aplikasi klien

Daftarkan setiap aplikasi klien yang memanggil API sebagai aplikasi di ID Microsoft Entra.

Di portal Microsoft Azure, cari dan pilih pendaftaran Aplikasi.
Pilih Pendaftaran baru.
Saat Halaman daftarkan aplikasi muncul, masukkan informasi pendaftaran aplikasi Anda:
- Di bagian Nama, masukkan nama aplikasi bermakna yang akan ditampilkan kepada pengguna aplikasi, seperti client-app.
- Di bagian Tipe akun yang didukung, pilih opsi yang sesuai dengan skenario Anda.
Di bagian URI Pengalihan, pilih Web dan biarkan bidang URL kosong untuk saat ini.
Pilih Daftar untuk membuat aplikasi.
Di halaman Gambaran Umum aplikasi, temukan nilai ID Aplikasi (klien) dan catat untuk digunakan nanti.
Buat rahasia klien untuk digunakan aplikasi ini dalam langkah berikutnya.
1. Di bawah bagian Kelola menu samping, pilih Sertifikat & rahasia.
2. Pada Rahasia klien, pilih + Rahasia klien baru.
3. Di bawah Tambahkan rahasia klien,berikan Deskripsi dan pilih kapan kunci harus kedaluwarsa.
4. Pilih Tambahkan.

Saat rahasia dibuat, catat nilai kunci untuk digunakan dalam langkah berikutnya. Anda tidak dapat mengakses rahasia lagi di portal.

Memberikan izin di ID Microsoft Entra

Sekarang setelah Anda mendaftarkan dua aplikasi untuk mewakili API dan kpnsol Pengujian, beri izin untuk mengizinkan aplikasi klien untuk memanggil backend-app.

Di portal Microsoft Azure, cari dan pilih pendaftaran Aplikasi.
Pilih aplikasi klien Anda. Kemudian di menu samping, pilih Izin API.
Pilih + Tambahkan Izin.
Di bawah Pilih API, pilih API Saya, lalu temukan dan pilih backend-app Anda.
Pilih Izin yang Didelegasikan, lalu pilih izin yang sesuai ke backend-app Anda.
Pilih Tambahkan izin.

Opsional:

Navigasikan ke halaman izin API aplikasi klien Anda.
Pilih Berikan persetujuan admin untuk <nama penyewa Anda> untuk memberikan persetujuan atas nama semua pengguna di direktori ini.

Mengonfigurasi server otorisasi OAuth 2.0 di API Management

Di Portal Microsoft Azure, navigasikan ke instans API Management Anda.
Di bawah Portal pengembang di menu samping, pilih OAuth 2.0 + OpenID Koneksi.
Di bawah tab OAuth 2.0, pilih + Tambahkan.
Masukkan nama dan deskripsi opsional di bidang Nama dan Deskripsi.

Catatan

Bidang ini mengidentifikasi server otorisasi OAuth 2.0 dalam layanan API Management saat ini. Nilainya tidak dihasilkan dari server OAuth 2.0.
Masukkan URL halaman pendaftaran klien - misalnya, https://contoso.com/login. Halaman ini adalah tempat pengguna dapat membuat dan mengelola akun mereka, jika penyedia layanan OAuth 2.0 Anda mendukung manajemen pengguna akun. Halaman bervariasi bergantung pada penyedia layanan OAuth 2.0 yang digunakan.

Jika penyedia OAuth 2.0 Anda tidak memiliki manajemen akun pengguna yang dikonfigurasi, masukkan URL tempat penampung di sini seperti URL perusahaan Anda, atau URL seperti http://localhost.
Bagian berikutnya dari formulir berisi Jenis pemberian otorisasi, URL titik akhir otorisasi, dan pengaturan Metode permintaan otorisasi.
- Pilih satu atau beberapa jenis pemberian Otorisasi yang diinginkan. Untuk contoh ini, pilih Kode otorisasi (default). Pelajari lebih lanjut
- Masukkan URL titik akhir Otorisasi. Anda dapat memperoleh URL titik akhir dari halaman Titik Akhir salah satu pendaftaran aplikasi Anda. Untuk aplikasi penyewa tunggal di ID Microsoft Entra, URL ini akan mirip dengan salah satu URL berikut, di mana {aad-tenant} diganti dengan ID penyewa Microsoft Entra Anda.
  
  Disarankan untuk menggunakan titik akhir v2; namun, API Management mendukung titik akhir v1 dan v2.
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/authorize (v2)
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/authorize (v1)
- Metode permintaan otorisasi menentukan bagaimana permintaan otorisasi dikirim ke server OAuth 2.0. Pilih POST.
Tentukan URL titik akhir Token, Metode autentikasi klien, Metode pengiriman token akses, dan cakupan Default.
- Masukkan URL titik akhir token. Untuk satu aplikasi penyewa di MICROSOFT Entra ID, aplikasi tersebut akan mirip dengan salah satu URL berikut, di mana {aad-tenant} diganti dengan ID penyewa Microsoft Entra Anda. Gunakan versi titik akhir yang sama (v2 atau v1) yang Anda pilih sebelumnya.
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/token (v2)
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/token (v1)
- Jika Anda menggunakan titik akhir v1, tambahkan parameter bodi:
  * Nama: sumber daya.
  * Nilai: ID Aplikasi (klien) aplikasi back-end.
- Jika Anda menggunakan titik akhir v2:
  Masukkan cakupan aplikasi terbelakang yang Anda buat di bidang Cakupan default.
  * Tetapkan nilai untuk accessTokenAcceptedVersion properti ke 2 dalam manifes aplikasi untuk pendaftaran backend-app dan client-app.
- Terima pengaturan default untuk metode autentikasi Klien dan Metode pengiriman token akses.
Di Kredensial klien, masukkan ID Klien dan Rahasia klien, yang Anda peroleh selama proses pembuatan dan konfigurasi aplikasi klien Anda.
Setelah ID klien dan Rahasia klien ditentukan, URL Pengalihan untuk kode otorisasi dibuat. URI ini digunakan untuk mengonfigurasi URL pengalihan dalam konfigurasi server OAuth 2.0 Anda.

Di portal pengembang baru, akhiran URI berbentuk:
- /signin-oauth/code/callback/{authServerName} untuk alur pemberian kode otorisasi
- /signin-oauth/implicit/callback untuk aliran pemberian implisit
Salin URI Pengalihan yang sesuai ke halaman Autentikasi pendaftaran aplikasi klien Anda. Dalam pendaftaran aplikasi, pilih Autentikasi>+ Tambahkan Web platform>, lalu masukkan URI Pengalihan.
Jika Jenis pemberian otorisasi diatur ke Kata sandi pemilik sumber daya, bagian Kredensial kata sandi pemilik sumber daya digunakan untuk menentukan kredensial tersebut; jika tidak, Anda dapat membiarkannya kosong.
Pilih Buat untuk menyimpan konfigurasi server otorisasi OAuth 2.0 API Management.
Menerbitkan kembali portal pengembang.

Penting

Saat membuat perubahan terkait OAuth 2.0, pastikan untuk menerbitkan ulang portal pengembang setelah setiap modifikasi sebagai perubahan yang relevan (misalnya, perubahan cakupan) jika tidak tidak dapat disebarluaskan ke portal dan kemudian digunakan dalam mencoba API.

Mengonfigurasi API untuk menggunakan otorisasi pengguna OAuth 2.0

Setelah menyimpan konfigurasi server OAuth 2.0, konfigurasikan API atau API untuk menggunakan konfigurasi ini.

Penting

Mengonfigurasi pengaturan otorisasi pengguna OAuth 2.0 untuk API memungkinkan API Management memperoleh token dari server otorisasi saat Anda menggunakan konsol pengujian di portal portal Azure atau pengembang. Pengaturan server otorisasi juga ditambahkan ke definisi dan dokumentasi API.
Untuk otorisasi OAuth 2.0 saat runtime, aplikasi klien harus memperoleh dan menyajikan token dan Anda perlu mengonfigurasi validasi token di API Management atau API backend. Misalnya, lihat Melindungi API di Azure API Management menggunakan otorisasi OAuth 2.0 dengan ID Microsoft Entra.

Klik API dari menu API Management di sebelah kiri.
Pilih nama API yang diinginkan dan pilih tab Pengaturan. Gulir ke bagian Keamanan, lalu pilih OAuth 2.0.
Pilih server Otorisasi yang diinginkan dari daftar drop-down, dan klik Simpan.

Portal pengembang - uji otorisasi pengguna OAuth 2.0

Setelah Anda mengonfigurasi server otorisasi OAuth 2.0 dan mengonfigurasi API Anda untuk menggunakan server tersebut, Anda dapat mengujinya dengan membuka portal pengembang dan memanggil API.

Klik Portal Pengembang di menu atas dari halaman Gambaran Umum instans Azure API Management Anda.
Telusuri ke operasi apa pun di bawah API di portal pengembang.
Pilih Coba untuk membawa Anda ke konsol pengembang.
Perhatikan item baru di bagian Otorisasi, sesuai dengan server otorisasi yang baru saja Anda tambahkan.
Pilih Kode otorisasi dari daftar turun bawah otorisasi.
Setelah diminta, masuk ke penyewa Microsoft Entra.
- Jika Anda sudah masuk dengan akun tersebut, Anda mungkin tidak akan diminta masuk.
Setelah berhasil masuk, Authorization header ditambahkan ke permintaan, dengan token akses dari ID Microsoft Entra. Berikut ini adalah contoh token yang disingkat (Dikodekan Base64):
```
Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA
```
Konfigurasikan nilai yang diinginkan untuk parameter yang tersisa, dan pilih Kirim untuk memanggil API.

Konfigurasi kebijakan validasi JWT untuk melakukan pra-otorisasi permintaan

Dalam konfigurasi sejauh ini, API Management tidak memvalidasi token akses. Ini hanya meneruskan token di header otorisasi ke API backend.

Untuk melakukan pra-otorisasi permintaan, konfigurasikan kebijakan validate-jwt untuk memvalidasi token akses setiap permintaan masuk. Jika permintaan tidak memiliki token yang valid, API Management akan memblokirnya.

Contoh kebijakan berikut, saat ditambahkan ke <inbound> bagian kebijakan, memeriksa nilai klaim audiens dalam token akses yang diperoleh dari ID Microsoft Entra yang disajikan di header Otorisasi. Ini mengembalikan pesan kesalahan jika token tidak valid. Konfigurasikan kebijakan ini pada cakupan kebijakan yang sesuai untuk skenario Anda.

openid-config Di URL, aad-tenant adalah ID penyewa di MICROSOFT Entra ID. Temukan nilai ini di portal Azure, misalnya, pada halaman Gambaran Umum sumber daya Microsoft Entra Anda. Contoh yang ditampilkan mengasumsikan aplikasi Microsoft Entra penyewa tunggal dan titik akhir konfigurasi v2.
Nilainya claim adalah ID klien dari backend-app yang Anda daftarkan di ID Microsoft Entra.

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

Catatan

URL openid-config sebelumnya sesuai dengan titik akhir v2. Untuk titik akhir v1 openid-config , gunakan https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration.

Untuk informasi mengenai cara mengonfigurasi kebijakan, lihat Mengatur atau mengedit kebijakan. Lihat referensi validasi-jwt untuk lebih banyak kustomisasi pada validasi JWT. Untuk memvalidasi JWT yang disediakan oleh layanan Microsoft Entra, API Management juga menyediakan kebijakan.validate-azure-ad-token

Untuk informasi selengkapnya tentang menggunakan OAuth 2.0 dan API Management, lihat Melindungi backend API web di Azure API Management menggunakan otorisasi OAuth 2.0 dengan ID Microsoft Entra.
Pelajari selengkapnya tentang alur kode otorisasi platform identitas Microsoft dan OAuth 2.0