Mengakses produk dan API dengan aman dengan aplikasi Microsoft Entra

BERLAKU UNTUK: Pengembang | Dasar | Standar | Premi

API Management sekarang mendukung akses berbasis aplikasi OAuth 2.0 bawaan ke API produk menggunakan alur kredensial klien. Fitur ini memungkinkan manajer API untuk mendaftarkan aplikasi MICROSOFT Entra ID, menyederhanakan akses API yang aman untuk pengembang melalui otorisasi OAuth 2.0.

Nota

Aplikasi saat ini dalam pratinjau terbatas. Untuk mendaftar, isi formulir ini.

Dengan fitur ini:

• Manajer API mengatur properti produk untuk mengaktifkan akses berbasis aplikasi.
• Manajer API mendaftarkan aplikasi klien di ID Microsoft Entra untuk membatasi akses ke produk tertentu.
• Pengembang dapat mengakses kredensial aplikasi klien menggunakan portal pengembang API Management.
• Menggunakan alur kredensial klien OAuth 2.0, pengembang, atau aplikasi mendapatkan token yang dapat mereka sertakan dalam permintaan API
• Token yang disajikan dalam permintaan API divalidasi oleh gateway API Management untuk mengotorisasi akses ke API produk.

Prasyarat

• Instans API Management yang disebarkan di tingkat Premium, Standar, Dasar, atau Pengembang . Jika Anda perlu menyebarkan instans, lihat Membuat instans layanan API Management.

• Setidaknya satu produk dalam instans API Management Anda, dengan setidaknya satu API yang ditetapkan untuknya.

  • Produk harus dalam status Diterbitkan sehingga dapat diakses oleh pengembang melalui portal pengembang.
  • Untuk pengujian, Anda dapat menggunakan produk Starter default dan Echo API yang ditambahkan ke dalamnya.
  • Jika Anda ingin membuat produk, lihat Membuat dan menerbitkan produk.

• Penentuan izin yang memadai pada penyewa Microsoft Entra Anda untuk bisa menetapkan peran Administrator Aplikasi, yang memerlukan setidaknya peran Administrator Peran Istimewa.

• Secara opsional, tambahkan satu atau beberapa pengguna di instans API Management Anda.

• Jika Anda memilih untuk menggunakan Azure PowerShell secara lokal:
  • Pasang 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.

Mengonfigurasikan identitas terkelola

1. Aktifkan identitas terkelola yang ditetapkan sistem untuk API Management di instans API Management Anda.

2. Tetapkan identitas peran RBAC Administrator Aplikasi di MICROSOFT Entra ID. Untuk menetapkan peran:

   1. Masuk ke portal dan navigasi ke ID Microsoft Entra.
   2. Di menu sebelah kiri, pilih Kelola>Peran dan administrator.
   3. Pilih Administrator aplikasi.
   4. Di menu sebelah kiri, pilih Kelola>Penugasan>+ Tambahkan penugasan.
   5. Di halaman Tambahkan penugasan , cari identitas terkelola instans API Management berdasarkan nama (nama instans API Management). Pilih identitas terkelola, lalu pilih Tambahkan.

Mengaktifkan akses berbasis aplikasi untuk produk

Ikuti langkah-langkah ini untuk mengaktifkan akses berbasis aplikasi untuk produk. Produk harus mengaktifkan pengaturan ini untuk dikaitkan dengan aplikasi klien di langkah selanjutnya.

Contoh berikut menggunakan produk Starter , tetapi pilih produk yang diterbitkan yang memiliki setidaknya satu API yang ditetapkan untuknya.

1. Masuk ke portal di URL kustom berikut untuk fitur aplikasi: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=aplikasi
2. Navigasi ke instans API Management Anda.
3. Di menu sebelah kiri, di bawah API, pilih Produk.
4. Pilih produk yang ingin Anda konfigurasi, seperti produk Starter .
5. Di menu sebelah kiri, di bawah Produk, pilih Properti.
6. Di bagian Akses berbasis aplikasi, aktifkan pengaturan token OAuth 2.0 (paling aman).
7. Secara opsional, aktifkan pengaturan Kunci langganan . Jika Anda mengaktifkan akses berbasis aplikasi dan persyaratan langganan, gateway API Management dapat menerima token OAuth 2.0 atau kunci langganan untuk akses ke API produk.
8. Pilih Simpan.

Petunjuk / Saran

Anda juga dapat mengaktifkan pengaturan token OAuth 2.0 saat membuat produk baru.

Mengaktifkan akses berbasis aplikasi membuat aplikasi perusahaan backend di ID Microsoft Entra untuk mewakili produk. ID aplikasi backend ditampilkan di halaman Properti produk.

Nota

ID aplikasi ini ditetapkan sebagai nilai Audiens saat membuat aplikasi klien untuk mengakses produk. Gunakan juga nilai ini saat menghasilkan token untuk memanggil API produk.

(Opsional) Meninjau pengaturan aplikasi produk di ID Microsoft Entra

Secara opsional tinjau pengaturan aplikasi perusahaan backend yang dibuat di MICROSOFT Entra ID untuk mewakili produk.

Aplikasi ini dinamai dengan format berikut: APIMProductApplication<product-name>. Misalnya, jika nama produk adalah Starter, nama aplikasinya adalah APIMProductApplicationStarter. Aplikasi ini memiliki peran Aplikasi yang ditentukan.

Untuk meninjau pengaturan aplikasi di Pendaftaran aplikasi:

1. Masuk ke portal dan buka Microsoft Entra ID>Kelola>Pendaftaran aplikasi.
2. Pilih Semua aplikasi.
3. Cari dan pilih aplikasi yang dibuat oleh API Management.
4. Di menu sebelah kiri, di bawah Kelola, pilih Peran aplikasi.
5. Konfirmasikan peran aplikasi yang ditetapkan oleh Azure API Management, seperti yang ditunjukkan pada cuplikan layar berikut:

Mendaftarkan aplikasi klien untuk mengakses produk

Sekarang daftarkan aplikasi klien yang membatasi akses ke satu atau beberapa produk.

• Produk harus mengaktifkan akses berbasis Aplikasi untuk dikaitkan dengan aplikasi klien.
• Setiap aplikasi klien memiliki satu pengguna (pemilik) dalam instans API Management. Hanya pemilik yang dapat mengakses API produk melalui aplikasi.
• Produk dapat dikaitkan dengan lebih dari satu aplikasi klien.

Untuk mendaftarkan aplikasi klien:

1. Masuk ke portal di URL kustom berikut untuk fitur aplikasi: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=aplikasi

2. Navigasi ke instans API Management Anda.

3. Di menu sebelah kiri, di bawah API, pilih Aplikasi>+ Daftarkan aplikasi.

4. Di halaman Daftarkan aplikasi , masukkan pengaturan aplikasi berikut ini:

   • Nama: Masukkan nama untuk aplikasi.
   • Pemilik: Pilih pemilik aplikasi dari daftar dropdown pengguna di instans API Management.
   • Memberikan akses ke produk yang dipilih: Pilih satu atau beberapa produk dalam instans API Management yang sebelumnya diaktifkan untuk akses berbasis Aplikasi.
   • Deskripsi: Secara opsional masukkan deskripsi.

   

5. Pilih Daftarkan.

Aplikasi ditambahkan ke daftar aplikasi di halaman Aplikasi . Pilih aplikasi untuk melihat detail seperti ID Klien. Anda memerlukan ID ini untuk menghasilkan token untuk memanggil API produk.

Petunjuk / Saran

• Setelah membuat aplikasi, secara opsional kaitkan dengan produk lain. Pilih aplikasi di halaman Aplikasi , lalu pilih Detail>Produk>+ Tambahkan produk.
• Anda juga dapat membuat atau mengaitkan aplikasi dengan mengedit produk dari halaman Produk .

Buat kode rahasia klien

Rahasia klien harus dihasilkan agar aplikasi klien menggunakan alur kredensial klien OAuth 2.0. Rahasia ini berlaku selama satu tahun tetapi dapat diregenerasi kapan saja.

1. Pada halaman Aplikasi , pilih aplikasi yang Anda buat.

2. Pada halaman Gambaran Umum aplikasi, di samping Rahasia Klien, pilih Tambahkan rahasia.

3. Pada halaman Rahasia klien baru , pilih Buat.

   Rahasia klien dihasilkan dan ditampilkan di bidang Rahasia klien . Pastikan untuk menyalin nilai rahasia dan menyimpannya dengan aman. Anda tidak akan dapat mengambilnya lagi setelah menutup halaman.

4. Pilih Tutup.

(Opsional) Meninjau pengaturan aplikasi klien di ID Microsoft Entra

Tinjau pengaturan aplikasi klien secara opsional di ID Microsoft Entra.

Aplikasi ini diberi nama dengan format berikut: APIMApplication<product-name>. Misalnya, jika nama produknya adalah Starter, nama aplikasinya mirip dengan APIMApplicationStarter.

Untuk meninjau pengaturan aplikasi di Pendaftaran aplikasi:

1. Masuk ke portal dan buka Microsoft Entra ID>Kelola>Pendaftaran aplikasi.

2. Pilih Semua aplikasi.

3. Cari dan pilih aplikasi klien yang dibuat oleh API Management.

4. Di menu sebelah kiri, di bawah Kelola, pilih Izin API.

5. Konfirmasikan bahwa aplikasi memiliki izin untuk mengakses aplikasi atau aplikasi produk backend.

   Misalnya, jika aplikasi klien memberikan akses ke produk Starter , aplikasi memiliki izin Product.Starter.All untuk mengakses aplikasi APIMProductApplicationStarter .

   

Mendapatkan pengaturan aplikasi di portal pengembang

Pengguna dapat masuk ke portal pengembang untuk melihat aplikasi klien yang mereka miliki.

1. Masuk ke portal pengembang (https://<your-apim-instance-name>.developer.azure-api.net) menggunakan akun pengguna yang ditetapkan sebagai pemilik aplikasi klien.

2. Di menu navigasi atas, pilih Aplikasi.

3. Aplikasi yang dimiliki pengguna muncul dalam daftar.

4. Pilih aplikasi untuk melihat detailnya, seperti ID Klien, Rahasia klien, dan Cakupan. Nilai-nilai ini diperlukan untuk menghasilkan token untuk memanggil API produk.

   

Membuat token dan menggunakan dengan panggilan API

Setelah Anda mengaktifkan akses berbasis aplikasi untuk produk dan mendaftarkan aplikasi klien, pengembang atau aplikasi dapat menghasilkan token untuk memanggil API produk. Token harus dimasukkan ke dalam Authorization di header permintaan.

Misalnya, pengembang atau aplikasi dapat menjalankan skrip Azure PowerShell berikut untuk memanggil aplikasi klien untuk menghasilkan token, lalu menggunakan token untuk memanggil API produk di API Management.

Perhatian

Skrip berikut adalah contoh untuk tujuan pengujian saja. Dalam produksi, gunakan metode aman untuk menyimpan dan mengambil rahasia klien.

Memanggil aplikasi klien untuk menghasilkan token

# Replace placeholder values with your own values.

$clientId = "00001111-aaaa-2222-bbbb-3333cccc4444" # Client (application) ID of client application
$clientSecret = "******" # Retrieve secret of client application in developer portal
$scopeOfOtherApp = "api://55556666-ffff-7777-aaaa-8888bbbb9999/.default" # Value of Audience in product properties
$tenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Directory (tenant) ID in Microsoft Entra ID

$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    scope         = $scopeOfOtherApp
}
$response = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" -ContentType "application/x-www-form-urlencoded" -Body $body
$token = $response.access_token

Memanggil API produk menggunakan token

Token yang dihasilkan pada langkah sebelumnya digunakan untuk memanggil API produk. Token diteruskan pada permintaan di header Otorisasi. Instans API Management memvalidasi token dan mengotorisasi akses ke API.

Skrip berikut menunjukkan contoh panggilan ke echo API.

# Gatewate endpoint to call. Update with URI of API operation you want to call.
$uri = "https://<gateway-hostname>/echo/resource?param1=sample"
$headers = @{
   "Authorization" = "Bearer $token"  # $token is the token generated in the previous script.
}
$body = @{
    "hello" = "world"
} | ConvertTo-Json -Depth 5

$getresponse = Invoke-RestMethod -Method Post -Uri $uri -ContentType "application/x-www-form-urlencoded" -Headers $headers -Body $body
Write-Host "Response:"
$getresponse | ConvertTo-Json -Depth 5

Penyelesaian Masalah

Kesalahan server internal saat mendaftarkan aplikasi di portal

Jika Anda tidak dapat mencantumkan aplikasi, atau Anda menerima kesalahan server internal saat mendaftarkan aplikasi di portal, periksa hal berikut:

• Peran Administrator Aplikasi ditetapkan ke identitas terkelola instans API Management di Microsoft Entra ID.
• Anda masuk ke portal di URL kustom berikut untuk fitur aplikasi: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=aplikasi. URL ini diperlukan untuk mengakses fitur aplikasi di API Management.

Konten terkait

• Membuat dan menerbitkan produk
• Autentikasi dan otorisasi ke API di API Management