验证 Microsoft Entra 令牌

项目
10/15/2024

适用于：所有 API 管理层级

validate-azure-ad-token 策略强制确保由 Microsoft Entra（前称为 Azure Active Directory）服务为目录中一组指定的主体提供的 JSON Web 令牌 (JWT) 的存在性和有效性。 JWT 可以从指定的 HTTP 标头、查询参数或使用策略表达式或上下文变量提供的值中提取。

注意

为了验证由 Microsoft Entra 以外的标识提供者提供的 JWT，API 管理还提供了通用 validate-jwt 策略。

注意

按照策略声明中提供的顺序设置策略的元素和子元素。详细了解如何设置或编辑 API 管理策略。

策略语句

<validate-azure-ad-token
    tenant-id="tenant ID or URL (for example, "https://contoso.partner.onmschina.cn") of the Microsoft Entra ID tenant"
    header-name="name of HTTP header containing the token (alternatively, use query-parameter-name or token-value attribute to specify token)"
    query-parameter-name="name of query parameter used to pass the token (alternative, use header-name or token-value attribute to specify token)"
    token-value="expression returning the token as a string (alternatively, use header-name or query-parameter attribute to specify token)"
    failed-validation-httpcode="HTTP status code to return on failure"
    failed-validation-error-message="error message to return on failure"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
    <client-application-ids>
        <application-id>Client application ID from Microsoft Entra</application-id>
        <!-- If there are multiple client application IDs, then add additional application-id elements -->
    </client-application-ids>
    <backend-application-ids>
        <application-id>Backend application ID from Microsoft Entra</application-id>
        <!-- If there are multiple backend application IDs, then add additional application-id elements -->
    </backend-application-ids>
    <audiences>
        <audience>audience string</audience>
        <!-- if there are multiple possible audiences, then add additional audience elements -->
    </audiences>
    <required-claims>
        <claim name="name of the claim as it appears in the token" match="all|any" separator="separator character in a multi-valued claim">
            <value>claim value as it is expected to appear in the token</value>
            <!-- if there is more than one allowed value, then add additional value elements -->
        </claim>
        <!-- if there are multiple possible allowed values, then add additional value elements -->
    </required-claims>
    <decryption-keys>
        <key>Base64 encoded signing key | certificate-id="mycertificate"</key>
        <!-- if there are multiple keys, then add additional key elements -->
    </decryption-keys>
</validate-azure-ad-token>

属性

属性	说明	需要	默认
tenant-id	Microsoft Entra ID 租户或以下已知租户之一的租户 ID 或 URL： - `organizations` 或 `https://login.partner.microsoftonline.cn/organizations` - 允许任何组织目录（任何 Microsoft Entra 目录）中的帐户提供的令牌 - `common` 或 `https://login.partner.microsoftonline.cn/common` - 允许任何组织目录（任何 Microsoft Entra 目录）中的帐户和 Microsoft 个人帐户（例如 Skype、XBox）提供的令牌允许使用策略表达式。	是	不适用
header-name	包含令牌的 HTTP 标头的名称。允许使用策略表达式。	必须指定 `header-name`、`query-parameter-name`、`token-value` 中的一个。	`Authorization`
query-parameter-name	包含令牌的查询参数的名称。允许使用策略表达式。	必须指定 `header-name`、`query-parameter-name`、`token-value` 中的一个。	空值
token-value	一个表达式，返回的字符串包含该令牌。令牌值中不得返回 `Bearer`。允许使用策略表达式。	必须指定 `header-name`、`query-parameter-name`、`token-value` 中的一个。	空值
failed-validation-httpcode	JWT 未通过验证时会返回的 HTTP 状态代码。允许使用策略表达式。	否	401
failed-validation-error-message	JWT 未通过验证时会在 HTTP 响应正文中返回的错误消息。此消息必须对任何特殊字符正确地进行转义。允许使用策略表达式。	否	默认错误消息取决于验证问题，例如“JWT 不存在”。
output-token-variable-name	字符串。成功进行令牌验证后，将作为 `Jwt` 类型的对象接收令牌值的上下文变量的名称。不允许使用策略表达式。	否	空值

元素

元素	说明	必需
audiences	包含一系列可接受且可存在于令牌上的受众声明。如果存在多个 `audience` 值，则会对每个值进行尝试，直到有一个值成功（如果所有值都试完却没有一个成功，则表明验证失败）。允许使用策略表达式。	否
backend-application-ids	包含可接受的后端应用程序 ID 的列表。这仅在高级情况下配置某些选项时才需要，并且通常可以删除。不允许使用策略表达式。	否
client-application-ids	包含可接受的客户端应用程序 ID 的列表。如果存在多个 `application-id` 元素，则会对每个值进行尝试，直到有一个值成功（如果所有值都试完却没有一个成功，则表明验证失败）。如果未提供客户端应用程序 ID，则应指定一个或多个 `audience` 声明。不允许使用策略表达式。	否
required-claims	包含一系列应存在于令牌上的声明值的 `claim` 元素，否则令牌会被视为无效。将 `match` 属性设置为 `all` 时，策略中的每个声明值都必须存在于令牌中，这样验证才会成功。将 `match` 属性设置为 `any` 时，至少一个声明必须存在于令牌中，这样验证才会成功。允许使用策略表达式。	否
decryption-keys	`key` 子元素中的 Base64 编码密钥列表，用于解密令牌。如果存在多个安全密钥，则会对每个密钥进行尝试，直到所有密钥都试完（这种情况表明验证失败）或直到有一个密钥成功为止。若要解密使用非对称密钥加密的令牌，可选择性地使用 `certificate-id` 属性指定公钥（该属性的值设置为上传到 API 管理的证书的标识符）。	否

声明属性

属性	说明	需要	默认
name	预期出现在令牌中的声明名称。允许使用策略表达式。	是	空值
match	`claim` 元素的 `match` 属性用于指定：是否策略中的每个声明值都必须存在于令牌中验证才会成功。可能的值为： - `all` - 策略中的每个声明值都必须存在于令牌中验证才会成功。 - `any` - 至少一个声明值必须存在于令牌中验证才会成功。允许使用策略表达式。	否	all
separator	字符串。指定要用于从多值声明中提取一组值的分隔符（例如 ","）。允许使用策略表达式。	否	空值

密钥属性

属性	说明	需要	默认
certificate-id	上传到 API 管理的证书实体的标识符，用于指定公钥以验证使用非对称密钥签名的令牌。	否	空值

使用情况

策略节：入站
策略范围：全局、工作区、产品、API、操作
网关：经典、消耗、自承载

使用注意事项

可以在不同的范围内为不同的目的使用访问限制策略。例如，可以通过在 API 级别应用 validate-azure-ad-token 策略来使用 Microsoft Entra 身份验证保护整个 API，也可以在 API 操作级别应用它并使用 claims 进行更精细的控制。

示例

简单的令牌验证

以下策略是 validate-azure-ad-token 策略的最简形式。它希望使用 Bearer 方案在默认 Authorization 标头中提供 JWT。在此示例中，使用命名值提供 Microsoft Entra 租户 ID 和客户端应用程序 ID。

<validate-azure-ad-token tenant-id="{{aad-tenant-id}}">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
</validate-azure-ad-token>

验证受众和声明是否正确

以下策略检查受众是否为 API 管理实例的主机名，以及 ctry 声明是否为 US。 Microsoft 租户 ID 是已知的 organizations 租户，它允许任何组织目录中的帐户提供的令牌。主机名是使用策略表达式提供的，客户端应用程序 ID 是使用命名值提供的。验证后，在 jwt 变量中提供解码的 JWT.

有关可选声明的更多详细信息，请阅读为你的应用提供可选声明。

<validate-azure-ad-token tenant-id="organizations" output-token-variable-name="jwt">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <required-claims>
        <claim name="ctry" match="any">
            <value>US</value>
        </claim>
    </required-claims>
</validate-azure-ad-token>

身份验证和授权

后续步骤

有关使用策略的详细信息，请参阅：

教程：转换和保护 API
策略参考，其中提供了策略语句及其设置的完整列表
策略表达式
设置或编辑策略
策略示例

通过