Включение единого входа для приложения вкладки

Статья
04/01/2024

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

Вот что вы узнаете в этом разделе:

Пользовательский интерфейс единого входа: Teams предоставляет пользователям вашего приложения настоящие возможности единого входа. Пользователи приложения могут использовать ваше приложение без повторного входа.
Единый вход в Teams во время выполнения. Приложение вкладки взаимодействует с Идентификатором Microsoft Entra во время выполнения для одноразовой проверки подлинности и авторизации для пользователей приложения.
Включение единого входа для приложения вкладки. Реализуйте задачи, связанные с включением единого входа в приложении вкладки.

Пользовательский интерфейс единого входа в Teams

Пользователи приложения входят в Teams с помощью личной учетной записи Майкрософт или учетной записи Microsoft 365. Вы можете воспользоваться этой учетной записью и использовать единый вход для проверки подлинности и авторизации пользователей приложения.

Снимок экрана: пользовательский интерфейс единого входа в приложении вкладки Teams.

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

Здесь можно увидеть пример пользовательского интерфейса с единым входом в приложении вкладки:

Графическое представление показывает взаимодействие с пользователем единого входа в приложении вкладки.

Улучшенный пользовательский интерфейс с единым входом

Вот что пользователи приложения получают благодаря единому входу:

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

Теперь посмотрим, что происходит в серверной части во время выполнения для поддержки единого входа в среде Teams.

Единый вход в Teams во время выполнения

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

На следующем рисунке показано, как работает единый вход, когда пользователь приложения Teams пытается получить доступ к приложению вкладки:

#	Взаимодействие	Что происходит?
1	Вкладка приложения → клиент Teams	Приложение вкладки совершает вызов JavaScript к `getAuthToken()`, при этом Teams получает команду на получение маркера доступа.
2	Идентификатор Microsoft Entra для клиента Teams →	Teams запрашивает конечную точку Microsoft Entra для маркера доступа для текущего пользователя приложения на основе удостоверения Teams.
3	Форма согласия с идентификатором Microsoft Entra →	Если текущий пользователь впервые использует ваше приложение вкладки, в Teams отображается запрос согласия, если приложению требуется доступ к защищенным данным. Пользователь приложения (или администратор) должен предоставить Teams согласие на использование удостоверения Teams пользователя приложения для получения маркера доступа из идентификатора Microsoft Entra. Кроме того, появляется запрос на обработку пошаговой проверки подлинности, например, двухфакторную проверку подлинности.
4	Microsoft Entra ID → клиент Teams	Идентификатор Microsoft Entra отправляет маркер доступа клиенту Teams. Маркер является веб-токеном JSON (JWT), и его проверка работает так же, как проверка маркера в большинстве стандартных потоков OAuth. Teams кэширует маркер от вашего имени, поэтому все будущие вызовы к `getAuthToken()` будут возвращать кэшированный маркер.
5	Клиент Teams → клиент приложения вкладки	Teams отправляет маркер доступа в приложение вкладки в качестве объекта результата, возвращенного вызовом `getAuthToken()`.
6	Приложение tab (между клиентом и сервером)	Приложение вкладки анализирует маркер доступа с помощью JavaScript, чтобы извлечь необходимые сведения, например адрес электронной почты пользователя приложения. Маркер, возвращенный в приложение вкладки, является одновременно маркером доступа и маркером удостоверения.

Дополнительные сведения см . в разделах Добавление кода для включения единого входа в приложении-вкладке и Добавление кода для включения единого входа в приложение бота.

Важно!

Метод getAuthToken() можно использовать только для согласия в ограниченном наборе интерфейсов API на уровне пользователя, таких как email, profile, offline_access и OpenId. Он не используется для других областей Graph, таких как User.Read или Mail.Read. Рекомендуемые обходные пути см. в статье Расширение возможностей приложения с помощью разрешений Microsoft Graph.
Сбой getAuthToken для анонимных пользователей, так как они не являются учетными записями Microsoft Entra.

Вкладки — это веб-страницы с поддержкой Teams. Чтобы включить единый вход на веб-странице, размещенной в приложении вкладки, добавьте клиентскую библиотеку JavaScript для Teams и вызовите microsoftTeams.initialize(). После инициализации вызовите microsoftTeams.getAuthToken(), чтобы получить маркер доступа для приложения.

Сценарии использования для включения единого входа

Вы можете включить единый вход в Teams для всех приложений, поддерживающих Microsoft Entra ID в качестве поставщика удостоверений. Единый вход можно использовать не только для проверки подлинности пользователей приложения вкладки, но и для бесперебойного доступа к различным ресурсам в среде Teams.

Ниже перечислены некоторые сценарии, в которых можно использовать API единого входа для проверки подлинности пользователей приложения:

Если нужно проверять подлинность пользователей в приложении вкладки Teams, API единого входа дает возможность пользователям использовать ваше приложение в Teams, при этом не требуется дополнительная проверка подлинности. В зависимости от удостоверения Teams пользователя приложения вы можете получить маркер доступа для них из идентификатора Microsoft Entra.
Если приложение использует диалоговые окна (называемые модулями задач в TeamsJS версии 1.x) из бота, вкладки, расширения сообщений или адаптивных карточек, вы можете использовать API единого входа для проверки подлинности пользователей приложения.
Вы также можете использовать API единого входа для проверки подлинности пользователей приложения, которые хотят получить доступ к Stageview без необходимости повторной проверки.

Совет

Api единого входа также можно использовать для проверки подлинности пользователей приложений в диалоговых окнах , внедряющих веб-содержимое.

Чтобы реализовать единый вход во время выполнения, настройте приложение так, чтобы использовать единый вход для проверки подлинности и авторизации пользователей приложения.

Включение единого входа для приложения вкладки Teams

В этом разделе описаны задачи, связанные с реализацией единого входа для приложения Teams. Эти задачи не зависит от языка и структуры.

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

Настройка приложения с идентификатором Microsoft Entra. Создайте приложение Microsoft Entra для создания идентификатора приложения и URI идентификатора приложения. Для создания маркера доступа настройте области и авторизуйте доверенные клиентские приложения.
Добавить код. Добавьте код для обработки маркера доступа, отправьте его в код сервера приложения в заголовке Authorization и проверьте маркер доступа при его получении.
Обновление манифеста приложения Teams. Обновите манифест клиентского приложения Teams с помощью идентификатора приложения и URI идентификатора приложения, созданного на идентификаторе Microsoft Entra ID, чтобы разрешить Teams запрашивать маркеры доступа от имени вашего приложения.

Сторонние файлы cookie на iOS

После выпуска обновления iOS 14 корпорация Apple по умолчанию заблокировала доступ всех приложений к сторонним файлам cookie. Поэтому приложения, использующие сторонние файлы cookie для проверки подлинности на вкладках "Канал" или "Чат" и "Личные", не могут выполнять рабочие процессы проверки подлинности в клиентах Teams iOS. Чтобы соответствовать требованиям конфиденциальности и безопасности, вы должны перейти на систему на основе токенов или использовать собственные файлы cookie для рабочих процессов проверки подлинности пользователей.

Поддержка мобильного клиента Teams

Единый вход поддерживается в следующих версиях мобильных приложений Teams:

Teams для Android (1416/1.0.0.2020073101 и более поздние версии)
Teams для iOS (версия 2.0.18 и более поздние версии)
Библиотека JavaScript Teams (версия 1.11 и более поздние версии) для работы единого входа на боковой панели собрания

Для лучшего взаимодействия с Teams используйте последнюю версию iOS и Android.

Пошаговые руководства

Используйте следующие пошаговые руководства по включению приложения единого входа для Teams.

Известные ограничения

Единый вход в Teams поддерживает только токен OAuth 2.0. Маркеры SAML не поддерживаются.
Несколько доменов для каждого приложения не поддерживаются. Дополнительные сведения см. в разделе Пользовательские приложения, созданные для вашей организации (бизнес-приложения).
Перенаправления не поддерживаются для iframe и приложений с брокером. Убедитесь, что вы используете MSAL.js в верхней рамке окна, если вы используете API перенаправления или используете всплывающее окно API (window.parent!==window) => true.

Следующее действие

Регистрация приложения вкладки в Microsoft Entra ID

См. также

Глоссарий

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