Adicionar autenticação de terceiros a Ações Universais de Cartões Ajustáveis

As Ações Universais de Cartões Ajustáveis utilizam o bot como o back-end comum para processar ações e introduzem um novo tipo Action.Executede ação , que funciona em todas as aplicações, como o Teams e o Outlook.

Observação

O suporte para a versão de esquema de Ações Universais de Cartões Ajustáveis v1.4 só está disponível para cartões enviados pelo bot.

Pode ativar os seguintes cenários com Action.Execute na Ação Universal de Cartões Ajustáveis:

• Ações Universais
• Exibições Específicas do Usuário
• Fluxos de Trabalho Sequenciais
• Vista Atualizada

Para saber mais sobre as Ações Universais de Cartões Ajustáveis, veja Ações Universais de Cartões Ajustáveis.

Se quiser adicionar vistas específicas do utilizador em instâncias em que é partilhado um Cartão Ajustável com a Ação Universal, no contexto de uma conversa de grupo ou de um canal, o utilizador poderá ter de ser autenticado.

No passado, os utilizadores que conversavam um-a-um com o bot tiveram de esperar enquanto lhes enviava um cartão de autenticação separado para se autenticarem. Para comunicar com o bot, o utilizador teria de mudar do chat ou canal de grupo que iria perturbar o fluxo.

Fluxo de autenticação no protocolo Action.Execute

O fluxo de autenticação do OAuth, dentro do protocolo, permite a Action.Execute autenticação no contexto da conversa de grupo ou da conversação do canal onde o Cartão Ajustável é partilhado.

Os bots podem responder com um pedido de início de sessão em resposta a Action.Execute :

• Cartões Ajustáveis enviados por bot numa conversa individual, chat de grupo ou num canal.
• Cartões Ajustáveis enviados pelo utilizador da aplicação através da aplicação de extensão de mensagens (apoiados por bot) numa conversa individual, chat de grupo ou canal.
• Cartões Ajustáveis presentes na área de composição ou pré-visualização enquanto o utilizador está a compor a mensagem. Na área de composição, a atualização em Cartão Ajustável funciona e o bot pode querer utilizar um token para fornecer uma vista específica do utilizador ao utilizador da aplicação antes de enviar o cartão para o chat.

Introdução ao OAuth ou ao fluxo de início de sessão nominal

Os passos de autenticação OAuth ou nominal para Cartões Ajustáveis com Ações Universais são semelhantes ao bot no Teams.

Certifique-se de que adicionou autenticação ao bot do Teams. Para saber mais sobre como criar um bot ativado para autenticação, como implementar o bot no Azure e associá-lo a um fornecedor de identidade e como integrar o bot no Microsoft Teams, consulte Adicionar autenticação ao bot do Teams.

Para uma experiência de início de sessão OAuth ou nominal na qual o utilizador é apresentado com um botão ou ligação de início de sessão, o seguinte é o fluxo de início de sessão oAuth ou nominal:

1. O cliente do Teams envia um Cartão Ajustável ou actionInvokeActivity um pedido ao bot.

2. O bot utiliza o protocolo Do Serviço de Tokens para verificar se já existe um token em cache para o utilizador especificado no activity.from.id campo. O canal é especificado no activity.channelId campo para o bot e a ligação que está configurada.

3. Se existir um token em cache, o bot pode utilizar este token. Se não existir nenhum token, o bot cria um OAuthCard e coloca-o na resposta com os seguintes valores:

   {
     'statusCode': 401,
     'type': 'application/vnd.microsoft.activity.loginRequest',
     'value': {
        'text': 'Please sign-in',
        'connectionName': '<configured-connection-name>',
        'buttons': [
           {
              'title': 'Sign-In',
              'text': 'Sign-In',
              'type': 'signin',
              'value': '<sign-in-URL>'
           }
        ]
     }
   }   
   

   • Os remetentes têm de incluir um valor que cumpra o formato OAuthCard.
   • Os remetentes têm de incluir um connectionName. Os recetores podem ignorar pedidos de início de sessão com um vazio ou em falta connectionName.
   • Os remetentes têm de incluir um button que tenha uma matriz de botões não vazios.

4. Ao receber esta resposta, o cliente do Teams mostra um botão Iniciar Sessão no rodapé do cartão onde o utilizador pode iniciar sessão.

   

5. Quando o utilizador seleciona o botão Iniciar Sessão , a página de início de sessão do fornecedor de identidade é aberta numa janela do browser. Após o utilizador iniciar sessão, a página Serviço de Tokens é apresentada com um valor de código de autorização.

6. O cliente do Teams cria e envia a adaptiveCard/action atividade de invocação com name. O valor inclui o state campo que contém o código de autorização:

   {
      'type': 'invoke',
      'name': 'adaptiveCard/action'
      'value': {
         'action': {
            'id': 'abc123',
            'type': 'Action.Execute',
            'verb': 'saveCommand',
            'data': {
               'firstName': 'Jeff',
               'lastName': 'Derstadt'
            }
         },
      'state': '123456'
      },
      ...
   }
   
   

   Os remetentes têm de incluir um state campo.

7. O canal fornece esta invocação ao bot, que utiliza o código de autenticação para obter o token do Serviço de Tokens. O Serviço de Tokens fornece o token de acesso do utilizador ao bot.

   Os recetores podem ignorar a adaptiveCard/action invocação ou resposta com um erro se existir um campo em falta ou vazio state .

   Se o valor no state campo estiver incorreto, o bot devolve um erro ao cliente do Teams da seguinte forma:

     {
      'statusCode': 401,
      'type': 'application/vnd.microsoft.error.invalidAuthCode',
     }
   

   O cliente do Teams pode pedir novamente ao utilizador o código de autorização correto ou pode enviar um Action.Execute pedido novamente.

8. Se o código de autorização no state campo estiver correto, o bot utiliza o token de acesso em nome do utilizador para realizar as ações.

9. O bot responde com um cartão ou mensagem ao cliente do Teams sem um erro.

Confira também

• Trabalhar com Ações Universais de Cartões Ajustáveis
• Ativar o SSO para Ações Universais de Cartões Ajustáveis