MSAL Interceptor

MSAL Angular biedt een Interceptor klasse die automatisch tokens verkrijgt voor uitgaande aanvragen die gebruikmaken van de Angular-client http voor bekende beveiligde resources. Dit document bevat meer informatie over het configureren en gebruiken van de MsalInterceptor.

Hoewel we aanbevelen om MsalInterceptor te gebruiken in plaats van de acquireTokenSilent API rechtstreeks te gebruiken, moet u er rekening mee houden dat het gebruik van de MsalInterceptor optioneel is. U kunt in plaats daarvan expliciet tokens verkrijgen met behulp van de acquireToken-API's.

Houd er rekening mee dat het MsalInterceptor voor uw gemak is voorzien en mogelijk niet in alle gebruiksscenario's past. We raden u aan uw eigen interceptor te schrijven als u specifieke vereisten hebt waarvoor de MsalInterceptor geen oplossing biedt.

Configuratie

Het configureren van de MsalInterceptor in de app.module.ts

De MsalInterceptor kan worden toegevoegd aan uw toepassing als provider in de app.module.ts, met de configuratie ervan. De import neemt een exemplaar van MSAL en twee Angular-specifieke configuratieobjecten in beslag. Het derde argument is een MsalInterceptorConfiguration object dat de waarden voor interactionType, a protectedResourceMapen een optioneel authRequestobject bevat.

Uw configuratie ziet er mogelijk uit zoals hieronder. Bekijk ons configuratiedocumenten op andere manieren om MSAL Angular voor uw app te configureren.

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

Interactietype

Hoewel de MsalInterceptor is ontworpen om tokens zonder gebruikersinteractie te verkrijgen, schakelt deze over op het interactief verkrijgen van tokens als een aanvraag zonder gebruikersinteractie mislukt. De InteractionType kan worden geïmporteerd uit @azure/msal-browser en ingesteld op Popup of Redirect.

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

Overzicht van beveiligde resources

De beveiligde resources en de bijbehorende scopes worden opgegeven als een protectedResourceMap in de configuratie van MsalInterceptor.

De URL's die u in de protectedResourceMap verzameling opgeeft, zijn hoofdlettergevoelig. Voeg voor elke resource de scopes toe die worden aangevraagd om in het toegangstoken te worden opgenomen.

Voorbeeld:

• ["user.read"] voor Microsoft Graph
• ["<Application ID URL>/scope"] voor aangepaste web-API's (dat wil zeggen, api://<Application ID>/access_as_user)

Scopes kunnen voor een resource op de volgende manieren worden gespecificeerd:

1. Een array van scopes die aan elke HTTP-aanvraag voor die resource worden toegevoegd, ongeacht de HTTP-methode.

{
    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. Een array van ProtectedResourceScopes, die alleen scopes koppelt voor specifieke HTTP-methoden.

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

Houd er rekening mee dat scopes voor een resource kunnen bestaan uit een combinatie van tekenreeksen en ProtectedResourceScopes. In het onderstaande voorbeeld heeft een GET verzoek de scopes "all.scope" en "read.scope", terwijl een PUT verzoek alleen "all.scope" zou hebben.

{
    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. Een bereikwaarde van null, waarmee wordt aangegeven dat een resource niet moet worden beveiligd en geen tokens worden opgehaald. Resources die niet in de protectedResourceMap resources zijn opgenomen, worden standaard niet beveiligd. Het opgeven van een bepaalde resource die niet moet worden beveiligd, kan handig zijn wanneer sommige routes op een resource moeten worden beveiligd en sommige niet. Houd er rekening mee dat de volgorde in protectedResourceMap van belang is, dus null-resource moet vóór vergelijkbare basis-URL's of jokertekens worden geplaatst.

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

Andere zaken om op te letten met betrekking tot de protectedResourceMap:

• Jokertekens: protectedResourceMap ondersteunt het gebruik van * jokertekens. Wanneer u jokertekens gebruikt, als er meerdere overeenkomende vermeldingen worden gevonden in de protectedResourceMap, wordt de eerste gevonden overeenkomst gebruikt (op basis van de volgorde van de protectedResourceMap).
• Relatieve paden: als er relatieve resourcepaden in uw toepassing zijn, moet u mogelijk het relatieve pad opgeven in de protectedResourceMap. Dit geldt ook voor problemen die zich kunnen voordoen met ngx-translate. Houd er rekening mee dat het relatieve pad in uw protectedResourceMap, afhankelijk van uw app, al dan niet een slash aan het begin nodig heeft en dat u mogelijk beide varianten moet proberen.

Exacte overeenkomst (strictMatching)

In msal-angular v5 maakt het URL-onderdeelpatroon voor protectedResourceMap vermeldingen standaard gebruik van strikte overeenkomende semantiek. Dit gedrag wordt bepaald door het strictMatching veld in MsalInterceptorConfiguration het veld.

Welke strikte overeenkomende wijzigingen

Met strikte overeenkomst (de v5-standaard):

• Een patroon zoals *.contoso.com komt overeen met app.contoso.com, maar nieta.b.contoso.com (een jokerteken kan geen puntscheidingstekens overspannen).
• Een patroon zoals https://graph.microsoft.com/v1.0/me komt alleen overeen met die exacte URL.

Bekende foutpatronen

De volgende protectedResourceMap sleutelpatronen werken bij legacy-matching, maar falen stilzwijgend bij strikte matching:

Standaardgedrag in v5 (geen configuratie nodig)

Strikte overeenkomsten zijn standaard ingeschakeld. Er is geen aanvullende configuratie vereist:

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

Afmelden voor verouderde matching

Als uw patronen afhankelijk zijn van de lossere matching uit v4, kunt u strictMatching: false instellen om het oude gedrag tijdelijk te behouden:

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

Richtlijnen voor omgevingsgestuurde configuraties

Als uw protectedResourceMap sleutels verwijzen naar Angular-waarden environment (bijvoorbeeld environment.apiConfig.uri), controleert u of deze waarden exacte paden zijn (bijvoorbeeld https://graph.microsoft.com/v1.0/me) of lege basis-URL's (bijvoorbeeld https://api.example.com). Exacte paden werken goed met strikte matching en vereisen geen speciale afhandeling:

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

Als de omgevingswaarde een lege basis-URL is en u moet overeenkomen met subpaden, voegt u een /* jokerteken toe:

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

Voor echt dynamische configuraties waarbij de vorm van de sleutels niet bekend is tijdens het bouwen (bijvoorbeeld APP_INITIALIZER, JSON geladen via fetch of platformBrowserDynamic), stel strictMatching: false in als een veilige tijdelijke standaardwaarde. Zie Oplossingsopties: optie B voor een codevoorbeeld.

Problemen met strikte overeenkomsten oplossen

Symptomen

• API-aanvragen retourneren 401 Niet geautoriseerd na een upgrade naar @azure/msal-angular v5 (of tussen v5 secundaire versies, zoals 5.0.x → 5.1.x).
• De Authorization: Bearer <token> header ontbreekt in uitgaande HTTP-aanvragen.
• Er worden geen fouten tijdens het buildproces of tijdens runtime gemeld — de mislukking verloopt stilzwijgend.
• Het probleem wordt mogelijk alleen weergegeven in bepaalde omgevingen (bijvoorbeeld fasering/productie), waarbij de API-basis-URL verschilt van ontwikkeling.

Herstelopties

Optie A: Sleutels bijwerken om te werken met strikte overeenkomsten (aanbevolen)

Werk uw protectedResourceMap sleutels bij om exacte paden of jokertekens te gebruiken die overeenkomen onder strikte overeenkomende regels. Deze benadering heeft de voorkeur omdat strikte overeenkomsten veiliger en voorspelbaarder zijn:

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

Optie B: instellen strictMatching: false (terugval voor dynamische configuraties)

Als uw protectedResourceMap sleutels dynamisch worden geladen tijdens runtime (bijvoorbeeld van APP_INITIALIZER, JSON-configuratie of platformBrowserDynamic) en u niet kunt garanderen dat ze exacte paden of jokertekens bevatten, ingesteld strictMatching: false als een tijdelijke veilige standaardwaarde:

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

Runtime-waarschuwing

MsalInterceptor verzendt een eenmalige runtimewaarschuwing via de MSAL-logboekregistratie tijdens de initialisatie wanneer strictMatching deze niet expliciet is geconfigureerd. Als u deze waarschuwing ziet, volgt u de bovenstaande oplossingsopties.

Optionele authRequest

Zie het authRequest voor meer informatie over de optionele MsalInterceptorConfiguration opties die kunnen worden ingesteld in het document.

Wijzigingen van msal-angular v1 in v2

• protectedResourceMap is verplaatst naar het MsalInterceptorConfiguration object en kan worden doorgegeven als Map<string, Array<string|ProtectedResourceScopes>>. MsalAngularConfiguration is afgeschaft en werkt niet meer.
• Het rootdomein in de protectedResourceMap plaatsen om alle routes te beveiligen wordt niet langer ondersteund. Gebruik in plaats daarvan jokertekens.

Zie onze FAQ’s voor meer informatie over het configureren van scopes.