使用 SAML 访问 Edge API

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

SAML 支持单点登录 (SSO) 环境。通过将 SAML 与 Edge 搭配使用,除了您提供并支持 SAML 的任何其他服务外,您可以为 Edge 界面和 API 支持单点登录。

前提条件:您必须为至少一个组织启用 SAML,然后才能使用它访问 Edge API。

SAML 和 OAuth2 之间的区别

设置 SAML 后,使用 SAML 与使用 OAuth2 访问 Edge API 非常相似。调用 Edge API 时,您需要在请求中包含 OAuth2 访问令牌。

访问 Edge API 时,SAML 和 OAuth2 之间的主要区别在于获取令牌的方式。如果使用 SAML,您必须在获取令牌对时包含以下内容:

  1. 地区:面向公有云的 Edge 用户在获取令牌时必须引用自己的地区名称。
  2. 密码:在请求访问/刷新令牌对时添加一次性密码。

SAML 与 Edge OAuth2 服务使用相同的端点,并添加了适当的可用区名称。

要通过 SAML 获取访问令牌,您可以使用以下方法之一(如本部分中所述):

此外,您还可以按照自动执行令牌生成流程中的说明,为机器用户自动生成令牌。

使用 get_token 获取访问令牌

您可以使用 get_token 实用程序使用您的凭据交换用于 SAML 的 OAuth2 访问令牌和刷新令牌。

如需使用 get_token 获取访问令牌,请执行以下操作

  1. SSO_LOGIN_URL 环境变量设置为您的登录网址。登录网址的格式如下:
    https://zoneName.login.apigee.com

    例如,对于名为“acme”的可用区,将 SSO_LOGIN_URL 设置为“https://acme.login.apigee.com”,如以下示例所示:

    export SSO_LOGIN_URL=https://acme.login.apigee.com
  2. 调用 get_token 以获取 OAuth2 访问令牌:
    get_token -u me@example.com

    系统会提示您访问显示的网址以获取一次性密码:

    Get passcode from https://acme.login.apigee.com/passcode
    [Note:  Passcode can be used only time time and expires] Input passcode (no spaces) and then press ENTER:

    如果您最近未通过身份提供方登录,系统会提示您登录。

    此网址返回的一次性密码将一直有效,直到您刷新该网址以获取新密码,或您将密码与 get_token 搭配使用来生成访问令牌为止。例如:

  3. 输入密码。get_token 实用程序获取 OAuth2 令牌,将访问令牌输出到 stdout,并将访问令牌和刷新令牌写入 ~/.sso-cli

  4. 调用 Edge API 并在 Authorization: Bearer 标头中传递访问令牌,如以下示例所示:
    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
      -H "Authorization: Bearer ACCESS_TOKEN"

    可以从 stdout 复制访问令牌的值。

    以下示例会获取有关指定组织的详细信息。如需查看 Management API 端点的完整列表,请参阅 Apigee Edge API 参考文档

当您的访问令牌到期,您可以再次调用 get_token 来获取新的访问令牌。例如:

get_token -u me@example.com

在刷新令牌过期之前,系统不会提示您输入新密码。

当刷新令牌到期后,get_token 会提示您输入新密码。您必须先生成新的密码,然后才能生成新的 OAuth2 访问令牌。

使用 Edge OAuth2 服务获取访问令牌

您可以使用 Edge OAuth2 服务获取用于 SAML 的访问令牌。如需使用 Edge API 对自己进行身份验证,请在初始请求中使用密码以获取访问/刷新令牌对,然后再次使用密码获取新的令牌对。

如需使用 Edge API 获取令牌对,请执行以下操作:

  1. 在浏览器中,转到以下网址以获取动态密码:
    https://zoneName.login.apigee.com/passcode

    例如,对于名为“acme”的区域,转到以下网址:

    https://acme.login.apigee.com/passcode

    如果您最近未通过身份提供方登录,系统会提示您登录。

    此网址会返回一个一次性密码,用作获取令牌的凭据,并且在您刷新该网址以获取新密码之前,该密码将一直有效;或者,您也可以将此密码与 get_token 搭配使用来生成访问令牌。例如:

  2. 向 Edge API 发送请求,如以下示例所示:
    curl https://zoneName.login.apigee.com/oauth/token \
          -s \
          -H "Accept: application/json" \
          -d 'grant_type=password&response_type=token&passcode=passcode'

    passcode 充当您的授权凭据。

    其中:

    • Authorization 头文件为“Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0”(使用此确切值)。
    • 请求类型为 POST
    • 请求正文包含以下内容:
      • grant_type”为“password”。
      • response_type 是“token”。
      • passcode,其中 passcode 是在上一步中返回的密码。

    此调用会将访问令牌和刷新令牌输出到屏幕上。

如需刷新访问令牌,请执行以下操作

请向 https://zoneName.login.apigee.com/oauth/token 提交请求,如以下示例所示:

curl https://zoneName.login.apigee.com/oauth/token \
      -d 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN'

其中:

  • 请求正文包含以下内容:
    • grant_type 是“refresh_token”。
    • refresh_token 是刷新令牌的值。
  • Authorization 头文件为“Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0”(使用此确切值)。
  • 请求类型为 POST

通过 SAML 访问 Edge API

您可以使用 curl 或 Apigee 便捷实用程序 acurl 等工具访问 Edge API。

使用 curl 时,您可以调用 Edge API 并在 Authorization: Bearer 标头中传递访问令牌,如以下示例所示:

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

使用 acurl 时,您无需指定 Authorization 标头。例如:

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

这些示例调用了一个 Edge API 端点,该端点可获取指定组织的详细信息。 如需查看 Edge API 端点的完整列表,请参阅 Apigee Edge API 参考文档

如需了解调用 API 的其他方法,包括确保令牌保持最新状态的方法,请参阅使用 OAuth2 访问 Edge API

SAML 可用区中的计算机用户

您可以使用 acurlget_token 实用程序为 SAML 可用区中的机器用户自动访问 Edge API 的脚本。以下示例展示了如何使用 get_token 请求访问令牌,然后将令牌值添加到 curl 调用中:

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

在上面的示例中,将 -m 的值设置为空字符串将阻止机器用户收到 MFA 代码提示。使用 --force-basic-auth 标志会覆盖由包含 SAML 区域的请求所触发的密码的标准提示。

或者,您也可以使用 acurl 实用程序合并令牌请求和 curl 调用。例如:

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