Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Baca dokumentasi Apigee Edge.
Ringkasan
Kebijakan Verifikasi Kunci API memungkinkan Anda menerapkan verifikasi kunci API saat runtime, sehingga hanya aplikasi dengan kunci API yang disetujui yang dapat mengakses API Anda. Kebijakan ini memastikan bahwa kunci API valid, belum dicabut, dan disetujui untuk menggunakan resource tertentu yang terkait dengan produk API Anda.
Kebijakan ini merupakan Kebijakan yang dapat diperluas, dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau pemanfaatan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaan, lihat Jenis kebijakan.
Untuk tutorial yang menunjukkan cara membangun proxy API yang menggunakan kebijakan Verifikasi Kunci API, lihat Mengamankan API dengan mewajibkan kunci API.
Sampel
Kunci dalam parameter kueri
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.queryparam.apikey" /> </VerifyAPIKey>
Dalam contoh ini, kebijakan mengharapkan untuk menemukan kunci API dalam variabel alur yang disebut
request.queryparam.apikey
. Variabel request.queryparam.{name}
adalah variabel alur Apigee standar yang diisi dengan nilai parameter kueri yang diteruskan dalam permintaan klien.
Perintah curl
berikut meneruskan kunci API dalam parameter kueri:
curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls
Kunci di header
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.header.x-apikey" /> </VerifyAPIKey>
Dalam contoh ini, kebijakan mengharapkan untuk menemukan kunci API dalam variabel alur yang disebut
request.header.x-apikey
. Variabel request.header.{name}
adalah variabel alur Apigee standar yang diisi dengan nilai header yang diteruskan dalam permintaan klien.
cURL berikut menunjukkan cara meneruskan kunci API di header:
curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"
Kunci dalam variabel
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="requestAPIKey.key"/> </VerifyAPIKey>
Kebijakan ini dapat mereferensikan variabel apa pun yang berisi kunci. Kebijakan dalam contoh ini mengekstrak kunci API dari variabel bernama requestAPIKey.key.
Anda dapat menentukan cara pengisian variabel tersebut. Misalnya, Anda dapat menggunakan kebijakan Ekstrak Variabel untuk mengisi requestAPIKey.key dari parameter kueri yang bernama myKey, seperti yang ditampilkan di bawah ini:
<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar"> <Source>request</Source> <QueryParam name="myKey"> <Pattern ignoreCase="true">{key}</Pattern> </QueryParam> <VariablePrefix>requestAPIKey</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
Variabel alur kebijakan akses
<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars"> <AssignVariable> <Name>devFirstName</Name> <Ref>verifyapikey.verify-api-key.developer.firstName</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>devLastName</Name> <Ref>verifyapikey.verify-api-key.developer.lastName</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>devEmail</Name> <Ref>verifyapikey.verify-api-key.developer.email</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
Apigee akan otomatis mengisi kumpulan variabel alur saat menjalankan kebijakan Verify API Key untuk kunci API yang valid. Anda dapat menggunakan variabel ini untuk mengakses informasi seperti nama aplikasi, ID aplikasi, dan informasi tentang developer atau perusahaan yang mendaftarkan aplikasi. Pada contoh di atas, Anda menggunakan kebijakan Tetapkan Pesan untuk mengakses nama depan, nama belakang, dan alamat email developer setelah Kunci Verify API dieksekusi.
Semua variabel ini diawali dengan:
verifyapikey.{policy_name}
Dalam contoh ini, nama kebijakan kunci Verify API adalah "verify-api-key". Oleh karena itu, Anda mereferensikan
nama depan developer yang membuat permintaan dengan mengakses
variabel verifyapikey.verify-api-key.developer.firstName.
Pelajari Apigee
Tentang kebijakan Verify API Key
Saat developer mendaftarkan aplikasi di Apigee, Apigee secara otomatis menghasilkan pasangan kunci dan rahasia konsumen. Anda dapat melihat pasangan kunci dan rahasia konsumen aplikasi di UI Apigee atau mengaksesnya dari Apigee API.
Pada saat pendaftaran aplikasi, developer memilih satu atau beberapa produk API untuk dikaitkan dengan aplikasi, di mana produk API merupakan kumpulan resource yang dapat diakses melalui proxy API. Kemudian, developer akan meneruskan kunci API (kunci konsumen) sebagai bagian dari setiap permintaan ke API di produk API yang terkait dengan aplikasi. Lihat Ringkasan publikasi untuk mengetahui informasi selengkapnya.
Kunci API dapat digunakan sebagai token autentikasi, atau dapat digunakan untuk mendapatkan token akses OAuth. Di OAuth, kunci API disebut sebagai "client id". Nama-nama tersebut dapat digunakan secara bergantian. Lihat rumah OAuth untuk informasi selengkapnya.
Apigee akan otomatis mengisi kumpulan variabel alur saat menjalankan kebijakan Verify API Key. Lihat Variabel alur di bawah untuk mengetahui informasi selengkapnya.
Referensi Elemen
Berikut adalah elemen dan atribut yang dapat Anda konfigurasi pada kebijakan ini:
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1"> <DisplayName>Custom label used in UI</DisplayName> <APIKey ref="variable_containing_api_key"/> <CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Default value</CacheExpiryInSeconds/> </VerifyAPIKey>
Atribut <VerifyAPIKey>
Contoh berikut menunjukkan atribut pada tag <VerifyAPIKey>
:
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
Tabel berikut menjelaskan atribut yang sama untuk semua elemen induk kebijakan:
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
name |
Nama internal kebijakan. Nilai atribut Atau, gunakan elemen |
T/A | Diperlukan |
continueOnError |
Setel ke Setel ke |
false | Opsional |
enabled |
Setel ke Setel ke |
true | Opsional |
async |
Atribut ini sudah tidak digunakan lagi. |
false | Tidak digunakan lagi |
Elemen <DisplayName>
Gunakan selain atribut name
untuk memberi label kebijakan di
editor proxy UI pengelolaan dengan nama natural-language yang berbeda.
<DisplayName>Policy Display Name</DisplayName>
Default |
T/A Jika Anda menghapus elemen ini, nilai atribut |
---|---|
Kehadiran | Opsional |
Jenis | String |
Elemen <APIKey>
Elemen ini menetapkan variabel flow yang berisi kunci API. Biasanya, klien mengirimkan kunci API dalam parameter kueri, header HTTP, atau parameter formulir. Misalnya, jika kunci dikirim dalam header
yang disebut x-apikey
, kunci tersebut akan ditemukan dalam variabel: request.header.x-apikey
Default | NA |
---|---|
Kehadiran | Diperlukan |
Jenis | String |
Atribut
Tabel berikut menjelaskan atribut elemen <APIKey>
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
referensi |
Referensi ke variabel yang berisi kunci API. Hanya satu lokasi yang diizinkan per kebijakan. |
T/A | Diperlukan |
Contoh
Dalam contoh ini, kunci diteruskan dalam parameter dan header yang disebut x-apikey
.
Sebagai parameter kueri:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.queryparam.x-apikey"/> </VerifyAPIKey>
Sebagai header HTTP:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.header.x-apikey"/> </VerifyAPIKey>
Sebagai parameter formulir HTTP:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.formparam.x-apikey"/> </VerifyAPIKey>
Elemen <CacheExpiryInSeconds>
Elemen ini menerapkan TTL pada cache, yang memungkinkan penyesuaian jangka waktu untuk akhir masa berlaku token akses yang di-cache. Rentang yang didukung adalah antara 1 dan 180 detik. Anda dapat menyediakan variabel alur dan variabel default. Jika diberikan, nilai variabel flow akan lebih diprioritaskan daripada nilai default yang ditentukan.
<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>
Default | T/A
Jika Anda menghapus elemen ini, periode habis masa berlaku default untuk token akses yang di-cache adalah 180 detik. |
---|---|
Kehadiran | Opsional |
Jenis | Bilangan bulat |
Nilai valid | Semua bilangan bulat positif bukan nol. Menentukan waktu habis masa berlaku dalam detik. |
Atribut
Tabel berikut menjelaskan atribut elemen <CacheExpiryInSeconds>
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
referensi |
Referensi ke variabel flow yang berisi nilai masa berlaku cache, yang dinyatakan dalam detik. Jika diberikan, nilai variabel flow akan lebih diprioritaskan daripada nilai default yang ditentukan. |
T/A | Opsional |
Skema
Variabel alur
Saat kebijakan Verifikasi Kunci API diterapkan pada kunci API yang valid, Apigee akan mengisi kumpulan variabel alur. Variabel ini tersedia untuk kebijakan atau kode yang dijalankan nanti dalam alur, dan sering digunakan untuk melakukan pemrosesan kustom berdasarkan atribut kunci API seperti nama aplikasi, produk API yang digunakan untuk mengizinkan kunci, atau atribut khusus kunci API.
Kebijakan ini mengisi beberapa jenis variabel alur, termasuk:
- Umum
- Aplikasi
- Developer
- Analisis
- Monetisasi
Setiap jenis variabel flow memiliki awalan yang berbeda. Semua variabel adalah skalar kecuali yang secara khusus ditunjukkan sebagai array.
Variabel alur umum
Tabel berikut mencantumkan variabel alur umum yang diisi oleh kebijakan Kunci Verify API. Semua variabel ini diawali dengan:
verifyapikey.{policy_name}
Contoh: verifyapikey.{policy_name}.client_id
Variabel yang tersedia meliputi:
Variabel | Deskripsi |
---|---|
client_id |
Kunci konsumen (alias kunci API atau kunci aplikasi) yang disediakan oleh aplikasi yang meminta. |
client_secret |
Rahasia konsumen yang terkait dengan kunci konsumen. |
redirection_uris |
Semua URI pengalihan dalam permintaan. |
developer.app.id |
ID developer atau aplikasi AppGroup yang membuat permintaan. |
developer.app.name |
Nama aplikasi developer atau aplikasi AppGroup yang membuat permintaan. |
developer.id |
ID developer atau AppGroup yang terdaftar sebagai pemilik aplikasi yang meminta. |
developer.{custom_attrib_name} |
Atribut kustom apa pun yang berasal dari profil kunci aplikasi. |
DisplayName |
Nilai atribut <DisplayName> kebijakan. |
failed |
Tetapkan ke "true" jika validasi Kunci API gagal. |
{custom_app_attrib} |
Atribut khusus apa pun yang berasal dari profil aplikasi. Tentukan nama atribut khusus. |
apiproduct.name* |
Nama produk API yang digunakan untuk memvalidasi permintaan. |
apiproduct.{custom_attrib_name}* |
Atribut khusus apa pun yang berasal dari profil produk API. |
apiproduct.developer.quota.limit* |
Batas kuota yang ditetapkan pada produk API, jika ada. |
apiproduct.developer.quota.interval* |
Interval kuota yang ditetapkan pada produk API, jika ada. |
apiproduct.developer.quota.timeunit* |
Unit waktu kuota yang ditetapkan pada produk API, jika ada. |
* Variabel produk API diisi secara otomatis jika produk API dikonfigurasi dengan lingkungan, proxy, dan resource yang valid (berasal dari proxy.pathsuffix ). Untuk mendapatkan petunjuk tentang cara menyiapkan produk API, lihat
Mengelola produk API. |
Variabel alur aplikasi
Variabel alur berikut yang berisi informasi tentang aplikasi diisi oleh kebijakan. Semua variabel ini diawali dengan:
verifyapikey.{policy_name}.app
.
Contoh:
verifyapikey.{policy_name}.app.name
Variabel yang tersedia meliputi:
Variabel | Deskripsi |
---|---|
name |
Nama aplikasi. |
id |
ID aplikasi. |
accessType |
Tidak digunakan oleh Apigee. |
callbackUrl |
URL callback aplikasi. Biasanya hanya digunakan untuk OAuth. |
DisplayName |
Nama tampilan aplikasi. |
status |
Status aplikasi, seperti 'disetujui' atau 'dicabut'. |
apiproducts |
Array berisi daftar produk API yang terkait dengan aplikasi. |
appFamily |
Semua kelompok aplikasi yang berisi aplikasi, atau "default". |
appParentStatus |
Status induk aplikasi, seperti 'aktif' atau 'tidak aktif' |
appType |
Jenis aplikasi sebagai "Developer". |
appParentId |
ID aplikasi induk. |
created_at |
Stempel tanggal/waktu saat aplikasi dibuat. |
created_by |
Alamat email developer yang membuat aplikasi. |
last_modified_at |
Stempel tanggal/waktu saat aplikasi terakhir diupdate. |
last_modified_by |
Alamat email developer yang terakhir kali mengupdate aplikasi. |
{app_custom_attributes} |
Atribut aplikasi kustom apa pun. Tentukan nama atribut khusus. |
Variabel alur AppGroup
Variabel alur berikut yang berisi informasi tentang
AppGroups
diisi oleh kebijakan. Atribut AppGroup ini hanya diisi jika
verifyapikey.{policy_name}.app.appType
adalah "AppGroup".
Semua variabel ini diawali dengan:
verifyapikey.{policy_name}.appgroup
.
Contoh:
verifyapikey.{policy_name}.appgroup.name
Variabel yang tersedia meliputi:
Variabel | Deskripsi |
---|---|
name |
Nama AppGroup. |
id |
ID AppGroup. |
displayName |
Nama tampilan AppGroup. |
appOwnerStatus |
Status pemilik aplikasi: 'active', 'inactive', atau 'login_lock'. |
created_at |
Stempel tanggal/waktu saat AppGroup dibuat. |
created_by |
Alamat email developer yang membuat AppGroup. |
last_modified_at |
Stempel tanggal/waktu saat AppGroup terakhir diubah. |
last_modified_by |
Alamat email developer yang terakhir kali mengubah AppGroup. |
{appgroup_custom_attributes} |
Atribut AppGroup kustom apa pun. Tentukan nama atribut khusus. |
Variabel alur developer
Variabel alur berikut yang berisi informasi tentang developer akan diisi oleh kebijakan. Semua variabel ini diawali dengan:
verifyapikey.{policy_name}.developer
Contoh:
verifyapikey.{policy_name}.developer.id
Variabel yang tersedia meliputi:
Variabel | Deskripsi |
---|---|
id |
Menampilkan {org_name}@@@{developer_id} |
userName |
Nama pengguna developer. |
firstName |
Nama depan developer. |
lastName |
Nama belakang developer. |
email |
Alamat email developer. |
status |
Status developer, sebagai aktif, tidak aktif, atau login_lock. |
apps |
Array aplikasi yang terkait dengan developer. |
created_at |
Stempel tanggal/waktu saat developer dibuat. |
created_by |
Alamat email pengguna yang membuat developer. |
last_modified_at |
Stempel tanggal/waktu saat developer terakhir diubah. |
last_modified_by |
Alamat email pengguna yang mengubah developer. |
{developer_custom_attributes} |
Atribut developer kustom apa pun. Tentukan nama atribut khusus. |
Variabel Analytics
Variabel berikut diisi secara otomatis di Analytics saat kebijakan Verify API Key diterapkan untuk kunci API yang valid. Variabel ini hanya diisi oleh kebijakan Kunci API Verifikasi dan kebijakan OAuth.
Variabel dan nilai dapat digunakan sebagai dimensi untuk membuat laporan Analytics guna mendapatkan visibilitas pola konsumsi oleh developer dan aplikasi.
apiproduct.name
developer.app.name
client_id
developer.id
Variabel alur monetisasi
Setelah mengautentikasi pengguna, kebijakan VerifyAPIKey memeriksa semua paket tarif yang dipublikasikan untuk menentukan, jika ada, mana yang aktif berdasarkan waktu aktivasi dan waktu habis masa berlakunya. Jika rencana tarif aktif yang dipublikasikan ditemukan, variabel alur berikut akan diisi:
Variabel | Deskripsi |
---|---|
mint.mintng_is_apiproduct_monetized |
true jika paket tarif aktif yang dipublikasikan ditemukan. |
mint.mintng_rate_plan_id |
ID paket tarif. |
mint.rateplan_end_time_ms |
Waktu habis masa berlaku untuk paket tarif. Contoh: 1619433556408 |
mint.rateplan_start_time_ms |
Waktu aktivasi paket tarif. Contoh: 1618433956209 |
Referensi error
Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan, serta variabel kesalahan yang disetel oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui apakah Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.
Error runtime
Error ini dapat terjadi saat kebijakan dijalankan.
Kode kesalahan | Status HTTP | Penyebab |
---|---|---|
keymanagement.service.consumer_key_missing_api_product_association |
400 |
Kredensial aplikasi tidak memiliki pengaitan produk API. Harap kaitkan penerapan kunci dengan produk API. Perhatikan bahwa ini berlaku untuk semua jenis aplikasi, seperti aplikasi developer dan aplikasi AppGroup. |
keymanagement.service.DeveloperStatusNotActive |
401 |
Developer yang membuat Aplikasi Developer yang memiliki kunci API yang Anda gunakan memiliki status tidak aktif. Jika status Developer Aplikasi disetel ke tidak aktif, semua Aplikasi Developer yang dibuat oleh developer tersebut akan dinonaktifkan. Pengguna admin dengan izin yang sesuai (seperti Administrator Organisasi) dapat mengubah status developer dengan cara berikut:
|
keymanagement.service.invalid_client-app_not_approved |
401 |
Aplikasi Developer yang terkait dengan kunci API dicabut. Aplikasi yang dicabut tidak dapat mengakses produk API apa pun dan tidak dapat memanggil API yang dikelola oleh Apigee. Admin org dapat mengubah status Aplikasi Developer menggunakan Apigee API. Lihat Membuat Pasangan Kunci atau Mengupdate Status Aplikasi Developer. |
oauth.v2.FailedToResolveAPIKey |
401 |
Kebijakan ini mengharapkan untuk menemukan kunci API dalam variabel yang ditentukan dalam elemen <APIKey> kebijakan. Error ini muncul jika variabel yang diharapkan tidak ada (tidak dapat diselesaikan). |
oauth.v2.InvalidApiKey |
401 |
Kunci API diterima oleh Apigee, tetapi tidak valid. Saat Apigee mencari kunci dalam database-nya, kunci tersebut harus sama persis dengan kunci yang dikirim dalam permintaan. Jika API sebelumnya berfungsi, pastikan kunci tidak dibuat ulang. Jika kunci dibuat ulang, Anda akan melihat error ini jika mencoba menggunakan kunci lama. Untuk mengetahui detailnya, lihat Mengontrol akses ke API dengan mendaftarkan aplikasi. |
oauth.v2.InvalidApiKeyForGivenResource |
401 |
Kunci API diterima oleh Apigee, dan kunci tersebut valid; tetapi, kunci tersebut tidak cocok dengan kunci yang disetujui di Aplikasi Developer yang terkait dengan proxy API Anda melalui Produk. |
Error saat deployment
Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.
Nama error | Penyebab |
---|---|
SpecifyValueOrRefApiKey |
Elemen <APIKey> belum memiliki nilai atau kunci yang ditentukan. |
Variabel kesalahan
Variabel ini ditetapkan saat terjadi error runtime. Untuk informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.
Variabel | Dari mana | Contoh |
---|---|---|
fault.name="fault_name" |
fault_name adalah nama kesalahan, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. | fault.name Matches "FailedToResolveAPIKey" |
oauthV2.policy_name.failed |
policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. | oauthV2.VK-VerifyAPIKey.failed = true |
Contoh respons error
{ "fault":{ "faultstring":"Invalid ApiKey", "detail":{ "errorcode":"oauth.v2.InvalidApiKey" } } }
{ "fault":{ "detail":{ "errorcode":"keymanagement.service.DeveloperStatusNotActive" }, "faultstring":"Developer Status is not Active" } }
Contoh aturan fault
<FaultRule name="FailedToResolveAPIKey"> <Step> <Name>AM-FailedToResolveAPIKey</Name> </Step> <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition> </FaultRule>