VerifyAPIKey 政策

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

内容

验证 API 密钥政策允许您在运行时对 API 密钥强制执行验证,仅允许拥有已批准 API 密钥的应用访问您的 API。此政策可确保 API 密钥有效、未被撤消,并且已获批准使用与 API 产品关联的特定资源。

示例

查询参数中的密钥

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

在此示例中,政策要求在名为 request.queryparam.apikey 的流变量中找到 API 密钥。变量 request.queryparam.{name} 是一个标准 Edge 流变量,使用客户端请求中传递的查询参数的值进行填充。

以下 curl 命令会在查询参数中传递 API 密钥:

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

标头中的密钥

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

在此示例中,政策要求在名为 request.header.x-apikey 的流变量中找到 API 密钥。变量 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>

该政策可以引用任何包含密钥的变量。此示例中的政策从名为 requestAPIKey.key 的变量中提取 API 密钥。

该变量的填充方式由您决定。例如,您可以使用提取变量政策从名为 myKey 的查询参数填充 requestAPIKey.key,如下所示:

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

在为有效的 API 密钥执行“验证 API 密钥”政策时,Edge 会自动填充一组流变量。您可以使用这些变量访问应用名称、应用 ID 等信息,以及有关注册应用的开发者或公司的信息。在上面的示例中,验证 API 密钥执行后,您可使用分配消息政策访问开发者的名字、姓氏和电子邮件地址。

这些变量均具有以下前缀:

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 密钥称为“客户端 ID”。这些名称可以互换使用。如需了解详情,请参阅 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">

下表介绍了所有政策父元素通用的特性:

属性 说明 默认 状态
name

政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。

(可选)使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

不适用 必需
continueOnError

设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。

设置为 true,即使在政策失败后,仍可以继续执行流。

false 可选
enabled

设置为 true 可强制执行政策。

设为 false关闭政策。即使政策仍附加到某个流,也不会强制执行该政策。

true 可选
async

此特性已弃用。

false 已弃用

<DisplayName> 元素

除了用于 name 属性之外,还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>
默认

不适用

如果省略此元素,则会使用政策的 name 属性的值。

状态 可选
类型 字符串

<APIKey> 元素

此元素指定包含 API 密钥的流变量。通常,客户端会在查询参数、HTTP 标头或表单参数中发送 API 密钥。例如,如果在名为 x-apikey 的标头中发送密钥,则可在以下变量中找到此密钥:request.header.x-apikey

默认 不适用
状态 必需
类型 字符串

属性

下表说明 <APIKey> 元素的属性

属性 说明 默认 状态
ref

对包含 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 密钥的自定义属性)执行自定义处理。

政策可填充几种不同类型的流变量,包括:

  • 常规
  • 应用
  • 开发者
  • 公司
  • Google Analytics(分析)

每种类型的流变量具有不同的前缀。所有变量均为标量,但明确指定为数组的变量除外。

常规流变量

下表列出由验证 API 密钥政策填充的常规流变量。这些变量均具有以下前缀:

verifyapikey.{policy_name}

例如:verifyapikey.{policy_name}.client_id

可用变量包括:

变量 说明
client_id 发出请求的应用提供的使用方密钥(也称为 API 密钥或应用密钥)。
client_secret 与使用方密钥关联的使用方密钥。
redirection_uris 请求中的任何重定向 URI。
developer.app.id

发出请求的开发者应用的 ID。

developer.app.name 发出请求的开发者应用的名称。
developer.id

注册为发出请求的应用的所有者的开发者的 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 产品配置了有效的环境、代理和资源(派生自 proxy.pathsuffix),则会自动填充 API 产品变量。如需了解如何设置 API 产品,请参阅使用 Edge Management API 发布 API

应用流变量

政策将填充以下包含应用相关信息的流变量。这些变量均具有以下前缀:

verifyapikey.{policy_name}.app.

例如:

verifyapikey.{policy_name}.app.name

可用变量包括:

变量 说明
name 应用的名称。
id 应用的 ID。
accessType Apigee 未使用。
callbackUrl 应用的回调网址。通常仅用于 OAuth。
DisplayName 应用的显示名。
status 应用状态,例如“已批准”或“已撤消”。
apiproducts 包含与应用关联的 API 产品列表的数组。
appFamily 包含该应用的任何应用系列(或“默认”)。
appParentStatus 应用父级的状态,例如“active”或“inactive”
appType 应用类型,即“公司”或“开发者”。
appParentId 父级应用的 ID。
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 开发者的状态,如 active、inactive 或 login_lock。
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

公司 ID。

apps 包含公司应用列表的数组。
appOwnerStatus
应用所有者的状态,可以是有效、无效或 login_lock。
created_at 公司的创建日期/时间戳。
created_by 创建公司的用户的电子邮件地址。
last_modified_at 上次修改公司的日期/时间戳。
last_modified_by 上次修改公司的用户的电子邮件地址。
{company_custom_attributes} 任何自定义公司特性。指定自定义属性的名称。

分析变量

对有效的 API 密钥强制执行验证 API 密钥政策时,Analytics(分析)中会自动填充以下变量。这些变量仅由验证 API 密钥政策和 OAuth 政策填充。

您可以将这些变量和值用作维度来构建 Analytics(分析)报告,从而了解开发者和应用的使用模式。

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

错误参考信息

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>

相关主题