MSAL インターセプター

MSAL Angular には、既知の保護されたリソースに対して Angular Interceptor クライアントを使用する送信要求のトークンを自動的に取得するhttp クラスが用意されています。 このドキュメントでは、 MsalInterceptorの構成と使用について詳しく説明します。

MsalInterceptor API の代わりにacquireTokenSilentを直接使用することをお勧めしますが、MsalInterceptorの使用は省略可能であることに注意してください。 代わりに acquireToken API を使用してトークンを明示的に取得することもできます。

MsalInterceptorは便宜上提供されており、すべてのユース ケースに適合しない場合があることに注意してください。 MsalInterceptorで対処されていない特定のニーズがある場合は、独自のインターセプターを記述することをお勧めします。

コンフィギュレーション

app.module.ts での MsalInterceptor の設定

MsalInterceptor は、設定とともに、app.module.ts 内でアプリケーションのプロバイダーとして追加できます。 インポートでは、MSAL のインスタンスと、2 つの Angular 固有の構成オブジェクトが取り込まれます。 3 番目の引数は MsalInterceptorConfiguration オブジェクトであり、 interactionType、 protectedResourceMap、および省略可能な authRequestの値が含まれます。

構成は次のようになります。 アプリ用に MSAL Angular を構成する他の方法については、 構成ドキュメント を参照してください。

import { NgModule } from '@angular/core';
import { HTTP_INTERCEPTORS, HttpClientModule } from "@angular/common/http";
import { AppComponent } from './app.component';
import { MsalModule, MsalRedirectComponent, MsalGuard, MsalInterceptor } from '@azure/msal-angular'; // Import MsalInterceptor
import { InteractionType, PublicClientApplication } from '@azure/msal-browser';

@NgModule({
    declarations: [
        AppComponent,
    ],
    imports: [
        MsalModule.forRoot( new PublicClientApplication({
            // MSAL Configuration
        }), {
            // MSAL Guard Configuration
        }, {
            // MSAL Interceptor Configurations
            interactionType: InteractionType.Redirect,
            protectedResourceMap: new Map([ 
                ['Enter_the_Graph_Endpoint_Here/v1.0/me', ['user.read']]
            ])
        })
    ],
    providers: [
        {
            provide: HTTP_INTERCEPTORS, // Provides as HTTP Interceptor
            useClass: MsalInterceptor,
            multi: true
        },
        MsalGuard
    ],
    bootstrap: [AppComponent, MsalRedirectComponent]
})
export class AppModule { }

相互作用の種類

MsalInterceptorはトークンをサイレントで取得するように設計されていますが、サイレント要求が失敗した場合は、対話形式でトークンの取得にフォールバックします。 InteractionTypeは@azure/msal-browserからインポートし、PopupまたはRedirectに設定できます。

{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map([ 
        ['Enter_the_Graph_Endpoint_Here/v1.0/me', ['user.read']]
    ])
}

保護されたリソース マップ

保護されたリソースと対応するスコープは、protectedResourceMap構成のMsalInterceptorとして提供されます。

protectedResourceMap コレクションに指定する URL は、大文字と小文字が区別されます。 リソースごとに、アクセス トークンで返されるように要求されているスコープを追加します。

例えば次が挙げられます。

• ["user.read"] 向け Microsoft Graph
• ["<Application ID URL>/scope"] カスタム Web API の場合 (つまり、 api://<Application ID>/access_as_user)

リソースのスコープは、次の方法で指定できます。

1. スコープの配列。HTTP メソッドに関係なく、そのリソースに対するすべての HTTP 要求に追加されます。

{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map<string, Array<string> | null>([
        ["https://graph.microsoft.com/v1.0/me", ["user.read", "profile"]],
        ["https://myapplication.com/user/*", ["customscope.read"]]
    ]),
}

1. 特定の HTTP メソッドに対してのみスコープをアタッチする ProtectedResourceScopesの配列。

{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map<string, Array<string|ProtectedResourceScopes> | null>([
        ["https://graph.microsoft.com/v1.0/me", ["user.read"]],
        ["http://myapplication.com", [
            {
                httpMethod: "POST",
                scopes: ["write.scope"]
            }
        ]]
    ])
}

リソースのスコープには、文字列と ProtectedResourceScopesの組み合わせを含めることができます。 次の例では、 GET 要求にはスコープ "all.scope" と "read.scope"が含まれますが、 PUT 要求には "all.scope"があります。

{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map<string, Array<string|ProtectedResourceScopes> | null>([
        ["http://myapplication.com", [
            "all.scope",
            {
                httpMethod: "GET",
                scopes: ["read.scope"]
            },
            {
                httpMethod: "POST",
                scopes: ["info.scope"]
            }
        ]]
    ])
}

1. リソースが保護されず、トークンを取得しないことを示す、 nullのスコープ値。 protectedResourceMapに含まれていないリソースは、既定では保護されません。 保護されていない特定のリソースを指定すると、リソース上の一部のルートを保護する場合や保護されないルートがある場合に便利です。 protectedResourceMapの順序が重要であるため、同様のベース URL またはワイルドカードの前に null リソースを配置する必要があることに注意してください。

{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map<string, Array<string> | null>([
        ["https://graph.microsoft.com/v1.0/me", ["user.read", "profile"]],
        ["https://myapplication.com/unprotected", null],
        ["https://myapplication.com/unprotected/post", [{ httpMethod: 'POST', scopes: null }]],
        ["https://myapplication.com", ["custom.scope"]]
    ]),
}

protectedResourceMapに関するその他の注意事項:

• ワイルドカード: protectedResourceMap では、ワイルドカードに * を使用できます。 ワイルドカードを使用する場合、 protectedResourceMapで複数の一致するエントリが見つかった場合は、見つかった最初の一致が ( protectedResourceMapの順序に基づいて) 使用されます。
• 相対パス: アプリケーションに相対リソース パスがある場合は、 protectedResourceMapに相対パスを指定する必要があります。 これは、ngx-translate で発生する可能性のある問題にも当てはまります。 protectedResourceMapの相対パスは、アプリによっては先頭のスラッシュが必要な場合と必要ない場合があり、両方を試す必要がある場合があることに注意してください。

厳密な照合 (strictMatching)

msal-angular v5 では、 protectedResourceMap エントリの URL コンポーネント パターン マッチングでは、既定で厳密な一致セマンティクスが使用されます。 この動作は、strictMatchingの MsalInterceptorConfiguration フィールドによって制御されます。

厳密な照合の変更点

厳密に一致する場合 (v5 の既定値):

• *.contoso.com のようなパターンは app.contoso.com には一致しますが、a.b.contoso.com には一致しません（ワイルドカードはドット区切りをまたぐことはできません）。
• https://graph.microsoft.com/v1.0/meのようなパターンは、その正確な URL にのみ一致します。

一般的なエラー パターン

次の protectedResourceMap キー パターンは従来の一致では機能しますが、厳密な一致では警告なしに失敗します。

v5 での既定の動作 (構成は必要ありません)

厳密な照合は既定で有効になっています。 追加の構成は必要ありません。

{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map([
        ["https://*.contoso.com/api", ["contoso.scope"]],
        ["https://graph.microsoft.com/v1.0/me", ["user.read"]]
    ])
    // strictMatching defaults to true in v5
}

従来の照合を無効にする

パターンが v4 の緩い一致に依存している場合は、レガシ動作を一時的に保持するように strictMatching: false を設定できます。

{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map([
        ["https://*.contoso.com/api", ["contoso.scope"]],
        ["https://graph.microsoft.com/v1.0/me", ["user.read"]]
    ]),
    strictMatching: false  // Use legacy matching for backwards compatibility
}

環境駆動型構成のガイダンス

protectedResourceMap キーが Angular environment 値 (environment.apiConfig.uri など) を参照している場合は、それらの値が正確なパス (https://graph.microsoft.com/v1.0/me など) かベア ベース URL (https://api.example.com など) であるかを確認します。 厳密なパスは厳密な一致で正しく機能し、特別な処理は必要ありません。

export function MSALInterceptorConfigFactory(): MsalInterceptorConfiguration {
  const protectedResourceMap = new Map<string, Array<string>>();
  // environment.apiConfig.uri is an exact path (e.g. "https://graph.microsoft.com/v1.0/me")
  // — strict matching works correctly
  protectedResourceMap.set(environment.apiConfig.uri, environment.apiConfig.scopes);

  return {
    interactionType: InteractionType.Redirect,
    protectedResourceMap,
  };
}

環境の値がベア ベース URL で、サブパスと一致する必要がある場合は、 /* ワイルドカードを追加します。

  // environment.apiConfig.uri is a base URL (e.g. "https://api.example.com")
  // Append /* to match all sub-paths
  protectedResourceMap.set(`${environment.apiConfig.uri}/*`, environment.apiConfig.scopes);

キーシェイプがビルド時に認識されない真に 動的な 構成 (たとえば、 APP_INITIALIZER、 fetch経由で読み込まれた JSON、 platformBrowserDynamic) の場合は、 strictMatching: false を一時的な安全な既定値として設定します。 コード例については、「 修正オプション-オプション B 」を参照してください。

厳密な照合のトラブルシューティング

Symptoms

• API 要求は、 v5 にアップグレードした後 (または 5.0.x → 5.1.x などの v5 マイナー バージョン間) に @azure/msal-angular を返します。
• Authorization: Bearer <token> ヘッダーが送信 HTTP 要求に含まれていない。
• ビルド時またはランタイム エラーは報告されません。エラーは サイレントです。
• この問題は、API ベース URL が開発と異なる特定の環境 (ステージング/運用など) でのみ発生する可能性があります。

修正オプション

オプション A: 厳密な照合を使用するようにキーを更新する (推奨)

厳密な一致規則に一致する正確なパスまたはワイルドカードを使用するように、 protectedResourceMap キーを更新します。 厳密な照合の方が安全で予測しやすいため、この方法をお勧めします。

{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map([
        // Exact path — matches only this URL
        ["https://graph.microsoft.com/v1.0/me", ["user.read"]],
        // Wildcard — matches all sub-paths of the API
        ["https://api.example.com/v1/*", ["api.scope"]]
    ])
    // strictMatching defaults to true — no need to set it
}

オプション B: strictMatching: false を設定する (動的構成のフォールバック)

protectedResourceMap キーが実行時に動的に読み込まれ (APP_INITIALIZER、JSON 構成、platformBrowserDynamicなど)、正確なパスやワイルドカードが含まれていることを保証できない場合は、strictMatching: falseを一時的な安全な既定値として設定します。

{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map([
        [config.apiUri, config.apiScopes]
    ]),
    // Dynamic keys may be base URLs without wildcards.
    // Remove once keys are migrated to exact paths or wildcard patterns.
    strictMatching: false
}

実行時警告

MsalInterceptor が明示的に構成されていない場合、初期化中に MSAL ロガーを介して strictMatchingが出力されます。 この警告が表示された場合は、上記の修正オプションに従ってください。

オプションの authRequest

authRequestで設定できるオプションのMsalInterceptorConfigurationの詳細については、こちらのマルチテナント ドキュメントを参照してください。

msal-angular v1 から v2 への変更

• protectedResourceMap は MsalInterceptorConfiguration オブジェクトに移動され、 Map<string, Array<string|ProtectedResourceScopes>>として渡すことができます。 MsalAngularConfiguration は非推奨となり、機能しなくなりました。
• すべてのルートを保護するためにルート ドメインを protectedResourceMap に配置することはサポートされなくなりました。 代わりにワイルドカード マッチングを使用してください。

スコープを構成する方法の詳細については、 FAQ を参照してください。