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

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

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

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

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

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

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

В MSAL также можно получить доступ к ресурсам версии 1.0. См. дополнительные сведения об областях для приложения версии 1.0.

Запрос областей для веб-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 Connect, рекомендуется следующий шаблон действий в контроллерах:

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

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

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

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

В общедоступных клиентских приложениях, таких как классические и мобильные приложения, вы можете делать следующее.

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

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

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

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

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

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

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