使用 OAuth2 访问 Edge API

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

借助 Apigee Edge，您可以进行通过 OAuth2 令牌进行身份验证的 Edge API 调用。 在 Edge 上，系统会为 Cloud 账号默认启用对 OAuth2 的支持。如果您使用的是 Edge 否则您不能使用 OAuth2 首先设置 SAML 或 LDAP。

OAuth2 的工作原理（与 Apigee Edge API 搭配使用）

调用 Apigee Edge API 需要进行身份验证，以便我们确认您的身份 你说的对。为了验证您的身份，我们需要随您的请求一起发送 OAuth2 访问令牌 访问该 API。

例如，如果您想获取 Edge 上某个组织的详细信息，您可以向 如下所示：

https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

但是，如果不告诉我们您的身份，您就无法直接发送相应请求。否则，任何人 可以查看贵组织的详细信息。

这正是 OAuth2 的用武之地：为了对您进行身份验证，我们需要您向我们发送一个访问令牌 包含的信息访问令牌可告知我们您的身份信息，从而确保您有权 查看组织的详细信息。

幸运的是，您可以通过将凭据发送到 Edge OAuth2 服务来获取令牌。通过 服务会返回访问令牌和刷新令牌。

OAuth2 流程：初始请求

下图显示了首次访问 Edge API 时的 OAuth2 流程 时间：

<ph type="x-smartling-placeholder">
</ph> OAuth 流程：第一个请求
图 1：OAuth 流程：第一个请求

如图 1 所示，当您向 Edge API 发出初始请求时：

  1. 您请求访问令牌。为此，您可以使用 Edge API、acurl 或 get_token。例如： 
    get_token
Enter username:
ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code if 'ahamilton@apigee.com' is MFA enabled or press ENTER:
123456
  2. Edge OAuth2 服务使用访问令牌进行响应，并将其输出到 stdout； 例如： 
    Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

    acurl 和 get_token 实用程序以静默方式保存访问和 刷新令牌写入 ~/.sso-cli（刷新令牌不会写入 stdout。）如果您使用 Edge OAuth2 服务获取令牌，则需要保存令牌以便 自己用。

  3. 使用访问令牌向 Edge API 发送请求。acurl 个附件 自动获取令牌；例如： 
    acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

    如果您使用其他 HTTP 客户端，请务必添加访问令牌。例如：

    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"
  4. Edge API 执行您的请求，通常返回包含数据的响应。

OAuth2 流程：后续请求

在后续请求中，您无需将凭据交换为令牌。相反， 您可以只添加已有的访问令牌（只要该令牌尚未过期）：

<ph type="x-smartling-placeholder">
</ph> OAuth 流程：后续请求
图 2：OAuth 流程：后续请求

如图 2 所示，在已经拥有访问令牌后：

  1. 使用访问令牌向 Edge API 发送请求。acurl 个附件 自动获取令牌。如果您使用其他工具，则需要手动添加令牌。
  2. Edge API 执行您的请求，通常返回包含数据的响应。

OAuth2 流程：访问令牌的过期时间

当访问令牌过期（12 小时后）后，您可以使用刷新令牌来获取新的 访问令牌：

<ph type="x-smartling-placeholder">
</ph> OAuth 流程：刷新访问令牌
图 3：OAuth 流程：刷新访问令牌

如图 3 所示，当访问令牌过期后：

  1. 您向 Edge API 发送请求，但您的访问令牌已过期。
  2. Edge API 拒绝您的请求为未授权的请求。
  3. 您向 Edge OAuth2 服务发送刷新令牌。如果您使用的是 acurl，则此步骤已完成 。
  4. Edge OAuth2 服务会返回一个新的访问令牌。
  5. 使用新的访问令牌向 Edge API 发送请求。
  6. Edge API 执行您的请求，通常返回包含数据的响应。

获取令牌

如需获取可发送到 Edge API 的访问令牌，您可以使用以下代码 Apigee 实用程序以及 curl 等实用程序：

  • get_token 实用程序：用 Apigee 凭据交换访问权限 和刷新可用于调用 Edge API 的令牌。
  • acurl 实用程序：提供封装标准的便捷封装容器 curl 命令。构建发送至边缘的 HTTP 请求 从 get_token 获取访问和刷新令牌，然后将访问令牌传递给 Edge API。
  • Edge OAuth2 服务中的令牌端点：将您的 通过调用 Edge API 访问和刷新令牌的 Apigee 凭据。

这些实用程序会交换您的 Apigee 账号凭据（电子邮件地址和 密码）。

  • 访问令牌将在 12 小时后过期。
  • 刷新令牌会在 30 天后过期。

因此，在您使用 acurl 或 get_token 成功进行 API 调用后， 您可以继续使用令牌对 30 天。届时，您必须重新输入 并获取新令牌

通过 OAuth2 访问 Edge API

如需访问 Edge API，请向 API 端点发送请求，并在其中包含访问令牌。 您可以使用任何 HTTP 客户端（包括 curl 等命令行实用程序）执行此操作， 基于浏览器的界面（例如 Postman）或 Apigee 实用程序（例如 acurl）。

如需了解如何使用 acurl 和 curl 访问 Edge API，请参阅 后面的部分。

使用 acurl

要使用 acurl 访问 Edge API，您的初始请求必须包含您的 凭据。Edge OAuth2 服务会返回访问令牌和刷新令牌。acurl 将令牌保存在本地。

在后续请求中，acurl 会使用 ~/.sso-cli 中保存的令牌，因此 在令牌过期之前不必再次提供凭据。

以下示例展示了初始 acurl 请求，该请求会获取 “ahamilton-eval”组织：

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -u ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code (no spaces) if 'ahamilton@apigee.com' is MFA-enabled or press ENTER:
1a2b3c
{
  "createdAt" : 1491854501264,
  "createdBy" : "noreply_iops@apigee.com",
  "displayName" : "ahamilton",
  "environments" : [ "prod", "test" ],
  "lastModifiedAt" : 1491854501264,
  "lastModifiedBy" : "noreply_iops@apigee.com",
  "name" : "ahamilton",
  "properties" : {
    "property" : [ {
      "name" : "features.isSmbOrganization",
      "value" : "false"
    }, {
      "name" : "features.isCpsEnabled",
      "value" : "true"
    } ]
  },
  "type" : "trial"
}

acurl https://api.enterprise.apigee.com/v1/o/ahamilton-eval/apis/helloworld/revisions/1/policies

[ "SOAP-Message-Validation-1", "Spike-Arrest-1", "XML-to-JSON-1" ]

除了获取组织的详细信息外，此示例还显示了第二个请求 用于获取“helloworld”中的政策列表API 代理。第二个请求使用 简写“o”搜索“组织”。

请注意，acurl 会在第二个请求上自动传递访问令牌。您 在 acurl 存储 OAuth2 令牌后，无需传递您的用户凭据。它 从 ~/.sso-cli 获取令牌，以用于后续调用。

如需了解详情，请参阅使用 acurl 访问 Edge API。

使用 curl

您可以使用 curl 访问 Edge API。为此，您必须先 访问令牌和刷新令牌您可以使用 get_token 或 Edge OAuth2 服务。

成功保存访问令牌后，请将其传入 Authorization 标头，如以下示例所示 显示：

curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

访问令牌在颁发后 12 小时内有效。访问令牌过期后，刷新令牌可使用 30 天时间来颁发 另一个访问令牌，而无需凭据。 Apigee 建议仅在引荐令牌过期后请求新的访问令牌，而不是在引荐令牌过期后请求该令牌 输入凭据并在每次调用 API 时发出新请求。

令牌过期

访问令牌过期后，您可以使用刷新令牌来获取新的访问令牌 您需要重新提交凭据

刷新访问令牌的方式取决于您所使用的工具：

  • acurl：无需执行任何操作。acurl 会自动刷新访问令牌 。
  • get_token：调用 get_token 以刷新访问令牌。
  • Edge OAuth2 服务：发送包含以下内容的请求： <ph type="x-smartling-placeholder">
      </ph>
    • 刷新令牌
    • “grant_type”表单参数已设置为“refresh_token”

针对机器用户的 OAuth2

您可以使用 acurl 和 get_token 实用程序为自动访问编写脚本 使用面向机器用户的 OAuth2 身份验证机制向 Edge API 开放。以下示例展示了如何 使用get_token 请求访问令牌，然后将令牌值添加到 curl 调用：

  USER=me@example.com
  PASS=not-that-secret
  TOKEN=$(get_token -u $USER:$PASS -m '')
  curl -H "Authorization: Bearer $TOKEN" 'https://api.enterprise.apigee.com/v1/organizations/...'

或者，您也可以使用 acurl 实用程序将令牌请求和 curl 调用结合使用。 例如：

  USER=me@example.com
  PASS=not-that-secret
  acurl -u $USER:$PASS -m '' 'https://api.enterprise.apigee.com/v1/organizations/...'

在这两个示例中，将 -m 的值设为空字符串会阻止机器用户 避免系统提示输入 MFA 代码