Поделиться через

Добавление сторонней проверки подлинности в расширение сообщений

  • Статья

Важно!

Примеры кода в этом разделе основаны на версии 4.6 и более поздних версиях пакета SDK Bot Framework. Если вы ищете документацию по более ранним версиям, см. раздел Расширения сообщений — пакет SDK версии 3 в папке Resources документации.

Примечание.

После добавления проверки подлинности в расширение сообщений необходимо добавить "token.botframework.com" в раздел "validDomains" манифеста.

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

Каждый запрос к службам включает идентификатор пользователя, отображаемое имя пользователя и идентификатор объекта Microsoft Entra.

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

Для пользователя, прошедшего проверку подлинности Teams, гарантируется наличие id и aadObjectId. Они используются в качестве ключей для поиска учетных данных или любого кэшированного состояния в службе. Кроме того, каждый запрос содержит идентификатор клиента Microsoft Entra, который используется для идентификации организации пользователя. Если применимо, запрос также содержит идентификатор команды и идентификатор канала, из которого поступил запрос.

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

Если служба требует проверки подлинности пользователя, пользователи должны войти в систему, прежде чем использовать расширение для сообщений. Шаги проверки подлинности в этом случае аналогичны шагам для бота или вкладки. Последовательность действий выглядит следующим образом:

  1. Пользователь отправляет запрос или запрос по умолчанию автоматически отправляется в службу.
  2. Ваша служба определяет, прошел ли пользователь проверку подлинности, проверяя его идентификатор Teams.
  3. Если пользователь не прошел проверку подлинности, отправьте ответ auth с предложением выполнить действие openUrl, включающим URL-адрес проверки подлинности.
  4. Используя заданный URL-адрес проверки подлинности, клиент Microsoft Teams запускает диалоговое окно, в котором размещается ваша веб-страница.
  5. После входа пользователя следует закрыть окно и отправить код проверки подлинности Teams клиенту.
  6. Затем Teams повторно отправляет в вашу службу запрос, содержащий код проверки подлинности, переданный на шаге 5.

Ваша служба должна проверить, что код проверки подлинности, полученный на шаге 6, соответствует шагу 5. Эти действия гарантируют, что злоумышленник не пытается подделать или скомпрометировать поток входа. Поток фактически "закрывает цикл", чтобы завершить последовательность безопасной проверки подлинности.

Ответ с помощью действия входа

Чтобы заставить пользователя без проверки подлинности выполнить вход, ответьте рекомендуемым действием типа openUrl , включающее URL-адрес проверки подлинности.

Пример ответа для действия входа

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

Примечание.

  • Чтобы интерфейс входа размещался во всплывающем окне Teams, доменная часть URL-адреса должна быть в списке допустимых доменов приложения. Дополнительные сведения см. в разделе validDomains в схеме манифеста.
  • Размер всплывающего окна проверки подлинности можно задать, включив в строку запроса параметры ширины и высоты Value = $"{_siteUrl}/searchSettings.html?height=600&width=600".

Запуск потока входа

Интерфейс входа должен обладать гибким дизайном и умещаться во всплывающем окне. Он должен интегрироваться с клиентской библиотекой JavaScript Microsoft Teams, которая использует передачу сообщений.

Как и в случае с другими встроенными пользовательскими интерфейсами Microsoft Teams, код в окне должен сначала вызвать app.initialize(). Если код выполняет поток OAuth, вы можете передать идентификатор пользователя Teams окну, которое затем передает его по URL-адресу для входа в OAuth.

Завершение потока входа

После того, как обработка запроса на вход завершена и пользователь перенаправлен обратно на страницу, она должен выполнить следующие действия:

  1. Генерировать код безопасности, случайное число. Этот код необходимо кэшировать в службе с учетными данными, полученными в потоке входа, например маркерами OAuth 2.0.
  2. Вызовите authentication.notifySuccess и передайте код безопасности.

После этого окно закрывается и управление передается клиенту Teams. Теперь клиент повторно отсылает исходный пользовательский запрос, содержащий код безопасности в свойстве state. Ваша программа может использовать код безопасности для поиска учетных данных, сохраненных ранее, для завершения последовательности проверки подлинности, а затем для выполнения запроса пользователя.

Пример повторно отправленного запроса

{
    "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"
}

Пример кода

Название примера Описание .NET Node.js Манифест
Расширения для сообщений — аутентификация и конфигурация Расширение сообщений, которое имеет страницу конфигурации, принимает поисковые запросы и возвращает результаты после входа пользователя. Просмотр Просмотр Просмотр

См. также

Включение единого входа для бота и приложения расширения сообщений