Kebijakan VerifyAPIKey

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

ikon kebijakan

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 adalah Kebijakan yang dapat diperluas dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau penggunaan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaannya, lihat Jenis kebijakan.

Untuk melihat tutorial yang menunjukkan cara membuat proxy API yang menggunakan kebijakan Verify API Key, lihat Mengamankan API dengan mewajibkan kunci API.

Sampel

Kunci di 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 dapat merujuk ke variabel apa pun yang berisi kunci. Kebijakan dalam contoh ini mengekstrak kunci API dari variabel bernama requestAPIKey.key.

Cara pengisian variabel tersebut terserah Anda. Misalnya, Anda dapat menggunakan kebijakan Extract Variables untuk mengisi requestAPIKey.key dari parameter kueri bernama myKey, seperti yang ditunjukkan di bawah:

<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 otomatis mengisi serangkaian variabel alur saat menjalankan kebijakan Verifikasi Kunci API 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. Dalam contoh di atas, Anda menggunakan kebijakan Assign Message untuk mengakses nama depan, nama belakang, dan alamat email developer setelah Verify API Key dieksekusi.

Semua variabel ini diawali dengan:

verifyapikey.{policy_name}

Dalam contoh ini, nama kebijakan Verify API key adalah "verify-api-key". Oleh karena itu, Anda mereferensikan nama depan developer yang membuat permintaan dengan mengakses variabel verifyapikey.verify-api-key.developer.firstName.

Mempelajari Apigee

Tentang kebijakan Verify API Key

Saat developer mendaftarkan aplikasi di Apigee, Apigee akan otomatis membuat pasangan kunci konsumen dan rahasia. 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, dengan produk API adalah kumpulan resource yang dapat diakses melalui proxy API. Kemudian, developer meneruskan kunci API (kunci konsumen) sebagai bagian dari setiap permintaan ke API dalam 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 beranda OAuth untuk mengetahui informasi selengkapnya.

Apigee otomatis mengisi serangkaian 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 umum untuk semua elemen induk kebijakan:

Atribut Deskripsi Default Kehadiran
name

Nama internal kebijakan. Nilai atribut name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter.

Secara opsional, gunakan elemen <DisplayName> untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.

 T/A Wajib
continueOnError

Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Perilaku ini wajar terjadi untuk sebagian besar kebijakan.

Tetapkan ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal. Lihat juga:

 false Opsional
enabled

Tetapkan ke true untuk menerapkan kebijakan.

Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur.

 benar Opsional
async

Atribut ini tidak digunakan lagi.

 false Tidak digunakan lagi

Elemen <DisplayName>

Gunakan selain atribut name untuk melabeli kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.

<DisplayName>Policy Display Name</DisplayName>
Default

T/A

Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan digunakan.
Kehadiran Opsional
Jenis String

Elemen <APIKey>

Elemen ini menentukan variabel alur yang berisi kunci API. Biasanya, klien mengirimkan kunci API dalam parameter kueri, header HTTP, atau parameter formulir. Misalnya, jika kunci dikirim di header yang disebut x-apikey, kunci akan ditemukan dalam variabel: request.header.x-apikey

Default NA
Kehadiran Wajib
Jenis String

Atribut

Tabel berikut menjelaskan atribut elemen <APIKey>

Atribut Deskripsi Default Kehadiran
ref

Referensi ke variabel yang berisi kunci API. Hanya satu lokasi yang diizinkan per kebijakan.

 T/A Wajib

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 masa berlaku token akses yang di-cache. Rentang yang didukung adalah antara 1 dan 180 detik. Anda dapat memberikan variabel alur dan variabel default. Jika diberikan, nilai variabel alur akan lebih diprioritaskan daripada nilai default yang ditentukan. 

<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>
Default T/A

Jika Anda menghilangkan elemen ini, periode habis masa berlaku default untuk token akses yang di-cache adalah 180 detik.
Kehadiran Opsional
Jenis Bilangan bulat
Nilai valid Bilangan bulat positif bukan nol. Menentukan waktu habis masa berlaku dalam detik.

Atribut

Tabel berikut menjelaskan atribut elemen <CacheExpiryInSeconds>

Atribut Deskripsi Default Kehadiran
ref

Referensi ke variabel alur yang berisi nilai untuk masa berlaku cache, yang dinyatakan dalam detik.

Jika diberikan, nilai variabel alur akan lebih diprioritaskan daripada nilai default yang ditentukan.

 T/A Opsional

Skema

Variabel alur

Jika kebijakan Verifikasi Kunci API diterapkan pada kunci API yang valid, Apigee akan mengisi serangkaian variabel alur. Variabel ini tersedia untuk kebijakan atau kode yang dieksekusi nanti dalam alur, dan sering digunakan untuk melakukan pemrosesan kustom berdasarkan atribut kunci API seperti nama aplikasi, produk API yang digunakan untuk mengotorisasi kunci, atau atribut kustom kunci API.

Kebijakan ini mengisi beberapa jenis variabel alur yang berbeda, termasuk:

  • Umum
  • Aplikasi
  • Developer
  • Analytics
  • Monetisasi

Setiap jenis variabel alur 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 Verifikasi Kunci 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 URI pengalihan apa pun dalam permintaan.
developer.app.id

ID developer atau AppGroup aplikasi yang membuat permintaan.
developer.app.name Nama aplikasi developer atau AppGroup aplikasi 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 Disetel ke "true" jika validasi Kunci API gagal.
{custom_app_attrib} Atribut kustom apa pun yang berasal dari profil aplikasi. Tentukan nama atribut kustom.
apiproduct.name* Nama produk API yang digunakan untuk memvalidasi permintaan.
apiproduct.{custom_attrib_name}* Atribut kustom 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 mengetahui 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 yang berisi daftar produk API yang terkait dengan aplikasi.
appFamily Setiap keluarga 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 diperbarui.
last_modified_by Alamat email developer yang terakhir kali memperbarui aplikasi.
{app_custom_attributes} Atribut aplikasi kustom apa pun. Tentukan nama atribut kustom.

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 mengubah AppGroup.
{appgroup_custom_attributes} Atribut AppGroup khusus apa pun. Tentukan nama atribut kustom.

Variabel alur developer

Variabel alur berikut yang berisi informasi tentang developer 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 kustom.

Variabel Analytics

Variabel berikut diisi secara otomatis di Analytics saat kebijakan Verifikasi Kunci API diterapkan untuk kunci API yang valid. Variabel ini hanya diisi oleh kebijakan Verify API Key dan kebijakan OAuth.

Variabel dan nilai dapat digunakan sebagai dimensi untuk membuat laporan Analytics guna mendapatkan visibilitas ke dalam pola penggunaan oleh developer dan aplikasi.

  • apiproduct.name
  • developer.app.name
  • client_id
  • developer.id

Variabel alur monetisasi

Setelah mengautentikasi pengguna, kebijakan VerifyAPIKey akan memeriksa semua paket tarif yang dipublikasikan untuk menentukan paket tarif mana yang aktif, jika ada, berdasarkan waktu aktivasi dan waktu berakhirnya. Jika paket tarif yang dipublikasikan dan aktif ditemukan, variabel alur berikut akan diisi:

Variabel Deskripsi
mint.mintng_is_apiproduct_monetized true jika paket tarif yang dipublikasikan dan aktif 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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause
keymanagement.service.consumer_key_missing_api_product_association 400

The application credential is missing an API product association. Please associate the key's application with an API product. Note that this applies for all application types, such as developer apps and AppGroup apps.
keymanagement.service.DeveloperStatusNotActive 401

The developer who created the Developer App that has the API key you are using has an inactive status. When an App Developer's status is set to inactive, any Developer Apps created by that developer are deactivated. An admin user with appropriate permissions (such as Organization Administrator) can change a developer's status in the following ways:
keymanagement.service.invalid_client-app_not_approved 401 The Developer App associated with the API key is revoked. A revoked app cannot access any API products and cannot invoke any API managed by Apigee. An org admin can change the status of a Developer App using the Apigee API. See Generate Key Pair or Update Developer App Status.
oauth.v2.FailedToResolveAPIKey 401 The policy expects to find the API key in a variable that is specified in the policy's <APIKey> element. This error arises when the expected variable does not exist (it cannot be resolved).
oauth.v2.InvalidApiKey 401 An API key was received by Apigee, but it is invalid. When Apigee looks up the key in its database, it must exactly match the one that was sent in the request. If the API worked previously, make sure the key was not regenerated. If the key was regenerated, you will see this error if you try to use the old key. For details, see Controlling access to your APIs by registering apps.
oauth.v2.InvalidApiKeyForGivenResource 401 An API key was received by Apigee, and it is valid; however, it does not match an approved key in the Developer App associated with your API proxy through a Product.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause
SpecifyValueOrRefApiKey The <APIKey> element does not have a value or key specified.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "FailedToResolveAPIKey"
oauthV2.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. oauthV2.VK-VerifyAPIKey.failed = true

Example error responses

{  
   "fault":{  
      "faultstring":"Invalid ApiKey",
      "detail":{  
         "errorcode":"oauth.v2.InvalidApiKey"
      }
   }
}
 
{  
   "fault":{  
      "detail":{  
         "errorcode":"keymanagement.service.DeveloperStatusNotActive"
      },
      "faultstring":"Developer Status is not Active"
   }
}

Example fault rule

<FaultRule name="FailedToResolveAPIKey">
    <Step>
        <Name>AM-FailedToResolveAPIKey</Name>
    </Step>
    <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition>
</FaultRule>