Перехватчик MSAL

MSAL Angular предоставляет класс Interceptor, который автоматически получает токены для исходящих запросов, отправляемых с помощью клиента Angular http к известным защищённым ресурсам. В этом документе содержатся дополнительные сведения о настройке и использовании MsalInterceptor.

Хотя мы рекомендуем использовать MsalInterceptor вместо acquireTokenSilent API напрямую, обратите внимание, что использование MsalInterceptor необязательно. При желании вы можете вместо этого явно получить токены с помощью API acquireToken.

Обратите внимание, что MsalInterceptor предоставляется для удобства и может не соответствовать всем вариантам использования. Мы рекомендуем вам написать собственный перехватчик, если у вас есть определенные потребности, которые не рассматриваются MsalInterceptor.

Configuration

Настройка MsalInterceptor в app.module.ts

MsalInterceptor можно добавить в ваше приложение в качестве провайдера в файле app.module.ts вместе с его конфигурацией. Импорт принимает экземпляр MSAL, а также два объекта конфигурации Angular. Третий MsalInterceptorConfiguration аргумент — это объект, содержащий значения для interactionType, a protectedResourceMapи необязательный authRequest.

Конфигурация может выглядеть следующим образом. Ознакомьтесь с нашим документом по конфигурации другими способами настройки MSAL Angular для приложения.

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

Тип взаимодействия

Хотя MsalInterceptor предназначен для получения токенов без вмешательства пользователя, в случае сбоя такого запроса он переключится на получение токенов в интерактивном режиме. InteractionType можно импортировать из @azure/msal-browser и установить значение Popup или Redirect.

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

Карта защищенных ресурсов

Защищённые ресурсы и соответствующие области доступа указываются как protectedResourceMap в конфигурации MsalInterceptor.

URL-адреса, которые вы указываете в коллекции protectedResourceMap, чувствительны к регистру. Для каждого ресурса добавьте области, которые запрашиваются для возврата в токене доступа.

Рассмотрим пример.

  • ["user.read"] для Microsoft Graph
  • ["<Application ID URL>/scope"] для пользовательских веб-API (то есть, api://<Application ID>/access_as_user)

Области можно указать для ресурса следующим образом:

  1. Массив областей, который будет добавлен к каждому HTTP-запросу к этому ресурсу независимо от метода 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. Массив ProtectedResourceScopes, используемый для применения областей видимости только к определённым 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"]
            }
        ]]
    ])
}

Обратите внимание, что области действия ресурса могут содержать комбинацию строк и ProtectedResourceScopes. В следующем примере запрос GET будет иметь области действия "all.scope" и "read.scope", тогда как запрос PUT будет иметь только "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. Значение области действия null, указывающее, что ресурс не должен быть защищен и не будет получать токены. Ресурсы, не включенные в него protectedResourceMap , не защищены по умолчанию. Указание конкретного ресурса как незащищённого может быть полезным, когда некоторые маршруты ресурса должны быть защищены, а некоторые — нет. Обратите внимание, что порядок в protectedResourceMap имеет значение, поэтому ресурс null следует размещать перед любыми аналогичными базовыми URL-адресами или шаблонами с подстановочными знаками.
{
    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"]]
    ]),
}

Другие вещи, которые следует отметить в отношении protectedResourceMap:

  • Подстановочные знаки: protectedResourceMap поддерживает использование * подстановочных знаков. При использовании подстановочных знаков, если в protectedResourceMap найдено несколько подходящих записей, будет использовано первое найденное совпадение (в зависимости от порядка в protectedResourceMap).
  • Относительные пути: если в приложении есть относительные пути к ресурсам, может потребоваться указать относительный путь в protectedResourceMapприложении. Это также относится к проблемам, которые могут возникнуть с ngx-translate. Имейте в виду, что относительный путь в вашем protectedResourceMap может как требовать, так и не требовать начального слеша в зависимости от приложения, поэтому, возможно, вам придётся проверить оба варианта.

Строгое сопоставление (strictMatching)

В msal-angular v5 шаблон компонента URL для protectedResourceMap записей использует строгую семантику сопоставления по умолчанию. Поле strictMatching в MsalInterceptorConfiguration управляет этим поведением.

Important

Если приложение динамически задает ключи protectedResourceMap (например, из файлов среды, APP_INITIALIZER или конфигурации JSON), и эти ключи представляют собой базовые URL-адреса без подпутей или подстановочных знаков, строгое сопоставление может незаметно помешать добавлению заголовка Authorization. Это приводит к ошибкам с кодом 401 без ошибок на этапе сборки и без предупреждений при отдельных запросах — только с одним предупреждением при инициализации, если strictMatching не настроено явно. Дополнительные сведения см. в разделе "Устранение неполадок с строгим сопоставлением ".

Что меняет строгое сопоставление

Behavior Устаревшее (strictMatching: false) Strict (по умолчанию в версии 5)
Экранирование метасимвола . и другие метасимволы регулярных выражений не экранируются; они работают как операторы регулярных выражений Все метахарактеры (включая .) рассматриваются как литералы
Привязка Шаблон может совпадать в любом месте строки Шаблон должен соответствовать полной строке (^…$)
Маска имени узла (*) * соответствует любой последовательности символов, включая . * соответствует любой последовательности символов, не включающей . (подстановочные знаки остаются в пределах одной метки DNS)
Путь, поиск и хэш-подстановочный знак (*) * соответствует любой последовательности символов * соответствует любой последовательности символов (без изменений)
? символ Передаётся в базовое регулярное выражение Обрабатывается как литеральный символ? (разделитель строки запроса в URL, а не подстановочный знак)

При строгом сопоставлении (по умолчанию версия 5):

  • Шаблон, такой как *.contoso.com, соответствует app.contoso.com, но неa.b.contoso.com (подстановочный знак не может захватывать разделители в виде точек).
  • Шаблон, например, https://graph.microsoft.com/v1.0/me соответствует только тому точному URL-адресу.

Распространенные шаблоны сбоев

protectedResourceMap Следующие ключевые шаблоны работают при устаревшем сопоставлении, но автоматически завершаются сбоем со строгим сопоставлением:

Шаблон ключа URL-адрес исходящего запроса Результат при строгом соответствии Исправление
https://api.example.com https://api.example.com/v1/users Нет совпадения — ключ разрешает путь /, запрос имеет путь /v1/users https://api.example.com/*
https://api.example.com/ https://api.example.com/v1/users Нет совпадения — завершающая косая черта жёстко привязывает шаблон ровно к / https://api.example.com/*
environment.apiConfig.uri (например, https://api.example.com) https://api.example.com/v1/users Нет совпадения — то же самое, что и выше `${environment.apiConfig.uri}/*`

Поведение по умолчанию в версии 5 (конфигурация не требуется)

Строгое сопоставление по умолчанию включено. Дополнительная конфигурация не требуется:

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

Отключение устаревшего сопоставления

Если ваши шаблоны зависят от менее строгого сопоставления в версии 4, вы можете задать strictMatching: false, чтобы временно сохранить прежнее поведение:

Note

Устаревшее сопоставление (strictMatching: false) поддерживается для обратной совместимости и может быть удалено в одной из следующих основных версий. Мы рекомендуем обновить шаблоны protectedResourceMap, чтобы они работали со строгим сопоставлением.

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

Руководство по конфигурациям на основе среды

protectedResourceMap Если ключи ссылаются на значения Angular environment (например, environment.apiConfig.uri), проверьте, являются ли эти значения точными путями (например, https://graph.microsoft.com/v1.0/me) или необнаженными базовыми URL-адресами (например, https://api.example.com). Точные пути работают правильно с строгим сопоставлением и не требуют специальной обработки:

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

Если значение переменной среды является простым базовым URL-адресом и нужно сопоставлять подпути, добавьте подстановочный знак /*:

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

Для действительно динамических конфигураций, в которых фигура ключа не известна во время сборки (например, APP_INITIALIZERJSON, загруженная через fetchили platformBrowserDynamic), задайте strictMatching: false в качестве временного безопасного по умолчанию. См. «Варианты исправления — вариант B» для примера кода.

Устранение неполадок при строгом сопоставлении

Симптомы
  • Запросы API возвращают 401 Unauthorized после обновления до версии @azure/msal-angular v5 (или при переходе между минорными версиями v5, например 5.0.x → 5.1.x).
  • Заголовок Authorization: Bearer <token>отсутствует из исходящих HTTP-запросов.
  • Об ошибках при сборке или во время выполнения не сообщается — сбой является тихим.
  • Проблема может отображаться только в определенных средах (например, промежуточной или рабочей среде), где базовый URL-адрес API отличается от разработки.
Исправление параметров

Вариант A. Обновление ключей для работы с строгим сопоставлением (рекомендуется)

protectedResourceMap Обновите ключи, чтобы использовать точные пути или подстановочные знаки, соответствующие строгим правилам сопоставления. Этот подход предпочтителен, так как строгое сопоставление является более безопасным и более предсказуемым:

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

Вариант B: Установите strictMatching: false (запасной вариант для динамических конфигураций)

Если ваши protectedResourceMap ключи загружаются динамически во время выполнения (например, из APP_INITIALIZER, JSON-конфигурации или platformBrowserDynamic) и вы не можете гарантировать, что они содержат точные пути или подстановочные знаки, задайте strictMatching: false как временное безопасное значение по умолчанию:

{
    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

Устаревшее сопоставление (strictMatching: false) поддерживается для обратной совместимости и может быть удалено в одной из следующих основных версий.

Предупреждение среды выполнения

MsalInterceptor выводит однократное предупреждение во время выполнения через средство журналирования MSAL при инициализации, если strictMatching не настроено явным образом. Если вы видите это предупреждение, следуйте приведенным выше параметрам исправления.

Необязательный параметр authRequest

Дополнительные сведения о необязательных authRequest параметрах, которые можно задать в документе MsalInterceptorConfigurationс несколькими клиентами, см. здесь.

Изменения от msal-angular версии 1 до версии 2

Note

unprotectedResourceMap в MsalAngularConfiguration MSAL Angular v1 устарел и больше не работает.

  • protectedResourceMap был перемещен в MsalInterceptorConfiguration объект и может передаваться как Map<string, Array<string|ProtectedResourceScopes>>. MsalAngularConfiguration не рекомендуется и больше не работает.
  • Размещение корневого домена в protectedResourceMap для защиты всех маршрутов больше не поддерживается. Вместо этого используйте подстановочные знаки.

Дополнительные сведения о настройке областей см. в наших часто задаваемых вопросых.

  • Last updated on