如何通过配置 OAuth 2.0 用户授权来对开发人员门户的测试控制台授权

  • 项目

许多 API 支持使用 OAuth 2.0 维护 API 的安全，并确保仅有效用户具有访问权限且只能访问有权访问的资源。 要将 Azure API 管理的交互式开发人员控制台与此类 API 配合使用，需通过该服务为 OAuth 2.0 用户授权配置外部提供程序。

通过在开发人员门户的测试控制台中配置 OAuth 2.0 用户授权，开发人员可以方便地获取 OAuth 2.0 访问令牌。 然后在测试控制台中，使用 API 调用将令牌传递到后端。 必须对令牌验证进行单独配置 - 使用 JWT 验证策略或在后端服务中配置。

先决条件

本文介绍如何配置 API 管理服务实例，以便在开发人员门户的测试控制台中使用 OAuth 2.0 授权，但不介绍如何配置 OAuth 2.0 提供程序。

如果尚未创建 API 管理服务实例，请参阅创建 API 管理服务实例。

可用性

重要

此功能在 API 管理的“高级”、“标准”、“基本”和“开发人员”层中可用 。

方案概述

在 API 管理中配置 OAuth 2.0 用户授权仅允许开发人员门户的测试控制台 (以及 Azure 门户中的测试控制台) 作为客户端从授权服务器获取令牌。 每个 OAuth 2.0 提供程序的配置不同，但步骤类似，且用于在 API Management 服务实例中配置 OAuth 2.0 的信息片段是相同的。 本文演示了将 Microsoft Entra ID 用作 OAuth 2.0 提供程序的示例。

下面是概要配置步骤：

  1. 在 Microsoft Entra ID 中注册一个应用程序 (backend-app)，用于表示 API。

  2. 在 Microsoft Entra ID 中注册另一个应用程序 (client-app)，用于表示需要调用 API 的客户端应用程序 - 在本例中为开发人员门户的测试控制台。

    在 Microsoft Entra ID 中授予权限，使客户端应用能够调用后端应用。

  3. 在开发人员门户中配置测试控制台，以使用 OAuth 2.0 用户授权调用 API。

  4. 将 API 配置为使用 OAuth 2.0 用户授权。

  5. 添加策略，为每个传入请求预授权 OAuth 2.0 令牌。 可以将 validate-jwt 策略用于任何 OAuth 2.0 提供程序。

此配置支持以下 OAuth 流：

Overview graphic to visually conceptualize the following flow.

  1. 开发人员门户使用客户端应用凭据从 Microsoft Entra ID 请求令牌。

  2. 成功进行验证后，Microsoft Entra ID 会颁发访问/刷新令牌。

  3. 开发人员（开发人员门户的用户）使用授权标头进行 API 调用。

  4. 通过由 Microsoft Entra ID 使用 API 管理中的 validate-jwt 策略来验证令牌。

  5. 开发人员会在开发人员门户中收到响应，具体取决于验证结果。

授权类型

Azure API Management 支持以下 OAuth 2.0 授予类型。 “授予类型”是指在客户端应用程序（此上下文中指的是开发人员门户中的测试控制台）获取后端 API 访问令牌的方法。 可以配置一个或多个授予类型，具体取决于你的 OAuth 2.0 提供程序和方案。

下面是高级摘要。 有关授予类型的详细信息，请参阅 OAuth 2.0 授权框架和 OAuth 授予类型。

授权类型 说明 方案
授权代码 交换令牌的授权代码 服务器端应用，如 Web 应用
隐式 立即返回访问令牌，无需额外授权代码交换步骤 无法保护机密或令牌的客户端，例如移动应用和单页应用

通常不建议这样做，因为在未确认客户端收到访问令牌的情况下，在 HTTP 重定向中返回访问令牌存在固有风险
资源所有者密码 请求用户凭据（用户名和密码），通常使用交互形式 适用于高度受信任的应用程序

仅当无法使用其他更安全的流时使用
客户端凭据 对应用进行身份验证和授权，而不是对用户 不要求特定用户具有数据访问权限的“计算机到计算机”应用程序，如 CLI、守护程序或后端上运行的服务

安全注意事项

请考虑授予类型如何生成令牌、令牌的范围以及令牌的公开方式。 恶意参与者可能会使用泄露的令牌来访问令牌范围内的其他资源。

在开发人员门户的测试控制台中配置 OAuth 2.0 用户授权时，请注意以下要点：

  • 将令牌作用域限制为开发人员测试 API 所需的最小作用域。 将范围限制为测试控制台，或限制为受影响的 API。 配置令牌作用域的步骤取决于 OAuth 2.0 提供程序。

    根据自己的方案，可以为创建的用于访问后端 API 的其他客户端应用程序配置更多或更少的限制性令牌范围。

  • 如果启用客户端凭据流，请特别注意。 使用客户端凭据流时，开发人员门户中的测试控制台不会要求提供凭据。 可能会无意中向开发人员控制台的开发人员或匿名用户公开访问令牌。

记录密钥信息

在本教程中，将要求你记录密钥信息以供以后参考：

  • 后端应用程序（客户端）ID：表示后端 API 的应用程序的 GUID
  • 后端应用程序范围：你可以创建的一个或多个用于访问 API 的范围。 范围格式为 api://<Backend Application (client) ID>/<Scope Name>（例如，api://1764e900-1827-4a0b-9182-b2c1841864c2/Read）
  • 客户端应用程序（客户端）ID：代表开发人员门户的应用程序的 GUID
  • 客户端应用程序机密值：GUID，用作与 Microsoft Entra ID 中的客户端应用程序交互的机密

向 OAuth 服务器注册应用程序

需要向 OAuth 2.0 提供程序注册两个应用程序：一个表示要保护的后端 API，另一个表示调用 API 的客户端应用程序 - 在本例中为开发人员门户的测试控制台。

下面是使用 Microsoft Entra ID 作为 OAuth 2.0 提供程序的示例步骤。 有关应用注册的详细信息，请参阅快速入门：配置应用程序以公开 Web API。

在 Microsoft Entra ID 中注册应用程序以表示 API

  1. 在 Azure 门户中，搜索并选择“应用注册”。

  2. 选择“新注册”。

  3. 出现“注册应用程序”页后，请输入应用程序的注册信息：

    • 在“名称”部分中，输入一个将显示给应用用户的有意义的应用程序名称，例如 backend-app。
    • 在“支持的帐户类型”部分，选择适合你的方案的选项。

  4. 将“重定向 URI”部分保留空白。 稍后，你将添加在 API 管理的 OAuth 2.0 配置中生成的重定向 URI。

  5. 选择“注册”以创建应用程序。

  6. 在应用的“概述”页上，找到“应用程序(客户端) ID”值，并记下该值以供后续使用 。

  7. 在边侧菜单的“管理”部分下，选择“公开 API”，并将“应用程序 ID URI”设置为默认值 。 记下此值以备将来使用。

  8. 选择“添加范围”按钮以显示“添加范围”页 ：

    1. 为 API 支持的范围输入一个“范围名称”，例如“Files.Read”。
    2. 在“谁能同意?”中，针对你的方案进行选择（例如“管理员和用户”）。 对于更高特权的方案，请选择“仅管理员”。
    3. 在“管理员同意显示名称”和“管理员同意说明”中输入相应内容。
    4. 确保选择了“已启用”范围状态。

  9. 选择“添加作用域”按钮以创建作用域。

  10. 重复前两个步骤，以添加 API 支持的所有范围。

  11. 创建范围后，请记下它们，以便在后续步骤中使用。

在 Microsoft Entra ID 中注册另一个应用程序，用于表示客户端应用程序

将每个调用 API 的客户端应用程序注册为 Microsoft Entra ID 中的应用程序。

  1. 在 Azure 门户中，搜索并选择“应用注册”。

  2. 选择“新注册”。

  3. 出现“注册应用程序”页后，请输入应用程序的注册信息：

    • 在“名称”部分中，输入一个将显示给应用用户的有意义的应用程序名称，例如 client-app。
    • 在“支持的帐户类型”部分，选择适合你的方案的选项。

  4. 在“重定向 URI”部分，选择“Web”并将 URL 字段暂时保留为空。

  5. 选择“注册”以创建应用程序。

  6. 在应用的“概述”页上，找到“应用程序(客户端) ID”值，并记下该值以供后续使用 。

  7. 为此应用程序创建客户端密码，以在后续步骤中使用。

    1. 在边侧菜单的“管理”部分下，选择“证书和机密”。
    2. 在“客户端机密”下，选择“+ 新建客户端机密”。
    3. 在“添加客户端机密”下，提供说明并选择密钥过期时间 。
    4. 选择 添加 。

创建机密后，请记下密钥值，以便在后续步骤中使用。 无法在门户中再次访问机密。

在 Microsoft Entra ID 中授予权限

现已注册了用于表示 API 和测试控制台的两个应用程序，请授予权限以允许客户端应用调用后端应用。

  1. 在 Azure 门户中，搜索并选择“应用注册”。

  2. 选择你的客户端应用程序。 然后在侧菜单中，选择“API 权限”。

  3. 选择“+ 添加权限”。

  4. 在“选择 API”下，选择“我的 API”，然后找到并选择你的 backend-app。

  5. 选择“委托的权限”，然后选择 backend-app 的适当权限。

  6. 选择“添加权限”。

可选：

  1. 导航到客户端应用的“API 权限”页。

  2. 选择“为 <your-tenant-name> 授予管理员同意”，以代表此目录中的所有用户授予同意。

在 API 管理中配置 OAuth 2.0 授权服务器

  1. 在 Azure 门户，导航到 API 管理实例。

  2. 在边侧菜单中的“开发人员门户”下，选择“OAuth 2.0 + OpenID Connect”。

  3. 在“OAuth 2.0”选项卡下，选择“+ 添加”。

    OAuth 2.0 menu

  4. 在“名称”和“说明”字段中输入名称和可选说明。

    注意

    这些字段可标识当前 API 管理服务中的 OAuth 2.0 授权服务器。 字段的值不来自 OAuth 2.0 服务器。

  5. 输入“客户端注册页 URL”，如 https://contoso.com/login。 如果 OAuth 2.0 提供程序支持用户管理帐户，用户可以在此页中创建和管理其帐户。 此页面因所使用的 OAuth 2.0 提供程序而异。

    如果 OAuth 2.0 提供程序尚未配置用户管理帐户功能，请在此处输入一个占位符 URL，例如公司的 URL，或 http://localhost 之类的 URL。

    OAuth 2.0 new server

  6. 此窗体的下一部分包含“授权的授权类型”、“授权终结点 URL”和“授权请求方法”设置。

    • 选择一个或多个所需的“授权授予类型”。 对于此示例，请选择“授权代码”（默认值）。 了解详细信息

    • 输入“授权终结点 URL”。 可以从其中一个应用注册的“终结点”页获取终结点 URL。 对于 Microsoft Entra ID 中的单租户应用，此 URL 将类似于以下 URL 之一，其中的 {aad-tenant} 替换为 Microsoft Entra 租户的 ID。

      建议使用 v2 终结点；但是，API 管理同时支持 v1 和 v2 终结点。

      https://login.partner.microsoftonline.cn/{aad-tenant}/oauth2/v2.0/authorize (v2)

      https://login.partner.microsoftonline.cn/{aad-tenant}/oauth2/authorize (v1)

    • “授权请求方法”指定如何向 OAuth 2.0 服务器发送授权请求。 选择“POST” 。

    Specify authorization settings

  7. 指定“令牌终结点 URL”、“客户端身份验证方法”、“访问令牌发送方法”和“默认范围”。

    • 输入“令牌终结点 URL”。 对于 Microsoft Entra ID 中的单租户应用，它将类似于以下 URL 之一，其中的 {aad-tenant} 替换为 Microsoft Entra 租户的 ID。 使用前面选择的同一终结点版本（v2 或 v1）。

      https://login.partner.microsoftonline.cn/{aad-tenant}/oauth2/v2.0/token (v2)

      https://login.partner.microsoftonline.cn/{aad-tenant}/oauth2/token (v1)

    • 如果使用 v1 终结点，请添加主体参数：
      * 名称：resource。
      * 值：后端应用的应用程序（客户端）ID。

    • 如果使用 v2 终结点：
      * 输入在“默认范围”字段中创建的后端应用范围。
      * 将后端应用和客户端应用注册的 accessTokenAcceptedVersion 属性值设置为应用程序清单中的 2。

    • 接受“客户端身份验证方法”和“访问令牌发送方法”的默认设置。

  8. 在“客户端凭据”中，输入“客户端 ID”和“客户端机密”，它们是在创建和配置客户端应用的过程中获取的。

  9. 指定“客户端 ID”和“客户端机密”以后，会生成“授权代码”的“重定向 URI”。 该 URI 用于在 OAuth 2.0 服务器配置中配置重定向 URI。

    在新的开发人员门户中，URI 后缀的形式为：

    • /signin-oauth/code/callback/{authServerName} - 授权代码授予流
    • /signin-oauth/implicit/callback - 隐式授权流

    Add client credentials for the OAuth 2.0 service

    将相应的重定向 URI 复制到客户端应用注册的“身份验证”页。 在应用注册中，选择“身份验证”>“+ 添加平台”>“Web”，然后输入重定向 URI。

  10. 如果“授权的授权类型”设置为“资源所有者密码”，则可使用“资源所有者密码凭据”部分指定这些凭据；否则可将其留空。

  11. 选择“创建”以保存 API Management OAuth 2.0 授权服务器配置。

  12. 重新发布开发人员门户。

    重要

    在进行与 OAuth 2.0 相关的更改时，请确保在每次修改后重新发布开发人员门户，否则相关更改（例如，范围更改）无法传播到门户中并随后用来试用 API。

将 API 配置为使用 OAuth 2.0 用户授权

保存 OAuth 2.0 服务器配置后，请将一个或多个 API 配置为使用此配置。

重要

  • 为 API 配置 OAuth 2.0 用户授权设置允许 API 管理在你使用 Azure 门户或开发人员门户中的测试控制台时，从授权服务器获取令牌。 授权服务器设置也会添加到 API 定义和文档。
  • 对于运行时的 OAuth 2.0 授权，客户端应用必须获取并显示令牌，并且你需要在 API 管理或后端 API 中配置令牌验证。 有关示例，请参阅使用 OAuth 2.0 授权和 Microsoft Entra ID 保护 Azure API 管理中的 API。

  1. 在左侧的“API Management”菜单中选择“API” 。

  2. 选择所需 API 的名称，并选择“设置”选项卡。滚动到“安全”部分，然后选择“OAuth 2.0” 。

  3. 从下拉列表中选择所需的“授权服务器”，并选择“保存”。

    Configure OAuth 2.0 authorization server

开发人员门户 - 测试 OAuth 2.0 用户授权

配置 OAuth 2.0 授权服务器并将 API 配置为使用该服务器以后，即可转到开发人员门户并调用 API 对其进行测试。

  1. 在 Azure API 管理实例“概述”页的顶部菜单中，选择“开发人员门户”。

  2. 在开发人员门户中浏览到 API 下的任一操作。

  3. 选择“试用”，随即你会转到开发人员控制台。

  4. 可以看到，“授权”部分出现了一个与刚刚添加的授权服务器对应的新项。

  5. 从授权下拉列表中选择“授权代码”。

    Select Authorization code authorization

  6. 根据系统提示登录到 Azure AD 租户。

    • 如果你已登录到帐户，则可能不会出现提示。

  7. 成功登录后，会将一个 Authorization 标头添加到请求，该标头包含从 Azure AD 获取的访问令牌。 以下是一个缩写示例令牌（Base64 编码）：

    Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA

  8. 为其余参数配置所需的值，然后选择“发送”以调用 API。

配置 JWT 验证策略，对请求进行预授权

在目前的配置中，API 管理不会验证访问令牌。 它仅将授权标头中的令牌传递给后端 API。

若要对请求进行预授权，请配置 validate-jwt 策略以验证每个传入请求的访问令牌。 如果某个请求没有有效的令牌，API 管理会阻止该请求。

将以下示例策略添加到 <inbound> 策略部分后，该策略将检查从 Azure AD 获取的访问令牌中的受众声明值，该令牌显示在授权标头中。 如果该令牌无效，则返回错误消息。 在适合方案的策略范围内配置此策略。

  • 在 openid-config URL 中，aad-tenant 是 Azure AD 中的租户 ID。 例如，在 Azure 门户中的 Azure AD 资源的“概述”页上找到此值。 显示的示例假定有一个单租户 Azure AD 应用和一个 v2 配置终结点。
  • claim 的值是你在 Azure AD 中注册的后端应用的客户端 ID。
<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.partner.microsoftonline.cn/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

注意

前面的 openid-config URL 对应于 v2 终结点。 对于 v1 openid-config 终结点，请使用 https://login.partner.microsoftonline.cn/{aad-tenant}/.well-known/openid-configuration。

有关如何配置策略的信息，请参阅设置或编辑策略。 有关 JWT 验证的更多自定义设置，请参阅 validate-jwt 参考。

后续步骤

若要详细了解如何使用 OAuth 2.0 和 API 管理，请参阅使用 OAuth 2.0 授权和 Microsoft Entra ID 保护 Azure API 管理中的 Web API 后端。