Получение и кэширование маркеров с помощью библиотеки проверки подлинности Майкрософт (MSAL)

  • Статья

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

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

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

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

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

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

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

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

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

  • API Microsoft Graph: https://graph.microsoft.com/User.Read
  • Пользовательский интерфейс веб-API: api://11111111-1111-1111-1111-111111111111/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) и имя области, например:

11111111-1111-1111-1111-111111111111/api.read

Совет

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

См. также

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