Partilhar via

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

  • Artigo

Importante

Os exemplos de código nesta secção baseiam-se na v4.6 e versões posteriores do SDK do Bot Framework. Se estiver à procura de documentação para versões anteriores, veja a secção Extensões de Mensagens – SDK v3 na pasta Recursos da documentação.

Observação

Depois de adicionar a autenticação à extensão de mensagem, tem de adicionar "token.botframework.com" à secção "validDomains" no manifesto.

Identifique o usuário

Todos os pedidos aos seus serviços incluem o ID de utilizador, o nome a apresentar do utilizador e o ID de objeto do Microsoft Entra.

"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 pedido contém o ID de inquilino do Microsoft Entra, que é utilizado para identificar a organização do utilizador. 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.

O seu serviço deve verificar se o código de autenticação recebido no passo 6 corresponde ao passo 5. Os passos garantem que um utilizador malicioso não tenta falsificar ou comprometer o fluxo de início de sessão. O fluxo "fecha efetivamente o ciclo" para concluir a sequência de autenticação segura.

Responda com uma ação de entrada

Para pedir a um utilizador não autenticado para iniciar sessão, responda com uma ação sugerida do tipo openUrl que inclui o 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. Deve integrar com a biblioteca de cliente JavaScript do Microsoft Teams, que utiliza a transmissão 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. Tem de colocar este código em cache no seu serviço, com as credenciais obtidas através do fluxo de início de sessão, 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 pedidos de pesquisa e devolve resultados após o utilizador iniciar sessão. View View Exibir

Confira também

Ativar o SSO para a aplicação de extensão de bot e mensagem