Langganan di API Management Azure

BERLAKU UNTUK: Semua tingkat API Management

Dalam Azure API Management, langganan adalah cara paling umum bagi konsumen API untuk mengakses API yang diterbitkan melalui instans API Management. Artikel ini memberikan gambaran umum tentang konsep tersebut.

Catatan

Langganan API Management digunakan khusus untuk memanggil API melalui API Management dengan menggunakan kunci langganan. Ini tidak sama dengan langganan Azure.

Apa itu langganan?

Dengan menerbitkan API melalui API Management, Anda dapat dengan mudah mengamankan akses API dengan menggunakan kunci langganan. Pengembang yang perlu menggunakan API yang diterbitkan harus menyertakan kunci langganan yang valid dalam permintaan HTTP saat proses pemanggilan API tersebut. Tanpa kunci langganan yang valid, panggilan akan:

• Ditolak segera oleh gateway API Management.
• Tidak diteruskan ke layanan back-end.

Untuk mengakses API, Anda memerlukan langganan dan kunci langganan. Langganan adalah wadah yang diberi nama untuk sepasang kunci langganan.

Sebagai tambahan,

• Pengembang bisa mendapatkan langganan tanpa memerlukan persetujuan dari penerbit API.
• Penerbit API juga dapat membuat langganan secara langsung untuk konsumen API.

Petunjuk

API Management juga mendukung mekanisme lain untuk mengamankan akses ke API, termasuk contoh berikut:

• OAuth2.0
• Sertifikat klien
• Batasi IP pemanggil

Mengelola kunci langganan

Meregenerasi kunci secara teratur adalah tindakan pencegahan keamanan umum. Seperti kebanyakan layanan Azure yang memerlukan kunci langganan, API Management menghasilkan kunci berpasangan. Setiap aplikasi yang menggunakan layanan dapat beralih dari kunci A ke kunci B dan meregenerasi kunci A dengan gangguan minimal, dan sebaliknya.

Alih-alih meregenerasi kunci, Anda dapat mengatur kunci tertentu dengan memanggil Langganan Azure API Management - Membuat Atau Memperbarui Azure REST API. Secara khusus, atur properties.primaryKey dan/atau properties.secondaryKey di isi permintaan HTTP.

Catatan

• API Management tidak menyediakan fitur bawaan untuk mengelola siklus hidup kunci langganan, seperti mengatur tanggal kedaluwarsa atau memutar kunci secara otomatis. Anda dapat mengembangkan alur kerja untuk mengotomatiskan proses ini dengan menggunakan alat seperti Azure PowerShell atau Azure SDK.
• Untuk menerapkan akses terbatas waktu ke API, penerbit API mungkin dapat menggunakan kebijakan dengan kunci langganan, atau menggunakan mekanisme yang menyediakan kedaluwarsa bawaan seperti autentikasi berbasis token.

Cakupan langganan

Anda dapat mengaitkan langganan dengan berbagai cakupan: produk, semua API, atau API individual.

Langganan untuk suatu produk

Secara tradisional, Anda mengaitkan langganan di API Management dengan satu cakupan produk . Pengembang:

• Temukan daftar produk di portal pengembang.
• Kirim permintaan langganan untuk produk yang ingin mereka gunakan.
• Akses API dalam produk dengan menggunakan kunci dalam langganan yang disetujui baik secara otomatis atau oleh penerbit API.

Saat ini, portal pengembang hanya menampilkan langganan cakupan produk di bawah bagian Profil Pengguna.

Langganan untuk semua API atau API individu

Anda juga dapat membuat kunci yang memberikan akses ke:

• satu API, atau
• Semua API dalam instans API Management.

Dalam kasus ini, Anda tidak perlu membuat produk dan menambahkan API ke dalamnya terlebih dahulu.

Langganan untuk mendapatkan semua akses

Setiap instans API Management dilengkapi dengan langganan semua akses bawaan yang memberikan akses ke semua API. Langganan dengan cakupan layanan ini memudahkan pemilik layanan untuk menguji dan men-debug API dalam konsol pengujian.

Peringatan

Langganan akses penuh memungkinkan akses ke setiap API dalam instans Manajemen API. Hanya pengguna yang berwenang yang harus menggunakan langganan ini. Jangan pernah menggunakan langganan ini untuk akses API rutin atau menyematkan kunci langganan semua akses di aplikasi klien.

Catatan

Jika Anda menggunakan langganan tercakup API, langganan semua API, atau langganan semua akses bawaan, kebijakan yang dikonfigurasi pada cakupan produk tidak diterapkan ke permintaan dari langganan tersebut.

Langganan mandiri

API Management juga memungkinkan langganan mandiri , yang tidak terkait dengan akun pengembang. Fitur ini berguna dalam skenario seperti beberapa pengembang atau tim yang berbagi langganan.

Membuat langganan tanpa menetapkan pemilik menjadikannya langganan mandiri. Untuk memberikan pengembang dan anggota tim Anda lainnya akses ke kunci langganan mandiri, juga:

• Bagikan kunci langganan secara manual.
• Gunakan sistem kustom untuk membuat kunci langganan tersedia untuk tim Anda.

Catatan

Anda tidak dapat secara langsung menetapkan langganan di API Management ke grup keamanan ID Microsoft Entra. Untuk menyediakan akses langganan ke beberapa pengguna dalam grup, buat langganan mandiri dan distribusikan kunci langganan ke anggota grup, atau integrasikan dengan ID Microsoft Entra untuk autentikasi dan gunakan kebijakan untuk mengontrol akses API berdasarkan keanggotaan grup.

Membuat dan mengelola langganan di portal Azure

Penerbit API (administrator atau pengembang dengan izin yang sesuai) dapat membuat langganan langsung di portal Microsoft Azure dengan masuk ke instans API Management mereka. Konsumen API tidak dapat membuat langganan melalui portal Microsoft Azure; mereka biasanya meminta langganan melalui portal pengembang atau menerimanya dari penerbit API.

Saat Anda membuat langganan di portal, langganan berada dalam status Aktif , yang berarti pelanggan dapat memanggil API terkait dengan menggunakan kunci langganan yang valid. Anda dapat mengubah status langganan sesuai kebutuhan. Misalnya, Anda dapat menangguhkan, membatalkan, atau menghapus langganan apa pun (termasuk langganan semua akses bawaan) untuk mencegah akses API.

Menggunakan kunci langganan

Pelanggan dapat menggunakan kunci langganan API Management dengan dua cara:

• Tambahkan header HTTP Ocp-Apim-Subscription-Key ke permintaan, meneruskan nilai kunci langganan yang valid.
• Sertakan parameter kueri kunci langganan dan nilai yang valid di URL. Parameter kueri dicentang hanya jika header tidak ada.

Petunjuk

Ocp-Apim-Subscription-Key adalah nama default header kunci langganan, dan subscription-key adalah nama default parameter kueri. Jika diinginkan, Anda dapat memodifikasi nama-nama ini di pengaturan untuk setiap API. Misalnya, di portal, perbarui nama-nama ini pada tab Pengaturan api.

Catatan

Ketika disertakan dalam header permintaan atau parameter kueri, kunci langganan secara default diteruskan ke backend dan mungkin diekspos dalam log pemantauan backend atau sistem lainnya. Jika data ini sensitif, Anda dapat mengonfigurasi kebijakan di akhir inbound bagian untuk menghapus header kunci langganan (set-header) atau parameter kueri (set-query-parameter).

Mengaktifkan atau menonaktifkan persyaratan langganan untuk API atau akses produk

Secara default saat Anda membuat API, kunci langganan diperlukan untuk akses API. Demikian pula, ketika Anda membuat produk, secara default kunci langganan diperlukan untuk mengakses API apa pun yang Anda tambahkan ke produk. Dalam skenario tertentu, penerbit API mungkin ingin menerbitkan produk atau API tertentu ke publik tanpa persyaratan langganan. Meskipun penerbit dapat memilih untuk mengaktifkan akses yang tidak aman (anonim) ke API tertentu, mengonfigurasi mekanisme lain untuk mengamankan akses klien disarankan.

Perhatian

Berhati-hatilah saat mengonfigurasi produk atau API yang tidak memerlukan langganan. Konfigurasi ini mungkin terlalu permisif dan dapat membuat API lebih rentan terhadap ancaman keamanan API tertentu.

Catatan

Produk terbuka memiliki pengaturan Memerlukan langganan yang dinonaktifkan, yang berarti bahwa pengguna tidak perlu berlangganan mereka. Untuk alasan ini, produk terbuka tidak muncul di halaman Produk portal pengembang.

Anda dapat menonaktifkan persyaratan langganan saat membuat API atau produk, atau yang lebih baru.

Untuk menonaktifkan persyaratan langganan dengan menggunakan portal:

• Nonaktifkan persyaratan untuk produk - Pada halaman Pengaturan produk, nonaktifkan Memerlukan langganan.
• Nonaktifkan persyaratan untuk API - Di halaman Pengaturan API, nonaktifkan Langganan yang diperlukan.

Setelah persyaratan langganan dinonaktifkan, API atau API yang dipilih dapat diakses tanpa kunci langganan.

Cara API Management menangani permintaan dengan atau tanpa kunci langganan

Permintaan API dengan kunci langganan

Saat API Management menerima permintaan API dari klien dengan kunci langganan, API akan menangani permintaan sesuai dengan aturan ini:

1. Ini memeriksa apakah kunci valid dan terkait dengan langganan aktif, yang didefinisikan sebagai:

   • Langganan yang dibatasi ke API.
   • Langganan yang berkaitan dengan produk yang diassign ke API.
   • Langganan yang mencakup semua API.
   • Langganan dengan lingkup layanan (terintegrasi dalam semua langganan akses).

   Jika kunci valid untuk langganan aktif pada cakupan yang sesuai, API Management akan memberikan akses. Ini menerapkan kebijakan tergantung pada konfigurasi definisi kebijakan pada cakupan tersebut.

2. Jika kunci tidak valid tetapi ada produk yang menyertakan API tanpa memerlukan langganan (produk terbuka ), API Management mengabaikan kunci dan menangani permintaan sebagai permintaan API tanpa kunci langganan (lihat bagian berikut).

3. Jika tidak, API Management menolak akses (401 kesalahan akses ditolak).

Permintaan API tanpa kunci langganan

Saat API Management menerima permintaan API dari klien tanpa kunci langganan, API akan menangani permintaan sesuai dengan aturan ini:

1. Ini memeriksa keberadaan produk yang menyertakan API tetapi tidak memerlukan langganan (produk terbuka ). Jika ada produk terbuka, API Management menangani permintaan dalam konteks API, kebijakan, dan aturan akses yang dikonfigurasi untuk produk terbuka. API dapat dikaitkan dengan paling banyak satu produk terbuka.
2. Jika produk terbuka termasuk API tidak ditemukan, API Management memeriksa apakah API memerlukan langganan. Jika langganan tidak diperlukan, API Management menangani permintaan dalam konteks API dan operasi tersebut.
3. Jika tidak ada produk atau API yang dikonfigurasi yang ditemukan, API Management menolak akses (kesalahan Akses 401 ditolak).

Tabel ringkasan

Tabel berikut ini meringkas cara gateway menangani permintaan API dengan atau tanpa kunci langganan dalam skenario yang berbeda. Tabel mencatat konfigurasi yang berpotensi mengaktifkan akses API anonim yang tidak diinginkan.

Semua produk yang ditetapkan ke API memerlukan langganan	API memerlukan langganan	Panggilan API dengan kunci langganan	Panggilan API tanpa kunci langganan	Skenario khusus
✔️	✔️	Akses diperbolehkan: Kunci khusus produk • Kunci cakupan API • Kunci yang tercakup untuk semua API • Kunci cakupan layanan Akses ditolak: • Kunci lain yang tidak dicakup oleh produk atau API yang berlaku	Akses ditolak	Akses API yang dilindungi menggunakan langganan berdasarkan produk atau berdasarkan API
✔️	❌	Akses diperbolehkan: Kunci khusus produk • Kunci cakupan API • Kunci yang tercakup untuk semua API • Kunci cakupan layanan • Kunci lain yang tidak dicakup oleh produk atau API yang berlaku	Akses diizinkan (konteks API)	• Akses API yang aman dengan langganan yang berskala produk • Akses anonim ke API. Jika akses anonim tidak dimaksudkan, konfigurasikan kebijakan tingkat API untuk menerapkan autentikasi dan otorisasi.
❌ 1	✔️	Akses diperbolehkan: Kunci khusus produk • Kunci cakupan API • Kunci yang tercakup untuk semua API • Kunci cakupan layanan Akses ditolak: • Kunci lain yang tidak dicakup oleh produk atau API yang berlaku	Akses diizinkan (konteks produk terbuka)	• Akses API yang dilindungi dengan langganan dengan cakupan API • Akses anonim ke API. Jika akses anonim tidak dimaksudkan, konfigurasikan dengan kebijakan produk untuk menerapkan autentikasi dan otorisasi
❌ 1	❌	Akses diperbolehkan: Kunci khusus produk • Kunci cakupan API • Kunci yang tercakup untuk semua API • Kunci cakupan layanan • Kunci lain yang tidak dicakup oleh produk atau API yang berlaku	Akses diizinkan (konteks produk terbuka)	Akses anonim ke API. Jika akses anonim tidak dimaksudkan, konfigurasikan dengan kebijakan produk untuk menerapkan autentikasi dan otorisasi

¹ Ada produk terbuka yang terkait dengan API.

Pertimbangan

• Akses API dalam konteks produk sama, baik produk diterbitkan atau tidak. Membatalkan penerbitan produk menyembunyikannya dari portal pengembang, tetapi tidak membatalkan kunci langganan baru atau yang sudah ada.
• Jika API tidak memerlukan autentikasi langganan, permintaan API apa pun yang menyertakan kunci langganan diperlakukan sama dengan permintaan tanpa kunci langganan. Kunci langganan diabaikan.
• "Konteks" akses API berarti kebijakan dan kontrol akses yang diterapkan pada cakupan tertentu (misalnya, API atau produk).

Konten terkait

Dapatkan informasi lebih lanjut tentang API Management:

• Pelajari bagaimana kebijakan API Management diterapkan pada cakupan yang berbeda.
• Pelajari konsep lain dalam API Management.
• Ikuti tutorial kami untuk mempelajari lebih lanjut tentang API Management.
• Lihat halaman FAQ kami untuk pertanyaan umum.