MSAL Interceptor

MSAL Angular tillhandahåller en Interceptor klass som automatiskt hämtar token för utgående begäranden som använder Angular-klienten http till kända skyddade resurser. Det här dokumentet innehåller mer information om hur du konfigurerar och använder MsalInterceptor.

Vi rekommenderar att du använder MsalInterceptor i stället för API:et acquireTokenSilent direkt, men observera att det är valfritt att använda det MsalInterceptor . Du kanske uttryckligen vill hämta token med api:erna acquireToken i stället.

Observera att MsalInterceptor tillhandahålls för enkelhets skull och kanske inte passar alla användningsfall. Vi rekommenderar att du skriver en egen interceptor om du har specifika behov som inte hanteras av MsalInterceptor.

Configuration

Konfigurera MsalInterceptor i app.module.ts

MsalInterceptor kan läggas till i din applikation som provider i app.module.ts, med tillhörande konfiguration. Importen tar in en instans av MSAL, samt två Angular-specifika konfigurationsobjekt. Det tredje argumentet är ett MsalInterceptorConfiguration objekt som innehåller värdena för interactionType, en protectedResourceMapoch en valfri authRequest.

Konfigurationen kan se ut som nedan. Se vårt konfigurationsdokument om andra sätt att konfigurera MSAL Angular för din app.

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

Interaktionstyp

MsalInterceptor Även om den är utformad för att hämta token tyst, i händelse av att en tyst begäran misslyckas, kommer den att återgå till att hämta token interaktivt. InteractionType Kan importeras från @azure/msal-browser och anges till Popup eller Redirect.

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

Skyddad resurskarta

De skyddade resurserna och motsvarande omfång tillhandahålls som en protectedResourceMap i konfigurationen MsalInterceptor .

Url:erna som du anger i protectedResourceMap samlingen är skiftlägeskänsliga. För varje resurs lägger du till omfång som begärs att returneras i åtkomsttoken.

Ett exempel:

• ["user.read"] för Microsoft Graph
• ["<Application ID URL>/scope"] för anpassade webb-API:er (det vill: api://<Application ID>/access_as_user)

Omfång kan anges för en resurs på följande sätt:

1. En matris med omfång som läggs till i varje HTTP-begäran till resursen, oavsett HTTP-metod.

{
    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. En matris med ProtectedResourceScopes, som endast kopplar omfång för specifika HTTP-metoder.

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

Observera att omfång för en resurs kan innehålla en kombination av strängar och ProtectedResourceScopes. I exemplet nedan kommer en GET begäran att ha omfången "all.scope" och "read.scope", medan som PUT begäran bara skulle ha "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. Ett omfångsvärde på null, som anger att en resurs ska vara oskyddad och inte får token. Resurser som inte ingår i protectedResourceMap skyddas inte som standard. Att ange en viss resurs som ska vara oskyddad kan vara användbart när vissa vägar på en resurs ska skyddas och vissa inte är det. Observera att ordningen i protectedResourceMap är viktig, så null-resursen bör placeras före liknande bas-URL:er eller jokertecken.

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

Andra saker att notera om protectedResourceMap:

• Jokertecken: protectedResourceMap stöder användning av * jokertecken. När jokertecken används, om flera matchande poster hittas i protectedResourceMap, används den första träffen (enligt ordningen i protectedResourceMap).
• Relativa sökvägar: Om det finns relativa resurssökvägar i ditt program kan du behöva ange den relativa sökvägen i protectedResourceMap. Detta gäller även för problem som kan uppstå med ngx-translate. Tänk på att den relativa sökvägen i din protectedResourceMap kan behöva ett inledande snedstreck eller inte, beroende på appen, och att du kan behöva prova båda alternativen.

Exakt matchning (strictMatching)

I msal-angular v5 använder URL-komponentmönstermatchning för protectedResourceMap poster strikt matchande semantik som standard. Fältet strictMatching på MsalInterceptorConfiguration styr det här beteendet.

Vad strikt matchning ändrar

Med strikt matchning (v5-standard):

• Ett mönster som *.contoso.com matchar app.contoso.com men intea.b.contoso.com (jokertecken kan inte sträcka sig över punktavgränsare).
• Ett mönster som https://graph.microsoft.com/v1.0/me matchar endast den exakta URL:en.

Vanliga felmönster

Följande protectedResourceMap nyckelmönster fungerar under äldre matchning men misslyckas tyst med strikt matchning:

Standardbeteende i v5 (ingen konfiguration krävs)

Strikt matchning är aktiverat som standard. Ingen ytterligare konfiguration krävs:

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

Att välja bort äldre matchning

Om dina mönster förlitar sig på den lösare matchningen från v4 kan du ställa in strictMatching: false för att tillfälligt behålla det äldre beteendet:

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

Vägledning för miljödrivna konfigurationer

Om dina protectedResourceMap nycklar refererar till Angular-värden environment (till exempel environment.apiConfig.uri), kontrollerar du om dessa värden är exakta sökvägar (till exempel https://graph.microsoft.com/v1.0/me) eller bare base-URL:er (till exempel https://api.example.com). Exakta sökvägar fungerar korrekt med strikt matchning och behöver inte särskild hantering:

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

Om miljövärdet endast är en bas-URL och du behöver matcha underordnade sökvägar lägger du till ett /* jokertecken:

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

För verkligt dynamiska konfigurationer där nyckelformen inte är känd vid byggtiden (till exempel APP_INITIALIZER, JSON-inläst via fetcheller platformBrowserDynamic), anges strictMatching: false som ett tillfälligt säkert standardvärde. Se Åtgärda alternativ – Alternativ B för ett kodexempel.

Felsökning av strikt matchning

Symptoms

• API-begäranden returnerar 401 Obehörig efter uppgradering till @azure/msal-angular v5 (eller mellan v5-delversioner som 5.0.x → 5.1.x).
• Rubrikfältet Authorization: Bearer <token>saknas från utgående HTTP-begäranden.
• Inga build-time- eller runtime-fel rapporteras – felet är tyst.
• Problemet kanske bara visas i vissa miljöer (till exempel mellanlagring/produktion) där API-bas-URL:en skiljer sig från utvecklingen.

Alternativ för att åtgärda

Alternativ A: Uppdatera nycklar så att de fungerar med strikt matchning (rekommenderas)

Uppdatera dina protectedResourceMap nycklar så att de använder exakta sökvägar eller jokertecken som matchar under strikta matchningsregler. Den här metoden är att föredra eftersom strikt matchning är säkrare och mer förutsägbar:

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

Alternativ B: Ange strictMatching: false (återställning för dynamiska konfigurationer)

Om dina protectedResourceMap nycklar läses in dynamiskt vid körning (till exempel från APP_INITIALIZER, JSON-konfiguration eller platformBrowserDynamic) och du inte kan garantera att de innehåller exakta sökvägar eller jokertecken anger du strictMatching: false som ett tillfälligt säkert standardvärde:

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

Körningsvarning

MsalInterceptor genererar en engångs-runtime-varning via MSAL-loggaren under initieringen när strictMatching inte är uttryckligen konfigurerad. Om du ser den här varningen följer du korrigeringsalternativen ovan.

Valfri authRequest

För mer information om det valfria authRequest som kan anges i MsalInterceptorConfiguration, se vår dokumentation om flera klientorganisationer här.

Ändringar från msal-angular v1 till v2

• protectedResourceMap har flyttats till objektet MsalInterceptorConfiguration och kan skickas som Map<string, Array<string|ProtectedResourceScopes>>. MsalAngularConfiguration har blivit inaktuell och fungerar inte längre.
• Det går inte längre att placera rotdomänen i protectedResourceMap för att skydda alla rutter. Använd jokerteckenmatchning i stället.

Mer information om hur du konfigurerar omfång finns i våra vanliga frågor och svar.