Pencegat MSAL

MSAL Angular menyediakan kelas Interceptor yang secara otomatis mendapatkan token untuk permintaan keluar yang menggunakan klien Angular http ke sumber daya terlindungi yang telah dikenal. Dokumen ini menyediakan informasi lebih lanjut tentang mengonfigurasi dan menggunakan MsalInterceptor.

Meskipun sebaiknya gunakan MsalInterceptor alih-alih acquireTokenSilent API secara langsung, harap perhatikan bahwa menggunakannya MsalInterceptor bersifat opsional. Anda mungkin ingin secara eksplisit memperoleh token menggunakan API acquireToken sebagai gantinya.

Harap dicatat bahwa MsalInterceptor disediakan untuk kenyamanan Anda dan mungkin tidak sesuai dengan semua kasus penggunaan. Kami mendorong Anda untuk menulis interceptor Anda sendiri jika Anda memiliki kebutuhan khusus yang tidak dapat dipenuhi oleh MsalInterceptor.

Konfigurasi

Mengonfigurasi `MsalInterceptor` di app.module.ts

MsalInterceptor dapat ditambahkan ke aplikasi Anda sebagai penyedia di app.module.ts, dengan konfigurasinya. Import tersebut menerima sebuah instans MSAL, serta dua objek konfigurasi khusus Angular. Argumen ketiga adalah MsalInterceptorConfiguration objek, yang berisi nilai untuk interactionType, , protectedResourceMapdan opsional authRequest.

Konfigurasi Anda mungkin terlihat seperti di bawah ini. Lihat dokumen konfigurasi kami tentang cara lain untuk mengonfigurasi MSAL Angular untuk aplikasi Anda.

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

Jenis Interaksi

Meskipun MsalInterceptor dirancang untuk memperoleh token tanpa interaksi pengguna, jika permintaan tanpa interaksi gagal, mekanisme ini akan beralih ke perolehan token secara interaktif. InteractionType dapat diimpor dari @azure/msal-browser dan diatur ke Popup atau Redirect.

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

Peta Sumber Daya yang Dilindungi

Sumber daya yang dilindungi dan cakupan akses terkait disediakan sebagai protectedResourceMap dalam konfigurasi MsalInterceptor.

URL yang Anda berikan dalam koleksi protectedResourceMap membedakan huruf besar dan huruf kecil. Untuk setiap sumber daya, tambahkan cakupan yang diminta untuk dikembalikan dalam token akses.

Contohnya:

["user.read"] untuk Microsoft Graph
["<Application ID URL>/scope"] untuk API web kustom (yaitu, api://<Application ID>/access_as_user)

Cakupan dapat ditentukan untuk sumber daya dengan cara berikut:

Larik cakupan akses, yang akan ditambahkan ke setiap permintaan HTTP ke sumber daya tersebut, apa pun metode HTTP-nya.

{
    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"]]
    ]),
}

Larik ProtectedResourceScopes, yang akan menerapkan cakupan hanya pada metode HTTP tertentu.

{
    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"]
            }
        ]]
    ])
}

Perhatikan bahwa cakupan untuk sumber daya dapat berisi kombinasi string dan ProtectedResourceScopes. Dalam contoh di bawah ini, GET permintaan akan memiliki cakupan "all.scope" dan "read.scope", sedangkan sebagai PUT permintaan hanya akan memiliki "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"]
            }
        ]]
    ])
}

Nilai cakupan , nullmenunjukkan bahwa sumber daya tidak akan dilindungi dan tidak akan mendapatkan token. Sumber daya yang tidak disertakan dalam protectedResourceMap tidak dilindungi secara bawaan. Menentukan sumber daya tertentu yang tidak terlindungi dapat berguna ketika beberapa rute pada sumber daya harus dilindungi, dan beberapa tidak. Perhatikan bahwa urutan dalam protectedResourceMap penting, jadi resource null harus ditempatkan sebelum URL dasar atau wildcard serupa.

{
    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"]]
    ]),
}

Hal-hal lain yang perlu diperhatikan mengenai protectedResourceMap:

Kartubebas: protectedResourceMap mendukung penggunaan * untuk kartubebas. Saat menggunakan kartubebas, jika beberapa entri yang cocok ditemukan di protectedResourceMap, kecocokan pertama yang ditemukan akan digunakan (berdasarkan urutan protectedResourceMap).
Jalur relatif: Jika ada jalur sumber daya relatif dalam aplikasi Anda, Anda mungkin perlu menyediakan jalur relatif di protectedResourceMap. Ini juga berlaku untuk masalah yang mungkin muncul dengan ngx-translate. Perlu diketahui bahwa jalur relatif pada protectedResourceMap Anda mungkin memerlukan atau tidak memerlukan garis miring di awal, tergantung pada aplikasi Anda, dan Anda mungkin perlu mencoba keduanya.

Pencocokan Tepat (`strictMatching`)

Dalam msal-angular v5, pencocokan pola komponen URL untuk entri protectedResourceMap menggunakan semantik pencocokan ketat secara default. Bidang strictMatching pada MsalInterceptorConfiguration mengontrol perilaku ini.

Important

Jika aplikasi Anda menetapkan kunci protectedResourceMap secara dinamis (misalnya, dari file environment, APP_INITIALIZER, atau konfigurasi JSON) dan kunci tersebut berupa URL dasar tanpa subpath atau karakter wildcard, pencocokan ketat dapat secara diam-diam mencegah header Authorization dilampirkan. Ini menghasilkan kesalahan 401 tanpa kesalahan build-time dan tidak ada peringatan per permintaan—hanya peringatan inisialisasi satu kali jika strictMatching tidak dikonfigurasi secara eksplisit. Lihat Pemecahan masalah pencocokan ketat untuk detailnya.

Perubahan pencocokan yang ketat

Behavior	Warisan (`strictMatching: false`)	Ketat (bawaan di v5)
Metacharacter melarikan diri	`.` dan metakarakter regex lainnya tidak di-escape; metakarakter tersebut berfungsi sebagai operator regex	Semua metakarakter (termasuk `.`) diperlakukan sebagai literal
Penjangkaran	Pola dapat cocok di mana saja dalam string	Pola harus cocok dengan string lengkap (`^…$`)
Host wildcard (`*`)	`*` cocok dengan urutan karakter apa pun, termasuk `.`	`` cocok untuk urutan karakter apa pun yang tidak* menyertakan `.` (karakter wildcard hanya berlaku dalam satu label DNS)
Karakter joker jalur/pencarian/hash (`*`)	`*` cocok dengan urutan karakter apa pun	`*` cocok dengan urutan karakter apa pun (tidak berubah)
`?` Karakter	Diteruskan ke regex yang mendasar	Diperlakukan sebagai literal`?` (pemisah query string URL, bukan wildcard)

Dengan pencocokan ketat (default v5):

Pola seperti *.contoso.com cocok dengan app.contoso.com tetapi tidaka.b.contoso.com (karakter wildcard tidak dapat mencakup pemisah titik).
Pola seperti https://graph.microsoft.com/v1.0/me hanya cocok dengan URL yang tepat.

Pola kegagalan umum

Pola kunci berikut protectedResourceMap berfungsi di bawah pencocokan warisan tetapi secara diam-diam gagal dengan pencocokan yang ketat:

Pola kunci	URL permintaan keluar	Hasil di bawah pencocokan ketat	Perbaiki
`https://api.example.com`	`https://api.example.com/v1/users`	Tidak cocok — kunci mengarah ke jalur `/`, permintaan memiliki jalur `/v1/users`	`https://api.example.com/*`
`https://api.example.com/`	`https://api.example.com/v1/users`	Tidak cocok — garis miring di akhir membatasi pola agar hanya cocok tepat dengan `/`	`https://api.example.com/*`
`environment.apiConfig.uri` (misalnya, `https://api.example.com`)	`https://api.example.com/v1/users`	Tidak ada kecocokan — sama seperti di atas	`${environment.apiConfig.uri}/*`

Perilaku default di v5 (tidak diperlukan konfigurasi)

Pencocokan ketat diaktifkan secara default. Tidak diperlukan konfigurasi tambahan:

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

Menonaktifkan pencocokan versi lama

Jika pola Anda mengandalkan pencocokan yang lebih longgar dari v4, Anda dapat menetapkan strictMatching: false untuk sementara agar perilaku lama tetap dipertahankan:

Note

Pencocokan lama (strictMatching: false) tersedia untuk kompatibilitas dengan versi sebelumnya dan mungkin dihapus pada versi utama mendatang. Kami menyarankan agar Anda memperbarui pola protectedResourceMap Anda agar kompatibel dengan pencocokan ketat.

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

Panduan untuk konfigurasi berbasis lingkungan

Jika kunci Anda protectedResourceMap mereferensikan nilai Angular environment (misalnya, environment.apiConfig.uri), periksa apakah nilai tersebut adalah jalur yang tepat (misalnya, https://graph.microsoft.com/v1.0/me) atau URL dasar kosong (misalnya, https://api.example.com). Jalur yang tepat berfungsi dengan benar dengan pencocokan yang ketat dan tidak memerlukan penanganan khusus:

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,
  };
}

Jika nilai environment berupa URL dasar saja dan Anda perlu mencocokkan subpath, tambahkan wildcard /*:

  // 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);

Untuk konfigurasi yang benar-benar dinamis di mana bentuk kunci tidak dikenal pada waktu build (misalnya, APP_INITIALIZER, JSON dimuat melalui fetch, atau platformBrowserDynamic), diatur strictMatching: false sebagai default aman sementara. Lihat Memperbaiki opsi—Opsi B untuk contoh kode.

Pemecahan masalah pencocokan ketat

Gejala

Permintaan API mengembalikan 401 Tidak Sah setelah meningkatkan ke @azure/msal-angular v5 (atau antara versi minor v5 seperti 5.0.x → 5.1.x).
Header Authorization: Bearer <token>tidak ada dalam permintaan HTTP keluar.
Tidak ada kesalahan saat build atau runtime yang dilaporkan—kegagalan tersebut senyap.
Masalah ini mungkin hanya muncul di lingkungan tertentu (misalnya, penahapan/produksi) di mana URL dasar API berbeda dari pengembangan.

Opsi perbaikan

Opsi A: Perbarui kunci untuk bekerja dengan pencocokan ketat (disarankan)

Perbarui kunci protectedResourceMap Anda agar menggunakan path yang tepat atau karakter pengganti yang sesuai dengan aturan pencocokan yang ketat. Pendekatan ini lebih disukai karena pencocokan ketat lebih aman dan lebih dapat diprediksi:

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

Opsi B: Atur strictMatching: false (fallback untuk konfigurasi dinamis)

Jika kunci protectedResourceMap Anda dimuat secara dinamis saat runtime (misalnya, dari APP_INITIALIZER, konfigurasi JSON, atau platformBrowserDynamic) dan Anda tidak dapat menjamin kunci tersebut berisi path atau wildcard yang tepat, atur strictMatching: false sebagai default aman sementara:

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

Note

Pencocokan lama (strictMatching: false) tersedia untuk kompatibilitas dengan versi sebelumnya dan dapat dihapus pada versi utama mendatang.

Peringatan waktu proses

MsalInterceptor mengeluarkan peringatan satu kali saat runtime melalui logger MSAL selama inisialisasi ketika strictMatching tidak dikonfigurasi secara eksplisit. Jika Anda melihat peringatan ini, ikuti opsi perbaikan di atas.

AuthRequest opsional

Untuk informasi selengkapnya tentang authRequest opsional yang dapat diatur di MsalInterceptorConfiguration, silakan lihat dokumentasi multi-tenant kami di sini.

Perubahan dari msal-angular v1 ke v2

Note

unprotectedResourceMap dalam MSAL Angular v1 sudah tidak MsalAngularConfiguration digunakan lagi dan tidak lagi berfungsi.

protectedResourceMap telah dipindahkan ke MsalInterceptorConfiguration objek, dan dapat diteruskan sebagai Map<string, Array<string|ProtectedResourceScopes>>. MsalAngularConfiguration tidak digunakan lagi dan tidak lagi berfungsi.
Menempatkan domain akar di protectedResourceMap untuk melindungi semua rute tidak lagi didukung. Silakan gunakan pencocokan wildcard sebagai gantinya.

Untuk informasi selengkapnya tentang cara mengonfigurasi cakupan, silakan lihat FAQ kami.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-07-02

Pencegat MSAL

Konfigurasi

Mengonfigurasi MsalInterceptor di app.module.ts

Jenis Interaksi

Peta Sumber Daya yang Dilindungi

Pencocokan Tepat (strictMatching)

Perubahan pencocokan yang ketat

Pola kegagalan umum

Perilaku default di v5 (tidak diperlukan konfigurasi)

Menonaktifkan pencocokan versi lama

Panduan untuk konfigurasi berbasis lingkungan

Pemecahan masalah pencocokan ketat

Gejala

Opsi perbaikan

Peringatan waktu proses

AuthRequest opsional

Perubahan dari msal-angular v1 ke v2

Saran dan Komentar

Sumber Daya Tambahan:

Mengonfigurasi `MsalInterceptor` di app.module.ts

Pencocokan Tepat (`strictMatching`)