Правило VerifyAPIKey

Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. Информация

Что

Правило "Проверка ключа API" позволяет принудительно проверять ключи API во время выполнения, разрешая доступ к вашим API только приложениям с одобренными ключами API. Это правило гарантирует, что ключи API действительны, не отозваны и имеют разрешение на использование определенных ресурсов, связанных с вашими продуктами API.

Примеры

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

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

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

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

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

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

verifyapikey.{policy_name}

Правила в отношении проверки ключа API

Когда разработчик регистрирует приложение в Edge, Edge автоматически создает пару идентификатора клиента и секрета. Посмотреть пару идентификатора клиента и секретного кода приложения можно в интерфейсе Edge или получить доступ к ним через API Edge.

При регистрации приложения разработчик выбирает один или несколько продуктов API, которые будут связаны с приложением. Продукт API – это набор ресурсов, доступных через прокси API. Затем разработчик передает ключ API (идентификатор клиента) как часть каждого запроса к API в продукте API, связанном с приложением. Подробнее см. в Обзоре публикации.

Ключи API можно использовать в качестве токенов аутентификации или для получения токенов доступа OAuth. В OAuth ключи API называются идентификаторами клиента. Эти названия можно использовать как синонимы. Подробнее о OAuth…

При выполнении правила "Проверка ключа API" Edge автоматически заполняет набор переменных потока. Подробнее о переменных потока…

Справочник элементов

Ниже перечислены элементы и атрибуты, которые можно настроить в этом правиле:

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

В следующей таблице описаны атрибуты, общие для всех родительских элементов политики:

Элемент <DisplayName>

Используйте в дополнение к атрибуту name , чтобы пометить политику в редакторе прокси-сервера пользовательского интерфейса управления другим именем на естественном языке.

<DisplayName>Policy Display Name</DisplayName>

Элемент <APIKey>

Этот элемент указывает переменную потока, содержащую ключ API. Как правило, клиент отправляет ключ API в параметре запроса, заголовке HTTP или параметре формы. Например, если ключ отправляется в заголовке x-apikey, он будет найден в переменной request.header.x-apikey.

Атрибуты

В таблице ниже описаны атрибуты элемента <APIKey>.

Примеры

В этих примерах ключ передается в параметрах и заголовке 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>

Схемы

Переменные процесса

Когда правило Verify API Key применяется к действительному ключу API, Edge заполняет набор переменных потока. Эти переменные доступны для правил или кода, выполняемого позже в потоке, и часто используются для выполнения пользовательской обработки на основе атрибутов ключа API, таких как название приложения, продукт API, используемый для авторизации ключа, или пользовательские атрибуты ключа API.

Правило заполняет несколько разных типов переменных потока, в том числе:

• Общие
• Для приложений
• Разработчик
• Компания
• Аналитика

У каждого типа переменной потока свой префикс. Все переменные являются скалярными, кроме тех, которые специально указаны как массивы.

Общие переменные потока

В таблице ниже перечислены общие переменные потока, которые заполняются правилом "Проверить ключ API". Все эти переменные имеют префикс:

verifyapikey.{policy_name}

Пример: verifyapikey.{policy_name}.client_id.

Доступны следующие переменные:

Переменные потока приложений

Правила заполняют следующие переменные потока, содержащие информацию о приложении: Все эти переменные имеют префикс:

verifyapikey.{policy_name}.app.

Пример:

verifyapikey.{policy_name}.app.name

Доступны следующие переменные:

Переменные потока разработчика

Правило заполняет следующие переменные потока, содержащие информацию о разработчике: Все эти переменные имеют префикс:

verifyapikey.{policy_name}.developer

Пример:

verifyapikey.{policy_name}.developer.id

Доступны следующие переменные:

Переменные потока компании

Правило заполняет следующие переменные потока, содержащие информацию о компании: Все эти переменные имеют префикс:

verifyapikey.{policy_name}.company

Пример:

verifyapikey.{policy_name}.company.name

Доступны следующие переменные:

Переменные Аналитики

Когда для действительного ключа API применяется правило "Проверять ключ API", в Аналитике автоматически заполняются следующие переменные: Эти переменные заполняются только правилом "Проверить ключ API" и правилами OAuth.

Переменные и значения можно использовать в качестве параметров для создания отчетов Аналитики, чтобы получать данные о том, как разработчики и приложения используют контент.

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

Справочник по ошибкам

В этом разделе описаны коды ошибок и сообщения об ошибках, которые возвращаются, а также переменные ошибок, которые задаются Edge, когда это правило вызывает ошибку. Эта информация важна, если вы разрабатываете правила обработки ошибок. Подробнее о том, что нужно знать об ошибках в правилах и об обработке ошибок…

Ошибки времени выполнения

Эти ошибки могут возникать при выполнении правил.

Ошибки развертывания

Эти ошибки могут возникать при развертывании прокси-сервера, содержащего это правило.

Переменные ошибок

Эти переменные задаются при возникновении ошибки выполнения. Подробнее о нарушениях правил…

Примеры ответов об ошибках

{
   "fault":{
      "faultstring":"Invalid ApiKey",
      "detail":{
         "errorcode":"oauth.v2.InvalidApiKey"
      }
   }
}

{
   "fault":{
      "detail":{
         "errorcode":"keymanagement.service.DeveloperStatusNotActive"
      },
      "faultstring":"Developer Status is not Active"
   }
}

Пример правила обработки ошибок

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

Статьи по теме