MSAL Interceptor

MSAL Angular stellt eine Interceptor Klasse bereit, die automatisch Token für ausgehende Anforderungen abruft, die den Angular-Client http für bekannte geschützte Ressourcen verwenden. Dieses Dokument enthält weitere Informationen zum Konfigurieren und Verwenden von MsalInterceptor.

Wir empfehlen zwar, MsalInterceptor anstelle der acquireTokenSilent-API direkt zu verwenden, bitte beachten Sie jedoch, dass die Verwendung von MsalInterceptor optional ist. Sie können stattdessen Token explizit mithilfe der acquireToken-APIs beziehen.

Bitte beachten Sie, dass dies MsalInterceptor für Ihren Komfort vorgesehen ist und möglicherweise nicht allen Anwendungsfällen entspricht. Wir ermutigen Sie, Ihren eigenen Interceptor zu implementieren, wenn Sie spezifische Anforderungen haben, die von der MsalInterceptor nicht abgedeckt werden.

Configuration

Konfiguration von MsalInterceptor in app.module.ts

Die MsalInterceptor kann Ihrer Anwendung in der app.module.ts als Provider zusammen mit ihrer Konfiguration hinzugefügt werden. Die Importe übernehmen eine Instanz von MSAL sowie zwei Angular-spezifische Konfigurationsobjekte. Das dritte Argument ist ein MsalInterceptorConfiguration Objekt, das die Werte für interactionType, a protectedResourceMapund optional authRequestenthält.

Ihre Konfiguration sieht möglicherweise wie unten aus. Weitere Möglichkeiten zum Konfigurieren von MSAL Angular für Ihre App finden Sie in unserem Konfigurationsdokument .

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

Obwohl MsalInterceptor dafür ausgelegt ist, Token im Hintergrund abzurufen, wird bei einem Fehlschlagen einer Anforderung im Hintergrund auf das interaktive Abrufen von Token zurückgegriffen. Die InteractionType Kann aus @azure/msal-browser importiert und auf Popup oder Redirectfestgelegt werden.

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

Übersicht geschützter Ressourcen

Die geschützten Ressourcen und die entsprechenden Bereichsangaben werden als protectedResourceMap in der MsalInterceptor-Konfiguration angegeben.

Bei den URLs, die Sie in der protectedResourceMap Auflistung angeben, wird die Groß-/Kleinschreibung beachtet. Fügen Sie für jede Ressource angeforderte Bereiche hinzu, die im Zugriffstoken zurückgegeben werden sollen.

Beispiel:

• ["user.read"] für Microsoft Graph
• ["<Application ID URL>/scope"] für benutzerdefinierte Web-APIs (d. h. api://<Application ID>/access_as_user)

Bereiche können für eine Ressource auf folgende Weise angegeben werden:

1. Ein Array von Bereichen, das jeder HTTP-Anforderung zu dieser Ressource hinzugefügt wird, unabhängig von der 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. Ein Array von ProtectedResourceScopes, das Bereiche nur für bestimmte HTTP-Methoden anfügt.

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

Beachten Sie, dass Scopes einer Ressource eine Kombination aus Strings und ProtectedResourceScopes enthalten können. Im folgenden Beispiel verfügt eine GET Anfrage über die Berechtigungsumfänge "all.scope" und "read.scope", während eine PUT Anfrage nur "all.scope" hätte.

{
    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. Ein Scope-Wert von null, der angibt, dass eine Ressource ungeschützt sein soll und keine Token erhalten wird. Nicht enthaltene protectedResourceMap Ressourcen sind standardmäßig nicht geschützt. Die Angabe einer bestimmten Ressource, die nicht geschützt werden soll, kann nützlich sein, wenn einige Routen für eine Ressource geschützt werden sollen und einige nicht. Beachten Sie, dass die Reihenfolge in protectedResourceMap wichtig ist; daher sollte die null-Ressource vor ähnlichen Basis-URLs oder Platzhaltern platziert werden.

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

Weitere Punkte, die bezüglich des protectedResourceMap zu beachten sind:

• Wildcards: protectedResourceMap unterstützt die Verwendung * für Wildcards. Bei Verwendung von Platzhaltern gilt: Wenn im protectedResourceMap mehrere übereinstimmende Einträge gefunden werden, wird der erste gefundene Treffer verwendet (basierend auf der Reihenfolge der protectedResourceMap).
• Relative Pfade: Wenn Ihre Anwendung relative Ressourcenpfade enthält, müssen Sie unter Umständen den relativen Pfad in protectedResourceMap angeben. Dies gilt auch für Probleme, die bei ngx-translate auftreten können. Beachten Sie, dass der relative Pfad in Ihrem protectedResourceMap je nach App möglicherweise einen führenden Schrägstrich benötigt oder auch nicht und dass Sie gegebenenfalls beide Varianten ausprobieren müssen.

Strikte Übereinstimmung (strictMatching)

In msal-angular v5 verwendet der Musterabgleich für URL-Komponenten bei den protectedResourceMap-Einträgen standardmäßig eine strikte Abgleichssemantik. Das Feld strictMatching in MsalInterceptorConfiguration steuert dieses Verhalten.

Welche strengen Abgleichsänderungen

Mit exakter Übereinstimmung (die Standardeinstellung in v5):

• Ein Muster wie *.contoso.com entspricht app.contoso.com aber nichta.b.contoso.com (ein Platzhalter kann keine durch Punkte getrennten Segmente überspannen).
• Ein Muster wie https://graph.microsoft.com/v1.0/me entspricht nur genau dieser URL.

Häufige Fehlermuster

Die folgenden protectedResourceMap Schlüsselmuster funktionieren beim Legacy-Abgleich, schlagen jedoch bei strikter Übereinstimmung stillschweigend fehl:

Standardverhalten in v5 (keine Konfiguration erforderlich)

Der strenge Abgleich ist standardmäßig aktiviert. Es ist keine zusätzliche Konfiguration erforderlich:

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

Legacy-Abgleich deaktivieren

Wenn Ihre Muster auf der weniger strikten Übereinstimmung aus v4 basieren, können Sie strictMatching: false festlegen, um das Legacy-Verhalten vorübergehend beizubehalten:

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

Leitfaden für umgebungsgesteuerte Konfigurationen

Wenn Ihre protectedResourceMap-Schlüssel auf Angular-environment-Werte verweisen (zum Beispiel environment.apiConfig.uri), prüfen Sie, ob diese Werte exakte Pfade (zum Beispiel https://graph.microsoft.com/v1.0/me) oder reine Basis-URLs (zum Beispiel https://api.example.com) sind. Exakte Pfade funktionieren bei strikter Übereinstimmung korrekt und benötigen keine Sonderbehandlung:

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

Wenn der Umgebungswert eine bare Basis-URL ist und Sie Unterpfade abgleichen müssen, fügen Sie einen /* Wildcard an:

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

Bei wirklich dynamischen Konfigurationen, bei denen die Struktur der Schlüssel zur Build-Zeit nicht bekannt ist (zum Beispiel APP_INITIALIZER, per fetch geladenes JSON oder platformBrowserDynamic), legen Sie strictMatching: false als vorübergehend sicheren Standardwert fest. Siehe Fixoptionen – Option B für ein Codebeispiel.

Problembehandlung beim strengen Abgleich

Symptome

• API-Anforderungen geben 401 Unauthorized nach dem Upgrade auf @azure/msal-angular v5 zurück (oder zwischen v5-Nebenversionen wie 5.0.x → 5.1.x).
• Der Authorization: Bearer <token> Header fehlt bei ausgehenden HTTP-Anforderungen.
• Es werden keine Buildzeit- oder Laufzeitfehler gemeldet – der Fehler wird im Hintergrund ausgeführt.
• Das Problem kann nur in bestimmten Umgebungen (z. B. Staging/Produktion) auftreten, bei denen sich die API-Basis-URL von der Entwicklung unterscheidet.

Optionen zur Fehlerbehebung

Option A: Aktualisieren von Schlüsseln für die Arbeit mit striktem Abgleich (empfohlen)

Aktualisieren Sie Ihre protectedResourceMap Schlüssel, um genaue Pfade oder Wildcards zu verwenden, die mit strengen Übereinstimmungsregeln übereinstimmen. Dieser Ansatz wird bevorzugt, da strenge Übereinstimmungen sicherer und vorhersehbarer sind:

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

Option B: Festlegen strictMatching: false (Fallback für dynamische Konfigurationen)

Wenn Ihre protectedResourceMap Schlüssel dynamisch zur Laufzeit geladen werden (z. B. aus APP_INITIALIZER, JSON-Konfiguration oder platformBrowserDynamic), und Sie können nicht garantieren, dass sie genaue Pfade oder Wildcards enthalten, legen strictMatching: false Sie sie als temporären sicheren Standardwert fest:

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

Laufzeitwarnung

MsalInterceptor gibt eine einmalige Laufzeitwarnung über den MSAL-Logger während der Initialisierung aus, wenn strictMatching sie nicht explizit konfiguriert ist. Wenn diese Warnung angezeigt wird, folgen Sie den oben aufgeführten Fixoptionen.

Optionaler Authentifizierungsanforderung

Weitere Informationen zu den optionalen authRequest, die in MsalInterceptorConfiguration festgelegt werden können, finden Sie bitte hier in unserer Dokumentation zu mehreren Mandanten.

Änderungen von msal-angular v1 zu v2

• protectedResourceMap wurde in das MsalInterceptorConfiguration-Objekt verschoben und kann als Map<string, Array<string|ProtectedResourceScopes>> übergeben werden. MsalAngularConfiguration wurde als veraltet eingestuft und funktioniert nicht mehr.
• Das Platzieren der Root-Domain in protectedResourceMap, um alle Routen zu schützen, wird nicht mehr unterstützt. Verwenden Sie stattdessen den Wildcardabgleich.

Weitere Informationen zum Konfigurieren von Bereichen finden Sie in unseren HÄUFIG gestellten Fragen.