Habilitar a autenticação usando o provedor OAuth de terceiros

Você pode habilitar a autenticação em seu aplicativo de guia usando provedores de identidade OAuth (IdP) de terceiros. Nesse método, a identidade do usuário do aplicativo é validada e concedida acesso por um IdP OAuth, como Microsoft Entra ID, Google, Facebook, GitHub ou qualquer outro provedor. Você precisará configurar uma relação de confiança com o IdP, e os usuários do seu aplicativo também devem ser registrados com ele.

Observação

Para que a autenticação funcione para sua guia em clientes móveis, você precisa garantir que você esteja usando pelo menos a versão 1.4.1 da biblioteca JavaScript do Microsoft Teams.
O TeamsJS inicia uma janela separada para o fluxo de autenticação. Defina o atributo SameSite como Lax. O cliente de desktop do Teams ou versões anteriores do Chrome ou Safari não são compatíveis com SameSite=Nenhum.

Observação

Este tópico reflete a versão 2.0.x da biblioteca de clientes JavaScript do Microsoft Teams (TeamsJS). Se você estiver usando uma versão anterior, consulte a visão geral da biblioteca do TeamsJS para obter diretrizes sobre as diferenças entre o TeamsJS mais recente e as versões anteriores.

Usar o OAuth IdP para habilitar a autenticação

O OAuth 2.0 é um padrão aberto para autenticação e autorização usado por Microsoft Entra ID e muitos outros provedores de identidade. Uma compreensão básica do OAuth 2.0 é um pré-requisito para trabalhar com autenticação no Teams. Para obter mais informações, consulte OAuth 2 simplificado que é mais fácil de seguir do que a especificação formal. O fluxo de autenticação para guias e bots é diferente porque as guias são semelhantes aos sites para que possam usar o OAuth 2.0diretamente. Os bots fazem algumas coisas de maneira diferente, mas os conceitos principais são idênticos.

Por exemplo, o fluxo de autenticação para guias e bots usando Node e o tipo de concessão implícita OAuth 2.0, consulte iniciar fluxo de autenticação para guias.

Esta seção usa Microsoft Entra ID como um exemplo de um provedor OAuth de terceiros para habilitar a autenticação em um aplicativo de guias.

Observação

Antes de mostrar um botão Logon para o usuário e chamar a authentication.authenticate API em resposta à seleção do botão, você deve aguardar a conclusão da inicialização do TeamsJS. Você pode encadear um .then() manipulador ou await para que a app.initialize() função seja concluída.

1. O usuário interage com o conteúdo na configuração da guia ou na página de conteúdo, geralmente um botão Entrar ou Fazer login.

2. A guia constrói o URL para sua página inicial de autenticação. Opcionalmente, ele usa informações de espaços reservados de URL ou chama app.getContext() o método TeamsJS para simplificar a experiência de autenticação do usuário. Por exemplo, ao autenticar com Microsoft Entra ID, se o login_hint parâmetro for definido como o endereço de email do usuário, o usuário não precisará entrar se tiver feito isso recentemente. Isso ocorre porque Microsoft Entra ID usa as credenciais armazenadas em cache do usuário. A janela pop-up é mostrada brevemente e depois desaparece.

3. Em seguida, a guia chama o authentication.authenticate() método.

4. O Teams abre a página inicial em um iframe em uma janela pop-up. A página inicial gera dados aleatóriosstate, salva-os para validação futura e redireciona para o ponto de extremidade do provedor de /authorize identidade, como https://login.microsoftonline.com/<tenant ID>/oauth2/authorize para Microsoft Entra ID. Substitua <tenant id> pelo seu próprio ID de locatário que é context.tid. Semelhante a outros fluxos de autenticação de aplicativo no Teams, a página inicial deve estar em um domínio que esteja em sua lista validDomains e no mesmo domínio que a página de redirecionamento de entrada de postagem.

   Observação

   O fluxo de concessão implícita OAuth 2.0 exige um state parâmetro na solicitação de autenticação, que contém dados de sessão exclusivos para evitar um ataque de falsificação de solicitação entre sites. Os exemplos usam um GUID gerado aleatoriamente para os state dados.

5. No site do provedor, o usuário entra e concede acesso à guia.

6. O provedor leva o usuário para a página de redirecionamento OAuth 2.0 da guia com um token de acesso.

7. A guia verifica se o valor retornado corresponde ao state que foi salvo anteriormente e chama authentication.notifySuccess(), que, por sua vez, chama o manipulador de sucesso (.then()) para o método baseado em authenticate() promessas da etapa 3.

8. O Teams fecha a janela pop-up.

9. A guia exibe a interface do usuário de configuração, atualiza ou recarrega o conteúdo das guias, dependendo de onde o usuário iniciou.

Observação

Se o aplicativo for compatível com SAML SSO, o token JWT gerado por SSO da guia não poderá ser usado, pois não é compatível.

Tratar o contexto da guia como dicas

Embora o contexto da guia forneça informações úteis sobre o usuário, não use estas informações para autenticar o usuário. Autentique o usuário mesmo que você obtenha as informações como parâmetros de URL na URL de conteúdo da guia ou chamando a app.getContext() função na biblioteca de clientes JavaScript do Microsoft Teams (TeamsJS). Um ator mal-intencionado pode invocar a URL de conteúdo da guia com seus próprios parâmetros. O ator também pode invocar uma página da Web representando o Microsoft Teams para carregar a URL de conteúdo da guia em um iframe e retornar seus próprios dados para a função getContext(). Você deve tratar as informações relacionadas à identidade no contexto da guia como uma dica e validá-la antes de usá-la. Consulte as notas em navegar até a página de autorização na sua página pop-up.

Exemplo de código

Código de exemplo mostrando o processo de autenticação da guia:

Nome de exemplo	Descrição	.NET	Node.js	Manifesto
Autenticação completa do aplicativo	Este exemplo mostra como usar a autenticação em uma extensão de bot, guia e mensagens com o SSO (logon único) e no Facebook usando um nome de usuário e senha	View	View	Exibir

Confira também

Para obter uma implementação detalhada para autenticação de guia usando Microsoft Entra ID, consulte:

• Autenticar um usuário em uma guia do Teams
• Autenticação silenciosa
• validDomains