Включение единого входа для приложения вкладки
Благодаря единому входу в Teams пользователи приложений могут использовать Teams для доступа к приложениям с вкладками. После входа в Teams с помощью учетной записи Microsoft или Microsoft 365 пользователи приложения смогут использовать ваше приложение без необходимости повторного входа. Приложение доступно для пользователей приложений на любом устройстве с доступом, предоставленным через Microsoft Entra ID.
В этом разделе вы узнаете следующее:
- Пользовательский интерфейс единого входа: Teams предоставляет пользователям вашего приложения настоящие возможности единого входа. Пользователи приложения могут использовать ваше приложение без повторного входа.
- Единый вход в Teams во время выполнения. Приложение вкладки взаимодействует с Microsoft Entra ID во время выполнения для одноразовой проверки подлинности и авторизации для пользователей приложения.
- Включение единого входа для приложения вкладки. Реализуйте задачи, связанные с включением единого входа в приложении вкладки.
Пользовательский интерфейс единого входа в Teams
Пользователи приложения входят в Teams с помощью личной учетной записи Майкрософт или учетной записи Microsoft 365. Вы можете воспользоваться этой учетной записью и использовать единый вход для проверки подлинности и авторизации пользователей приложения.
- Teams выполняет проверку подлинности и сохраняет удостоверение пользователя приложения.
- Приложение вкладки использует сохраненное удостоверение пользователя, который уже проверен в Teams.
- Пользователь приложения должен дать согласие Teams на использование удостоверения для доступа к приложению вкладки.
- Пользователь приложения может получить доступ к приложению, используя веб-интерфейс, классическое приложение или мобильный клиент.
Здесь можно увидеть пример пользовательского интерфейса с единым входом в приложении вкладки:
Улучшенный пользовательский интерфейс с единым входом
Вот что пользователи приложения получают благодаря единому входу:
- Teams получает маркер доступа для текущего пользователя приложения из Microsoft Entra ID. Это взаимодействие с Microsoft Entra ID невидимо для пользователя приложения. Он преобразуется в получение доступа к приложению, не выходя из среды Teams.
- Пользователь приложения должен давать согласие только в мультитенантной среде. Если пользователь и приложение находятся в одном и том же клиенте, пользователю нет необходимости давать согласие, чтобы использовать приложение.
- После первого предоставления согласия для Teams пользователь сможет использовать приложение без необходимости снова давать согласие, даже на других устройствах. В силу этого повышается удобство использования.
- Кроме того, администратор клиента может дать согласие от имени пользователей приложения. В этом сценарии, когда администратор клиента дает согласие для пользователей приложения в клиенте, пользователям приложения вообще не нужно запрашивать согласие. Это означает, что пользователи приложения не видят диалоговые окна согласия и могут легко получить доступ к приложению.
- Маркер доступа предварительно извлекается Teams для повышения производительности и времени загрузки приложения в среде Teams.
- Пользователям приложения не нужно запоминать или записывать несколько паролей для доступа к приложениям и их использования в среде Teams.
Теперь посмотрим, что происходит в серверной части во время выполнения для поддержки единого входа в среде Teams.
Единый вход в Teams во время выполнения
Единый вход реализуется в приложении вкладки путем получения маркера доступа для пользователя приложения Teams, который в настоящее время вошел в систему. Этот процесс включает в себя клиент приложения вкладки и сервер, клиент Teams и Microsoft Entra ID. Во время этого взаимодействия пользователь приложения должен дать согласие на использование удостоверения Teams для получения маркера доступа в мультитенантной среде.
На следующем рисунке показано, как работает единый вход, когда пользователь приложения Teams пытается получить доступ к приложению вкладки:
| # | Взаимодействие | Что происходит? |
|---|---|---|
| 1 | Вкладка приложения → клиент Teams | Приложение вкладки совершает вызов JavaScript к getAuthToken(), при этом Teams получает команду на получение маркера доступа. |
| 2 | → Microsoft Entra ID клиента Teams | Teams запрашивает Microsoft Entra конечную точку для маркера доступа для текущего пользователя приложения на основе удостоверения Teams. |
| 3 | Форма согласия Microsoft Entra ID → | Если текущий пользователь впервые использует ваше приложение вкладки, в Teams отображается запрос согласия, если приложению требуется доступ к защищенным данным. Пользователь приложения (или администратор) должен предоставить Teams согласие на использование удостоверения Teams пользователя приложения для получения маркера доступа от Microsoft Entra ID. Кроме того, появляется запрос на обработку пошаговой проверки подлинности, например, двухфакторную проверку подлинности. |
| 4 | Клиент Microsoft Entra ID → Teams | Microsoft Entra ID отправляет маркер доступа клиенту 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 ID.
- Если приложение использует диалоговые окна (называемые модулями задач в TeamsJS версии 1.x) из бота, вкладки, расширения сообщений или адаптивных карточек, вы можете использовать API единого входа для проверки подлинности пользователей приложения.
- Вы также можете использовать API единого входа для проверки подлинности пользователей приложения, которые хотят получить доступ к Stageview без необходимости повторной проверки.
Совет
Api единого входа также можно использовать для проверки подлинности пользователей приложений в диалоговых окнах , внедряющих веб-содержимое.
Чтобы реализовать единый вход во время выполнения, настройте приложение так, чтобы использовать единый вход для проверки подлинности и авторизации пользователей приложения.
Включение единого входа для приложения вкладки Teams
В этом разделе описаны задачи, связанные с реализацией единого входа для приложения Teams. Эти задачи не зависит от языка и структуры.
Чтобы включить единый вход для приложения на вкладке Teams, выполните следующие действия.
- Настройка приложения с помощью Microsoft Entra ID. Создайте приложение 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.
- Microsoft Entra единого входа для вкладок и расширения сообщений
- Создание бота с проверкой подлинности единого входа
Рекомендации
Ниже приведены рекомендуемые методики:
- Вызывайте маркер доступа только в случае, если он нужен: вызывайте
getAuthToken()только в случае, если вам требуется маркер доступа. Его можно вызвать, когда пользователь обращается к приложению вкладки, а также для использования определенной функции, для которой требуется проверка пользователя. - Не храните маркер доступа в коде на стороне клиента: не кэшируйте и не храните маркер доступа в коде клиента приложения. Клиент Teams кэширует маркер доступа (или запрашивает новый, если срок его действия истекает). Это помогает избежать случайных утечек маркера из веб-приложения.
- Используйте серверный код для вызовов Microsoft Graph: всегда используйте код на стороне сервера для вызовов Microsoft Graph или других вызовов, которым требуется передавать маркер доступа. Никогда не возвращайте маркер OBO клиенту, чтобы клиент мог выполнять прямые вызовы в Microsoft Graph. Это помогает защитить маркер от перехвата или утечки. Дополнительные сведения см. в статье Расширение возможностей приложения вкладки с помощью разрешений и области Microsoft Graph.
Известные ограничения
- В настоящее время единый вход в Teams поддерживает только маркеры OAuth 2.0. Маркеры SAML не поддерживаются.
- Несколько доменов для каждого приложения не поддерживаются. Дополнительные сведения см. в разделе Пользовательские приложения, созданные для вашей организации (бизнес-приложения).
- Перенаправления не поддерживаются для приложений с поддержкой iframed или брокером. Убедитесь, что вы используете MSAL.js в верхней рамке окна, если вы используете API перенаправления или используете всплывающее окно API
(window.parent!==window) => true.
Следующее действие
См. также
Platform Docs
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по