使用 OAuth2 访问 Edge API

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

Apigee Edge 允许您发出经过 OAuth2 令牌身份验证的 Edge API 调用。对于云账号，Edge 默认启用对 OAuth2 的支持。如果您使用的是 Edge for Private Cloud，则必须先设置 SAML 或 LDAP，然后才能使用 OAuth2。

OAuth2 的工作方式（使用 Apigee Edge API）

对 Apigee Edge API 的调用需要进行身份验证，以便我们能够确定您的身份。为了验证您的身份，我们要求您在发送请求以访问 API 时附上 OAuth2 访问令牌。

例如，如果您想获取有关 Edge 上的组织的详细信息，可以向如下网址发送请求：

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

不过，您不能在未告知我们您的身份信息的情况下发送该要求。否则，任何人都可以查看您组织的详细信息。

这时，OAuth2 就派上用场了：为了验证您的身份，您还需要在该请求中向我们发送访问令牌。访问令牌会告知我们您的身份，以便我们确保您有权查看组织的详细信息。

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

OAuth2 流程：初始请求

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

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. 边缘 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 流程：后续请求

在后续请求中，您无需再将凭据换成令牌。不过，您可以直接包含已有的访问令牌，只要该令牌尚未过期即可：

OAuth 流程：后续请求
图 2：OAuth 流程：后续请求

如图 2 所示，如果您已有访问令牌：

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

OAuth2 流程：访问令牌过期

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

OAuth 流程：刷新访问令牌
图 3：OAuth 流程：刷新访问令牌

如图 3 所示，当您的访问令牌过期时：

  1. 您向 Edge API 发送了请求，但您的访问令牌已过期。
  2. Edge API 会因未经授权而拒绝您的请求。
  3. 您将刷新令牌发送到 Edge OAuth2 服务。如果您使用的是 acurl，系统会自动为您完成此操作。
  4. 边缘 OAuth2 服务会返回新的访问令牌。
  5. 您使用新访问令牌向 Edge API 发送请求。
  6. Edge API 会执行您的请求，并通常会返回包含数据的响应。

获取令牌

如需获取可发送到 Edge API 的访问令牌，除了 curl 等实用程序之外，您还可以使用以下 Apigee 实用程序：

  • get_token 实用程序：将您的 Apigee 凭据交换为访问令牌和刷新令牌，以便您用于调用 Edge API。
  • acurl 实用程序：围绕标准 curl 命令提供便捷的封装容器。构建发送到 Edge API 的 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 等基于浏览器的界面，或 acurl 等 Apigee 实用程序。

以下各部分介绍了如何使用 acurl 和 curl 访问 Edge API。

使用 acurl

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

在后续请求中，acurl 会使用 ~/.sso-cli 中保存的令牌，因此您无需再次添加凭据，直到令牌失效为止。

以下示例展示了获取“ahamilton-eval”组织详细信息的初始 acurl 请求：

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 代理中的政策列表。第二个请求在网址中使用了“organizations”的缩写“o”。

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

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

使用 curl

您可以使用 curl 访问 Edge API。为此，您必须先获取访问令牌和刷新令牌。您可以使用 get_token 等实用程序或 Edge OAuth2 服务获取这些信息。

成功保存访问令牌后，您可以在对 Edge API 的调用中传递该令牌，如以下示例所示：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 服务：发送包含以下内容的请求：
    • 刷新令牌
    • 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 代码。