Intercettore MSAL

MSAL Angular fornisce una Interceptor classe che acquisisce automaticamente i token per le richieste in uscita che usano il client Angular http per le risorse protette note. Questo documento fornisce altre informazioni sulla configurazione e sull'uso di MsalInterceptor.

Anche se è consigliabile usare direttamente l'api MsalInterceptor anziché l'API acquireTokenSilent , tenere presente che l'uso MsalInterceptor di è facoltativo. È possibile acquisire in modo esplicito i token usando le API acquireToken.

Si noti che MsalInterceptor viene fornito per comodità e potrebbe non adattarsi a tutti i casi d'uso. Si consiglia di scrivere un intercettore personalizzato se si dispone di esigenze specifiche che non vengono gestite da MsalInterceptor.

Configurazione

Configurazione di MsalInterceptor nella app.module.ts

Il MsalInterceptor può essere aggiunto all'applicazione come provider in app.module.ts, insieme alla relativa configurazione. Le istruzioni di importazione includono un'istanza di MSAL, nonché due oggetti di configurazione specifici per Angular. Il terzo argomento è un MsalInterceptorConfiguration oggetto che contiene i valori per interactionType, un protectedResourceMape un oggetto facoltativo authRequest.

La configurazione potrebbe essere simile alla seguente. Consulta la documentazione sulla configurazione per altri modi di configurare MSAL Angular per la tua 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 { }

Tipo di interazione

Sebbene MsalInterceptor sia progettato per acquisire i token in modo invisibile, nel caso in cui una richiesta invisibile non riesca, si passerà all'acquisizione interattiva dei token. Può InteractionType essere importato da @azure/msal-browser e impostato su Popup o Redirect.

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

Mappa risorse protette

Le risorse protette e gli ambiti corrispondenti sono forniti come protectedResourceMap nella configurazione MsalInterceptor.

Gli URL specificati nella protectedResourceMap raccolta fanno distinzione tra maiuscole e minuscole. Per ogni risorsa, aggiungere gli ambiti da restituire nel token di accesso.

Per esempio:

• ["user.read"] per Microsoft Graph
• ["<Application ID URL>/scope"] per le API Web personalizzate (ovvero api://<Application ID>/access_as_user)

Gli ambiti possono essere specificati per una risorsa nei modi seguenti:

1. Matrice di ambiti, che verranno aggiunti a ogni richiesta HTTP a tale risorsa, indipendentemente dal metodo 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. Un array di ProtectedResourceScopes, che applicherà gli scope solo per metodi HTTP specifici.

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

Si noti che gli ambiti di una risorsa possono contenere una combinazione di stringhe e ProtectedResourceScopes. Nell'esempio seguente, una richiesta GET avrà gli scope "all.scope" e "read.scope", mentre una richiesta PUT avrebbe solo "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. Valore di ambito di null, che indica che una risorsa deve essere non protetta e non otterrà i token. Le risorse non incluse in protectedResourceMap non sono protette per impostazione predefinita. Specificare una particolare risorsa come non protetta può essere utile quando alcuni percorsi di una risorsa devono essere protetti, mentre altri no. Si noti che l'ordine in protectedResourceMap è importante, quindi la risorsa null deve essere inserita prima di qualsiasi URL di base o carattere jolly simile.

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

Altri aspetti da tenere presenti riguardo al protectedResourceMap:

• Caratteri jolly: protectedResourceMap supporta l'uso di * per i caratteri jolly. Quando si usano caratteri jolly, se in protectedResourceMap vengono trovate più voci corrispondenti, verrà usata la prima voce trovata (in base all'ordine di protectedResourceMap).
• Percorsi relativi: se nell'applicazione sono presenti percorsi di risorse relativi, potrebbe essere necessario specificare il percorso relativo in protectedResourceMap. Questo vale anche per i problemi che possono verificarsi con ngx-translate. Tieni presente che il percorso relativo in protectedResourceMap potrebbe richiedere o meno uno slash iniziale, a seconda della tua app, e che potrebbe essere necessario provare entrambe le opzioni.

Corrispondenza esatta (strictMatching)

Per impostazione predefinita, in msal-angular v5 la corrispondenza dei modelli dei componenti URL per le voci protectedResourceMap utilizza criteri di corrispondenza rigorosi. Il campo strictMatching in MsalInterceptorConfiguration controlla questo comportamento.

Quali modifiche rigorose corrispondono

Con corrispondenza rigorosa (impostazione predefinita v5):

• Un modello come *.contoso.com corrisponde a app.contoso.com ma nona.b.contoso.com (il carattere jolly non può attraversare i separatori punto).
• Un modello come https://graph.microsoft.com/v1.0/me corrisponde solo all'URL esatto.

Modelli di errore comuni

I seguenti protectedResourceMap pattern di chiave funzionano con la modalità di corrispondenza legacy, ma falliscono silenziosamente con la corrispondenza rigorosa:

Comportamento predefinito nella versione 5 (nessuna configurazione necessaria)

La corrispondenza rigorosa è abilitata per impostazione predefinita. Non è necessaria alcuna configurazione aggiuntiva:

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

Disattivare la corrispondenza legacy

Se i pattern si basano sulla corrispondenza meno restrittiva di v4, puoi impostare strictMatching: false per mantenere temporaneamente il comportamento precedente:

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

Linee guida per le configurazioni guidate dall'ambiente

Se le protectedResourceMap chiavi fanno riferimento a valori Angular environment (ad esempio, environment.apiConfig.uri), controllare se tali valori sono percorsi esatti (ad esempio, https://graph.microsoft.com/v1.0/me) o URL di base bare (ad esempio, https://api.example.com). I percorsi esatti funzionano correttamente con la corrispondenza esatta e non richiedono una gestione speciale:

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

Se il valore dell'ambiente è un URL di base semplice e devi farlo corrispondere ai sottopercorsi, aggiungi un carattere jolly /*:

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

Per configurazioni realmente dinamiche in cui la forma chiave non è nota in fase di compilazione ( APP_INITIALIZERad esempio , JSON caricato tramite fetcho platformBrowserDynamic), impostato strictMatching: false come predefinito temporaneo sicuro. Vedere Opzioni di correzione: opzione B per un esempio di codice.

Risoluzione dei problemi di corrispondenza rigorosa

Symptoms

• Le richieste API restituiscono 401 Non autorizzato dopo l'aggiornamento alla @azure/msal-angular versione 5 (o tra versioni secondarie v5, ad esempio 5.0.x → 5.1.x).
• L'intestazione Authorization: Bearer <token>non è presente nelle richieste HTTP in uscita.
• Non vengono segnalati errori in fase di compilazione o di runtime: l'errore è invisibile all'utente.
• Il problema potrebbe essere visualizzato solo in determinati ambienti (ad esempio, gestione temporanea/produzione) in cui l'URL di base dell'API è diverso dallo sviluppo.

Opzioni di correzione

Opzione A: aggiornare le chiavi per funzionare con la corrispondenza esatta (consigliato)

Aggiorna le chiavi protectedResourceMap in modo che utilizzino percorsi esatti o caratteri jolly che corrispondano in base a regole di corrispondenza rigorose. Questo approccio è preferibile perché la corrispondenza rigorosa è più sicura e più prevedibile:

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

Opzione B: Impostare strictMatching: false (fallback per le configurazioni dinamiche)

Se le chiavi protectedResourceMap vengono caricate dinamicamente in fase di esecuzione (ad esempio, da APP_INITIALIZER, configurazione JSON o platformBrowserDynamic) e non è possibile garantire che contengano percorsi esatti o caratteri jolly, imposta strictMatching: false come valore predefinito temporaneo sicuro:

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

Avviso di runtime

MsalInterceptor genera un avviso di runtime una tantum tramite il logger MSAL durante l'inizializzazione se strictMatching non è configurato esplicitamente. Se viene visualizzato questo avviso, seguire le opzioni di correzione riportate sopra.

AuthRequest facoltativo

Per ulteriori informazioni sull'authRequest facoltativo che può essere impostato nel MsalInterceptorConfiguration, consulta la nostra documentazione multi-tenant qui.

Modifiche da msal-angular v1 a msal-angular v2

• protectedResourceMap è stato spostato nell'oggetto MsalInterceptorConfiguration e può essere passato come Map<string, Array<string|ProtectedResourceScopes>>. MsalAngularConfiguration è stato deprecato e non funziona più.
• L'inserimento del dominio radice in protectedResourceMap per proteggere tutte le route non è più supportato. Utilizzare invece la corrispondenza con caratteri jolly.

Per altre informazioni su come configurare gli ambiti, vedere le domande frequenti.