Cara mengonfigurasi otorisasi pengguna OAuth 2.0 di konsol pengujian portal pengembang

BERLAKU UNTUK: Pengembang | Dasar | Dasar v2 | Standar | Standar v2 | Premium | Premium v2

Banyak API mendukung OAuth 2.0 untuk memastikan bahwa hanya pengguna yang valid yang memiliki akses, dan untuk membatasi pengguna ke sumber daya yang mereka berhak. 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 dengan 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.

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 tingkat tinggi:

  1. Daftarkan aplikasi (aplikasi backend) di Microsoft Entra ID untuk mewakili API.

  2. 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.

  3. Konfigurasikan konsol pengujian di portal pengembang untuk memanggil API menggunakan otorisasi pengguna OAuth 2.0.

  4. Konfigurasikan API untuk menggunakan otorisasi pengguna OAuth 2.0.

  5. Tambahkan kebijakan untuk melakukan praotorisasi token OAuth 2.0 untuk setiap permintaan masuk. Anda dapat menggunakan validate-jwt kebijakan untuk penyedia OAuth 2.0 mana pun.

Konfigurasi ini mendukung alur OAuth berikut:

Diagram yang secara visual mewakili alur berikut.

  1. Portal pengembang meminta token dari ID Microsoft Entra menggunakan kredensial aplikasi klien.

  2. Setelah validasi berhasil, Microsoft Entra ID mengeluarkan token akses/pembaruan.

  3. Pengembang (pengguna portal pengembang) melakukan panggilan API dengan header otorisasi.

  4. Token divalidasi dengan penyedia OAuth 2.0 menggunakan kebijakan validate-jwt. Untuk penyedia Microsoft Entra ID, API Management juga menyediakan kebijakan validate-azure-ad-token.

  5. Berdasarkan hasil validasi, pengembang 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 hibah, tergantung pada penyedia dan skenario OAuth 2.0 Anda.

Berikut ini 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 Tukar kode otorisasi dengan token Aplikasi sisi server seperti aplikasi web
Kode otorisasi + PKCE Peningkatan pada alur kode otorisasi dengan membuat tantangan kode yang dikirim bersama 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

Tidak disarankan karena risiko melekat pada pengembalian token akses di pengalihan HTTP tanpa konfirmasi bahwa token tersebut 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 alih-alih 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:

  • Batasilah cakupan token hingga minimum yang diperlukan agar pengembang dapat 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. Contoh ditampilkan nanti dalam artikel ini menggunakan ID Microsoft Entra.

    Bergantung pada skenario Anda, Anda mungkin 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 utama

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 mungkin Anda buat untuk mengakses API. Format cakupannya adalah api://<Backend Application (client) ID>/<Scope Name> (misalnya, api://a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/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 perlu mendaftarkan dua aplikasi dengan penyedia OAuth 2.0 Anda: satu mewakili API backend yang akan dilindungi, dan yang kedua mewakili aplikasi klien yang memanggil API, dalam hal ini, konsol pengujian di portal pengembang.

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

Mendaftarkan aplikasi di ID Microsoft Entra untuk mewakili API

  1. Di portal Microsoft Azure, cari dan pilih pendaftaran Aplikasi.

  2. Pilih Pendaftaran baru.

  3. Saat Halaman daftarkan aplikasi muncul, masukkan informasi pendaftaran aplikasi Anda:

    • Di bagian Nama , masukkan nama aplikasi yang bermakna yang ditampilkan kepada pengguna aplikasi, seperti backend-app.
    • Di bagian Tipe akun yang didukung, pilih opsi yang sesuai dengan skenario Anda.

  4. Biarkan bagian URI Pengalihan kosong. Kemudian, Anda menambahkan URI pengalihan yang dihasilkan dalam konfigurasi OAuth 2.0 di API Management.

  5. Pilih Daftar untuk membuat aplikasi.

  6. Di halaman Gambaran Umum aplikasi, temukan nilai ID Aplikasi (klien) dan catat untuk digunakan nanti.

  7. Di bawah bagian Kelola menu samping, pilih Ekspos API dan atur URI ID Aplikasi dengan nilai default. Catat nilai ini untuk digunakan nanti.

  8. Pilih tombol Tambahkan cakupan untuk menampilkan halaman Tambahkan cakupan:

    1. Masukkan Nama Cakupan untuk cakupan yang didukung oleh API (misalnya, Files.Read).
    2. Di Siapa yang 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.

  9. Pilih tombol Tambahkan cakupan untuk membuat cakupan.

  10. Ulangi dua langkah sebelumnya untuk menambahkan semua ruang lingkup yang didukung oleh API Anda.

  11. 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.

  1. Di portal Microsoft Azure, cari dan pilih pendaftaran Aplikasi.

  2. Pilih Pendaftaran baru.

  3. Saat Halaman daftarkan aplikasi muncul, masukkan informasi pendaftaran aplikasi Anda:

    • Di bagian Nama , masukkan nama aplikasi yang bermakna yang ditampilkan kepada pengguna aplikasi, seperti aplikasi klien.
    • Di bagian Tipe akun yang didukung, pilih opsi yang sesuai dengan skenario Anda.

  4. Di bagian URI Pengalihan, pilih Web dan biarkan bidang URL kosong untuk saat ini.

  5. Pilih Daftar untuk membuat aplikasi.

  6. Di halaman Gambaran Umum aplikasi, temukan nilai ID Aplikasi (klien) dan catat untuk digunakan nanti.

  7. 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 konsol Pengujian, beri izin kepada aplikasi klien untuk memanggil aplikasi backend.

  1. Di portal Microsoft Azure, cari dan pilih pendaftaran Aplikasi.

  2. Pilih aplikasi klien Anda. Kemudian di menu bar samping, di bawah Kelola, pilih Izin API.

  3. Pilih +Tambahkan izin.

  4. Di bawah Pilih API, pilih API Saya, lalu temukan dan pilih aplikasi backend Anda (aplikasi yang terdaftar untuk API backend Anda).

  5. Pilih Izin yang Didelegasikan, lalu pilih izin yang sesuai ke backend-app Anda.

  6. Pilih Tambahkan izin.

Opsional:

  1. Navigasikan ke halaman izin API aplikasi klien Anda.

  2. 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

  1. Di Portal Microsoft Azure, navigasikan ke instans API Management Anda.

  2. Di bawah Portal pengembang di menu bilah samping, pilih OAuth 2.0 + OpenID Connect.

  3. Di bawah tab OAuth 2.0, pilih + Tambahkan.

    Cuplikan layar menu OAuth 2.0.

  4. 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 berasal dari server OAuth 2.0.

  5. 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.

    Cuplikan layar kotak dialog server baru OAuth 2.0.

  6. 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). Untuk mempelajari selengkapnya, lihat Jenis pemberian otorisasi.

    • 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 mirip dengan salah satu URL berikut, di mana <your-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/<your-tenant>/oauth2/v2.0/authorize (v2)

      https://login.microsoftonline.com/<your-tenant>/oauth2/authorize (v1)

    • Metode permintaan otorisasi menentukan bagaimana permintaan otorisasi dikirim ke server OAuth 2.0. Pilih POST.

      Cuplikan layar kotak dialog pengaturan otorisasi.

  7. Tentukan Token endpoint URL, Metode autentikasi klien, Metode pengiriman token akses, dan cakupan default.

    • Masukkan URL titik akhir token. Untuk aplikasi tenan tunggal di Microsoft Entra ID, aplikasi ini mirip dengan salah satu URL berikut, di mana <your-tenant> diganti dengan ID tenan Microsoft Entra Anda. Gunakan versi titik akhir yang sama (v2 atau v1) yang Anda pilih sebelumnya.

      https://login.microsoftonline.com/<your-tenant>/oauth2/v2.0/token (v2)

      https://login.microsoftonline.com/<your-tenant>/oauth2/token (v1)

    • Jika Anda menggunakan titik akhir v1, tambahkan parameter bodi:
      * Nama: sumber daya.
      * Nilai: aplikasi back-end ID Aplikasi (klien).

    • Jika Anda menggunakan titik akhir v2:
      Masukkan cakupan aplikasi back-end yang Anda buat di bidang Cakupan default.
      * Tetapkan nilai untuk requestedAccessTokenVersion 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.

  8. Di Kredensial klien, masukkan ID Klien dan Rahasia klien, yang Anda peroleh selama proses pembuatan dan konfigurasi aplikasi klien Anda.

  9. 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

    Cuplikan layar memperlihatkan kotak dialog Tambahkan kredensial klien untuk layanan OAuth 2.0.

    Salin URI Pengalihan yang sesuai ke halaman Autentikasi pendaftaran aplikasi klien Anda. Dalam pendaftaran aplikasi, pilih >, lalu masukkan URI Pengalihan.

  10. 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.

  11. Pilih Buat untuk menyimpan konfigurasi server otorisasi OAuth 2.0 API Management.

  12. Menerbitkan kembali portal pengembang.

    Penting

    Saat membuat perubahan terkait OAuth 2.0, pastikan untuk menerbitkan ulang portal pengembang setiap kali ada modifikasi, karena perubahan yang relevan (misalnya, perubahan cakupan) sehingga perubahan tersebut tidak dapat disebarluaskan ke portal untuk selanjutnya digunakan dalam mencoba API tersebut.

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.

  1. Di bawah API pada menu bilah samping, pilih API.

  2. Pilih nama API yang diinginkan dan pilih tab Pengaturan. Gulir ke bagian Keamanan, lalu pilih OAuth 2.0.

  3. Pilih server Otorisasi yang diinginkan dari daftar drop-down, dan klik Simpan.

    Cuplikan layar memperlihatkan opsi Konfigurasikan server otorisasi OAuth 2.0.

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.

  1. Klik Portal Pengembang di menu atas dari halaman Gambaran Umum instans Azure API Management Anda.

  2. Telusuri ke operasi apa pun di bawah API di portal pengembang.

  3. Pilih Coba untuk membawa Anda ke konsol pengembang.

  4. Perhatikan item baru di bagian Otorisasi, sesuai dengan server otorisasi yang baru saja Anda tambahkan.

  5. Pilih Kode otorisasi dari daftar turun bawah otorisasi.

    Pilih Otorisasi kode otorisasi

  6. Setelah diminta, masuk ke tenant Microsoft Entra.

    • Jika Anda sudah masuk dengan akun tersebut, Anda mungkin tidak akan diminta masuk.

  7. Setelah berhasil masuk, header Authorization ditambahkan ke permintaan, dengan token akses dari ID Microsoft Entra. Berikut ini adalah contoh token yang disingkat (Dikodekan Base64):

    Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA

  8. Konfigurasikan nilai yang diinginkan untuk parameter yang tersisa, dan pilih Kirim untuk memanggil API.

Mengonfigurasi 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 praotorisasi permintaan, konfigurasikan kebijakan validate-jwt untuk memvalidasi token akses setiap permintaan masuk. Jika permintaan tidak memiliki token yang valid, API Management akan memblokirnya. Saat menggunakan penyedia ID Microsoft Entra, Anda juga dapat menggunakan kebijakan validate-azure-ad-token.

Contoh kebijakan berikut, saat ditambahkan ke bagian kebijakan <inbound>, memeriksa nilai klaim audiens dalam token akses yang diperoleh dari Microsoft Entra ID 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 menganggap aplikasi Microsoft Entra (tenant tunggal) dan titik akhir konfigurasi v2.
  • Nilai claim adalah Client ID dari backend-app yang Anda daftarkan pada Microsoft Entra ID.
<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

Konten terkait

  • Last updated on