Habilitar o logon único para o aplicativo de guia

Artigo
11/14/2023

Com o SSO (logon único) no Teams, os usuários do aplicativo têm a vantagem de usar o Teams para acessar aplicativos de guia. Depois de fazer logon no Teams usando a conta Microsoft ou Microsoft 365, os usuários do aplicativo podem usar seu aplicativo sem a necessidade de entrar novamente. Seu aplicativo está disponível para usuários de aplicativo em qualquer dispositivo com o acesso concedido por meio de Microsoft Entra ID.

Veja o que você aprenderá nesta seção:

Experiência do usuário de logon único: o Teams oferece aos usuários do aplicativo uma verdadeira experiência de logon único. Os usuários do aplicativo podem usar seu aplicativo sem entrar novamente.
SSO no Teams em runtime: seu aplicativo de guia interage com Microsoft Entra ID em runtime para autenticação e autorização única para os usuários do aplicativo.
Habilitar o SSO para seu aplicativo de guia: implemente as tarefas envolvidas para habilitar o SSO no aplicativo de guias.

Experiência do usuário de logon único no Teams

Os usuários do aplicativo entrarão no Teams usando a conta pessoal da Microsoft ou a conta do Microsoft 365. Você pode aproveitar essa conta e usar o SSO para autenticar e autorizar os usuários do aplicativo.

A captura de tela mostra a experiência do usuário do SSO em um aplicativo de guias do teams.

O Teams autentica e armazena a identidade do usuário do aplicativo.
Seu aplicativo de guia usa a identidade armazenada do usuário do aplicativo que já está validado pelo Teams.
O usuário do aplicativo precisa dar consentimento ao Teams para usar a identidade para acessar seu aplicativo de guias.
O usuário do aplicativo pode acessar o aplicativo na Web, na área de trabalho ou no cliente móvel.

Você pode exibir aqui um exemplo de experiência do usuário com o logon único em um aplicativo de guia:

A representação gráfica mostra a experiência do usuário do SSO no aplicativo de guias.

Aprimorar a experiência do usuário com o logon único

Veja o que os usuários do aplicativo ganham com a experiência de logon único:

O Teams obtém o token de acesso do usuário do aplicativo atual de Microsoft Entra ID. Essa interação com Microsoft Entra ID é invisível para o usuário do aplicativo. Ele se traduz para obter o acesso ao aplicativo sem precisar sair do ambiente do Teams.
Um usuário de aplicativo precisa consentir apenas em um ambiente multilocatário. Se o usuário do aplicativo e o aplicativo residirem no mesmo locatário, o usuário do aplicativo não precisará dar consentimento para usar o aplicativo.
Depois de consentir para o Teams pela primeira vez, o usuário do aplicativo pode usar seu aplicativo sem ter mais a necessidade de consentir, mesmo em outro dispositivo. Por esse motivo, ele oferece uma melhor experiência do usuário.
- Como alternativa, o administrador de locatários pode dar consentimento em nome dos usuários do aplicativo. Nesse cenário, quando o administrador do locatário consente para os usuários do aplicativo no locatário, os usuários do aplicativo não precisam ser solicitados para consentimento. Isso significa que os usuários do aplicativo não veem as caixas de diálogo de consentimento e podem acessar o aplicativo perfeitamente.
O token de acesso é pré-buscado pelo Teams para melhorar o desempenho e o tempo de carga do aplicativo no ambiente do Teams.
Os usuários do aplicativo não precisam memorizar ou gravar várias senhas para acessar e usar aplicativos no ambiente do Teams.

Agora, vamos ver o que acontece no back-end durante o runtime para obter a experiência de logon único no Teams.

Logon único no Teams em runtime

Obtenha o logon único em um aplicativo de guia obtendo o token de acesso para o usuário do aplicativo Teams que está conectado no momento. Esse processo envolve o cliente do aplicativo de guia e o servidor, o cliente do Teams e Microsoft Entra ID. Durante essa interação, o usuário do aplicativo deve dar consentimento para usar a identidade do Teams para obter o token de acesso em um ambiente multilocatário.

A imagem a seguir mostra como o logon único funciona quando um usuário do aplicativo Teams tenta acessar o aplicativo de guia:

#	Interação	O que está acontecendo
1	Aplicativo de guia → cliente do Teams	O aplicativo de guia faz uma chamada JavaScript para `getAuthToken()`, que informa ao Teams para obter um token de acesso.
2	Cliente do Teams → Microsoft Entra ID	O Teams solicita Microsoft Entra ponto de extremidade para o token de acesso para o usuário do aplicativo atual com base na identidade do Teams.
3	Formulário de Consentimento Microsoft Entra ID →	Se o usuário atual do aplicativo estiver usando seu aplicativo de guia pela primeira vez, o Teams exibirá a solicitação de consentimento se o aplicativo precisar acessar dados protegidos. O usuário do aplicativo (ou o administrador) deve dar consentimento ao Teams por usar a identidade do Teams do usuário do aplicativo para obter o token de acesso do Microsoft Entra ID. Como alternativa, haverá uma solicitação para lidar com a autenticação step-up, como a autenticação de dois fatores.
4	Microsoft Entra ID → Cliente do Teams	Microsoft Entra ID envia o token de acesso para o Cliente do Teams. O token é um JWT (JSON Web Token) e sua validação funciona como a validação de token na maioria dos fluxos OAuth padrão. O Teams armazena o token em seu nome para que futuras chamadas para `getAuthToken()` retornem o token armazenado em cache.
5	Cliente do Teams → Cliente do aplicativo de guia	O Teams envia o token de acesso para o aplicativo de guia como parte do objeto de resultado retornado pela chamada do `getAuthToken()`.
6	Aplicativo Tab (entre cliente e servidor)	O aplicativo de guia analisa o token de acesso usando o JavaScript para extrair as informações necessárias, como o endereço de email do usuário do aplicativo. O token devolvido para o aplicativo de guia é um token de acesso e um token de identidade.

Para obter mais informações, consulte Adicionar código para habilitar o SSO em um aplicativo de guia e Adicionar código para habilitar o SSO em seu aplicativo bot.

Importante

O getAuthToken() é válido apenas para permitir um conjunto limitado de APIs a nível de usuário, como email, perfil, offline_access e OpenId. Ele não é usado para escopos do Graph como User.Read ou Mail.Read. Para obter soluções alternativas sugeridas, confira Estender seu aplicativo com permissões do Microsoft Graph.
O getAuthToken falha para usuários anônimos, pois eles não são contas Microsoft Entra.

As guias são páginas da Web com reconhecimento do Teams. Para habilitar o SSO em uma página da Web hospedada dentro de um aplicativo de guias, adicione a biblioteca de clientes JavaScript do Teams e chame microsoftTeams.initialize(). Após a inicialização, chame microsoftTeams.getAuthToken() para obter o token de acesso para seu aplicativo.

Casos de uso para habilitar o logon único

Você pode habilitar o SSO no Teams para todos os aplicativos que dão suporte a Microsoft Entra ID como um provedor de identidade. Além de usar o logon único para autenticar usuários de aplicativos em um aplicativo de guia, você também pode usá-lo para habilitar o acesso contínuo no Teams.

Alguns cenários em que você pode usar a API de logon único para autenticar os usuários do seu aplicativo são:

Se você quiser autenticar os usuários do seu aplicativo em um aplicativo de guia do Teams, a API de logon único permitirá que os usuários do aplicativo usem seu aplicativo no Teams sem a necessidade de autenticação adicional. Com base na identidade do Teams do usuário do aplicativo, você pode obter o token de acesso para eles de Microsoft Entra ID.
Se o aplicativo usar caixas de diálogo (conhecidos como módulos de tarefa no TeamsJS v1.x) de dentro de um bot, uma guia, uma extensão de mensagem ou Cartões Adaptáveis, você poderá usar a API do SSO para autenticar os usuários do aplicativo.
Você também pode usar a API do SSO para autenticar os usuários do aplicativo que desejam acessar o Stageview sem precisar ser validado novamente.

Dica

Você também pode usar a API do SSO para autenticar usuários de aplicativo em caixas de diálogo que inserem conteúdo da Web.

Para obter o logon único em runtime, configure seu aplicativo para habilitar o logon único para autenticar e autorizar usuários de aplicativos.

Habilitar o SSO para um aplicativo de guia do Teams

Esta seção descreve as tarefas envolvidas na implementação do SSO para um aplicativo do Teams. Essas tarefas possuem uma linguagem e estrutura desconhecida.

Para habilitar o SSO para um aplicativo de guia do Teams:

Configurar o aplicativo com Microsoft Entra ID: criar um aplicativo Microsoft Entra para gerar uma ID do aplicativo e um URI de ID do aplicativo. Para gerar token de acesso, configure escopos e autorize aplicativos cliente confiáveis.
Adicionar código: adicione o código para manipular o token de acesso, envie esse token para o código do servidor do aplicativo no cabeçalho Autorização e valide o token de acesso quando ele for recebido.
Atualizar o manifesto do aplicativo teams: atualize o manifesto do aplicativo cliente do Teams com a ID do aplicativo e o URI de ID do aplicativo gerado no Microsoft Entra ID para permitir que o Teams solicite tokens de acesso em nome do seu aplicativo.

Cookies de terceiros no iOS

Após a atualização do iOS 14, a Apple bloqueou o acesso de cookies de terceiros para todos os aplicativos por padrão. Portanto, os aplicativos que usam cookies de terceiros para autenticação em suas guias Canal ou Chat e aplicativos pessoais não poderão concluir seus fluxos de trabalho de autenticação em clientes iOS do Teams. Para estar em conformidade com os requisitos de privacidade e segurança, você deve migrar para um sistema baseado em token ou usar cookies primários para os fluxos de trabalho de autenticação do usuário.

Suporte de cliente móvel do Teams

Para o aplicativo móvel do Teams, as versões de cliente que dão suporte ao logon único são:

Teams para Android (1416/1.0.0.2020073101 and later)
Teams para iOS (version: 2.0.18 and later)
Biblioteca JavaScript do Teams (versão: 1.11 e posterior) para o SSO funcionar no painel do lado da reunião

Para obter uma melhor experiência no Teams, use a versão mais recente do iOS e Android.

Guias passo a passo

Use os seguintes guias passo a passo para habilitar o aplicativo SSO para Teams:

Práticas recomendadas

Aqui está uma lista de práticas recomendadas:

Chame o token de acesso somente quando precisar dele: chame o getAuthToken() somente quando precisar de um token de acesso. Você pode chamá-lo quando um usuário do aplicativo acessa seu aplicativo de guia ou para usar uma função específica que requer validação do usuário do aplicativo.
Não armazene o token de acesso no código do lado do cliente: não armazene em cache ou armazene o token de acesso no código do lado do cliente do aplicativo. O cliente do Teams armazena em cache o token de acesso (ou solicita um novo se expirar). Isso garante que não haja vazamento acidental do token do seu aplicativo Web.
Use o código do lado do servidor para chamadas do Microsoft Graph: use sempre o código do lado do servidor para fazer as chamadas do Microsoft Graph ou outras chamadas que exijam a passagem de um token de acesso. Nunca retorne o token OBO ao cliente para permitir que o cliente faça chamadas diretas ao Microsoft Graph. Isso ajuda a proteger o token de ser interceptado ou vazado. Para mais informações, confira Estender o aplicativo de guia com permissões e escopo do Microsoft Graph.

Limitações conhecidas

Atualmente, o logon único no Teams dá suporte apenas ao token OAuth 2.0. Ele não dá suporte ao token SAML.
Não há suporte para vários domínios por aplicativo. Para obter mais informações, consulte aplicativos personalizados criados para sua organização (aplicativos LOB).
Não há suporte para redirecionamentos para aplicativos com iframed ou intermediados. Verifique se você usa MSAL.js no quadro superior da janela se usar as APIs de redirecionamento ou usar a API (window.parent!==window) => truepop-up .

Próxima etapa

Registrar seu aplicativo de guia no Microsoft Entra ID