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

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 a ID do 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 solicitação contém a ID de locatário do 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 se 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 inclua a URL de autenticação.

Exemplo de resposta para uma ação de entrada

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

Inicie o fluxo de entrada

Sua experiência de entrada deve ser responsiva e se encaixar em uma janela pop-up. Ele deve se integrar à biblioteca de cliente 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 em cache esse código em seu serviço, com as credenciais obtidas por meio do fluxo de login, como tokens OAuth 2.0.

2. Chamar authentication.notifySuccess e passar o código de segurança.

   Importante

   Lembre-se de que há considerações de segurança para o notifySuccess() parâmetro result. Para obter informações adicionais, consulte a seção comentários da documentação de referência do TeamsJS para a função notifySuccess().

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

Confira também

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