Adicionar autenticação de terceiros à sua extensão de mensagem

  • Artigo

Importante

Os exemplos de código nesta seção são baseados em versões v4.6 e posteriores do SDK do Bot Framework. Se você estiver procurando documentação para versões anteriores, consulte a seção Extensões de Mensagem – v3 SDK na pasta Recursos da documentação.

Observação

Depois de adicionar autenticação à extensão de mensagem, você deve adicionar "token.botframework.com" à seção "validDomains" no manifesto.

Identifique o usuário

Cada solicitação para seus serviços inclui a ID do usuário, o nome de exibição do usuário e Microsoft Entra ID do objeto.

"from": {
  "id": "29:1C7dbRrC_5yzN1RGtZIrcWT0xz88KPGP9sxdpVpV8sODlgPHeQE9RqQ02hnpuKzy6zZ-AaZx6swUOMj_Dsdse3TQ4sIaeebbFBF-VgjJy_nY",
  "name": "Larry Jin",
  "aadObjectId": "cd723fa0-0591-416a-9290-e93ecf3a9b92"
},

Os valores id e aadObjectId são garantidos para o usuário autenticado do Teams. Eles são usados como chaves para pesquisar as credenciais ou qualquer estado armazenado em cache em seu serviço. Além disso, cada solicitação contém a ID do locatário Microsoft Entra, que é usada para identificar a organização do usuário. Se aplicável, a solicitação também conterá a ID da equipe e a ID do canal dos quais a solicitação é originada.

Autenticação

Se o serviço exigir autenticação de usuário, os usuários deverão entrar antes de usarem a extensão de mensagem. As etapas de autenticação são semelhantes às de um bot ou guia. A sequência é a seguinte:

  1. O usuário emite uma consulta ou a consulta padrão é enviada automaticamente ao seu serviço.
  2. O serviço verifica se o usuário é autenticado inspecionando a ID de usuário do Teams.
  3. Se o usuário não estiver autenticado, envie uma resposta auth com uma ação sugerida openUrl incluindo a URL de autenticação.
  4. O cliente do Microsoft Teams inicia uma caixa de diálogo que hospeda sua página da Web usando a URL de autenticação fornecida.
  5. Depois que o usuário entrar, você deverá fechar a janela e enviar um código de autenticação para o cliente do Teams.
  6. Em seguida, o cliente do Teams emiti novamente a consulta ao seu serviço, que inclui o código de autenticação passado na Etapa 5.

Seu serviço deve verificar o código de autenticação recebido na etapa 6 corresponde à etapa 5. As etapas garantem que um usuário mal-intencionado não tente falsificar ou comprometer o fluxo de entrada. O fluxo efetivamente "fecha o loop" para concluir a sequência de autenticação segura.

Responda com uma ação de entrada

Para solicitar que um usuário não autenticado entre, responda com uma ação sugerida do tipo openUrl que inclui a URL de autenticação.

Exemplo de resposta para uma ação de entrada

{
  "composeExtension":{
    "type":"auth",
    "suggestedActions":{
      "actions":[
        {
          "type": "openUrl",
          "value": "https://example.com/auth",
          "title": "Sign in to this app"
        }
      ]
    }
  }
}

Observação

  • Para que a experiência de entrada seja hospedada em uma janela pop-up do Teams, a parte do domínio da URL deve estar na lista de domínios válidos do seu aplicativo. Para obter mais informações, confira validDomains no esquema de manifesto.
  • O tamanho do pop-up de autenticação pode ser definido incluindo parâmetros da cadeia de caracteres de consulta de largura e altura, Value = $"{_siteUrl}/searchSettings.html?height=600&width=600".

Inicie o fluxo de entrada

Sua experiência de entrada deve ser responsiva e se encaixar em uma janela pop-up. Ele deve integrar-se à biblioteca de clientes JavaScript do Microsoft Teams, que usa a passagem de mensagens.

Assim como com outras experiências inseridas em execução no Microsoft Teams, o código dentro da janela precisa primeiro chamar app.initialize(). Se o código executar um fluxo OAuth, você poderá passar a ID de usuário do Teams para sua janela, que a passa para a URL de entrada do OAuth.

Conclua o fluxo de entrada

Quando a solicitação de entrada for concluída e redirecionada de volta para sua página, ela deverá executar as seguintes etapas:

  1. Gerar um código de segurança, um número aleatório. Você deve armazenar esse código em cache em seu serviço, com as credenciais obtidas por meio do fluxo de entrada, como tokens OAuth 2.0.
  2. Chamar authentication.notifySuccess e passar o código de segurança.

Nesse ponto, a janela é fechada e o controle é passado para o cliente do Teams. O cliente agora emiti novamente a consulta do usuário original, juntamente com o código de segurança na propriedade state. Seu código pode usar o código de segurança para pesquisar as credenciais armazenadas anteriormente para concluir a sequência de autenticação e, em seguida, concluir a solicitação do usuário.

Exemplo de solicitação reemitida

{
    "name": "composeExtension/query",
    "value": {
        "commandId": "insertWiki",
        "parameters": [{
            "name": "searchKeyword",
            "value": "lakers"
        }],
        "state": "12345",
        "queryOptions": {
            "skip": 0,
            "count": 25
        }
    },
    "type": "invoke",
    "timestamp": "2017-04-26T05:18:25.629Z",
    "localTimestamp": "2017-04-25T22:18:25.629-07:00",
    "entities": [{
        "locale": "en-US",
        "country": "US",
        "platform": "Web",
        "type": "clientInfo"
    }],
    "text": "",
    "attachments": [],
    "address": {
        "id": "f:7638210432489287768",
        "channelId": "msteams",
        "user": {
            "id": "29:1A5TJWHkbOwSyu_L9Ktk9QFI1d_kBOEPeNEeO1INscpKHzHTvWfiau5AX_6y3SuiOby-r73dzHJ17HipUWqGPgw",
            "aadObjectId": "fc8ca1c0-d043-4af6-b09f-141536207403"
        },
        "conversation": {
            "id": "19:7705841b240044b297123ad7f9c99217@thread.skype"
        },
        "bot": {
            "id": "28:c073afa8-7e77-4f92-b3e7-aa589e952a3e",
            "name": "maotestbot2"
        },
        "serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/",
        "useAuth": true
    },
    "source": "msteams"
}

Exemplo de código

Nome de exemplo Descrição .NET Node.js Manifesto
Extensões de mensagem – autenticação e configuração Uma extensão de mensagem que tem uma página de configuração, aceita solicitações de pesquisa e retorna resultados após a entrada do usuário. View View Exibir

Confira também

Habilitar o SSO para seu aplicativo de extensão de bot e mensagem