سیاست VerifyAPIKey

شما در حال مشاهده مستندات Apigee Edge هستید.
به مستندات Apigee X مراجعه کنید . اطلاعات

چه

سیاست تأیید کلید API به شما امکان می‌دهد تأیید کلیدهای API را در زمان اجرا اعمال کنید و فقط به برنامه‌هایی که کلیدهای API تأیید شده دارند، اجازه دسترسی به APIهای شما را بدهید. این سیاست تضمین می‌کند که کلیدهای API معتبر هستند، لغو نشده‌اند و برای مصرف منابع خاص مرتبط با محصولات API شما تأیید شده‌اند.

نمونه‌ها

پارامتر پرس و جو را وارد کنید 

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>

در این مثال، این سیاست انتظار دارد کلید API را در یک متغیر جریان به نام request.queryparam.apikey پیدا کند. متغیر request.queryparam.{name} یک متغیر جریان استاندارد Edge است که با مقدار پارامتر پرس‌وجو که در درخواست کلاینت ارسال شده است، پر می‌شود.

دستور curl زیر، کلید API را در یک پارامتر query ارسال می‌کند:

curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

کلید را در هدر وارد کنید 

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>

در این مثال، این سیاست انتظار دارد کلید API را در یک متغیر جریان به نام request.header.x-apikey پیدا کند. متغیر request.header.{name} یک متغیر جریان استاندارد Edge است که با مقدار هدر ارسال شده در درخواست کلاینت پر می‌شود.

cURL زیر نحوه ارسال کلید API را در یک هدر نشان می‌دهد:

curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"

متغیر را وارد کنید 

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>

این سیاست می‌تواند به هر متغیری که حاوی کلید است، ارجاع دهد. سیاست در این مثال، کلید API را از متغیری به نام requestAPIKey.key استخراج می‌کند.

نحوه‌ی پر کردن آن متغیر به خودتان بستگی دارد. برای مثال، می‌توانید از سیاست Extract Variables برای پر کردن requestAPIKey.key از یک پارامتر پرس‌وجو به نام myKey استفاده کنید، همانطور که در زیر نشان داده شده است:

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

متغیرهای جریان سیاست دسترسی 

<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 هنگام اجرای خط‌مشی Verify API Key برای یک کلید API معتبر، به‌طور خودکار مجموعه‌ای از متغیرهای جریان را پر می‌کند. شما می‌توانید از این متغیرها برای دسترسی به اطلاعاتی مانند نام برنامه، شناسه برنامه و اطلاعات مربوط به توسعه‌دهنده یا شرکتی که برنامه را ثبت کرده است، استفاده کنید. در مثال بالا، شما از خط‌مشی Assign Message برای دسترسی به نام، نام خانوادگی و آدرس ایمیل توسعه‌دهنده پس از اجرای Verify API Key استفاده می‌کنید.

این متغیرها همگی با پیشوند زیر شروع می‌شوند:

verifyapikey.{policy_name}

در این مثال، نام سیاست کلید تأیید API، « verify-api-key » است. بنابراین، شما با دسترسی به متغیر verifyapikey.verify-api-key.developer.firstName.

لبه را یاد بگیرید

درباره سیاست تأیید کلید API

وقتی یک توسعه‌دهنده برنامه‌ای را در Edge ثبت می‌کند، Edge به‌طور خودکار یک جفت کلید مصرف‌کننده و رمز عبور ایجاد می‌کند. می‌توانید جفت کلید مصرف‌کننده و رمز عبور برنامه را در رابط کاربری Edge مشاهده کنید یا از طریق Edge API به آنها دسترسی داشته باشید.

در زمان ثبت برنامه، توسعه‌دهنده یک یا چند محصول API را برای ارتباط با برنامه انتخاب می‌کند، که در آن یک محصول API مجموعه‌ای از منابع قابل دسترسی از طریق پروکسی‌های API است. سپس توسعه‌دهنده کلید API (کلید مصرف‌کننده) را به عنوان بخشی از هر درخواست به یک API در یک محصول API مرتبط با برنامه ارسال می‌کند. برای اطلاعات بیشتر به نمای کلی انتشار مراجعه کنید.

کلیدهای API می‌توانند به عنوان توکن‌های احراز هویت استفاده شوند، یا می‌توانند برای دریافت توکن‌های دسترسی OAuth مورد استفاده قرار گیرند. در OAuth، به کلیدهای API "شناسه کلاینت" گفته می‌شود. این نام‌ها را می‌توان به جای یکدیگر استفاده کرد. برای اطلاعات بیشتر به صفحه اصلی OAuth مراجعه کنید.

Edge هنگام اجرای خط‌مشی تأیید کلید API، به‌طور خودکار مجموعه‌ای از متغیرهای جریان را پر می‌کند. برای اطلاعات بیشتر به متغیرهای جریان در زیر مراجعه کنید.

مرجع عنصر

در زیر عناصر و ویژگی‌هایی که می‌توانید در این سیاست پیکربندی کنید، آمده است:

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

ویژگی‌های <VerifyAPIKey>

مثال زیر ویژگی‌های موجود در تگ <VerifyAPIKey> را نشان می‌دهد: 

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">

جدول زیر ویژگی هایی را توصیف می کند که برای همه عناصر اصلی خط مشی مشترک هستند:

صفت توضیحات پیش فرض حضور
name

نام داخلی سیاست. مقدار مشخصه name می تواند شامل حروف، اعداد، فاصله، خط تیره، زیرخط و نقطه باشد. این مقدار نمی تواند بیش از 255 کاراکتر باشد.

در صورت تمایل، از عنصر <DisplayName> برای برچسب گذاری خط مشی در ویرایشگر پروکسی UI مدیریت با نامی به زبان طبیعی دیگر استفاده کنید.

 N/A مورد نیاز
continueOnError

برای بازگرداندن خطا در صورت شکست خط مشی، روی false تنظیم کنید. این رفتار مورد انتظار برای اکثر سیاست ها است.

روی true تنظیم کنید تا اجرای جریان حتی پس از شکست خط مشی ادامه یابد.

 نادرست اختیاری
enabled

برای اجرای خط مشی روی true تنظیم کنید.

برای خاموش کردن خط مشی، روی false تنظیم کنید. این سیاست حتی اگر به یک جریان وابسته باشد اجرا نخواهد شد.

 درست است اختیاری
async

این ویژگی منسوخ شده است.

 نادرست منسوخ شده است

عنصر <DisplayName>

علاوه بر ویژگی name برای برچسب‌گذاری خط‌مشی در ویرایشگر پروکسی رابط کاربری مدیریت با نامی متفاوت و به زبان طبیعی، از آن استفاده کنید.

<DisplayName>Policy Display Name</DisplayName>
پیش فرض

N/A

اگر این عنصر را حذف کنید، از مقدار ویژگی name خط مشی استفاده می شود.

حضور اختیاری
تایپ کنید رشته

عنصر <APIKey>

این عنصر متغیر جریانی را که حاوی کلید API است، مشخص می‌کند. معمولاً کلاینت کلید API را در یک پارامتر پرس‌وجو، هدر HTTP یا یک پارامتر فرم ارسال می‌کند. برای مثال، اگر کلید در هدری به نام x-apikey ارسال شود، کلید در متغیر request.header.x-apikey یافت می‌شود.

پیش‌فرض نه
حضور مورد نیاز
نوع رشته

ویژگی‌ها

جدول زیر ویژگی‌های عنصر <APIKey> را شرح می‌دهد.

ویژگی توضیحات پیش‌فرض حضور
مرجع

ارجاعی به متغیری که حاوی کلید API است. فقط یک مکان برای هر خط‌مشی مجاز است.

 ناموجود مورد نیاز

مثال‌ها

در این مثال‌ها، کلید به صورت پارامترها و یک هدر به نام x-apikey ارسال می‌شود.

به عنوان پارامتر پرس و جو: 

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.x-apikey"/>
</VerifyAPIKey>

به عنوان یک هدر HTTP: 

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey"/>
</VerifyAPIKey>

به عنوان پارامتر فرم HTTP: 

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.formparam.x-apikey"/>
</VerifyAPIKey>

طرحواره‌ها

متغیرهای جریان

وقتی سیاست تأیید کلید API روی یک کلید API معتبر اعمال می‌شود، Edge مجموعه‌ای از متغیرهای جریان را پر می‌کند. این متغیرها برای سیاست‌ها یا کدهایی که بعداً در جریان اجرا می‌شوند، در دسترس هستند و اغلب برای انجام پردازش‌های سفارشی بر اساس ویژگی‌های کلید API مانند نام برنامه، محصول API مورد استفاده برای تأیید کلید یا ویژگی‌های سفارشی کلید API استفاده می‌شوند.

این سیاست چندین نوع متغیر جریان مختلف را پر می‌کند، از جمله:

  • عمومی
  • برنامه
  • توسعه‌دهنده
  • شرکت
  • تجزیه و تحلیل

هر نوع متغیر جریان پیشوند متفاوتی دارد. همه متغیرها اسکالر هستند، به جز آنهایی که به طور خاص به عنوان آرایه نشان داده شده‌اند.

متغیرهای جریان عمومی

جدول زیر متغیرهای جریان عمومی که توسط سیاست تأیید کلید API پر شده‌اند را فهرست می‌کند. همه این متغیرها با پیشوند زیر مشخص شده‌اند: 

verifyapikey.{policy_name}

برای مثال: verifyapikey.{policy_name}.client_id

متغیرهای موجود عبارتند از:

متغیر توضیحات
client_id کلید مصرف‌کننده (معروف به کلید API یا کلید برنامه) که توسط برنامه درخواست‌کننده ارائه می‌شود.
client_secret راز مصرف‌کننده مرتبط با کلید مصرف‌کننده.
redirection_uris هرگونه URI ریدایرکت در درخواست.
developer.app.id

شناسه برنامه توسعه‌دهنده‌ای که درخواست را ارسال می‌کند.

developer.app.name نام برنامه‌ی توسعه‌دهنده‌ای که درخواست را ارسال می‌کند.
developer.id

شناسه توسعه‌دهنده‌ای که به عنوان مالک برنامه درخواست‌کننده ثبت شده است.

developer.{custom_attrib_name} هر ویژگی سفارشی مشتق شده از پروفایل کلید برنامه
DisplayName مقدار ویژگی <DisplayName> مربوط به خط‌مشی.
failed وقتی اعتبارسنجی کلید API با شکست مواجه می‌شود، روی "true" تنظیم شود.
{custom_app_attrib}

هر ویژگی سفارشی که از پروفایل برنامه مشتق شده است. نام ویژگی سفارشی را مشخص کنید.

apiproduct.name* نام محصول API که برای اعتبارسنجی درخواست استفاده می‌شود.
apiproduct.{custom_attrib_name}* هر ویژگی سفارشی که از پروفایل محصول API مشتق شده باشد.
apiproduct.developer.quota.limit* محدودیت سهمیه تعیین‌شده برای محصول API، در صورت وجود.
apiproduct.developer.quota.interval* فاصله سهمیه‌بندی تعیین‌شده روی محصول API، در صورت وجود.
apiproduct.developer.quota.timeunit* واحد زمان سهمیه‌بندی که روی محصول API تنظیم شده است، در صورت وجود.
* متغیرهای محصول API در صورتی که محصولات API با محیط، پروکسی‌ها و منابع معتبر (مشتق شده از proxy.pathsuffix ) پیکربندی شده باشند، به طور خودکار پر می‌شوند. برای دستورالعمل‌های مربوط به تنظیم محصولات API، به استفاده از API مدیریت Edge برای انتشار APIها مراجعه کنید.

متغیرهای جریان برنامه

متغیرهای جریان زیر که حاوی اطلاعاتی در مورد برنامه هستند، توسط این سیاست پر می‌شوند. همه این متغیرها با پیشوند زیر شروع می‌شوند:

verifyapikey.{policy_name}.app .

برای مثال:

verifyapikey.{policy_name}.app.name

متغیرهای موجود عبارتند از:

متغیر توضیحات
name نام برنامه.
id شناسه برنامه.
accessType توسط شرکت Apigee استفاده نشده.
callbackUrl URL فراخوانی برنامه. معمولاً فقط برای OAuth استفاده می‌شود.
DisplayName نام نمایشی برنامه.
status وضعیت برنامه، مانند «تایید شده» یا «لغو شده».
apiproducts آرایه‌ای شامل لیست محصولات API مرتبط با برنامه.
appFamily هر خانواده برنامه‌ای که شامل برنامه یا «برنامه پیش‌فرض» باشد.
appParentStatus وضعیت والد برنامه، مانند «فعال» یا «غیرفعال»
appType نوع برنامه، به صورت «شرکت» یا «توسعه‌دهنده».
appParentId شناسه برنامه مادر.
created_at مهر تاریخ/زمان هنگام ایجاد برنامه.
created_by آدرس ایمیل توسعه‌دهنده‌ای که برنامه را ایجاد کرده است.
last_modified_at مهر تاریخ/زمان آخرین به‌روزرسانی برنامه.
last_modified_by آدرس ایمیل توسعه‌دهنده‌ای که آخرین بار برنامه را به‌روزرسانی کرده است.
{app_custom_attributes} هر ویژگی سفارشی برنامه. نام ویژگی سفارشی را مشخص کنید.

متغیرهای جریان توسعه‌دهنده

متغیرهای جریان زیر که حاوی اطلاعاتی در مورد توسعه‌دهنده هستند، توسط این سیاست پر می‌شوند. همه این متغیرها با پیشوند زیر شروع می‌شوند: 

verifyapikey.{policy_name}.developer

برای مثال:

verifyapikey.{policy_name}.developer.id

متغیرهای موجود عبارتند از:

متغیر توضیحات
id مقدار {org_name}@@@{developer_id} را برمی‌گرداند.
userName نام کاربری توسعه‌دهنده.
firstName نام کوچک توسعه‌دهنده.
lastName نام خانوادگی توسعه‌دهنده.
email آدرس ایمیل توسعه‌دهنده.
status وضعیت توسعه‌دهنده، فعال، غیرفعال یا قفل ورود.
apps مجموعه‌ای از برنامه‌های مرتبط با توسعه‌دهنده.
created_at مهر تاریخ/زمانی که توسعه‌دهنده ایجاد شده است.
created_by آدرس ایمیل کاربری که توسعه‌دهنده را ایجاد کرده است.
last_modified_at مهر تاریخ/زمان آخرین باری که توسعه‌دهنده تغییر داده شده است.
last_modified_by آدرس ایمیل کاربری که توسعه‌دهنده را تغییر داده است.
{developer_custom_attributes} هر ویژگی سفارشی توسعه‌دهنده. نام ویژگی سفارشی را مشخص کنید.
Company نام شرکت، در صورت وجود، مرتبط با توسعه‌دهنده.

متغیرهای جریان شرکت

متغیرهای جریان زیر که حاوی اطلاعاتی در مورد شرکت هستند، توسط این سیاست پر می‌شوند. همه این متغیرها با پیشوند زیر شروع می‌شوند: 

verifyapikey.{policy_name}.company

برای مثال: 

verifyapikey.{policy_name}.company.name

متغیرهای موجود عبارتند از:

متغیر توضیحات
name نام شرکت.
displayName نام نمایشی شرکت.
id

شناسه شرکت.

apps آرایه‌ای شامل لیست برنامه‌های شرکت.
appOwnerStatus
وضعیت مالک برنامه، فعال، غیرفعال یا قفل ورود.
created_at مهر تاریخ/زمان تأسیس شرکت.
created_by آدرس ایمیل کاربری که شرکت را ایجاد کرده است.
last_modified_at مهر تاریخ/زمان آخرین باری که شرکت اصلاح شده است.
last_modified_by آدرس ایمیل کاربری که آخرین بار شرکت را تغییر داده است.
{company_custom_attributes} هر ویژگی سفارشی شرکت. نام ویژگی سفارشی را مشخص کنید.

متغیرهای تحلیلی

متغیرهای زیر به طور خودکار در آنالیتیکس، زمانی که سیاست تأیید کلید API برای یک کلید API معتبر اعمال می‌شود، پر می‌شوند. این متغیرها فقط توسط سیاست تأیید کلید API و سیاست‌های OAuth پر می‌شوند.

متغیرها و مقادیر می‌توانند به عنوان ابعادی برای ساخت گزارش‌های تحلیلی مورد استفاده قرار گیرند تا توسعه‌دهندگان و برنامه‌ها بتوانند الگوهای مصرف را به خوبی مشاهده کنند.

  • نام محصول API
  • نام برنامه‌نویس
  • شناسه مشتری
  • شناسه توسعه‌دهنده

مرجع خطا

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:
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.

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>

مباحث مرتبط