Mengonfigurasi pengelola kredensial - akses yang didelegasikan pengguna ke API backend

BERLAKU UNTUK: Semua tingkatAN API Management

Artikel ini memandu Anda melalui langkah-langkah tingkat tinggi untuk mengonfigurasi dan menggunakan koneksi terkelola yang memberikan izin yang didelegasikan pengguna atau grup Microsoft ke API OAuth 2.0 backend. Ikuti langkah-langkah ini untuk skenario saat aplikasi klien (atau bot) perlu mengakses sumber daya online aman backend atas nama pengguna yang diautentikasi (misalnya, memeriksa email atau membuat pesanan).

Gambaran umum skenario

Catatan

Skenario ini hanya berlaku untuk penyedia info masuk yang dikonfigurasi dengan jenis pemberian kode otorisasi.

Dalam skenario ini, Anda mengonfigurasi koneksi terkelola yang memungkinkan aplikasi klien (atau bot) mengakses API backend atas nama pengguna atau grup Microsoft Entra. Misalnya, Anda mungkin memiliki aplikasi web statis yang mengakses API GitHub backend dan yang ingin Anda akses data khusus untuk pengguna yang masuk. Diagram berikut mengilustrasikan skenario.

• Pengguna harus mengotorisasi aplikasi untuk mengakses sumber daya aman atas nama mereka, dan untuk mengotorisasi aplikasi, pengguna harus mengautentikasi identitas mereka
• Untuk melakukan operasi atas nama pengguna, aplikasi memanggil layanan backend eksternal, seperti Microsoft Graph atau GitHub
• Setiap layanan eksternal memiliki cara untuk mengamankan panggilan tersebut - misalnya, dengan token pengguna yang secara unik mengidentifikasi pengguna
• Untuk mengamankan panggilan ke layanan eksternal, aplikasi harus meminta pengguna untuk masuk, sehingga dapat memperoleh token pengguna
• Sebagai bagian dari konfigurasi, penyedia kredensial terdaftar menggunakan manajer kredensial dalam instans API Management. Ini berisi informasi tentang IdP yang akan digunakan, bersama dengan ID dan rahasia klien OAuth yang valid, cakupan OAuth untuk diaktifkan, dan metadata koneksi lain yang diperlukan oleh penyedia identitas tersebut.
• Selain itu, koneksi dibuat dan digunakan untuk membantu masuk pengguna dan mendapatkan token pengguna sehingga dapat dikelola

Prasyarat

• Akses ke penyewa Microsoft Entra tempat Anda memiliki izin untuk membuat pendaftaran aplikasi dan untuk memberikan persetujuan admin untuk izin aplikasi. Pelajari lebih lanjut

  Jika ingin membuat penyewa pengembang sendiri, Anda dapat mendaftar ke Program Pengembang Microsoft 365.

• Satu atau beberapa pengguna atau grup di penyewa untuk mendelegasikan izin.

• Instans API Management yang sedang berjalan. Jika perlu, buat instans Azure API Management.

• API OAuth 2.0 backend yang ingin Anda akses atas nama pengguna atau grup.

• Jika Anda memilih untuk menggunakan Azure PowerShell secara lokal:
  • Instal versi terbaru modul Az PowerShell.
  • Sambungkan ke akun Azure Anda menggunakan cmdlet Connect-AzAccount.
• Jika Anda memilih untuk menggunakan Azure Cloud Shell:
  • Lihat Gambaran Umum Azure Cloud Shell untuk informasi selengkapnya.

Langkah 1: Memprovisikan perwakilan layanan Azure API Management Data Plane

Anda perlu menyediakan perwakilan layanan Azure API Management Data Plane untuk memberi pengguna atau grup izin yang didelegasikan yang diperlukan. Gunakan langkah-langkah berikut untuk memprovisikan perwakilan layanan menggunakan Azure PowerShell.

1. Masuk ke Azure PowerShell.

2. Jika modul AzureAD belum diinstal, instal dengan perintah berikut:

   Install-Module -Name AzureAD -Scope CurrentUser -Repository PSGallery -Force
   

3. Koneksi ke penyewa Anda dengan perintah berikut:

   Connect-AzureAD -TenantId "<YOUR_TENANT_ID>"
   

4. Jika diminta, masuk dengan kredensial akun administrator penyewa Anda.

5. Provisikan perwakilan layanan Azure API Management Data Plane dengan perintah berikut:

   New-AzureADServicePrincipal -AppId c8623e40-e6ab-4d2b-b123-2ca193542c65 -DisplayName "Azure API Management Data Plane"
   

Langkah 2: Membuat pendaftaran aplikasi Microsoft Entra

Buat aplikasi ID Microsoft Entra untuk delegasi pengguna dan berikan izin yang sesuai untuk membaca koneksi di API Management.

1. Masuk ke portal Azure dengan akun dengan izin yang memadai di penyewa.
2. Di bawah Layanan Azure, cari ID Microsoft Entra.
3. Di menu sebelah kiri, pilih Pendaftaran aplikasi, lalu pilih + Pendaftaran baru.
4. Pada halaman Daftarkan aplikasi , masukkan pengaturan pendaftaran aplikasi Anda:
   1. Di Nama, masukkan nama yang bermakna yang akan ditampilkan kepada pengguna aplikasi, seperti UserPermissions.
   2. Di Jenis akun yang didukung, pilih opsi yang sesuai dengan skenario Anda, misalnya, Akun dalam direktori organisasi ini saja (Penyewa tunggal).
   3. Atur URI Pengalihan ke Web, dan masukkan https://www.postman-echo.com/get.
5. Di menu sebelah kiri, pilih Izin API, lalu pilih + Tambahkan izin.
   1. Pilih tab API yang digunakan organisasi saya, ketik Azure API Management Data Plane, dan pilih.
   2. Di bawah Izin, pilih Otorisasi.Baca, lalu pilih Tambahkan izin.
6. Di menu sebelah kiri, pilih Gambaran Umum. Pada halaman Gambaran Umum , temukan nilai ID Aplikasi (klien) dan rekam untuk digunakan di langkah selanjutnya.
7. Di menu sebelah kiri, pilih Sertifikat & rahasia, lalu pilih + Rahasia klien baru.
   1. Masukkan Deskripsi.
   2. Pilih opsi untuk Kedaluwarsa.
   3. Pilih Tambahkan.
   4. Salin Nilai rahasia klien sebelum meninggalkan halaman. Anda membutuhkannya di langkah selanjutnya.

Langkah 3: Mengonfigurasi penyedia kredensial di API Management

1. Masuk ke portal dan buka instans API Management Anda.
2. Di menu sebelah kiri, pilih Pengelola kredensial, lalu pilih + Buat.
   
3. Pada halaman Buat penyedia kredensial, masukkan pengaturan untuk penyedia kredensial untuk API Anda. Untuk skenario ini, dalam jenis Grant, Anda harus memilih Kode otorisasi. Untuk informasi selengkapnya, lihat Mengonfigurasi penyedia kredensial di pengelola kredensial.
4. Pilih Buat.
5. Saat diminta, tinjau URL pengalihan OAuth yang ditampilkan, dan pilih Ya untuk mengonfirmasi bahwa URL tersebut cocok dengan URL yang Anda masukkan dalam pendaftaran aplikasi.

Langkah 4: Mengonfigurasi koneksi

Setelah membuat penyedia kredensial, Anda dapat menambahkan koneksi ke penyedia. Pada tab Koneksi ion, selesaikan langkah-langkah untuk koneksi Anda:

1. Masukkan nama Koneksi ion, lalu pilih Simpan.
2. Di bawah Langkah 2: Masuk ke koneksi Anda, pilih tautan untuk masuk ke penyedia kredensial. Selesaikan langkah-langkah di sana untuk mengotorisasi akses, dan kembali ke API Management.
3. Di bawah Langkah 3: Tentukan siapa yang akan memiliki akses ke koneksi ini (Kebijakan akses), pilih + Tambahkan. Bergantung pada skenario delegasi Anda, pilih Pengguna atau Grup.
4. Di jendela Pilih item , buat pilihan dalam urutan berikut:
   1. Pertama, cari satu atau beberapa pengguna (atau grup) untuk menambahkan dan mencentang kotak pilihan.
   2. Kemudian, dalam daftar yang muncul, cari pendaftaran aplikasi yang Anda buat di bagian sebelumnya.
   3. Lalu klik Pilih.
5. Pilih Selesaikan.

Koneksi baru muncul dalam daftar koneksi, dan memperlihatkan status Koneksi. Jika Anda ingin membuat koneksi lain untuk penyedia kredensial, selesaikan langkah-langkah sebelumnya.

Tip

Gunakan portal untuk menambahkan, memperbarui, atau menghapus koneksi ke penyedia kredensial kapan saja. Untuk informasi selengkapnya, lihat Mengonfigurasi beberapa koneksi.

Langkah 5: Memperoleh token akses ID Microsoft Entra

Untuk mengaktifkan akses yang didelegasikan pengguna ke API backend, token akses untuk pengguna atau grup yang didelegasikan harus disediakan pada runtime dalam get-authorization-context kebijakan. Biasanya ini dilakukan secara terprogram di aplikasi klien Anda dengan menggunakan Microsoft Authentication Library (MSAL). Bagian ini menyediakan langkah-langkah manual untuk membuat token akses untuk pengujian.

1. Tempelkan URL berikut di browser Anda, ganti nilai untuk <tenant-id> dan <client-id> dengan nilai dari pendaftaran aplikasi Microsoft Entra Anda:

   https://login.microsoftonline.com/<tenant-id>/oauth2/authorize?client_id=<client-id>&response_type=code&redirect_uri=https://www.postman-echo.com/get&response_mode=query&resource=https://azure-api.net/authorization-manager&state=1234`
   

2. Saat diminta, masuk. Dalam isi respons, salin nilai kode yang disediakan (misalnya: "0.AXYAh2yl…").

3. Kirim permintaan berikut POST ke titik akhir token, ganti <tenant-id> dengan ID penyewa Anda dan sertakan parameter header dan isi yang ditunjukkan dari pendaftaran aplikasi Anda dan kode yang Anda salin di langkah sebelumnya.

   POST https://login.microsoftonline.com/<tenant-id>/oauth2/token HTTP/1.1
   

   Header

   Content-Type: application/x-www-form-urlencoded

   Isi

   grant_type: "authorization_code"
   client_id: <client-id>
   client_secret: <client-secret>
   redirect_uri: <redirect-url> 
   code: <code>   ## The code you copied in the previous step
   

4. Dalam isi respons, salin nilai access_token yang disediakan (misalnya: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjZqQmZ1...). Anda akan meneruskan nilai ini dalam konfigurasi kebijakan di langkah berikutnya.

Langkah 6: Mengonfigurasi kebijakan get-authorization-context untuk API backend

Konfigurasikan kebijakan get-authorization-context untuk API backend yang ingin Anda akses atas nama pengguna atau grup. Untuk tujuan pengujian, Anda dapat mengonfigurasi kebijakan menggunakan token akses ID Microsoft Entra untuk pengguna yang Anda peroleh di bagian sebelumnya.

1. Masuk ke portal dan buka instans API Management Anda.

2. Di menu sebelah kiri, pilih API lalu pilih API backend OAuth 2.0 Anda.

3. Pilih Semua operasi. Di bagian Pemrosesan masuk, pilih (</>) ikon (penyunting kode).

4. Konfigurasikan get-authorization-context kebijakan di bagian inbound , atur identity-type ke jwt:

   <policies>
       <inbound>
           [...]
           <get-authorization-context provider-id="<credential-provider-id>" authorization-id="<connection-id>" context-variable-name="auth-context" identity-type="jwt" identity="<access-token>" ignore-error="false" />
           [...]
       </inbound> 
   </policies>
   

Dalam definisi kebijakan sebelumnya, ganti:

• <credential-provider-id> dan <connection-id> dengan nama penyedia kredensial dan koneksi, masing-masing, yang Anda konfigurasikan dalam langkah sebelumnya.

• <access-token> dengan token akses ID Microsoft Entra yang Anda buat di langkah sebelumnya.

Langkah 7: Uji API

1. Pada tab Uji , pilih satu operasi yang Anda konfigurasi.

2. Pilih Kirim.

   Respons yang berhasil mengembalikan data pengguna dari API backend.

Konten terkait

• Pelajari selengkapnya tentang kebijakan autentikasi dan otorisasi
• Pelajari selengkapnya tentang cakupan dan izin di ID Microsoft Entra.