共用方式為

驗證 Microsoft Entra 權杖

  • 發行項

適用於：所有 APIM 層

validate-azure-ad-token 原則會強制 JSON Web 權杖 (JWT) 存在且有效，而該權杖是由 Microsoft Entra (先前稱為 Azure Active Directory) 服務為目錄中一組特定的主體所提供。 JWT 可以從指定 HTTP 標頭、查詢參數或使用原則運算式或內容變數提供的值中擷取。

注意

若要驗證 Microsoft Entra 以外的識別提供者所提供的 JWT，APIM 也會提供一般 validate-jwt 原則。

注意

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

原則陳述式

<validate-azure-ad-token
    tenant-id="tenant ID or URL (for example, "https://contoso.onmicrosoft.com") 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>

屬性

屬性 描述 是必要欄位 預設
租用戶識別碼 Microsoft Entra ID 租用戶的租用戶識別碼或 URL，或下列其中一個已知的租用戶：

- organizations 或 https://login.microsoftonline.com/organizations - 以允許來自任何組織目錄 (任何 Microsoft Entra 目錄) 中帳戶的權杖
- common 或 https://login.microsoftonline.com/common - 以允許來自任何組織目錄 (任何 Microsoft Entra 目錄) 中帳戶，以及來自個人 Microsoft 帳戶 (例如 Skype、XBox) 的權杖

允許使用原則運算式。		 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
decryption-keys 子元素的清單 key ，用來解密以非對稱密鑰簽署的令牌。 如果有多個金鑰存在，則會嘗試每個金鑰，直到所有金鑰都用盡（在此情況下驗證失敗）或金鑰成功為止。

使用certificate-id屬性值設定為上傳至 API 管理 之憑證標識碼的屬性來指定公鑰。		 No

宣告屬性

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

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

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

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

金鑰屬性

屬性 描述 是必要欄位 預設
certificate-id 上傳到 APIM 的憑證實體識別碼，用於指定公開金鑰以驗證以非對稱金鑰簽署的權杖。 Yes 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 租用戶識別碼是已知的 organizations 租用戶，其會允許來自任何組織目錄中帳戶的權杖。 主機名稱是使用原則運算式來提供，而用戶端應用程式識別碼則是使用具名值來提供。 驗證之後，在 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>

相關內容

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