Przechwytnika MSAL

Biblioteka MSAL Angular udostępnia klasę Interceptor, która automatycznie pobiera tokeny dla żądań wychodzących wysyłanych za pomocą klienta Angular http do znanych zasobów chronionych. Ten dokument zawiera więcej informacji na temat konfigurowania i używania programu MsalInterceptor.

Mimo że zalecamy bezpośrednie używanie interfejsu MsalInterceptor API zamiast interfejsu acquireTokenSilent API, należy pamiętać, że użycie elementu MsalInterceptor jest opcjonalne. Możesz też zamiast tego jawnie pozyskać tokeny za pomocą interfejsów API acquireToken.

Należy pamiętać, że element MsalInterceptor jest udostępniany dla wygody użytkownika i może nie pasować do wszystkich zastosowań. Zachęcamy do napisania własnego przechwytnika, jeśli mają Państwo szczególne potrzeby, które nie są uwzględnione przez MsalInterceptor.

Konfiguracja

Konfigurowanie MsalInterceptor w app.module.ts

MsalInterceptor można dodać do aplikacji jako dostawcę w pliku app.module.ts wraz z jego konfiguracją. Importy obejmują instancję MSAL, a także dwa obiekty konfiguracji specyficzne dla Angulara. Trzeci argument jest obiektem MsalInterceptorConfiguration , który zawiera wartości interactionType, , protectedResourceMapi opcjonalny authRequest.

Konfiguracja może wyglądać podobnie do poniższej. Zapoznaj się z naszym dokumentem konfiguracji na inne sposoby konfigurowania usługi MSAL Angular dla aplikacji.

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

Typ interakcji

MsalInterceptor Chociaż element jest przeznaczony do uzyskiwania tokenów w trybie dyskretnym, w przypadku niepowodzenia żądania dyskretnego nastąpi powrót do interaktywnego uzyskiwania tokenów. Element InteractionType można zaimportować z @azure/msal-browser i ustawić na Popup lub Redirect.

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

Mapa chronionych zasobów

Chronione zasoby i odpowiadające im zakresy są udostępniane jako protectedResourceMap w MsalInterceptor konfiguracji.

Adresy URL podane w kolekcji protectedResourceMap rozróżniają wielkość liter. Dla każdego zasobu dodaj żądane zakresy, które mają zostać zwrócone w tokenie dostępu.

Przykład:

  • ["user.read"] dla Microsoft Graph
  • ["<Application ID URL>/scope"] dla niestandardowych internetowych API (czyli api://<Application ID>/access_as_user)

Zakresy można określić dla zasobu w następujący sposób:

  1. Tablica zakresów, która zostanie dodana do każdego żądania HTTP do tego zasobu, niezależnie od metody HTTP.
{
    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. Tablica elementów ProtectedResourceScopes, które będą dołączać zakresy tylko dla określonych metod HTTP.
{
    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"]
            }
        ]]
    ])
}

Należy pamiętać, że zakresy zasobu mogą zawierać kombinację ciągów i ProtectedResourceScopes. W poniższym przykładzie żądanie GET będzie miało zakresy "all.scope" i "read.scope", natomiast żądanie PUT będzie miało tylko "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. Wartość zakresu wskazująca null, że zasób ma być niechroniony i nie otrzyma tokenów. Zasoby nieuwzględnione w elemencie protectedResourceMap nie są domyślnie chronione. Określenie określonego zasobu, który ma być niechroniony, może być przydatne, gdy niektóre trasy w zasobie mają być chronione, a niektóre nie. Należy pamiętać, że kolejność w elemencie protectedResourceMap ma znaczenie, dlatego zasób null należy umieścić przed podobnymi bazowymi adresami URL lub symbolami wieloznacznymi.
{
    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"]]
    ]),
}

Inne kwestie dotyczące elementu protectedResourceMap, na które należy zwrócić uwagę:

  • Symbole wieloznaczne: protectedResourceMap obsługuje używanie * symboli wieloznacznych. W przypadku użycia symboli wieloznacznych, jeśli w elemencie protectedResourceMap zostanie znalezionych wiele pasujących wpisów, użyte zostanie pierwsze znalezione dopasowanie (na podstawie kolejności elementów protectedResourceMap).
  • Ścieżki względne: jeśli w aplikacji istnieją względne ścieżki zasobów, może być konieczne podanie ścieżki względnej w pliku protectedResourceMap. Dotyczy to również problemów, które mogą wystąpić z ngx-translate. Pamiętaj, że ścieżka względna w elemencie protectedResourceMap może, zależnie od aplikacji, wymagać ukośnika na początku lub nie, więc może być konieczne wypróbowanie obu wariantów.

Dokładne dopasowanie (strictMatching)

W msal-angular v5 wzorzec składnika adresu URL pasujący do protectedResourceMap wpisów domyślnie używa ściśle pasującej semantyki. Pole strictMatching w obszarze MsalInterceptorConfiguration steruje tym zachowaniem.

Ważna

Jeśli aplikacja dynamicznie ustawia klucze protectedResourceMap (na przykład na podstawie plików środowiskowych, APP_INITIALIZER lub konfiguracji JSON), a klucze te są bazowymi adresami URL bez podścieżek lub symboli wieloznacznych, ścisłe dopasowanie może po cichu uniemożliwić dołączenie nagłówka Authorization. Powoduje to błędy 401 bez błędu w czasie kompilacji i bez ostrzeżenia dla poszczególnych żądań — tylko jednokrotne ostrzeżenie inicjowania, jeśli strictMatching nie jest jawnie skonfigurowane. Aby uzyskać szczegółowe informacje, zobacz Rozwiązywanie problemów ze ścisłym dopasowywaniem .

Jakie ścisłe zmiany dopasowania

Behavior Starsza wersja (strictMatching: false) Strict (wartość domyślna w wersji 5)
Metacharacter ucieka . i inne metaznaki wyrażeń regularnych nie są poprzedzone znakiem ucieczki; działają jak operatory wyrażeń regularnych Wszystkie metaznaki (w tym .) są traktowane jako znaki dosłowne
Kotwiczenie Wzorzec może pasować w dowolnym miejscu w ciągu znaków Wzorzec musi być zgodny z pełnym ciągiem (^…$)
Symbol wieloznaczny nazwy hosta (*) * pasuje do dowolnej sekwencji znaków, w tym . * pasuje do dowolnej sekwencji znaków, która nie zawiera . (symbole wieloznaczne pozostają w jednej etykiecie DNS)
Ścieżka/wyszukiwanie/symbol wieloznaczny skrótu (*) * pasuje do dowolnej sekwencji znaków * pasuje do dowolnej sekwencji znaków (bez zmian)
? znak Przekazywane do bazowego wyrażenia regularnego Traktowane jako literal? (separator parametrów zapytania w adresie URL, a nie symbol wieloznaczny)

Z ścisłym dopasowaniem (ustawienie domyślne w wersji 5):

  • Wzorzec taki jak *.contoso.com dopasowuje app.contoso.com, ale niea.b.contoso.com (symbol wieloznaczny nie może obejmować separatorów w postaci kropek).
  • Wzorzec taki jak https://graph.microsoft.com/v1.0/me pasuje tylko do tego dokładnego adresu URL.

Typowe wzorce błędów

Następujące protectedResourceMap wzorce kluczy działają w trybie starszego dopasowania, ale po cichu zawodzą przy ścisłym dopasowaniu:

Schemat klucza Adres URL żądania wychodzącego Wynik przy ścisłym dopasowaniu Napraw.
https://api.example.com https://api.example.com/v1/users Brak dopasowania — klucz wskazuje ścieżkę /, żądanie ma ścieżkę /v1/users https://api.example.com/*
https://api.example.com/ https://api.example.com/v1/users Brak dopasowania — ukośnik na końcu zakotwicza wzorzec dokładnie do / https://api.example.com/*
environment.apiConfig.uri (na przykład https://api.example.com) https://api.example.com/v1/users Brak dopasowania — tak samo jak powyżej `${environment.apiConfig.uri}/*`

Domyślne zachowanie w wersji 5 (nie jest wymagana konfiguracja)

Ścisłe dopasowywanie jest domyślnie włączone. Nie jest wymagana żadna dodatkowa konfiguracja:

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

Rezygnacja ze starszego mechanizmu dopasowywania

Jeśli Twoje wzorce opierają się na mniej rygorystycznym dopasowywaniu z v4, możesz tymczasowo ustawić strictMatching: false, aby zachować dotychczasowe działanie:

Note

Starsze dopasowanie (strictMatching: false) jest zapewniane na potrzeby zgodności z poprzednimi wersjami i może zostać usunięte w przyszłej wersji głównej. Zalecamy zaktualizowanie protectedResourceMap wzorców tak, aby działały ze ścisłym dopasowaniem.

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

Wskazówki dotyczące konfiguracji opartych na środowisku

Jeśli klucze protectedResourceMap odwołują się do wartości Angular environment (na przykład environment.apiConfig.uri), sprawdź, czy te wartości są dokładnymi ścieżkami (na przykład https://graph.microsoft.com/v1.0/me) czy bazowymi adresami URL (na przykład https://api.example.com). Dokładne ścieżki działają prawidłowo z ścisłym dopasowaniem i nie wymagają specjalnej obsługi:

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

Jeśli wartość zmiennej środowiskowej jest samym podstawowym adresem URL i musisz dopasować podścieżki, dodaj symbol wieloznaczny /*:

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

W przypadku naprawdę dynamicznych konfiguracji, w których kształt klucza nie jest znany w czasie kompilacji (na przykład APP_INITIALIZER, plik JSON załadowany za pośrednictwem fetchlub platformBrowserDynamic), ustaw strictMatching: false jako tymczasową bezpieczną wartość domyślną. Zobacz Opcje poprawki — opcja B , aby zapoznać się z przykładem kodu.

Rozwiązywanie problemów ze ścisłym dopasowywaniem

Symptoms
  • Żądania API zwracają 401 Unauthorized po uaktualnieniu do wersji @azure/msal-angular 5 (lub między podrzędnymi wersjami v5, takimi jak 5.0.x → 5.1.x).
  • Brak nagłówka Authorization: Bearer <token>w wychodzących żądaniach HTTP.
  • Nie są zgłaszane żadne błędy czasu kompilacji ani czasu wykonywania — błąd jest cichy.
  • Problem może występować tylko w niektórych środowiskach (na przykład w środowisku przejściowym/produkcyjnym), gdzie podstawowy adres URL interfejsu API różni się od programowania.
Opcje naprawy

Opcja A: Aktualizowanie kluczy w celu pracy z ścisłym dopasowaniem (zalecane)

Zaktualizuj klucze protectedResourceMap tak, aby używały dokładnych ścieżek lub symboli wieloznacznych pasujących zgodnie ze ścisłymi zasadami dopasowywania. Takie podejście jest preferowane, ponieważ ścisłe dopasowywanie jest bezpieczniejsze i bardziej przewidywalne:

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

Opcja B: Ustaw strictMatching: false (awaryjnie dla konfiguracji dynamicznych)

Jeśli Twoje klucze protectedResourceMap są ładowane dynamicznie w czasie wykonywania (na przykład z APP_INITIALIZER, pliku JSON z konfiguracją lub platformBrowserDynamic) i nie możesz zagwarantować, że zawierają dokładne ścieżki ani symbole wieloznaczne, ustaw strictMatching: false jako tymczasową bezpieczną wartość domyślną:

{
    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

Starsze dopasowanie (strictMatching: false) jest zapewniane na potrzeby zgodności z poprzednimi wersjami i może zostać usunięte w przyszłej wersji głównej.

Ostrzeżenie dotyczące środowiska uruchomieniowego

MsalInterceptor generuje jednorazowe ostrzeżenie w czasie wykonywania za pośrednictwem rejestratora MSAL podczas inicjalizacji, gdy strictMatching nie jest jawnie skonfigurowane. Jeśli widzisz to ostrzeżenie, postępuj zgodnie z powyższymi opcjami poprawki.

Opcjonalny authRequest

Aby uzyskać więcej informacji na temat opcjonalnych ustawień authRequest, które można skonfigurować w MsalInterceptorConfiguration, zapoznaj się z naszą dokumentacją dotyczącą architektury wielodzierżawnej tutaj.

Zmiany w msal-angular z wersji v1 na v2

Note

Element unprotectedResourceMap w msAL Angular v1 MsalAngularConfiguration został przestarzały i już nie działa.

  • protectedResourceMap został przeniesiony do MsalInterceptorConfiguration obiektu i można go przekazać jako Map<string, Array<string|ProtectedResourceScopes>>. MsalAngularConfiguration został przestarzały i już nie działa.
  • Umieszczenie domeny głównej w elemencie protectedResourceMap, aby chronić wszystkie ścieżki, nie jest już obsługiwane. Zamiast tego użyj dopasowywania za pomocą symboli wieloznacznych.

Aby uzyskać więcej informacji na temat konfigurowania zakresów, zobacz często zadawane pytania.

  • Last updated on