您正在查看的是 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 流程:
如图 1 所示,当您向 Edge API 发出初始请求时:
- 您请求访问令牌。您可以使用 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
- Edge OAuth2 服务会返回一个访问令牌,并将其输出到
stdout
;例如:Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0 RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG 420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M 2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw
acurl
和get_token
实用程序会以静默方式将访问令牌和刷新令牌保存到~/.sso-cli
(刷新令牌不会写入stdout
)。如果您使用 Edge OAuth2 服务获取令牌,则需要自行保存以供日后使用。 - 您使用访问令牌向 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"
- Edge API 会执行您的请求,并且通常会返回包含数据的响应。
OAuth2 流程:后续请求
在后续请求中,您无需使用凭据交换令牌。您可以只添加您已拥有的访问令牌(只要它尚未过期):
如图 2 所示,如果您已经拥有访问令牌,则:
- 您使用访问令牌向 Edge API 发送请求。
acurl
会自动附加令牌。如果您使用其他工具,则需要手动添加令牌。 - Edge API 会执行您的请求,并且通常会返回包含数据的响应。
OAuth2 流程:访问令牌何时过期
当访问令牌到期(12 小时后)时,您可以使用刷新令牌获取新的访问令牌:
如图 3 所示,当您的访问令牌已过期时:
- 您向 Edge API 发送请求,但访问令牌已过期。
- Edge API 会拒绝您的请求,因为它未授权。
- 您向 Edge OAuth2 服务发送刷新令牌。如果您使用的是
acurl
,系统会自动为您完成此操作。 - Edge OAuth2 服务会使用新的访问令牌进行响应。
- 使用新的访问令牌向 Edge API 发送请求。
- 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)或 Apigee 实用程序(例如 acurl
)。
以下部分介绍了如何使用 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" ]
除了获取组织的详细信息之外,此示例还显示了第二个请求,用于获取“结算”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
您可以使用 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 代码提示。