Microsoft Entra トークンの検証
適用対象: すべての API Management レベル
この validate-azure-ad-token ポリシーでは、ディレクトリ内の指定されたプリンシパルのセットに対して Microsoft Entra (旧称: Azure Active Directory) サービスによって提供された JSON Web トークン (JWT) の存在と有効性が強制されます。 JWT は、ポリシー式またはコンテキスト変数を使用して指定された HTTP ヘッダー、クエリ パラメーター、または値から抽出できます。
Note
Microsoft Entra 以外の ID プロバイダーによって提供された JWT を検証できるように、API Management には汎用の validate-jwt ポリシーも用意されています。
Note
ポリシーの要素と子要素を、ポリシー ステートメントで指定された順序で設定します。 API Management ポリシーを設定または編集する方法について説明します。
ポリシー ステートメント
<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>
属性
| 属性 | 説明 | 必要 | Default |
|---|---|---|---|
| tenant-id | Microsoft Entra ID テナントのテナント ID または URL、または次の既知のテナントのいずれか。 - organizations または https://login.microsoftonline.com/organizations - 任意の組織ディレクトリ (任意の Microsoft Entra ディレクトリ) 内のアカウントからのトークンを許可します- common または https://login.microsoftonline.com/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 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 つのクレームがトークン内に存在する必要があります。 ポリシー式を使用できます。 |
いいえ |
| decryption-keys | 非対称キーで署名されたトークンの暗号化の解除に使用される key サブ要素の一覧。 キーが複数存在する場合は、すべてのキーを使い果たすか (この場合検証は失敗します)、キーの検証が成功するまで、各キーが試されます。値が、API Management にアップロードされた証明書の識別子に設定された certificate-id 属性を使用して公開キーを指定します。 |
いいえ |
claim の属性
| 属性 | 説明 | 必要 | Default |
|---|---|---|---|
| name | トークンに表示されるクレームの名前。 ポリシー式を使用できます。 | はい | 該当なし |
| match | claim 要素の match 属性では、検証が成功するためにポリシー内のクレーム値がすべてトークン内に存在する必要があるかどうかを指定します。 次のいずれかの値になります。- all - 検証が成功するには、ポリシー内のクレーム値がすべてトークン内に存在する必要があります。- any - 検証が成功するには、ポリシー内のクレーム値が少なくとも 1 つトークン内に存在する必要があります。ポリシー式を使用できます。 |
No | all |
| separator | 文字列。 複数値を含む要求から一連の値を抽出するために使用する区切り記号を指定します (例: ",")。 ポリシー式を使用できます。 | いいえ | N/A |
key の属性
| 属性 | 説明 | 必要 | Default |
|---|---|---|---|
| 証明書 ID | API Management にアップロードされた証明書エンティティの識別子。非対称キーで署名付きトークンを検証する際に、公開キーを指定するために使用されます。 | はい | 該当なし |
使用法
- ポリシー セクション: inbound
- ポリシー スコープ: グローバル、ワークスペース、製品、API、操作
- ゲートウェイ: クラシック、v2、従量課金、セルフホステッド、ワークスペース
使用上の注意
- さまざまな目的に応じて異なるスコープでアクセス制限ポリシーを使用できます。 たとえば、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 テナント 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>
関連ポリシー
関連するコンテンツ
ポリシーに対する処理の詳細については、次のトピックを参照してください。