通过要求 API 密钥保护 API

本页面适用于 ApigeeApigee Hybrid

查看 Apigee Edge 文档。

视频:观看此视频短片,了解如何保护 API。

学习内容

本教程介绍如何:

  • 创建需要 API 密钥的 API 代理。
  • 创建 API 产品、开发者和开发者应用。
  • 使用 API 密钥调用 API。

请务必保护您的 API 免遭未经授权的访问。一种方法是使用 API 密钥。

当应用向配置为验证 API 密钥的 API 代理发出请求时,应用必须提供有效的密钥。在运行时,“验证 API 密钥”政策会检查提供的 API 密钥:

  • 有效
  • 尚未撤消
  • 匹配公开所请求资源的 API 产品的 API 密钥

如果密钥有效,则允许请求。如果密钥无效,则请求会导致授权失败。

创建 API 代理

Cloud 控制台中的 Apigee

  1. 在 Google Cloud 控制台中,前往代理开发 > API 代理页面。

    前往 API 代理

  2. 在 Google Cloud 窗格的项目选择器中选择您的组织。组织名称与您的 Google Cloud 项目名称相同。
  3. 点击 + 创建
  4. 创建代理窗格的代理模板下,选择反向代理(最常见)。反向代理会将传入流量路由到后端服务。
  5. 按如下方式配置代理:
    名称
    代理名称 helloworld_apikey
    基本路径

    /helloapikey

    项目基本路径是用于向 API 代理发出请求的网址的一部分。

    说明 hello world protected by API key
    目标(现有 API)

    http://mocktarget.apigee.net

    这定义了 Apigee 在对 API 代理的请求上调用的目标网址。 此目标只返回一个简单的响应:Hello, Guest!

  6. 点击下一步
  7. 部署(可选)。将这些字段留空。
  8. 点击创建
  9. Apigee 会创建新代理,并在代理摘要窗格中显示代理详情摘要。

经典版界面

  1. 转到 Apigee 界面并登录。
  2. 使用界面左上角的下拉菜单选择您的组织。
  3. 点击开发 > API 代理以显示 API 代理列表。

  4. 点击新建
    创建代理按钮
  5. 在“构建代理”向导中,选择反向代理(最常见) (Reverse proxy (most common))。
  6. 按如下方式配置代理:
    在此字段中 执行该操作
    代理名称 输入:helloworld_apikey
    项目基本路径

    更改为:/helloapikey

    项目基本路径是用于向 API 代理发出请求的网址的一部分。

    说明 输入:hello world protected by API key
    目标(现有 API)

    输入:http://mocktarget.apigee.net

    这定义了 Apigee 在对 API 代理的请求上调用的目标网址。 此目标只返回一个简单的响应:Hello, Guest!

  7. 点击下一步
  8. 通用政策 (Common policies) 页面上,选择 API 密钥。此选项会自动向您的 API 代理添加两个政策,并创建生成 API 密钥所需的 API 产品。
  9. 点击下一步
  10. 在摘要页面上,确保已选择部署环境,然后点击创建并部署
  11. 点击修改代理 (Edit proxy),以显示 API 代理的概览页面。

查看政策

Cloud 控制台中的 Apigee

  1. helloworld_apikey 代理的代理摘要窗格中,点击开发标签页。
  2. 政策菜单中,点击 添加政策
  3. 创建政策窗格中,选择安全性下的验证 API 密钥
  4. Verify API Key 窗格中,使用以下值填写名称显示名称部分中的必填字段:
    • 名称:输入政策名称。例如 VerifyAPIKey
    • 显示名称:输入要在界面中使用的政策名称。例如 Verify API Key
  5. 点击创建
  6. 点击 可添加其他政策。
  7. 创建政策窗格中,选择中介下的分配消息
  8. 分配消息窗格中,使用以下值填充名称显示名称部分中的必填字段:
    • 名称:输入政策名称。例如 AssignMessage
    • 显示名称:输入要在界面中使用的政策名称。例如 Assign Message
  9. 点击创建
  10. 以下 XML 代码中的 <APIKey> 元素用于指定传入请求中 API 密钥的位置。 默认情况下,该政策会从 HTTP 请求中名为 apikey 的查询参数中检索密钥。
    <APIKey ref="request.queryparam.apikey" />

    名称 apikey 是任意名称,可以是包含 API 密钥的任何属性。

  11. 分配消息政策的内容更新为以下内容:
  12. <AssignMessage async="false" continueOnError="false" enabled="true" name="remove-query-param-apikey">
        <DisplayName>Remove Query Param apikey</DisplayName>
        <Remove>
            <QueryParams>
                <QueryParam name="apikey"/>
            </QueryParams>
        </Remove>
        <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
        <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
  13. 添加 VerifyApiKeyRemove Query Param apikey 政策。
    1. 代理端点菜单中,点击 Preflow
    2. 在可视化编辑器的请求窗格中,点击 添加政策步骤
    3. 添加政策步骤窗格中,选择 Verify API Key
    4. 点击添加
    5. 在可视化编辑器的请求窗格中,点击 添加政策步骤
    6. 添加政策步骤窗格中,选择 Remove Query Param apikey
    7. 点击添加
  14. 点击保存
  15. 将代理部署到环境:
    1. 点击部署
    2. 选择修订版本环境
    3. 点击部署
  16. 按照 尝试调用 API 中的说明调用 API,以测试您的更改。

经典版界面

  1. 在 API 代理编辑器中,点击开发标签页。您将看到 API 代理的请求流程中添加了两个政策:
    • 验证 API 密钥 - 检查 API 调用,以确保存在有效的 API 密钥(作为查询参数发送)。
    • 删除查询参数 apikey - 一项分配消息政策,选中后会移除 API 密钥,以防不必要地传递和公开该 API 密钥。
  2. 点击流视图中的验证 API 密钥政策图标,然后在下部的代码视图中查看政策的 XML 配置。<APIKey> 元素会告知政策应在调用时从何处查找 API 密钥。默认情况下,它会在 HTTP 请求中查找作为名为 apikey 的查询参数的密钥:

    <APIKey ref="request.queryparam.apikey" />

    名称 apikey 是任意名称,可以是包含 API 密钥的任何属性。

尝试调用 API

在此步骤中,您将对目标服务直接进行成功的 API 调用,然后对 API 代理进行失败调用,以了解它如何受政策保护。

  1. 成功

    在网络浏览器中,转到以下地址。这是将 API 代理配置为将请求转发到的目标服务,但您现在将直接命中它:

    http://mocktarget.apigee.net

    您应该成功收到以下响应:Hello, Guest!

  2. 失败

    现在尝试调用您的 API 代理:

    curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey

    其中,YOUR ENV_GROUP_HOSTNAME 是环境组主机名。请参阅查找环境组主机名

    如果没有验证 API 密钥政策,则此调用将返回与前一调用相同的响应。但在这种情况下,您应该会收到以下错误响应:

    {"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

    也就是说,您未正确传递有效的 API 密钥(作为查询参数)。

在接下来的步骤中,您将获得所需的 API 密钥。

添加 API 产品

Cloud 控制台中的 Apigee

如需使用 Apigee 界面添加 API 产品,请执行以下操作:

  1. 在 Google Cloud 控制台中,前往分发 > API 产品页面:

    前往 API 产品

  2. 点击 +创建
  3. 输入 API 产品的产品详情
    字段 说明
    名称 API 产品的内部名称。请勿在名称中指定特殊字符。
    注意:API 产品一经创建,便无法再修改其名称。
    显示名称 API 产品的显示名称。显示名用于界面中,您可以随时进行修改。如果未指定,则使用 Name 值。此字段会使用 Name 值自动填充;您可以修改或删除其内容。显示名可以包含特殊字符。
    说明 API 产品的说明。
    环境 API 产品将允许访问的环境。例如,testprod
    访问 选择公开
    自动批准访问请求 从任何应用启用此 API 产品的密钥请求的自动批准。
    配额 在本教程中忽略。
    允许的 OAuth 范围 在本教程中忽略。
  4. 操作部分中,点击添加操作
  5. API 代理字段中,选择您刚刚创建的 API 代理。
  6. 路径字段中,输入“/”。忽略其他字段。
  7. 点击保存以保存该操作。
  8. 点击保存以保存该 API 产品。

如需详细了解如何添加 API 产品,请参阅 创建 API 产品

经典版界面

如需使用 Apigee 界面添加 API 产品,请执行以下操作:

  1. 选择发布 > API 产品
  2. 点击+创建
  3. 输入 API 产品的产品详细信息。
    字段 说明
    名称 API 产品的内部名称。请勿在名称中指定特殊字符。
    注意:API 产品一经创建,便无法再修改其名称。
    显示名称 API 产品的显示名称。显示名用于界面中,您可以随时进行修改。如果未指定,则系统会使用 Name 值。此字段会使用 Name 值自动填充;您可以修改或删除其内容。显示名可以包含特殊字符。
    说明 API 产品的说明。
    环境 API 产品将允许访问的环境。例如 testprod
    访问 选择公开
    自动批准访问请求 从任何应用启用此 API 产品的密钥请求的自动批准。
    配额 在本教程中忽略。
    允许的 OAuth 范围 在本教程中忽略。
  4. 操作 (Operations) 部分中,点击添加操作 (ADD AN OPERATION)。
  5. 在“API 代理”字段中,选择您刚刚创建的 API 代理。
  6. 在“路径”字段中,输入“/”。忽略其他字段。
  7. 点击保存以保存该操作。
  8. 点击保存以保存该 API 产品。

将开发者和应用添加到您的组织

接下来,我们将模拟开发者注册使用 API 的工作流。开发者将有一个或多个应用调用您的 API,并且每个应用都会获得唯一的 API 密钥。这样,API 提供方就可以更精细地控制对 API 的访问,并更精细地按应用报告 API 流量。

创建一个开发者

Cloud 控制台中的 Apigee

如需创建开发者,请执行以下操作:

  1. 在 Google Cloud 控制台中,前往分发 > 开发者页面:

    前往开发者

  2. 点击 + 创建
  3. 添加开发者窗口中输入以下内容:
    字段
    名字 Keyser
    姓氏 Soze
    电子邮件 keyser@example.com
    用户名 keyser
  4. 点击添加

如需详细了解如何创建开发者,请参阅 注册应用开发者

经典版界面

如需创建开发者,请执行以下操作:

  1. 在菜单中选择 Publish > Developers
    注意:如果您仍在“开发”屏幕中,请点击 DEVELOP 旁边的 "<",以显示菜单,然后依次选择发布 > 开发者
  2. 点击 + 开发者
  3. 在“新开发者”窗口中输入以下内容:
    在此字段中 Enter
    名字 Keyser
    姓氏 Soze
    用户名 keyser
    电子邮件 keyser@example.com
  4. 点击创建

注册一个应用

Cloud 控制台中的 Apigee

  1. 在 Google Cloud 控制台中,前往分发 > 应用页面:

    前往“应用”

  2. 点击 + 创建
  3. 创建应用窗口中输入以下内容:
    字段
    应用名称 输入:keyser_app
    显示名称 输入:keyser_app
    开发者 选择:Keyser Soze (keyser@example.com)
    回调网址 留空
    备注 留空
  4. 在“凭证”部分中,点击添加凭证
  5. 选择从不。此应用的凭据永不会过期。
  6. 点击添加商品
  7. 选择您刚创建的产品。
  8. 点击添加
  9. 点击创建

如需详细了解如何注册应用,请参阅 注册应用

经典版界面

如需注册开发者应用,请执行以下操作:

  1. 选择发布 > 应用
  2. 点击 + 应用
  3. 在“新开发者应用”窗口中输入以下内容:
    字段
    名称显示名 输入:keyser_app
    开发者 选择:Keyser Soze (keyser@example.com)
    回调网址备注 留空
  4. 在“凭据”部分,选择永不。此应用的凭据永不会过期。
  5. 点击添加产品
  6. 选择您刚创建的产品。
  7. 点击创建

获取 API 密钥

Cloud 控制台中的 Apigee

如需获取 API 密钥,请执行以下操作:

  1. 在 Google Cloud 控制台中,前往分发 > 应用页面。

    前往应用

  2. 从应用列表中选择所需的应用。
  3. 查看应用页面上,点击凭据密钥字段旁边的 。请注意,此密钥与您创建的产品相关联。
  4. 点击 复制。 您将在下一步中使用此密钥。

经典版界面

如需获取 API 密钥,请执行以下操作:

  1. 在“应用”页面(发布 > 应用)上,点击 keyser_app
  2. keyser_app 页面上,点击凭据部分中密钥旁边的显示。请注意,此密钥与您创建的产品相关联。
  3. 选择并复制密钥。您将在下一步中用到它。

使用密钥调用 API

您拥有 API 密钥后,就可以使用它来调用 API 代理了。按所示粘贴 API 密钥,将其作为查询参数。确保查询参数中不存在额外空格。

curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey?apikey=YOUR_API_KEY

现在,在调用 API 代理时,您应得到以下响应:Hello, Guest!

恭喜!您创建了一个 API 代理,并要求在调用中包含有效的 API 密钥,以对其进行保护。

请注意,通常情况下,最好将 API 密钥作为查询参数传递。您应该考虑改为在 HTTP 标头中传递它

最佳做法:在 HTTP 标头中传递密钥

在这一步中,您将修改代理,以在名为 x-apikey 的标头中查找 API 密钥。

Cloud 控制台中的 Apigee

  1. 在 Google Cloud 控制台中,前往代理开发 > API 代理页面。
  2. 前往 API 代理

  3. 从代理列表中选择所需的代理。
  4. 代理详情页面上,点击开发
  5. 修改政策 XML,以指示政策在标头中查找,而不是在 queryparam 中查找:
  6. <APIKey ref="request.header.x-apikey"/>
  7. 点击保存以保存所做更改。
  8. 点击部署
  9. 选择修订版本环境
  10. 点击部署
  11. 使用 c网址 发出以下 API 调用,以将 API 密钥作为名为 x-apikey 的标头传递。别忘了替换您的组织名称。

    curl -v -H "x-apikey: YOUR_API_KEY" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey

请注意,如需完全完成更改,您还需要配置“分配消息”政策以移除标头,而不是查询参数。例如:

<Remove>
  <Headers>
      <Header name="x-apikey"/>
  </Headers>
</Remove>

经典版界面

  1. 修改 API 代理。依次选择开发 > API 代理 > helloworld_apikey,然后转到开发视图。
  2. 选择验证 API 密钥政策,然后修改政策 XML 以指示政策在 header 而不是 queryparam 中查找:

    <APIKey ref="request.header.x-apikey"/>
  3. 保存 API 代理,然后使用部署进行部署。
  4. 使用 cURL 发出以下 API 调用,以将 API 密钥作为名为 x-apikey 的标头传递。别忘了替换您的组织名称。

    curl -v -H "x-apikey: {api_key_goes_here}" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey

请注意,如需完全完成更改,您还需要配置“分配消息”政策以移除标头,而不是查询参数。例如:

<Remove>
  <Headers>
      <Header name="x-apikey"/>
  </Headers>
</Remove>

相关主题

以下是一些与 API 产品和密钥相关的主题:

API 保护通常涉及其他安全机制,例如 OAuth,这是一种将凭据(如用户名和密码)换成访问令牌的开放协议。访问令牌是长的随机字符串,可通过消息流水线在例如应用之间传递,而且不会泄露原始凭据。

如需简要了解安全相关主题,请参阅保护代理