Кэширование в MSAL.js

Когда MSAL получает маркер, он кэширует его для дальнейшего использования. MSAL управляет временем жизни токенов и их обновлением за вас. acquireTokenSilent() API получает маркеры доступа из кэша для данной учетной записи и обновляет их при необходимости.

Хранилище кэша

Расположение хранилища кэша можно настроить с помощью объекта конфигурации, который используется для создания экземпляра MSAL:

import { PublicClientApplication, BrowserCacheLocation } from "@azure/msal-browser";

const pca = new PublicClientApplication({
    auth: {
        clientId: "Enter_the_Application_Id_Here", // e.g. "00001111-aaaa-2222-bbbb-3333cccc4444" (guid)
        authority: "https://login.microsoftonline.com/Enter_the_Tenant_Info_Here", // e.g. "common" or your tenantId (guid),
        redirectUri: "/"
    },
    cache: {
       cacheLocation: BrowserCacheLocation.SessionStorage // "sessionStorage"
    }
});

По умолчанию MSAL хранит различные артефакты аутентификации, получаемые от поставщика удостоверений, в хранилище браузера, используя Web Storage API, поддерживаемый всеми современными браузерами. Соответственно, MSAL предлагает два метода постоянного хранения: sessionStorage (по умолчанию) и localStorage. Кроме того, MSAL предоставляет memoryStorage параметр, позволяющий отказаться от хранения кэша в хранилище браузеров.

Расположение кэша Очищено Общий для окон и вкладок Поддерживается поток перенаправления
sessionStorage окно/вкладка закрыть Нет Да
localStorage закрытие браузера (если пользователь не выбрал «оставаться в системе») Да Да
memoryStorage обновление и навигация по страницам Нет Нет

Note

Хотя состояние аутентификации может быть утрачено в sessionStorage и в памяти из-за закрытия окна/вкладки или обновления страницы/перехода, соответственно, у пользователей по-прежнему остается активный сеанс у поставщика удостоверений (IdP), если cookie сеанса еще не истек, и они могут повторно пройти аутентификацию без каких-либо дополнительных запросов.

Выбор между различными расположениями хранилища отражает компромисс между лучшим взаимодействием с пользователем и повышением безопасности. Как указано в приведенной выше таблице, локальное хранилище дает лучший пользовательский интерфейс, а хранилище памяти обеспечивает лучшую безопасность, так как конфиденциальная информация не хранится в хранилище браузеров. Дополнительные сведения см. в разделе о безопасности и кэшированных артефактах ниже.

Заметки о локальном хранилище

Начиная с версии 4, если вы используете расположение кэша localStorage, данные аутентификации шифруются, если только пользователь не выберет «Не выходить из системы» при входе в систему. Используемый алгоритм шифрования — AES-GCM с помощью HKDF для получения ключа. Базовый ключ хранится в файле cookie сеанса msal.cache.encryptionс названием .

Этот файл cookie автоматически удаляется при закрытии экземпляра браузера (не вкладки), что делает невозможным расшифровку артефактов проверки подлинности после завершения сеанса. Эти просроченные артефакты аутентификации удаляются при следующей инициализации MSAL, и пользователю может потребоваться пройти аутентификацию повторно. Расположение localStorage по-прежнему обеспечивает сохраняемость кэша между вкладками для всех пользователей, но сохраняется только в сеансах браузера для пользователей, которые выбрали "Сохранить вход" (KMSI).

Important

Цель этого шифрования — уменьшить сохраняемость артефактов проверки подлинности, а не обеспечить дополнительную безопасность. Если плохой субъект получает доступ к хранилищу браузера, он также имеет доступ к ключу или имеет возможность запрашивать маркеры от вашего имени без необходимости кэша вообще. Это ваша ответственность за обеспечение того, что ваше приложение не уязвимо для атак XSS. Дополнительные сведения см. в разделе "Безопасность ".

Note

Хранение файлов cookie для временных артефактов аутентификации не рекомендуется использовать в MSAL.js v4. Этот раздел сохраняется для приложений, которые по-прежнему используют MSAL.js версии 3 или более ранних версий.

Браузер MSAL можно настроить для хранения временных артефактов проверки подлинности с помощью файлов cookie. Этот параметр позволяет поддерживать браузеры, которые могут очистить локальное или сеансное хранилище во время потоков входа на основе перенаправления (например, Internet Explorer, Firefox в частном режиме). Обратите внимание, что при выборе этого варианта сами токены по-прежнему хранятся в хранилище браузера или в памяти. Дополнительные сведения см. в разделе о конфигурации .

Security

Мы считаем sessionStorage/localStorage безопасными, если в вашем приложении отсутствуют уязвимости межсайтового скриптинга (XSS) и связанные с ними уязвимости. Ознакомьтесь с памяткой OWASP по предотвращению XSS для защиты ваших приложений от XSS. Если вы по-прежнему обеспокоены, мы рекомендуем вместо этого использовать вариант memoryStorage.

Кэшированные артефакты

Чтобы обеспечить эффективное получение токенов без ущерба для удобства пользователей, MSAL кэширует различные артефакты, полученные в результате вызовов API. Ниже приведена сводка сущностей в кэше MSAL:

  • Постоянные артефакты (сохраняются после завершения запроса — см. также: время жизни токенов)
    • токены доступа
    • токены ID
    • Маркеры обновления
    • accounts
  • Эфемерные артефакты (ограничено временем выполнения запроса)
    • метаданные запроса (например, state, nonce, authority)
    • Ошибки
    • состояние взаимодействия
  • Телеметрия
    • предыдущий неудачный запрос
    • данные о производительности

Note

Временные записи кэша всегда хранятся в хранилище сеансов или в памяти. MSAL возвращается в хранилище памяти, если хранилище сеансов недоступно.

Note

Код авторизации хранится только в памяти и отбрасывается после его обмена на токены.

переопределение temporaryCacheLocation

Note

Параметр temporaryCacheLocation конфигурации устарел в MSAL.js версии 4. Этот раздел сохраняется для приложений, которые по-прежнему используют MSAL.js версии 3 или более ранних версий.

Предупреждение

Переопределение temporaryCacheLocation следует выполнять с осторожностью, особенно при выборе localStorage. Работа более чем в одной вкладке или окне не поддерживается, и вы можете неожиданно получать interaction_in_progress ошибки. Это обходной путь, а не полноценно поддерживаемая функция.

При использовании MSAL.js с конфигурацией по умолчанию в сценарии, в котором пользователь перенаправляется после успешной проверки подлинности в новом окне или вкладке, код авторизации OAuth 2.0 с потоком PKCE будет прерван. В этом случае исходное окно или вкладка, где хранится состояние аутентификации (верификатор кода и challenge), будут потеряны, а процесс аутентификации завершится ошибкой.

Чтобы обработать этот сценарий, можно настроить MSAL на использование localStorage в качестве места хранения кэша, переопределив свойство конфигурации temporaryCacheLocation. Это позволяет хранить верификатор кода и challenge в localStorage браузера, которое сохраняется в нескольких вкладках и окнах.

Сохраняемость кэша во время MSAL.js обновлений и откатов

Иногда MSAL.js необходимо внести изменения в форму кэшированных артефактов для поддержки новых требований, функций или исправлений ошибок. Как можно чаще эти изменения выполняются в обратном режиме, чтобы обеспечить, чтобы при обновлении приложения до новой версии или откате до более старой, кэш, присутствующий в браузере пользователя, по-прежнему можно использовать. Однако это не всегда возможно, и вы можете оказаться в ситуации, когда одновременно существуют несколько копий кэша: одна из них используется текущей запущенной версией MSAL.js, а другая была создана версией, которая использовалась до обновления. Это делается, чтобы приложения могли при необходимости корректно выполнить откат. В большинстве случаев при обновлении MSAL.js переносит имеющиеся данные кэша в новый формат, обеспечивая плавное обновление. В редких случаях, например при обновлении с версии 3 до версии 4, это может оказаться невозможным из-за требований безопасности или конфиденциальности, и это всегда приводит к увеличению номера основной версии.

При изменении критического кэша старый кэш хранится в течение 5 дней по умолчанию, чтобы разрешить откат при необходимости. Время хранения старого кэша можно настроить с помощью конфигурации cacheRetentionDaysкэшаPublicClientApplication. Если кэш не использовался в течение этого времени, он очищается при следующем инициализации MSAL.js. Кроме того, если вы не предполагаете, что потребуется откат, можно установить это значение в 0, чтобы указать, что старый кэш всегда должен удаляться сразу при обновлении до новой версии MSAL.js. И наоборот, если у вас есть более длинное окно развертывания для обновлений, вы можете задать это значение дольше.

Note

Токены доступа и обновления удаляются после истечения срока их действия, даже если настроенное значение cacheRetentionDays еще не достигнуто. Действительные токены доступа также могут быть удалены в любое время, если хранилище браузера достигает предельного объёма. При достижении квот хранилища маркеры доступа удаляются в порядке очереди FIFO: сначала записи, созданные предыдущей версией MSAL.js, а затем записи, созданные текущей версией MSAL.js.

const config = {
    auth: {
        clientId: "<your-client-id>"
    },
    cache: {
        cacheLocation: "localStorage",
        cacheRetentionDays: 0 // Set this to the number of days you want old cache to be preserved in the event a rollback is needed (Default 5 days)
    }
}

const pca = new PublicClientApplication(config);
await pca.initialize();

Комментарии

  • Мы не рекомендуем, чтобы бизнес-логика приложений зависела от прямого использования сущностей из кэша. Вместо этого используйте соответствующий API MSAL, когда вам нужно получить токены или получить сведения об учетных записях.
  • Ключи, используемые для шифрования маркеров владения (PoP), хранятся с помощью сочетания API IndexedDB и хранилища памяти. Дополнительные сведения см. в access-token-proof-of-possession.

Дополнительные сведения

  • Last updated on