Добавление проверки подлинности к своему расширению обмена сообщениямиAdd authentication to your messaging extension

Важно!

Примеры кода, приведенные в этом разделе, основаны на 4,6 и более поздних версиях пакета SDK Bot.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Если вы ищете документацию по более ранним версиям, ознакомьтесь с разделом Messaging Extensions – v3 SDK в папке resources этой документации.If you're looking for documentation for earlier versions, see the Messaging Extensions - v3 SDK section in the Resources folder of the documentation.

Идентификация пользователяIdentify the user

Каждый запрос к службам включает в себя идентификатор пользователя, который выполнил запрос, а также отображаемое имя пользователя и идентификатор объекта Azure Active Directory.Every request to your services includes the obfuscated ID of the user that performed the request, as well as 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"
},

Гарантируется, что значения id и aadObjectId значения для пользователя Teams прошли проверку подлинности.The id and aadObjectId values are guaranteed to be that of the authenticated Teams user. Они могут использоваться в качестве ключей для поиска учетных данных или любого кэшированного состояния в службе.They can be used as keys to look up credentials or any cached state in your service. Кроме того, каждый запрос содержит идентификатор клиента Azure Active Directory для пользователя, который можно использовать для определения организации пользователя.In addition, each request contains the Azure Active Directory tenant ID of the user, which can be used to identify the user’s organization. Если это возможно, запрос также содержит идентификаторы команд и каналов, из которых поступил запрос.If applicable, the request also contains the team and channel IDs from which the request originated.

Проверка подлинностиAuthentication

Если для вашей службы требуется проверка подлинности пользователя, необходимо войти в систему, прежде чем ее сможет использовать расширение системы обмена сообщениями.If your service requires user authentication, you need to sign in the user before he or she can use the messaging extension. Если вы написали робот или вкладку, которые подписываются пользователю, этот раздел должен быть знаком.If you have written a bot or a tab that signs in the user, this section should be familiar.

Последовательность выглядит следующим образом:The sequence is as follows:

  1. Пользователь выдает запрос, или запрос по умолчанию автоматически отправляется в службу.User issues a query, or the default query is automatically sent to your service.
  2. Служба проверяет, прошел ли пользователь проверку подлинности, проверив идентификатор пользователя Teams.Your service checks whether the user has first authenticated by inspecting the Teams user ID.
  3. Если пользователь не прошел проверку подлинности, отправьте auth ответ с openUrl предложенным действием, включая URL-адрес проверки подлинности.If the user has not authenticated, send back an auth response with an openUrl suggested action including the authentication URL.
  4. Клиент Microsoft Teams запускает всплывающее окно, в котором размещается веб-страница, используя указанный URL-адрес проверки подлинности.The Microsoft Teams client launches a pop-up window hosting your webpage using the given authentication URL.
  5. После входа пользователя необходимо закрыть окно и отправить ему код проверки подлинности в клиент Teams.After the user signs in, you should close your window and send an "authentication code" to the Teams client.
  6. Затем клиент Teams повторно отправляет запрос в службу, который включает код проверки подлинности, переданный на шаге 5.The Teams client then reissues the query to your service, which includes the authentication code passed in step 5.

Ваша служба должна проверить, что код проверки подлинности, полученный на шаге 6, соответствует тому, что получено на шаге 5.Your service should verify that the authentication code received in step 6 matches the one from step 5. Это гарантирует, что злоумышленник не будет пытаться подменить или ослабить процесс входа в систему.This ensures that a malicious user does not try to spoof or compromise the sign-in flow. Это фактически "закрывает цикл" для завершения безопасной последовательности проверки подлинности.This effectively "closes the loop" to finish the secure authentication sequence.

Ответ с действием входаRespond with a sign-in action

Чтобы выдать запрос пользователю, не прошедшему проверку подлинности, выполните ответ с openUrl предложенным действием типа, которое включает URL-адрес проверки подлинности.To prompt an unauthenticated user to sign in, respond with a suggested action of type openUrl that includes the authentication URL.

Пример отклика для действия при входеResponse example for a sign-in action

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

Примечание

Для того чтобы при входе в систему можно было размещаться в всплывающем окне Teams, в списке допустимых доменов приложения должен находиться домен, являющийся частью URL-адреса.For the sign-in experience to be hosted in a Teams pop-up, the domain portion of the URL must be in your app’s list of valid domains. (См. раздел валиддомаинс в схеме манифеста.)(See validDomains in the manifest schema.)

Запуск процесса входаStart the sign-in flow

Ваш интерфейс пользователя должен отвечать на запросы и размещаться в всплывающем окне.Your sign-in experience should be responsive and fit within a popup window. Он должен интегрироваться с клиентским пакетом SDK для Microsoft Teams JavaScript, который использует передачу сообщений.It should integrate with the Microsoft Teams JavaScript client SDK, which uses message passing.

Как и другие встроенные возможности, выполняемые в Microsoft Teams, код в окне должен вызываться microsoftTeams.initialize()первым.As with other embedded experiences running inside Microsoft Teams, your code inside the window needs to first call microsoftTeams.initialize(). Если ваш код выполняет процесс OAuth, можно передать идентификатор пользователя Teams в ваше окно, которое затем может передать его в URL-адрес входа OAuth.If your code performs an OAuth flow, you can pass the Teams user ID into your window, which then can pass it to the OAuth sign-in URL.

Завершение процесса входаComplete the sign-in flow

Когда запрос на вход завершается и перенаправляется обратно на страницу, он должен выполнить следующие действия:When the sign-in request completes and redirects back to your page, it should perform the following steps:

  1. Создайте код безопасности.Generate a security code. (Это может быть случайное число.) Необходимо кэшировать этот код в службе, а также учетные данные, полученные с помощью процесса входа (например, OAuth 2,0 tokens).(This can be a random number.) You need to cache this code on your service, along with the credentials obtained through the sign-in flow (such as OAuth 2.0 tokens).
  2. Позвоните microsoftTeams.authentication.notifySuccess и передайте код безопасности.Call microsoftTeams.authentication.notifySuccess and pass the security code.

На этом шаге окно закрывается и управление передается клиенту Teams.At this point, the window closes and control is passed to the Teams client. Теперь клиент может повторно отправить исходный запрос пользователя, а также код безопасности в state свойстве.The client now can reissue the original user query, along with the security code in the state property. Код может использовать код безопасности для поиска ранее сохраненных учетных данных, чтобы выполнить последовательность проверки подлинности, а затем выполнить запрос пользователя.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.

Пример повторной выданной заявкиReissued 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"
}