使用 OAuth2 访问 Edge API

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

Apigee Edge 使您能够进行使用 OAuth2 令牌进行身份验证的 Edge API 调用。在 Edge 上,系统会默认为 Cloud 帐号启用对 OAuth2 的支持。如果您将 Edge 用于私有云,则必须先设置 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 APIacurlget_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

    acurlget_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. Edge 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 天。

因此,在成功使用 acurlget_token 进行 API 调用后,您可以继续使用该令牌对 30 天。到期后,您必须重新输入凭据并获取新令牌。

通过 OAuth2 访问 Edge API

如需访问 Edge API,您可以向 API 端点发送请求,并附上访问令牌。您可以使用任何 HTTP 客户端执行此操作,包括命令行实用程序(例如 curl)、基于浏览器的界面(例如 Postman)或 Apigee 实用程序(例如 acurl)。

以下部分介绍了如何使用 acurlcurl 访问 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" ]

除了获取组织的详细信息之外,此示例还显示了第二个请求,用于获取“结算”API 代理中的政策列表。第二个请求使用缩写“o”来表示网址中“organizations”。

请注意,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

您可以使用 acurlget_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 代码提示。