通过要求 API 密钥保护 API

您正在查看 Apigee X 文档。
查看 Apigee Edge 文档。

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

学习内容

本教程介绍如何:

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

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

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

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

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

创建 API 代理

  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 代理的概览页面。

查看政策

  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://EXTERNAL_IP/helloapikey

    其中,EXTERNAL_IP 是面向互联网的 IP 地址(在安装 Apigee 时定义)的地址。请参阅配置路由

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

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

    也就是说,您未正确传递有效的 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 流量。

创建一个开发者

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

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

注册一个应用

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

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

获取 API 密钥

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

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

使用密钥调用 API

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

curl -v -k https://EXTERNAL_IP/helloapikey?apikey=your_api_key

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

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

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

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

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

  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://EXTERNAL_IP/helloapikey

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

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

相关主题

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

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

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