你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

在 Azure API 管理中将 OAuth 2.0 授权和 Microsoft Entra ID 配合使用来保护 API

适用于:所有 API 管理层级

本文介绍了完成以下操作的大致步骤:将 OAuth 2.0 协议与 Microsoft Entra ID配合使用以配 Azure API 管理实例,以保护 API。

有关 API 授权的概念概述,请参阅 API 管理中对 API 的身份验证和授权

必备条件

在执行本文中的步骤之前,必须提供:

  • API 管理实例
  • 一个使用 API 管理实例的已发布 API
  • 一个 Microsoft Entra 租户

概述

执行以下步骤,在 API 管理中将 OAuth 2.0 授权和 Microsoft Entra ID 配合使用,以保护 API。

  1. 在 Microsoft Entra ID 中注册应用程序(在本文中称为后端应用)以保护对 API 的访问。

    若要访问 API,用户或应用程序将获取并提供一个有效的 OAuth 令牌,该令牌通过每个 API 请求授予对此应用的访问权限。

  2. 在 API 管理中配置 validate-jwt 策略,以验证每个传入 API 请求中提供的 OAuth 令牌。 可以将有效的请求传递给 API。

有关 OAuth 授权流以及如何生成所需 OAuth 令牌的详细信息不在本文的讨论范围之内。 通常,单独的客户端应用用于从 Microsoft Entra ID 获取授权访问 API 的令牌。 有关其他信息的链接,请参阅后续步骤

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

使用 Azure 门户首先注册一个表示某个 API 的应用程序,以通过 Microsoft Entra ID 保护该 API。

有关应用注册的详细信息,请参阅快速入门:配置应用程序以公开 Web API

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

  2. 选择“新注册”。

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

    • 在“名称”部分中,输入一个将显示给应用用户的有意义的应用程序名称,例如 backend-app
    • 在“支持的帐户类型”部分,选择适合你的方案的选项。
  4. 将“重定向 URI”部分保留空白。

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

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

  7. 在边侧菜单的“管理”部分下,选择“公开 API”,并将“应用程序 ID URI”设置为默认值 。 如果要开发单独的客户端应用以获取用于访问后端应用的 OAuth 2.0 令牌,请记录此值以供以后使用。

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

    1. 在“范围名称”、“管理员同意显示名称”和“管理员同意说明”中输入新值 。
    2. 确保选择了“已启用”范围状态。
  9. 选择“添加作用域”按钮以创建作用域。

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

  11. 创建范围后,请记下它们以供稍后使用。

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

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

  • openid-config URL 中,aad-tenant 是 Microsoft Entra ID 中的租户 ID。 例如,可在 Azure 门户中的 Microsoft Entra 资源的“概述”页上找到此值。 显示的示例假定有一个单租户 Microsoft Entra 应用和一个 v2 配置终结点。
  • claim 的值是你在 Microsoft Entra ID 中注册的后端应用的客户端 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.microsoftonline.com/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <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.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration

有关如何配置策略的信息,请参阅设置或编辑策略。 有关 JWT 验证的更多自定义设置,请参阅 validate-jwt 参考。 API 管理还提供了 validate-azure-ad-token 策略用于验证 Microsoft Entra 服务提供的 JWT。

授权工作流

  1. 用户或应用程序从 Microsoft Entra ID 获取令牌,该令牌具有授予对后端应用的访问权限的权限。

  2. 该令牌将添加到对 API 管理的 API 请求的授权标头中。

  3. API 管理通过使用 validate-jwt 策略验证令牌。

    • 如果某个请求没有有效的令牌,API 管理会阻止该请求。

    • 如果请求附带有效令牌,网关可以将请求转发到 API。

后续步骤