Поделиться через

Получение и кэширование токенов с помощью библиотеки MSAL (Microsoft Authentication Library)

  • Статья

Маркеры доступа позволяют клиентам безопасно вызывать веб-API, защищенные платформой Azure. Получить маркер с использованием библиотеки проверки подлинности Майкрософт (MSAL) можно несколькими способами. Для некоторых из них необходимо вмешательство пользователя через веб-браузер, в то время как для других оно не требуется. Обычно метод, используемый для получения маркера, зависит от того, является ли приложение общедоступным клиентским приложением (классическим или мобильным) или конфиденциальным клиентским приложением (веб-приложением, веб-API или приложением управляющей программы).

MSAL кэширует токен после его получения. Прежде чем пытаться получить маркер другими способами, код приложения должен сначала попытаться получить его из кэша автоматически.

Вы также можете очистить кэш токенов, удалив учетные записи из него. Однако сеансовый файл cookie в браузере при этом не удаляется.

Области доступа при получении токенов

Области — это разрешения, которые предоставляет веб-API и к которым клиентские приложения могут запрашивать доступ. Клиентские приложения запрашивают согласие пользователя на эти области при отправке запросов на аутентификацию для получения токенов, предоставляющих доступ к веб-API. MSAL позволяет получать токены для доступа к API платформы идентификации Microsoft. Протокол версии 2.0 использует области вместо ресурса в запросах. В зависимости от того, какую версию токенов принимает веб-API, конечная точка версии 2.0 возвращает соответствующий маркер доступа в MSAL.

Для некоторых методов получения токена MSAL требуется параметр scopes. Параметр scopes представляет собой простой список строк, которые объявляют нужные разрешения и запрашиваемые ресурсы. Известными областями являются разрешения Microsoft Graph.

Запрос областей доступа для веб-API

Когда вашему приложению необходимо запросить токен доступа с определенными разрешениями для ресурса API, передайте scopes, содержащие URI идентификатора приложения API-интерфейса, в следующем формате: <app ID URI>/<scope>.

Ниже приведен ряд примеров значений области для разных ресурсов.

  • API Microsoft Graph: https://graph.microsoft.com/User.Read
  • Пользовательский веб-API: api://00001111-aaaa-2222-bbbb-3333cccc4444/api.read

Формат значения области зависит от ресурса (API), получающего маркер доступа, и от принимаемых им значений утверждений aud.

Только для Microsoft Graph область user.read сопоставляется с https://graph.microsoft.com/User.Read и оба формата областей могут быть взаимозаменяемыми.

Некоторые веб-API, такие как API Azure Resource Manager (https://management.core.windows.net/), ожидают косую черту (/) в заявке аудитории (aud) маркера доступа. В этом случае передайте область как https://management.core.windows.net//user_impersonation, включая двойную косую черту (//).

Для других интерфейсов API может потребоваться, чтобы в значение области не включалась схема или узел, а ожидаемыми значениями были только идентификатор приложения (GUID) и имя области, например:

00001111-aaaa-2222-bbbb-3333cccc4444/api.read

Совет

Если подчиненный ресурс не находится под вашим контролем, возможно, потребуется попробовать разные форматы значений области видимости (например, с/без схемы и узла), если вы получаете 401 или другие ошибки при передаче маркера доступа ресурсу.

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

Например, можно разрешить пользователю вход в систему, но сначала запретить ему доступ к любым ресурсам. Позже вы сможете предоставить им возможность просмотра их календаря, запросив область календаря через метод получения токенов и получив на это согласие пользователя. Например, запросив области https://graph.microsoft.com/User.Read и https://graph.microsoft.com/Calendar.Read.

Получение токенов в автоматическом режиме (из кэша)

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

Исходный код приложения должен сначала попытаться автоматически получить маркер из кэша. Если вызов метода возвращает ошибку или исключение "Требуется UI", попробуйте получить токен другим способом.

Существует два потока, в которых не следует пытаться незаметно получить токен:

  • Поток клиентских учетных данных, который использует не кэш токенов пользователей, а кэш токенов приложения. Этот метод отвечает за проверку этого кэша маркеров приложения перед отправкой запроса в службу маркеров безопасности.
  • Поток с использованием кода авторизации в веб-приложениях, так как он активирует код, получаемый приложением при входе пользователя в систему, и содержит его согласие для дополнительных областей. Так как в качестве параметра передается код, а не учетная запись, метод не может выполнять поиск в кэше до активации кода, который инициирует вызов службы.

Для веб-приложений, использующих поток авторизации OpenID Connect, рекомендуется в контроллерах использовать следующий паттерн:

  • создание экземпляра конфиденциального клиентского приложения с помощью кэша токенов с использованием настраиваемой сериализации;
  • получение токена с помощью потока кода авторизации.

Получение токенов

Метод получения токена зависит от того, является ли приложение публичным клиентом или конфиденциальным клиентским приложением.

Общедоступные клиентские приложения

В общедоступных клиентских приложениях (настольных и мобильных устройствах) можно:

  • Получите токены в интерактивном режиме, заставив пользователя войти в систему через пользовательский интерфейс или всплывающее окно.
  • Бесшумно получать токен для вошедшего в систему пользователя, используя встроенную проверку подлинности Windows (IWA/Kerberos), если настольное приложение выполняется на компьютере Windows, присоединенном к домену или к Azure.
  • Получите токен с именем пользователя и паролем в настольных клиентских приложениях .NET Framework (не рекомендуется). Не используйте имя пользователя и пароль в конфиденциальных клиентских приложениях.
  • Получать токен через поток кода на устройстве в приложениях, выполняемых на устройствах без веб-браузера. Пользователю предоставляется URL-адрес и код, которые он вводит в веб-браузере на другом устройстве для входа в систему. Затем идентификатор Microsoft Entra отправляет маркер обратно на устройство без браузера.

Конфиденциальные клиентские приложения:

Для конфиденциальных клиентских приложений (веб-приложения, веб-API или демон-приложения, к примеру, службы Windows), можно;

  • Получите токены для самого приложения, а не для пользователя, используя поток учетных данных клиента. Эту методику можно использовать для средств синхронизации или средств, которые обрабатывают пользователей в целом, а не отдельного пользователя.
  • Используйте поток On-Behalf-Of (OBO), чтобы веб-API мог вызвать API от имени пользователя. Приложение идентифицируется по учетным данным клиента для получения токена на основе утверждения от пользователя (например, токена SAML или JWT). Этот поток используется приложениями, которым требуется доступ к ресурсам определенного пользователя в вызовах между службами. Токены должны кэшироваться на основе сеанса, а не на основе пользователя.
  • Получаете токены с помощью потока кода авторизации в веб-приложениях после входа пользователя через URL-адрес запроса авторизации. Приложение OpenID Connect обычно использует этот механизм, который позволяет пользователю входить с помощью OpenID Connect, а затем получать доступ к веб-API от имени пользователя. Маркеры можно кэшировать для пользователей или на сеанс. При кэшировании токенов на основе пользователя мы рекомендуем ограничить время существования сеанса, чтобы Microsoft Entra ID мог часто проверять состояние политик условного доступа.

Результаты аутентификации

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

  • Маркер доступа для доступа веб-API к ресурсам. Эта строка обычно представляет собой JWT в кодировке Base64, но клиент никогда не должен пытаться просматривать токен доступа. Стабильность формата не гарантируется, и он может быть зашифрован для ресурса. Люди, код которых зависит от содержимого маркера доступа на стороне клиента, являются одним из наиболее распространенных источников ошибок и разрывов логики клиента.
  • Маркер идентификации пользователя (JWT).
  • Срок действия токена, то есть дата и время завершения его применимости.
  • Идентификатор клиента содержит сведения о клиенте, в котором был найден пользователь. Для гостевых пользователей (сценарии Microsoft Entra B2B) идентификатор арендатора является идентификатором гостевого арендатора, а не уникальным арендатором. Когда токен предоставляется в имени пользователя, результат аутентификации также содержит сведения об этом пользователе. Для потоков конфиденциальных клиентов, где токены запрашиваются без пользователя (для приложения), эта информация пользователя имеет значение NULL.
  • Области, для которых выдан токен.
  • Уникальный идентификатор пользователя.

(Расширенный) доступ к кэшированным маркерам пользователя в фоновых приложениях и службах

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

Сегодня большинство фоновых процессов используют разрешения приложений, когда им необходимо работать с данными пользователя без их присутствия для аутентификации или повторной аутентификации. Поскольку разрешения приложения часто требуют согласия администратора, что требует повышения привилегий, возникают ненужные трения, поскольку разработчик не намеревался получать разрешение сверх того, на которое пользователь изначально дал свое согласие для своего приложения.

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

Доступ к кэшу токенов вошедшего в систему пользователя из фоновых приложений, API и служб

Заметка

При интерактивном получении токенов с помощью брокера проверки подлинности брокер сначала будет искать в кэше и возвращать кэшированный токен при наличии (проблема с GitHub — acquireToken использует кэширование).

См. также

В документации библиотек некоторых платформ, поддерживаемых MSAL, содержатся дополнительные сведения о кэше токенов. Например: