Průsečík MSAL

MSAL Angular poskytuje Interceptor třídu, která automaticky získává tokeny pro odchozí požadavky, které používají klienta Angular http ke známým chráněným prostředkům. Tento dokument obsahuje další informace o konfiguraci a použití nástroje MsalInterceptor.

I když doporučujeme používat MsalInterceptor namísto přímého použití rozhraní API acquireTokenSilent, mějte na paměti, že použití MsalInterceptor je volitelné. Místo toho můžete chtít explicitně získat tokeny pomocí rozhraní API acquireToken.

Upozorňujeme, že MsalInterceptor je k dispozici pro vaše pohodlí a nemusí vyhovovat všem případům použití. Doporučujeme vám napsat vlastní interceptor, pokud máte specifické potřeby, které MsalInterceptor neřeší.

Konfigurace

Konfigurace MsalInterceptor v souboru app.module.ts

MsalInterceptor můžete do své aplikace přidat jako provider v souboru app.module.ts, včetně jeho konfigurace. Importy zahrnují instanci MSAL a také dva konfigurační objekty specifické pro Angular. Třetí argument je MsalInterceptorConfiguration objekt, který obsahuje hodnoty pro interactionType, protectedResourceMapa a volitelné authRequest.

Vaše konfigurace může vypadat podobně jako v následujícím příkladu. Podívejte se na náš konfigurační dokument o dalších způsobech konfigurace MSAL Angular pro vaši aplikaci.

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 interakce

I když je MsalInterceptor navržen tak, aby získával tokeny bez zásahu uživatele, pokud takový požadavek selže, přejde na interaktivní získání tokenů. Lze InteractionType importovat z @azure/msal-browser a nastavit na Popup nebo Redirect.

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

Mapa chráněných zdrojů

Chráněné prostředky a odpovídající obory jsou poskytovány jako protectedResourceMap v MsalInterceptor konfiguraci.

Adresy URL, které zadáte v kolekci protectedResourceMap , rozlišují malá a velká písmena. Pro každý prostředek přidejte rozsahy, které se mají vrátit v přístupovém tokenu.

Příklad:

• ["user.read"] pro Microsoft Graph
• ["<Application ID URL>/scope"] pro vlastní webová rozhraní API (to znamená api://<Application ID>/access_as_user)

Obory lze pro prostředek zadat následujícími způsoby:

1. Pole rozsahů oprávnění, které budou přidány ke každému požadavku HTTP na daný prostředek bez ohledu na použitou metodu 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. Pole ProtectedResourceScopes, které připojí obory pouze pro konkrétní metody 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"]
            }
        ]]
    ])
}

Všimněte si, že oblasti působnosti prostředku mohou obsahovat kombinaci řetězců a ProtectedResourceScopes. V níže uvedeném příkladu bude mít požadavek GET rozsahy oprávnění "all.scope" a "read.scope", zatímco požadavek PUT bude mít jen "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. Hodnota oboru null, která označuje, že prostředek nemá být chráněný a nebude dostávat tokeny. Zdroje, které nejsou součástí protectedResourceMap, nejsou ve výchozím nastavení chráněny. Určení konkrétního prostředku, který má být nechráněný, může být užitečné, když jsou některé trasy v prostředku chráněné a některé ne. Všimněte si, že na pořadí v protectedResourceMap záleží, takže prázdný prostředek by měl být uveden před všemi podobnými základními adresami URL nebo zástupnými znaky.

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

Další věci, které je třeba poznamenat týkající se protectedResourceMap:

• Zástupné znaky: protectedResourceMap podporuje použití * jako zástupného znaku. Při použití zástupných znaků platí, že pokud je v protectedResourceMap nalezeno více odpovídajících položek, použije se první nalezená odpovídající položka (na základě pořadí protectedResourceMap).
• Relativní cesty: Pokud vaše aplikace obsahuje relativní cesty ke zdrojům, možná bude nutné zadat relativní cestu do protectedResourceMap. To platí také pro problémy, ke kterým může dojít při překladu ngx. Mějte na paměti, že relativní cesta v prvku protectedResourceMap může nebo nemusí vyžadovat úvodní lomítko v závislosti na vaší aplikaci, a možná bude nutné vyzkoušet obě možnosti.

Přesná shoda (strictMatching)

V msal-angular v5 používá porovnávání vzorů komponent URL pro položky protectedResourceMap ve výchozím nastavení striktní sémantiku porovnávání. Pole strictMatching na MsalInterceptorConfiguration určuje toto chování.

Jaké striktní změny párování

Při striktní shodě (výchozí nastavení v5):

• Vzor jako *.contoso.com odpovídá app.contoso.com, ale nea.b.contoso.com (zástupný znak nemůže přesahovat oddělovače teček).
• Vzor jako https://graph.microsoft.com/v1.0/me odpovídá pouze té přesné adrese URL.

Běžné vzory selhání

Následující protectedResourceMap vzory klíčů fungují při legacy matching, ale při striktním porovnávání selžou bez upozornění:

Výchozí chování v 5 (nevyžaduje se konfigurace)

Ve výchozím nastavení je povolené striktní porovnávání. Nevyžaduje se žádná další konfigurace:

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

Odhlášení ze starší verze párování

Pokud vaše vzory spoléhají na volné párování z v4, můžete nastavit strictMatching: false , aby se starší chování dočasně zachovalo:

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

Pokyny pro konfigurace řízené prostředím

Pokud vaše klíče protectedResourceMap odkazují na hodnoty environment v Angularu (například environment.apiConfig.uri), zkontrolujte, zda jsou tyto hodnoty přesné cesty (například https://graph.microsoft.com/v1.0/me), nebo samotné základní adresy URL (například https://api.example.com). Přesné cesty fungují správně při striktní shodě a nevyžadují speciální zacházení:

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

Pokud je hodnota prostředí pouze základní adresa URL a potřebujete, aby odpovídala i podcestám, přidejte zástupný znak /*:

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

Pro skutečně dynamické konfigurace, ve kterých není obrazec klíče známý v době sestavení (například APP_INITIALIZERJSON načtený prostřednictvím fetchnebo platformBrowserDynamic), je nastavený strictMatching: false jako dočasné bezpečné výchozí nastavení. Viz Možnosti opravy – Možnost B pro příklad kódu.

Řešení potíží s striktním párováním

Příznaky

• Požadavky API vracejí 401 Unauthorized po upgradu na @azure/msal-angular v5 (nebo mezi dílčími verzemi v5, jako jsou 5.0.x → 5.1.x).
• V odchozích požadavcích HTTP Authorization: Bearer <token> hlavička.
• Nejsou hlášeny žádné chyby při sestavení ani za běhu — selhání je tiché.
• Problém se může objevit jenom v určitých prostředích (například v přípravném nebo produkčním prostředí), kde se základní adresa URL rozhraní API liší od vývoje.

Oprava možností

Možnost A: Aktualizace klíčů tak, aby fungovaly se striktní shodou (doporučeno)

Aktualizujte své protectedResourceMap klíče tak, aby používaly přesné cesty nebo zástupné znaky, které odpovídají přísným pravidlům porovnávání. Tento přístup se upřednostňuje, protože striktní porovnávání je bezpečnější a předvídatelnější:

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

Možnost B: Nastavte strictMatching: false (záložní varianta pro dynamické konfigurace)

Pokud se vaše klíče protectedResourceMap načítají dynamicky za běhu aplikace (například z APP_INITIALIZER, konfigurace JSON nebo platformBrowserDynamic) a nemůžete zaručit, že obsahují přesné cesty nebo zástupné znaky, nastavte strictMatching: false jako dočasné bezpečné výchozí nastavení:

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

Upozornění modulu runtime

MsalInterceptor vypíše během inicializace v loggeru MSAL jednorázové upozornění za běhu, pokud strictMatching není explicitně nakonfigurován. Pokud se zobrazí toto upozornění, postupujte podle výše uvedených možností opravy.

Volitelný authRequest

Další informace o volitelném nastavení authRequest, které lze nastavit v MsalInterceptorConfiguration, najdete v naší dokumentaci k architektuře multi-tenant zde.

Změny z msal-angular v1 na v2

• protectedResourceMap byl přesunut do objektu MsalInterceptorConfiguration a lze jej předat jako Map<string, Array<string|ProtectedResourceScopes>>. MsalAngularConfiguration je zastaralý a už nefunguje.
• Vložení kořenové domény do značky protectedResourceMap za účelem ochrany všech tras již není podporováno. Místo toho použijte porovnávání pomocí zástupných znaků.

Další informace o konfiguraci oborů najdete v našich nejčastějších dotazech.