MSAL Interceptor

Az MSAL Angular egy Interceptor osztályt biztosít, amely automatikusan tokeneket szerez be az Angular http ügyfelet használó, ismert védett erőforrásokhoz irányuló kimenő kérésekhez. Ez a dokumentum további információt nyújt a konfigurálásáról és használatáról.MsalInterceptor

Bár azt javasoljuk, hogy a acquireTokenSilent API közvetlen használata helyett a MsalInterceptor elemet használja, kérjük, vegye figyelembe, hogy a MsalInterceptor használata nem kötelező. Előfordulhat, hogy ehelyett explicit módon az acquireToken API-k használatával szeretne tokeneket lekérni.

Kérjük, vegye figyelembe, hogy a(z) MsalInterceptor az Ön kényelmét szolgálja, és nem feltétlenül felel meg minden felhasználási esetnek. Azt javasoljuk, hogy írjon saját interceptort, ha olyan speciális igényei vannak, amelyeket a MsalInterceptor nem fed le.

Konfiguráció

A MsalInterceptorapp.module.ts konfigurálása

A MsalInterceptor szolgáltatóként hozzáadható az alkalmazáshoz az app.module.ts fájlban, a konfigurációjával együtt. Az importálás az MSAL egy példányát, valamint két Angular-specifikus konfigurációs objektumot vesz igénybe. A harmadik argumentum egy MsalInterceptorConfiguration objektum, amely a interactionType, egy protectedResourceMap és egy opcionális authRequest értékeit tartalmazza.

A konfiguráció az alábbihoz hasonlóan nézhet ki. Tekintse meg az MSAL Angular alkalmazáshoz való konfigurálásának egyéb módjait a konfigurációs dokumentumunkban .

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

Interakció típusa

Bár a MsalInterceptor úgy lett kialakítva, hogy a tokeneket felhasználói beavatkozás nélkül szerezze be, ha egy ilyen kérés meghiúsul, interaktív módon próbál tokeneket beszerezni. A InteractionType importálható innen: @azure/msal-browser, és Popup vagy Redirect értékre állítható.

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

Védett erőforrás-térkép

A védett erőforrások és a megfelelő hatókörök a protectedResourceMap konfiguráció részeként MsalInterceptor vannak megadva.

A(z) protectedResourceMap gyűjteményben megadott URL-ek különbséget tesznek a kis- és nagybetűk között. Minden erőforráshoz adjon hozzá a hozzáférési jogkivonatban visszaadandó hatóköröket.

Például:

  • ["user.read"]Microsoft Graph
  • ["<Application ID URL>/scope"] egyéni webes API-khoz (azaz api://<Application ID>/access_as_user)

Hatókörök az alábbi módokon adhatók meg egy erőforráshoz:

  1. Hatókörök tömbje, amely a HTTP-metódustól függetlenül minden HTTP-kéréshez hozzá lesz adva az adott erőforráshoz.
{
    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. Egy tömb ProtectedResourceScopes, amely csak adott HTTP-metódusokhoz csatol hatóköröket.
{
    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"]
            }
        ]]
    ])
}

Vegye figyelembe, hogy egy erőforrás hatókörei sztringek és ProtectedResourceScopes kombinációját tartalmazhatják. Az alábbi példában egy GET kérés hatókörei "all.scope" és "read.scope", míg egy PUT kérésnek csak "all.scope" lenne.

{
    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. A null hatókörérték azt jelzi, hogy egy erőforrás védelem nélkül marad, és nem kap tokeneket. A nem a protectedResourceMap fájlban szereplő erőforrások alapértelmezés szerint nem védettek. A védelem nélküli erőforrások megadása akkor lehet hasznos, ha egy erőforrás egyes útvonalait védeni kell, és vannak, amelyek nem. Vegye figyelembe, hogy a(z) protectedResourceMap sorrendje számít, ezért a null erőforrást minden hasonló alap URL vagy helyettesítő karakter elé kell helyezni.
{
    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"]]
    ]),
}

Egyéb megjegyzés a következőkkel kapcsolatban protectedResourceMap:

  • Helyettesítő karakterek: protectedResourceMap helyettesítő karakterek használatát * támogatja. Helyettesítő karakterek használatakor, ha a protectedResourceMap területen több egyező bejegyzés található, a rendszer az elsőként talált egyezést használja (a protectedResourceMap sorrendje alapján).
  • Relatív elérési utak: Ha az alkalmazásban relatív erőforrás-elérési utak találhatók, előfordulhat, hogy meg kell adnia a relatív elérési utat a protectedResourceMap. Ez az ngx-translate használatával felmerülő problémákra is vonatkozik. Ne feledje, hogy az Ön protectedResourceMap elemében szereplő relatív elérési úthoz az alkalmazástól függően szükség lehet kezdő perjelre, de az is lehet, hogy nem, ezért előfordulhat, hogy mindkét változatot ki kell próbálnia.

Szigorú egyezés (strictMatching)

Az msal-angular v5-ben a protectedResourceMap bejegyzések URL-összetevőmintáinak illesztése alapértelmezés szerint szigorú egyezési szemantikát használ. A MsalInterceptorConfigurationstrictMatching mezője szabályozza ezt a viselkedést.

Important

Ha az alkalmazás dinamikusan állítja be protectedResourceMap a kulcsokat (például környezeti fájlokból APP_INITIALIZERvagy JSON-konfigurációból), és ezek a kulcsok alap URL-címek, amelyek nem használnak segéd- vagy helyettesítő karaktereket, a szigorú egyeztetés csendben megakadályozhatja a Authorization fejléc csatolását. Ez 401 hibát eredményez összeállítási idő és kérésenkénti figyelmeztetés nélkül – csak egyszeri inicializálási figyelmeztetést, ha strictMatching nincs explicit módon konfigurálva. A részletekért tekintse meg a szigorú egyeztetés hibaelhárítását ismertető cikket.

Mit változtat a pontos egyezés

Magatartás Korábbi (strictMatching: false) Szigorú (alapértelmezett v5)
Metakarakter escape-elése . és más regex metacharacterek nem szöknek meg; regex operátorként működnek Az összes metakaraktert (beleértve a . elemet is) literálként kell kezelni
Horgonyzás A minta a sztringen belül bárhol megegyezhet A mintának meg kell egyeznie a teljes karakterlánccal (^…$)
Állomásnévhelyettesítő karakter (*) * bármilyen karaktersorozatnak megfelel, beleértve a . * bármely olyan karaktersorozatnak megfelel, amely nem tartalmaz .-t (a helyettesítő karakterek egyetlen DNS-címkén belül érvényesek)
Elérési út/keresés/hash helyettesítő karakter (*) * bármely karaktersorozatnak megfelel * bármilyen karaktersorozatnak megfelel (változatlan)
? Karakter Továbbítva a mögöttes regex számára Literálként? kezelve (az URL lekérdezési karakterláncának elválasztója, nem helyettesítő karakter)

Szigorú egyeztetéssel (az alapértelmezett v5-ös verzióval):

  • Egy olyan minta, mint a *.contoso.com, illeszkedik a app.contoso.com elemre, de nema.b.contoso.com (a helyettesítő karakter nem terjedhet ki a pontelválasztókra).
  • Egy olyan minta, mint https://graph.microsoft.com/v1.0/me egyezik csak azzal a pontos URL-címel.

Gyakori hibaminták

Az alábbi protectedResourceMap kulcsminták régi illesztéssel működnek, de szigorú illesztés esetén csendben sikertelenek lesznek:

Kulcsmintázat Kimenő kérés URL-címe Szigorú egyeztetés alatt álló eredmény Kijavítás
https://api.example.com https://api.example.com/v1/users Nincs egyezés – a kulcs a(z) / elérési útra oldódik fel, a kérés elérési útja /v1/users https://api.example.com/*
https://api.example.com/ https://api.example.com/v1/users Nincs egyezés – a záró perjel pontosan a / elemhez horgonyozza a mintát https://api.example.com/*
environment.apiConfig.uri (például: https://api.example.com) https://api.example.com/v1/users Nincs egyezés – ugyanaz, mint fent `${environment.apiConfig.uri}/*`

Alapértelmezett viselkedés az 5-ös verzióban (nincs szükség konfigurációra)

A szigorú egyeztetés alapértelmezés szerint engedélyezve van. Nincs szükség további konfigurációra:

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

Kilépés az örökölt egyeztetésből

Ha a minták a v4-ből származó lazább egyezésre támaszkodnak, beállíthatja strictMatching: false , hogy ideiglenesen megtartsa az örökölt viselkedést:

Note

Az örökölt egyezés (strictMatching: false) a visszamenőleges kompatibilitás érdekében érhető el, és egy későbbi főverzióban eltávolítható. Javasoljuk, hogy frissítse a protectedResourceMap mintákat úgy, hogy szigorú illesztéssel működjenek.

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

Útmutatás a környezetalapú konfigurációkhoz

Ha a protectedResourceMap kulcsok Angular environment értékekre hivatkoznak (például environment.apiConfig.uri), ellenőrizze, hogy ezek az értékek pontos elérési utak-e (például https://graph.microsoft.com/v1.0/me) vagy egyszerű alap-URL-ek (például https://api.example.com). A pontos útvonalak megfelelően működnek a szigorú megfeleltetéssel, és nincs szükség speciális kezelésre:

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

Ha a környezeti változó értéke egy egyszerű alap-URL, és az alútvonalakat is illesztenie kell, fűzzön hozzá egy /* helyettesítő karaktert:

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

Az igazán dinamikus konfigurációkhoz, ahol a kulcs szerkezete fordítási időben nem ismert (például APP_INITIALIZER, a(z) fetch használatával betöltött JSON vagy platformBrowserDynamic esetén), állítsa be a(z) strictMatching: false értéket ideiglenes, biztonságos alapértelmezettként. Lásd a Javítás beállításai – B lehetőség egy példakódhoz.

Szigorú egyeztetés hibaelhárítása

Symptoms
  • Az API-kérések a 401-es „Unauthorized” hibát adják vissza a @azure/msal-angular v5-re történő frissítés után (vagy a v5 alverziói közötti frissítéskor, például 5.0.x → 5.1.x esetén).
  • A Authorization: Bearer <token> fejléc hiányzik a kimenő HTTP-kérelmekből.
  • Nem jelentkeznek sem fordításkori, sem futásidejű hibák – a meghibásodás csendes.
  • A probléma csak bizonyos környezetekben (például átmeneti/éles környezetben) jelenhet meg, ahol az API-alap URL-címe eltér a fejlesztéstől.
Beállítások javítása

A lehetőség: Frissítse a kulcsokat, hogy szigorú megfeleltetéssel működjenek (ajánlott)

Frissítse a protectedResourceMap kulcsokat úgy, hogy pontos elérési utakat vagy a szigorú egyeztetési szabályoknak megfelelő helyettesítő karaktereket használjon. Ez a megközelítés azért ajánlott, mert a szigorú egyeztetés biztonságosabb és kiszámíthatóbb:

{
    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 lehetőség: Állítsa be a strictMatching: false értéket (tartalék megoldás dinamikus konfigurációkhoz)

Ha az Ön protectedResourceMap kulcsai futásidőben dinamikusan töltődnek be (például APP_INITIALIZER, JSON-konfiguráció vagy platformBrowserDynamic alapján), és nem tudja garantálni, hogy pontos elérési utakat vagy helyettesítőjeleket tartalmaznak, ideiglenes biztonságos alapértelmezésként állítsa be a(z) strictMatching: false értéket:

{
    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

Az örökölt egyezés (strictMatching: false) a visszamenőleges kompatibilitás érdekében érhető el, és egy későbbi főverzióban eltávolítható.

Futásidejű figyelmeztetés

MsalInterceptor Egyszeri futásidejű figyelmeztetést ad ki az MSAL-naplózón keresztül az inicializálás során, ha strictMatching nincs explicit módon konfigurálva. Ha ezt a figyelmeztetést látja, kövesse a fenti javítási beállításokat.

Választható hitelesítés

A(z) MsalInterceptorConfiguration területen beállítható opcionális authRequest elemről további információért tekintse meg itt a több-bérlős dokumentációnkat.

Msal-angular v1 és v2 közötti változások

Note

Az MSAL Angular v1 MsalAngularConfiguration elemében található unprotectedResourceMap elavult, és már nem működik.

  • protectedResourceMap átkerült az MsalInterceptorConfiguration objektumba, és Map<string, Array<string|ProtectedResourceScopes>> értékként adható át. MsalAngularConfiguration elavult, és a továbbiakban nem működik.
  • A gyökérdomain protectedResourceMap elembe helyezése az összes útvonal védelme érdekében már nem támogatott. Kérjük, ehelyett használjon helyettesítőkarakteres egyeztetést.

A hatókörök konfigurálásáról további információt a gyakori kérdések között talál.

  • Last updated on