Fluxo de autenticação do Microsoft Teams para botsMicrosoft Teams authentication flow for bots

O OAuth 2,0 é um padrão aberto para autenticação e autorização usados pelo Azure Active Directory (Azure AD) e muitos outros provedores de identidade.OAuth 2.0 is an open standard for authentication and authorization used by Azure Active Directory (Azure AD) and many other identity providers. Uma compreensão básica do OAuth 2,0 é um pré-requisito para trabalhar com autenticação no Microsoft Teams; Veja aqui uma boa visão geral que é mais fácil de seguir do que a especificação formal.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. O fluxo de autenticação para guias e bots é um pouco diferente — guias são muito semelhantes aos sites para que eles possam usar o OAuth 2,0 diretamente, enquanto os bots não são e precisam fazer algumas coisas de forma diferente, mas os conceitos principais são idênticos.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.

Confira o exemplo de autenticação do repositório do GitHub do Microsoft Teams para obter um exemplo que demonstra o fluxo de autenticação para bots usando node. js e o tipo de concessão de código de autorização 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.

Diagrama de sequência de autenticação de bot

  1. O usuário envia uma mensagem para o bot.The user sends a message to the bot.
  2. O bot determina se o usuário precisa entrar.The bot determines if the user needs to sign in.
    • Neste exemplo, o bot armazena o token de acesso no armazenamento de dados do usuário.In this example, the bot stores the access token in its user data store. Ele solicita que o usuário entre se não tiver um token validado para o provedor de identidade selecionado.It asks the user to sign in if it doesn't have a validated token for the selected identity provider. (Exibir código)(View code)
  3. O bot cria a URL para a página inicial do fluxo de autenticação e envia um cartão para o usuário com uma signin ação.The bot constructs the URL to the start page of the authentication flow, and sends a card to the user with a signin action. (Exibir código)(View code)
    • Como outros fluxos de autenticação de aplicativos no Microsoft Teams, a página inicial deve estar em um domínio validDomains que esteja na sua lista e no mesmo domínio que a página de redirecionamento pós-logon.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.
    • Importante: o fluxo de concessão do código de autorização OAuth 2,0 state chama um parâmetro na solicitação de autenticação que contém um token de sessão exclusivo para evitar um ataque de falsificação de solicitação entre sites.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. O exemplo usa um GUID gerado aleatoriamente.The example uses a randomly-generated GUID.
  4. Quando o usuário seleciona o botão de entrada , o Microsoft Teams abre uma janela pop-up e navega para a página inicial.When the user selects the signin button, Teams opens a popup window and navigates to the start page.
  5. A página inicial redireciona o usuário para o ponto de extremidade do authorize provedor de identidade.The start page redirects the user to the identity provider's authorize endpoint. (Exibir código)(View code)
  6. No site do provedor, o usuário entra e concede acesso ao bot.On the provider's site, the user signs in and grants access to the bot.
  7. O provedor leva o usuário para a página de redirecionamento OAuth do bot com um código de autorização.The provider takes the user to the bot's OAuth redirect page with an authorization code.
  8. O bot reconsidera o código de autorização para um token de acesso e associa o token ao usuário que iniciou o fluxo de entrada.The bot redeems the authorization code for an access token, and provisionally associates the token with the user that initiated the sign-in flow. A seguir, chamamos isso de um token provisório.Below, we call this a provisional token.
    • No exemplo, o bot associa o valor do state parâmetro com a ID do usuário que iniciou o processo de entrada para que ele possa correspondê-lo mais tarde com o state valor retornado pelo provedor de identidade.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. (Exibir código)(View code)
    • Importante: o bot armazena o token que recebe do provedor de identidade e o associa a um usuário específico, mas está marcado como "validação pendente".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". O token provisório ainda não pode ser usado; Ele deve ser validado ainda mais:The provisional token can't be used yet; it must be further validated:
      1. Validar o que é recebido do provedor de identidade.Validate what's received from the identity provider. O valor do state parâmetro deve ser confirmado em relação ao que foi salvo anteriormente.The value of the state parameter must be confirmed against what was saved earlier.
      2. Validar o que é recebido do teams.Validate what's received from Teams. Uma validação de autenticação de duas etapas é executada para garantir que o usuário que autorizou o bot com o provedor de identidade seja o mesmo usuário que está batendo papo com o 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. Isso protege contra ataques Man-in-the-Middle e phishing .This guards against man-in-the-middle and phishing attacks. O bot gera um código de verificação e o armazena, associado ao usuário.The bot generates a verification code and stores it, associated with the user. O código de verificação é enviado automaticamente pelo Teams, conforme descrito abaixo.The verification code is sent automatically by Teams as described below. (Exibir código)(View code)
  9. O retorno de chamada OAuth renderiza uma página que notifySuccess("<verification code>")chama.The OAuth callback renders a page that calls notifySuccess("<verification code>"). (Exibir código)(View code)
  10. O Microsoft Teams fecha a janela pop-up <verification code> e envia notifySuccess() o enviado para de volta para o bot.Teams closes the pop-up window and sends the <verification code> sent to notifySuccess() back to the bot. O bot recebe uma mensagem Invoke com name = signin/verifyState.The bot receives an invoke message with name = signin/verifyState.
  11. O bot verifica o código de verificação de entrada em relação ao código de verificação armazenado com o token provisório do usuário.The bot checks the incoming verification code against the verification code stored with the user's provisional token. (Exibir código)(View code)
  12. Se houver correspondência, o bot marca o token como validado e pronto para uso.If they match, the bot marks the token as validated and ready for use. Caso contrário, o fluxo de autenticação falhará e o bot excluirá o token provisionado.Otherwise, the auth flow fails, and the bot deletes the provisional token.

Observação

Se você tiver problemas com a autenticação em dispositivos móveis, verifique se o SDK JavaScript foi atualizado para a versão 1.4.1 ou posterior.If you experience issues with authentication on mobile, ensure your JavaScript SDK is updated to version 1.4.1 or later.

ExemplosSamples

Para ver o código de exemplo que mostra o processo de autenticação do bot, confira:For sample code showing the bot authentication process see:

Mais detalhesMore details

Para obter instruções detalhadas de implementação para a autenticação de bot direcionando o Azure AD, confira:For detailed implementation walkthroughs for bot authentication targeting Azure AD see: