Adicionar autenticação à sua extensão de mensagensAdd authentication to your messaging extension

Importante

Os exemplos de código nesta seção são baseados em 4.6 e versões posteriores do SDK da Estrutura de Bot.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Se você estiver procurando documentação para versões anteriores, consulte a seção Extensões de Mensagens - V3 SDK na pasta Recursos da documentação.If you're looking for documentation for earlier versions, see the Messaging Extensions - v3 SDK section in the Resources folder of the documentation.

Identificar o usuárioIdentify the user

Todas as solicitações aos seus serviços incluem a ID do usuário, o nome de exibição do usuário e Azure Active Directory ID do objeto.Every request to your services includes the user ID, the user's display name and Azure Active Directory object ID.

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

Os id valores e são aadObjectId garantidos para o usuário Teams autenticado.The id and aadObjectId values are guaranteed for the authenticated Teams user. Eles são usados como chaves para procurar as credenciais ou qualquer estado armazenado em cache em seu serviço.They are used as keys to look up the credentials or any cached state in your service. Além disso, cada solicitação contém Azure Active Directory ID de locatário do usuário, que é usada para identificar a organização do usuário.In addition, each request contains the Azure Active Directory tenant ID of the user, which is used to identify the user’s organization. Se aplicável, a solicitação também contém a ID de equipe e a ID do canal da qual a solicitação é originada.If applicable, the request also contains the team Id and channel ID from which the request is originated.

AutenticaçãoAuthentication

Se o serviço exigir autenticação do usuário, os usuários devem entrar antes de usar a extensão de mensagens.If your service requires user authentication, the users must sign in before they use the messaging extension. As etapas de autenticação são semelhantes às de um bot ou guia. A sequência é a seguinte:The authentication steps are similar to that of a bot or tab. The sequence is as follows:

  1. O usuário emite uma consulta ou a consulta padrão é enviada automaticamente ao seu serviço.User issues a query, or the default query is automatically sent to your service.
  2. Seu serviço verifica se o usuário é autenticado inspecionando Teams ID do usuário.Your service checks whether the user is authenticated by inspecting the Teams user ID.
  3. Se o usuário não for autenticado, envie uma resposta auth com uma openUrl ação sugerida, incluindo a URL de autenticação.If the user is not authenticated, send back an auth response with an openUrl suggested action including the authentication URL.
  4. O Microsoft Teams cliente inicia uma caixa de diálogo hospedando sua página da Web usando a URL de autenticação determinada.The Microsoft Teams client launches a dialog box hosting your webpage using the given authentication URL.
  5. Depois que o usuário entrar, você deve fechar a janela e enviar um código de autenticação para o Teams cliente.After the user signs in, you should close your window and send an authentication code to the Teams client.
  6. O Teams cliente, em seguida, reeditará a consulta para o seu serviço, que inclui o código de autenticação passado na Etapa 5.The Teams client then reissues the query to your service, which includes the authentication code passed in Step 5.

Seu serviço deve verificar se o código de autenticação recebido na etapa 6 corresponde ao da etapa 5.Your service should verify that the authentication code received in step 6 matches the one from step 5. Isso garante que um usuário mal-intencionado não tente fazer a spoof ou comprometer o fluxo de login.This ensures that a malicious user does not try to spoof or compromise the sign in flow. Isso efetivamente "fecha o loop" para concluir a sequência de autenticação segura.This effectively "closes the loop" to finish the secure authentication sequence.

Responder com uma ação de loginRespond with a sign-in action

Para solicitar que um usuário não autenticado entre, responda com uma ação sugerida do tipo que inclui a openUrl URL de autenticação.To prompt an unauthenticated user to sign in, respond with a suggested action of type openUrl that includes the authentication URL.

Exemplo de resposta para uma ação de loginResponse example for a sign-in action

{
  "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 login seja hospedada em uma janela pop-up Teams, a parte de domínio da URL deve estar na lista de domínios válidos do aplicativo.For the sign in experience to be hosted in a Teams pop-up window, the domain portion of the URL must be in your app’s list of valid domains. Para obter mais informações, consulte validDomains no esquema de manifesto.For more information, see validDomains in the manifest schema.

Iniciar o fluxo de loginStart the sign in flow

Sua experiência de login deve ser responsiva e adequada dentro de uma janela pop-up.Your sign in experience must be responsive and fit within a pop-up window. Ele deve se integrar ao Microsoft Teams SDK do cliente JavaScript, que usa a passagem de mensagens.It should integrate with the Microsoft Teams JavaScript client SDK, which uses message passing.

Assim como outras experiências incorporadas em execução dentro Microsoft Teams, seu código dentro da janela precisa chamar primeiro microsoftTeams.initialize() .As with other embedded experiences running inside Microsoft Teams, your code inside the window needs to first call microsoftTeams.initialize(). Se seu código executar um fluxo OAuth, você poderá passar a ID do usuário Teams para sua janela, que o passa para a URL de entrada do OAuth.If your code performs an OAuth flow, you can pass the Teams user ID into your window, which then passes it to the OAuth sign-in URL.

Concluir o fluxo de loginComplete the sign in flow

Quando a solicitação de entrar é concluída e redireciona de volta para sua página, ela deve executar as seguintes etapas:When the sign in request completes and redirects back to your page, it must perform the following steps:

  1. Gere um código de segurança.Generate a security code. Esse é um número aleatório.This is a random number. Você deve armazenar em cache esse código em seu serviço, juntamente com as credenciais obtidas por meio do fluxo de logon, como tokens OAuth 2.0.You must cache this code on your service, along with the credentials obtained through the sign in flow, such as OAuth 2.0 tokens.
  2. Chame microsoftTeams.authentication.notifySuccess e passe o código de segurança.Call microsoftTeams.authentication.notifySuccess and pass the security code.

Neste ponto, a janela fecha e o controle é passado para o cliente Teams.At this point, the window closes and control is passed to the Teams client. O cliente agora reeditará a consulta de usuário original, juntamente com o código de segurança na state propriedade.The client now reissues the original user query, along with the security code in the state property. Seu código pode usar o código de segurança para procurar as credenciais armazenadas anteriormente para concluir a sequência de autenticação e concluir a solicitação do usuário.Your code can use the security code to look up the credentials stored earlier to complete the authentication sequence and then complete the user request.

Exemplo de solicitação reemissãoReissued request example

{
    "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ódigoCode sample

Exemplo de nomeSample name DescriçãoDescription .NET.NET Node.jsNode.js
Extensões de mensagens - auth e configMessaging extensions - auth and config Uma Extensão de Mensagens que tem uma página de configuração, aceita solicitações de pesquisa e retorna resultados depois que o usuário se inscreveu.A Messaging Extension that has a configuration page, accepts search requests, and returns results after the user has signed in. ViewView ViewView