Adicionar autenticação de terceiros às Ações Universais de Cartões Adaptáveis

  • Artigo

As Ações Universais de Cartões Adaptáveis usam o bot como o back-end comum para lidar com ações e introduzir um novo tipo Action.Executede ação , que funciona entre aplicativos, como Teams e Outlook.

Observação

O suporte ao esquema de Ações Universais de Cartões Adaptáveis v1.4 só está disponível para cartões enviados por bot.

Você pode habilitar os seguintes cenários com Action.Execute em seus Cartões Adaptáveis Ação Universal:

Para saber mais sobre Ações Universais de Cartões Adaptáveis, confira Ações Universais de Cartões Adaptáveis.

Se você quiser adicionar exibições específicas do usuário em instâncias em que um Cartão Adaptável com a Ação Universal é compartilhado, no contexto de um chat em grupo ou um canal, o usuário pode precisar ser autenticado.

No passado, os usuários que conversavam um contra um com o bot tiveram que esperar enquanto você enviava a eles uma cartão de autenticação separada. Para se comunicar com o bot, o usuário precisaria alternar do chat de grupo ou do canal que incomodaria o fluxo.

Fluxo de autenticação no protocolo Action.Execute

O fluxo de autenticação para OAuth, dentro do Action.Execute protocolo, permite a autenticação dentro do contexto do chat em grupo ou da conversa de canal em que o Cartão Adaptável é compartilhado.

Os bots podem responder com a solicitação de entrada em resposta a Action.Execute :

  • Cartões Adaptáveis enviados por bot em um chat individual, chat em grupo ou um canal.
  • Cartões Adaptáveis enviados pelo usuário do aplicativo por meio de aplicativo de extensão de mensagem (com suporte por bot) em chat individual, chat em grupo ou canal.
  • Cartões Adaptáveis presentes na área de composição ou visualização enquanto o usuário está compondo a mensagem. Na área de composição, a atualização no Cartão Adaptável funciona e o bot pode querer usar um token para fornecer uma exibição específica do usuário para o usuário do aplicativo antes de enviar o cartão para o chat.

Introdução ao fluxo de logon OAuth ou nominal

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

Verifique se você adicionou autenticação ao bot do Teams. Para saber mais sobre como criar um bot habilitado para autenticação, como implantar o bot no Azure e associá-lo a um provedor de identidade e como integrar o bot no Microsoft Teams, confira adicionar autenticação ao bot do Teams.

Para uma experiência de logon OAuth ou nominal na qual o usuário é apresentado com um botão ou link de entrada, o seguinte é o fluxo de logon OAuth ou nominal:

A captura de tela mostra o fluxo de autenticação dos Cartões Adaptáveis com Ações Universais.

  1. O cliente do Teams envia um Cartão Adaptável ou actionInvokeActivity uma solicitação para o bot.

  2. O bot usa o protocolo Serviço de Token para marcar se já houver um token armazenado em cache para o usuário especificado no activity.from.id campo. O canal é especificado no activity.channelId campo para o bot e a conexão configurada.

  3. Se houver um token armazenado em cache, o bot poderá usar esse token. Se não houver nenhum token, o bot criará um OAuthCard e o colocará 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 devem incluir um valor que adere ao formato OAuthCard.
    • Os remetentes devem incluir um connectionName. Os receptores podem ignorar solicitações de entrada com um vazio ou ausente connectionName.
    • Os remetentes devem incluir um button que tenha uma matriz de botões não vazia.

  4. Ao receber essa resposta, o cliente do Teams mostra um botão de entrada no rodapé cartão em que o usuário pode entrar.

    A captura de tela mostra o botão Sign-In no cartão Adaptável.

  5. Quando o usuário seleciona o botão Entrar , a página de entrada do provedor de identidade é aberta em uma janela do navegador. Depois que o usuário entra, a página Serviço de Token aparece com um valor de código de autorização.

  6. O cliente do Teams cria e envia a atividade de invocação adaptiveCard/action 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 devem incluir um state campo.

  7. O canal fornece essa invocação para o bot, que usa o código de autenticação para recuperar o token do Serviço de Token. O Serviço de Token fornece o token de acesso do usuário ao bot.

    Os receptores podem ignorar a adaptiveCard/action invocação ou a resposta com um erro se houver um campo ausente ou vazio state .

    Se o valor no state campo estiver incorreto, o bot retornará um erro ao cliente do Teams da seguinte maneira:

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

    O cliente do Teams pode solicitar novamente ao usuário o código de autorização correto ou enviar uma solicitação Action.Execute novamente.

  8. Se o código de autorização no state campo estiver correto, o bot usará o token de acesso em nome do usuário para executar suas ações.

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

Confira também