适用于 bot 的 Microsoft 团队身份验证流Microsoft Teams authentication flow for bots


本节中的文章基于 v3 Bot 框架 SDK。The articles in this section are based on the v3 Bot Framework SDK. 如果您要查找当前文档(SDK 版本4.6 或更高版本),请参阅 "对话 bot " 部分。If you're looking for current documentation (version 4.6 or later of the SDK) see the Conversational Bots section.

OAuth 2.0 是一种开放的标准,用于 Azure AD 和许多其他标识提供程序使用的身份验证和授权。OAuth 2.0 is an open standard for authentication and authorization used by Azure AD and many other identity providers. 对 OAuth 2.0 的基本了解是在团队中使用身份验证的先决条件;下面是一个很好的概述,比正式规范更易于遵循。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. 选项卡和 bot 的身份验证流略有不同,因为选项卡非常类似于网站,因此它们可以直接使用 OAuth 2.0,而 bot 不是,并且必须以不同方式执行几项操作,但核心概念是相同的。Authentication flow for tabs and bots are a little different because tabs are very similar to websites so they can use OAuth 2.0 directly, and bots are not and must do a few things differently, but the core concepts are identical.

请参阅 GitHub 存储库Microsoft 团队身份验证示例,该示例演示使用使用OAuth 2.0 授权代码授予类型的节点的身份验证流。See the GitHub repo Microsoft Teams Authentication Sample for an example that demonstrates authentication flow for bots using Node using the OAuth 2.0 authorization code grant type.

Bot 身份验证序列图

  1. 用户向 bot 发送一封邮件。The user sends a message to the bot.
  2. 机器人确定用户是否需要登录。The bot determines if the user needs to sign in.
    • 在此示例中,机器人将访问令牌存储在其用户数据存储中。In this example, the bot stores the access token in its user data store. 如果没有为选定的标识提供程序验证令牌,则它要求用户登录。It asks the user to log in if it doesn't have a validated token for the selected identity provider. 查看代码(View code)
  3. 机器人将 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)
    • 与团队中的其他应用程序身份验证流一样,起始页必须位于validDomains列表中的域中,并且在与登录后重定向页面相同的域中。Like other application auth flows in Teams, the start page must be on a domain that's in your validDomains list, and on 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. 当用户单击登录按钮时,团队会打开一个弹出窗口,并将其导航到起始页。When the user clicks on the signin button, Teams opens a popup window and navigates it to the start page.
  5. 起始页将用户重定向到标识提供程序的authorize终结点。The start page redirects the user to the identity provider's authorize endpoint. 查看代码(View code)
  6. 在提供程序的网站上,用户登录并授予对机器人的访问权限。On the provider's site, the user signs in and grants access to the bot.
  7. 提供程序使用授权代码将用户带到 bot 的 OAuth 重定向页面。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.
    • 在此示例中,机器人将state参数值与启动登录进程的用户的 id 关联,以便以后能够将其与标识提供程序返回的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)
    • 重要说明:机器人存储从标识提供程序接收的令牌,并将其与特定用户相关联,但它被标记为 "挂起验证"。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 cannot 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.
      2. 验证从团队收到的内容。Validate what's received from Teams. 执行两步身份验证验证,以确保通过标识提供程序向 bot 授权的用户是与 bot 聊天的用户。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. 机器人生成验证代码并存储它,与用户相关联。The bot generates a verification code and stores it, associated with the user. 由团队自动发送验证代码,如下面的步骤9和10中所述。The verification code is sent automatically by Teams as described below in steps 9 and 10. 查看代码(View code)
  9. OAuth 回调将呈现一个调用notifySuccess("<verification code>")的页面。The OAuth callback renders a page that calls notifySuccess("<verification code>"). 查看代码(View code)
  10. 团队关闭弹出窗口,并将<verification code>发送到notifySuccess()的自动程序发送回机器人。Teams closes the popup 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. 如果匹配,则机器人标记令牌为已验证,可供使用。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.


如果你在移动时遇到身份验证问题,请确保你的 Javascript SDK 更新到版本1.4.1 或更高版本。If you experience issues with authentication on mobile, ensure your Javascript SDK is update to version 1.4.1 or later.


有关显示 bot 身份验证过程的示例代码,请参阅:For sample code showing the bot authentication process see:

更多详细信息More details

有关针对 Azure Active Directory 的 bot 身份验证的详细实施演练,请参阅:For detailed implementation walkthroughs for bot authentication targeting Azure Active Directory see: