Microsoft Entra トークンの検証

  • [アーティクル]

適用対象: すべての API Management レベル

この validate-azure-ad-token ポリシーでは、ディレクトリ内の指定されたプリンシパルのセットに対して Microsoft Entra (旧称: Azure Active Directory) サービスによって提供された JSON Web トークン (JWT) の存在と有効性が強制されます。 JWT は、ポリシー式またはコンテキスト変数を使用して指定された HTTP ヘッダー、クエリ パラメーター、または値から抽出できます。

Note

別の ID プロバイダーによって提供された JWT を検証するために、API Management では汎用 validate-jwt ポリシーも提供されます。

Note

ポリシーの要素と子要素を、ポリシー ステートメントで指定された順序で設定します。 API Management ポリシーを設定または編集する方法について説明します。

ポリシー ステートメント

<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>

属性

属性 説明 必要 Default
tenant-id Microsoft Entra サービスのテナント ID または URL。 ポリシー式を使用できます。 はい 該当なし
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 not present" (JWT が存在しません) など)。
output-token-variable-name 文字列 をオンにします。 成功したトークンの検証において、Jwt 型のオブジェクトとしてトークン値を受け取るコンテキスト変数の名前。 ポリシー式は使用できません。 いいえ 該当なし

要素

要素 説明 必須
audiences トークン上に存在する可能性がある、許容される対象ユーザー クレームの一覧を記載します。 audience の値が複数存在する場合は、すべての値が消費される (この場合検証は失敗します) かいずれかの値の検証が成功するまで、各値について検証が行われます。 ポリシー式を使用できます。 いいえ
backend-application-ids 受け入れ可能なバックエンド アプリケーション ID のリストが含まれます。 これは、オプションの構成に高度なケースでのみ必要であり、通常は削除できます。 ポリシー式は使用できません。 いいえ
client-application-ids 受け入れ可能なクライアント アプリケーション ID のリストが含まれます。 application-id 要素が複数存在する場合は、すべての値が消費される (この場合検証は失敗します) かいずれかの値の検証が成功するまで、各値について検証が行われます。 クライアント アプリケーション ID が指定されていない場合は、1 つ以上の audience クレームを指定する必要があります。 ポリシー式は使用できません。 いいえ
required-claims トークン上に存在すると予測される、有効とみなすクレームの値に対する claim 要素の一覧を記載します。 match 属性を all に設定した場合、検証が成功するにはポリシー内のクレーム値がすべてトークン内に存在する必要があります。 match 属性を any に設定した場合、検証が成功するには少なくとも 1 つのクレームがトークン内に存在する必要があります。 ポリシー式を使用できます。 いいえ

claim の属性

属性 説明 必要 Default
name トークンに表示されるクレームの名前。 ポリシー式を使用できます。 はい 該当なし
match claim 要素の match 属性では、検証が成功するためにポリシー内のクレーム値がすべてトークン内に存在する必要があるかどうかを指定します。 次のいずれかの値になります。

- all - 検証が成功するには、ポリシー内のクレーム値がすべてトークン内に存在する必要があります。

- any - 検証が成功するには、ポリシー内のクレーム値が少なくとも 1 つトークン内に存在する必要があります。

ポリシー式を使用できます。		 No all
separator 文字列。 複数値を含む要求から一連の値を抽出するために使用する区切り記号を指定します (例: ",")。 ポリシー式を使用できます。 いいえ 該当なし

使用法

使用上の注意

  • さまざまな目的に応じて異なるスコープでアクセス制限ポリシーを使用できます。 たとえば、API 全体を Microsoft Entra 認証を使用して保護するには、validate-azure-ad-token ポリシーを API レベルに適用します。または、これを API 操作レベルに適用して、claims を使用してきめ細かい制御を行うこともできます。
  • 顧客向けの Microsoft Entra ID (プレビュー) はサポートされていません。

例

単純なトークン検証

次のポリシーは、 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 Management インスタンスのホスト名であり、 ctry 要求がUSであることを確認します。 ホスト名はポリシー式を使用して提供され、Microsoft Entra テナント ID とクライアント アプリケーション ID は名前付き値を使用して提供されます。 デコードされた 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>

関連するコンテンツ

ポリシーに対する処理の詳細については、次のトピックを参照してください。