Share via

驗證 Microsoft Entra 權杖

  • 發行項

適用於：所有 API 管理 層

此 validate-azure-ad-token 原則會針對目錄中的指定主體集，強制執行 Microsoft Entra （先前稱為 Azure Active Directory） 服務所提供的 JSON Web 令牌存在和有效性。 JWT 可以從指定 HTTP 標頭、查詢參數或使用原則運算式或內容變數提供的值中擷取。

注意

為了驗證另一個識別提供者提供的 JWT，APIM 也會提供一般的 validate-jwt 原則。

注意

請依照原則陳述式中提供的順序，來設定原則的元素和子元素。 深入了解如何設定或編輯 APIM 原則。

原則陳述式

<validate-azure-ad-token
    tenant-id="tenant ID or URL (for example, "contoso.onmicrosoft.com") of the Azure Active Directory service"
    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 Azure Active Directory</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 Azure Active Directory</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>
</validate-azure-ad-token>

屬性

屬性 描述 是必要欄位 預設
租用戶識別碼 Microsoft Entra 服務的租用戶識別碼或 URL。 允許使用原則運算式。 Yes N/A
header-name 保留權杖的 HTTP 標頭名稱。 允許使用原則運算式。 您必須指定 header-name、query-parameter-name 或 token-value 的其中之一。 Authorization
query-parameter-name 保留權杖的查詢參數名稱。 允許使用原則運算式。 您必須指定 header-name、query-parameter-name 或 token-value 的其中之一。 N/A
token-value 運算式，傳回包含標記的字串。 您不得傳回 Bearer 做為權杖值的一部分。 允許使用原則運算式。 您必須指定 header-name、query-parameter-name 或 token-value 的其中之一。 N/A
failed-validation-httpcode JWT 未通過驗證時所要傳回的 HTTP 狀態碼。 允許使用原則運算式。 No 401
failed-validation-error-message 如果 JWT 未通過驗證，在 HTTP 回應主體中傳回的錯誤訊息。 此訊息必須正確逸出任何特殊字元。 允許使用原則運算式。 No 預設錯誤訊息視驗證問題而定，例如「JWT 不存在」。
output-token-variable-name 字串。 成功驗證權杖時，將接收權杖值做為型別 Jwt 物件的內容變數名稱。 不允許使用原則運算式。 No N/A

元素

元素 描述 必要
audiences 包含可呈現在權杖上之可接受的受眾宣告清單。 audience如果有多個值存在，則會嘗試每個值，直到所有值都用盡為止（在此情況下驗證失敗），或直到一個值成功為止。 允許使用原則運算式。 No
backend-application-ids 包含可接受的後端應用程式識別碼清單。 這僅在進階案例中才能設定選項，而且通常可以移除。 不允許使用原則運算式。 No
client-application-ids 包含可接受的用戶端應用程式識別碼清單。 application-id如果有多個元素存在，則會嘗試每個值，直到全部耗盡（在此情況下驗證失敗）或直到成功為止。 如果未提供用戶端應用程式識別碼，則應該指定一或多個 audience 宣告。 不允許使用原則運算式。 No
required-claims 包含應存在於權杖上才會被視為有效之宣告值的 claim 元素清單。 當 match 屬性設定為 all 時，原則中的每個宣告值都必須存在於權杖，才能驗證成功。 當 match 屬性設定為 any 時，至少一個宣告必須存在於權杖，才能驗證成功。 允許使用原則運算式。 No

宣告屬性

屬性 描述 是必要欄位 預設
NAME 預期要出現在權杖中的宣告名稱。 允許使用原則運算式。 Yes N/A
match claim 元素的 match 屬性可指定原則中的每個宣告值是否都必須存在於權杖，才能驗證成功。 可能的值包括：

- all - 原則中的每個宣告值都必須存在於權杖，才能驗證成功。

- any - 至少一個宣告必須存在於權杖，才能驗證成功。

允許使用原則運算式。		 No 全部
separator 字串。 指定用於從多重值宣告中擷取一組值的分隔符號 (例如 ",")。 允許使用原則運算式。 No N/A

使用方式

使用注意事項

  • 您可以針對不同的用途，在不同的範圍中使用存取限制原則。 例如，您可以透過在 API 層級套用 validate-azure-ad-token 原則，以 Microsoft Entra 驗證保護整個 API，您也可以在 API 作業層級套用該原則並使用 claims 進行更細微的控制。
  • 不支援適用於客戶的 Microsoft Entra ID (預覽版)。

範例

簡單權杖驗證

下列原則是 validate-azure-ad-token 原則的最低形式。 其預期會使用 Bearer 配置，在預設 Authorization 標頭中提供 JWT。 在此範例中，Microsoft Entra 租用戶識別碼和用戶端應用程式識別碼是使用具名值所提供。

<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 Entra 租用戶識別碼和用戶端應用程式識別碼則是使用具名值所提供。 驗證之後，在 jwt 變數中提供解碼的 JWT。

如需選擇性宣告的詳細資訊，請參閱向應用程式提供選擇性宣告。

<validate-azure-ad-token tenant-id="{{aad-tenant-id}}" 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>

相關內容

如需使用原則的詳細資訊，請參閱：