Kebijakan VerifyAPIKey

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

Apa

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.

Contoh

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 Edge 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 Edge 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>

Edge 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 Edge

Tentang kebijakan Verify API Key

Saat developer mendaftarkan aplikasi di Edge, Edge akan otomatis membuat pasangan kunci rahasia dan konsumen. Anda dapat melihat pasangan kunci konsumen dan rahasia aplikasi di UI Edge atau mengaksesnya dari Edge 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.

Edge 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"/>
</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	Ketersediaan
`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 kebijakan di editor proxy UI pengelolaan dengan nama natural language yang berbeda.	T/A	Wajib
`continueOnError`	Tetapkan ke `false` untuk menampilkan error saat kebijakan gagal. Diharapkan untuk sebagian besar kebijakan. Setel ke `true` agar eksekusi alur dapat dilanjutkan bahkan setelah kebijakan gagal.	salah	Opsional
`enabled`	Setel ke `true` untuk menerapkan kebijakan. Setel ke `false` untuk menonaktifkan kebijakan. Kebijakan ini tidak akan ditegakkan meskipun tetap terikat pada alur.	true	Opsional
`async`	Atribut ini tidak digunakan lagi.	salah	Tidak digunakan lagi

<DisplayName> elemen

Gunakan selain atribut name untuk memberi label kebijakan di editor proxy UI dengan nama natural language yang berbeda.

<DisplayName>Policy Display Name</DisplayName>

Default

Default	T/A Jika Anda menghapus elemen ini, nilai atribut `name` kebijakan akan menjadi data
Ketersediaan	Opsional
Jenis	String

T/A

Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan menjadi data

Ketersediaan 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
Ketersediaan	Wajib
Jenis	String

Atribut

Tabel berikut menjelaskan atribut elemen <APIKey>

Atribut	Deskripsi	Default	Ketersediaan
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>

Skema

Variabel alur

Jika kebijakan Verifikasi Kunci API diterapkan pada kunci API yang valid, Edge akan mengisi serangkaian variabel aliran. 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
Perusahaan
Analytics

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 aplikasi developer yang membuat permintaan. Catatan: Jangan gunakan variabel `developer.app.id` untuk tujuan berikut: ID untuk kebijakan Kuota Kunci Peta Nilai Kunci (KVM) ID yang dikirim ke target untuk digunakan dalam logika bisnis backend ID ini dibuat secara internal oleh Apigee dan tidak dijamin akan tetap sama dari waktu ke waktu. Misalnya, Apigee dapat mengubah format atau panjang variabel ini.
`developer.app.name`	Nama aplikasi dari aplikasi developer yang membuat permintaan.
`developer.id`	ID developer yang terdaftar sebagai pemilik aplikasi yang meminta. Catatan: Jangan gunakan variabel `developer.id` untuk tujuan berikut: ID Kuota Kunci KVM ID yang dikirim ke target untuk digunakan dalam logika bisnis backend ID ini dibuat secara internal oleh Apigee dan tidak dijamin akan tetap sama dari waktu ke waktu. Misalnya, Apigee dapat mengubah format atau panjang variabel ini.
`developer.{custom_attrib_name}`	Atribut khusus apa pun yang berasal dari profil kunci aplikasi
`DisplayName`	Nilai atribut <DisplayName> kebijakan.
`failed`	Ditetapkan ke "true" jika validasi Kunci API gagal.
`{custom_app_attrib}`	Atribut kustom apa pun yang berasal dari profil aplikasi. Tentukan nama atribut kustom. Catatan: Jika atribut kustom Aplikasi dan atribut kustom Kunci aplikasi memiliki nama yang sama, maka atribut kustom Kunci aplikasi akan diprioritaskan.
`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 Menggunakan Edge Management API untuk Memublikasikan 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 "Perusahaan" atau "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 developer

Variabel alur berikut yang berisi informasi tentang developer diisi oleh kebijakan. Semua variabel ini diawali dengan:

verifyapikey.{policy_name}.developer

Catatan: Jika variabel alur verifyapikey.{policy_name}.app.appType adalah "Developer", maka atribut developer akan diisi. Jika app.appType adalah "Perusahaan", maka atribut perusahaan akan diisi.

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.
`Company`	Nama perusahaan, jika ada, yang terkait dengan developer.

Variabel alur perusahaan

Variabel alur berikut yang berisi informasi tentang perusahaan diisi oleh kebijakan. Semua variabel ini diawali dengan:

verifyapikey.{policy_name}.company

Catatan: Jika verifyapikey.{policy_name}.app.appType adalah "Perusahaan", maka atribut perusahaan akan diisi. Jika app.appType adalah "Developer", maka atribut developer akan diisi.

Contoh:

verifyapikey.{policy_name}.company.name

Variabel yang tersedia meliputi:

Variabel	Deskripsi
`name`	Nama perusahaan.
`displayName`	Nama tampilan perusahaan.
`id`	ID perusahaan. Catatan: Jangan gunakan variabel `company.id` untuk tujuan berikut: ID Kuota Kunci KVM ID yang dikirim ke target untuk digunakan dalam logika bisnis backend ID ini dibuat secara internal oleh Apigee dan tidak dijamin akan tetap sama dari waktu ke waktu. Misalnya, Apigee dapat mengubah format atau panjang variabel ini.
`apps`	Array yang berisi daftar aplikasi perusahaan.
`appOwnerStatus`	Status pemilik aplikasi, sebagai aktif, tidak aktif, atau login_lock.
`created_at`	Stempel tanggal/waktu saat perusahaan dibuat.
`created_by`	Alamat email pengguna yang membuat perusahaan.
`last_modified_at`	Stempel tanggal/waktu saat perusahaan terakhir diubah.
`last_modified_by`	Alamat email pengguna yang terakhir mengubah perusahaan.
`{company_custom_attributes}`	Atribut perusahaan 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

Referensi error

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.CompanyStatusNotActive`	401	The Company associated with the Developer App that has the API key you are using has an inactive status. When a Company's status is set to inactive, you cannot access the developers or apps associated with that Company. An org admin can change a Company's status using the management API. See Set the Status of a Company.
`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: Management API: Set Developer Status Management UI: In Register app developers, see the instructions for deactivating (and activating) a developer.
`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 Edge. An org admin can change the status of a Developer App using the management API. See Approve or Revoke Developer App.
`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 Edge, but it is invalid. When Edge looks up the key in its database, it must exactly match the on 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 Register apps and manage API keys.
`oauth.v2.InvalidApiKeyForGivenResource`	401	An API key was received by Edge, and it is valid; however, it does not match an approved key in the Developer App associated with your API proxy through a Product.

Note: Currently Edge does not report the ApiKeyNotApproved error accurately. Instead, if a key is not approved (its status is set to "revoked" or "pending"), you will get the FailedToResolveAPIKey error instead. For more information and a possible workaround, see this post on the Apigee Community.

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

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{
   "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>

Kebijakan VerifyAPIKey

Apa

Contoh

Kunci di parameter kueri

Kunci di header

Kunci dalam variabel

Variabel alur kebijakan akses

Mempelajari Edge

Tentang kebijakan Verify API Key

Referensi Elemen

Atribut <VerifyAPIKey>

&lt;DisplayName&gt; elemen

Elemen <APIKey>

Atribut

Contoh

Skema

Variabel alur

Variabel alur umum

Variabel alur aplikasi

Variabel alur developer

Variabel alur perusahaan

Variabel Analytics

Referensi error

Runtime errors

Deployment errors

Fault variables

Example error responses

Example fault rule

Topik terkait

<DisplayName> elemen