Compartir a través de

验证 Microsoft Entra 令牌

  • Artículo

适用于：所有 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 certificate-id="mycertificate"/>
        <!-- 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 子元素的列表，用于解密使用非对称密钥签名的令牌。 如果存在多个密钥，则会对每个密钥进行尝试，直到所有密钥都试完（这种情况表明验证失败）或直到有一个密钥成功为止。

使用 certificate-id 属性（其值设置为上传到 API 管理的证书的标识符）指定公钥。		 否

声明属性

属性 说明 需要 默认
name 预期出现在令牌中的声明名称。 允许使用策略表达式。 是 空值
match claim 元素的 match 属性用于指定：是否策略中的每个声明值都必须存在于令牌中验证才会成功。 可能的值为：

- all - 策略中的每个声明值都必须存在于令牌中验证才会成功。

- any - 至少一个声明值必须存在于令牌中验证才会成功。

允许使用策略表达式。		 否 all
separator 字符串。 指定要用于从多值声明中提取一组值的分隔符（例如 ","）。 允许使用策略表达式。 否 空值

密钥属性

属性 说明 需要 默认
certificate-id 上传到 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>

后续步骤

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