Процесс проверки подлинности для боты в Microsoft TeamsAuthentication flow for bots in Microsoft Teams

OAuth 2,0 — это открытый стандарт проверки подлинности и авторизации, используемый Azure Active Directory (Azure AD) и многими другими поставщиками удостоверений.OAuth 2.0 is an open standard for authentication and authorization used by Azure Active Directory (Azure AD) and many other identity providers. Основное понимание OAuth 2,0 является необходимым условием для работы с проверкой подлинности в Teams; Вот хороший обзор , который легче следовать, чем формальное описание.A basic understanding of OAuth 2.0 is a prerequisite for working with authentication in Teams; here's a good overview that's easier to follow than the formal specification. Процесс проверки подлинности для вкладок и боты немного отличается — вкладки очень похожи на веб-сайты, поэтому они могут использовать OAuth 2,0 напрямую, в то время как боты не так и не должны выполнять несколько действий по-разному, но основные понятия идентичны.Authentication flow for tabs and bots is a little different — tabs are very similar to websites so they can use OAuth 2.0 directly, while bots aren't and must do a few things differently — but the core concepts are identical.

Пример проверки подлинности Microsoft Teams в репозитории GitHub, демонстрирующий процесс проверки подлинности для боты с помощью Node.js и типа предоставления кода авторизации OAuth 2,0.See the GitHub repo Microsoft Teams Authentication Sample for an example that demonstrates authentication flow for bots using Node.js and the OAuth 2.0 authorization code grant type.

Схема последовательности проверки подлинности на Bot

  1. Пользователь отправляет сообщение в Bot.The user sends a message to the bot.
  2. Элемент Bot определяет, нужно ли выполнять вход в систему.The bot determines if the user needs to sign in.
    • В этом примере элемент Bot хранит маркер доступа в хранилище данных пользователя.In this example, the bot stores the access token in its user data store. Он просит пользователя выполнить вход, если у него нет проверенного маркера для выбранного поставщика удостоверений.It asks the user to sign in if it doesn't have a validated token for the selected identity provider. (Перейти к коду)(View code)
  3. Элемент Bot создает URL-адрес начальной страницы для процесса проверки подлинности и отправляет карточку пользователю с signin действием.The bot constructs the URL to the start page of the authentication flow, and sends a card to the user with a signin action. (Перейти к коду)(View code)
    • Как и в случае с другими потоками проверки подлинности приложений в Teams, начальная страница должна находиться в домене, который находится в validDomains списке, и в том же домене, что и страница перенаправления после входа.Like other application auth flows in Teams, the start page must be in a domain that's on your validDomains list, and in the same domain as the post-login redirect page.
    • Важно! код авторизации OAuth 2,0 вызывает для state параметра в запросе на проверку подлинности, который содержит уникальный маркер сеанса для предотвращения атаки на межсайтовый запрос на межсайтовую подделку.IMPORTANT: The OAuth 2.0 authorization code grant flow calls for a state parameter in the authentication request which contains a unique session token to prevent a cross-site request forgery attack. В этом примере используется идентификатор GUID, созданный случайным образом.The example uses a randomly-generated GUID.
  4. Когда пользователь нажимает кнопку Signing (войти ), Teams открывает всплывающее окно и переходит на начальную страницу.When the user selects the signin button, Teams opens a popup window and navigates to the start page.

Примечание

Размер всплывающего окна можно контролировать с помощью параметров строки запроса Width и Height в URL-адресе.The size of the pop-up window can be controlled through width and height query string parameters in the URL. Например, если вы добавите ширину = 500 и высота = 500, вы получите всплывающее окно, 500x500 Пиксели.For example if you add width=500 and height=500, you'll get a popup that's 500x500 pixels. В Teams будет отображаться всплывающее окно с заданным размером в пикселах, до максимального значения в процентах от размера основного окна.Teams will show the pop-up window with the given pixel size, up to a maximum that's a percentage of the size of the main window. 5. Начальная страница перенаправляет пользователя на конечную точку поставщика удостоверений authorize .The start page redirects the user to the identity provider's authorize endpoint. (Перейти к коду)(View code) 6. На сайте поставщика пользователь входит в систему и предоставляет доступ к Bot.On the provider's site, the user signs in and grants access to the bot. 7. Поставщик переводит пользователя на страницу переадресации OAuth на Bot с кодом авторизации.The provider takes the user to the bot's OAuth redirect page with an authorization code. 8. Bot пополняет код авторизации для маркера доступа , а затем связывает маркер с пользователем, который инициировал процесс входа.The bot redeems the authorization code for an access token, and provisionally associates the token with the user that initiated the sign-in flow. Ниже мы вызываем этот описатель подготовки.Below, we call this a provisional token. * В этом примере с помощью Bot связывается значение state параметра с идентификатором пользователя, который инициировал процесс входа, поэтому он может впоследствии сопоставлять его со state значением, возвращенным поставщиком удостоверений.In the example, the bot associates the value of the state parameter with the ID of the user that initiated the sign-in process so it can later match it with the state value returned by the identity provider. (Перейти к коду)(View code) * Важно! элемент Bot хранит маркер, который он получает от поставщика удостоверений, и связывает его с определенным пользователем, но отмечено как "Ожидание проверки".IMPORTANT: The bot stores the token it receives from the identity provider and associates it with a specific user, but it is marked as "pending validation". Вы пока не можете использовать предварительный маркер. необходимо выполнить дальнейшую проверку:The provisional token can't be used yet; it must be further validated: 1. Проверка того, что получено от поставщика удостоверений.Validate what's received from the identity provider. Значение state параметра должно быть подтверждено относительно того, что было сохранено ранее.The value of the state parameter must be confirmed against what was saved earlier. 1. Проверка того, что получено от Teams.Validate what's received from Teams. Проверка подлинности выполняется в два этапа с учетом того, что пользователь, уполномоченный с помощью поставщика удостоверений, — это тот же пользователь, что и в чате.A two-step authentication validation is performed to ensure that the user who authorized the bot with the identity provider is the same user who is chatting with the bot. Это защищает от атак "злоумышленник в середине" и " Фишинг ".This guards against man-in-the-middle and phishing attacks. Bot создает код проверки и сохраняет его, связанный с пользователем.The bot generates a verification code and stores it, associated with the user. Код проверки автоматически отправляется Teams, как описано ниже.The verification code is sent automatically by Teams as described below. (Перейти к коду)(View code) 9. Обратный вызов OAuth отображает страницу, которая вызывается notifySuccess("<verification code>") .The OAuth callback renders a page that calls notifySuccess("<verification code>"). (Перейти к коду)(View code) 10. Teams закрывает всплывающее окно и отправляет <verification code> notifySuccess() ответ на задний план.Teams closes the pop-up window and sends the <verification code> sent to notifySuccess() back to the bot. Bot получает сообщение о вызове name = signin/verifyState .The bot receives an invoke message with name = signin/verifyState. 11. Bot проверяет входящий код проверки относительно кода проверки, хранящегося в пользовательском маркере подготовки.The bot checks the incoming verification code against the verification code stored with the user's provisional token. (Перейти к коду)(View code) 12. Если они совпадают, элемент Bot помечает маркер как проверенный и готовый к использованию.If they match, the bot marks the token as validated and ready for use. В противном случае произойдет сбой процесса проверки подлинности, а Bot будет удален.Otherwise, the auth flow fails, and the bot deletes the provisional token.

Примечание

При возникновении проблем с проверкой подлинности на мобильном устройстве убедитесь, что пакет SDK для JavaScript обновлен до версии 1.4.1 или более поздней версии.If you experience issues with authentication on mobile, ensure your JavaScript SDK is updated to version 1.4.1 or later.

ПримерыSamples

Пример кода, демонстрирующий процесс создания подлинности на Bot, см.For sample code showing the bot authentication process see:

Дополнительные сведенияMore details

Подробные пошаговые руководства по реализации проверки подлинности, нацеленной на Azure AD, приведены ниже.For detailed implementation walkthroughs for bot authentication targeting Azure AD see: