Проверка подлинности с помощью API бота Подключение or

  • Статья

Бот взаимодействует со службой Bot Connector по протоколу HTTP через защищенный канал (SSL/TLS). Запрос, отправляемый ботом в службу Bot Connector, должен содержать сведения, с помощью которых служба будет проверять удостоверение бота. Точно так же, когда служба Bot Connector отправляет запрос боту, она должна включить в него сведения, с помощью которых бот проверит удостоверение службы. В этой статье описываются технологии проверки подлинности и требования к проверке подлинности уровня службы, выполняемой между ботом и службой Bot Connector. Если вы пишете собственный код проверки подлинности, необходимо реализовать процедуры безопасности, описанные в этой статье, чтобы бот мог обмениваться сообщениями со службой Bot Подключение or.

Важно!

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

Если вы используете пакет SDK Bot Framework, вам не нужно реализовать процедуры безопасности, описанные в этой статье, так как пакет SDK автоматически делает его для вас. Просто настройте проект с использованием идентификатора приложения и пароля, полученных для бота во время регистрации, а все остальное сделает пакет SDK.

Технологии проверки подлинности

Для установления доверительных отношений между ботом и службой Bot Connector используются следующие четыре технологии проверки подлинности.

Технология Description
SSL/TLS SSL/TLS используется для всех подключений между службами. Сертификаты X.509v3 используются для идентификации всех служб HTTPS. Клиенты всегда должны проверять сертификаты службы, чтобы убедиться в их надежности и допустимости. (В рамках этой схемы сертификаты клиента не используются.)
OAuth 2.0 OAuth 2.0 использует службу входа учетной записи Идентификатора Майкрософт для создания безопасного маркера, который бот может использовать для отправки сообщений. Этот маркер работает между службами. Вход пользователя не требуется.
JSON Web Token (JWT) JSON Web Token используется для кодирования маркеров, отправляемых ботам и из них. Клиенты должны полностью проверять все получаемые маркеры JWT в соответствии с требованиями, описанными в этой статье.
Метаданные OpenID Служба Bot Connector публикует список допустимых маркеров, используемых для подписи собственных маркеров JWT в метаданных OpenID в хорошо известной статической конечной точке.

В этой статье описывается, как использовать эти технологии с помощью стандартных форматов HTTPS и JSON. Специальные пакеты SDK не требуются, хотя вы можете найти, что вспомогательные средства для OpenID и другие полезны.

Проверка подлинности запросов от бота к службе бота Подключение or

Для взаимодействия со службой Bot Connector необходимо указать маркер доступа в заголовке Authorization каждого запроса API, используя следующий формат:

Authorization: Bearer ACCESS_TOKEN

Чтобы получить и использовать токен JWT для бота, выполните следующее:

  1. Бот отправляет HTTP-запрос GET в службу входа MSA.
  2. Ответ от службы содержит маркер JWT для использования.
  3. Бот включает этот токен JWT в заголовок авторизации в запросах к службе Bot Подключение or.

Шаг 1. Запрос маркера доступа из службы входа учетной записи Идентификатора Microsoft Entra

Важно!

Если вы еще этого не сделали, необходимо зарегистрировать бот в Bot Framework, чтобы получить его AppID и пароль. Идентификатор приложения и пароль бота потребуются для запроса маркера доступа.

Удостоверение бота можно управлять в Azure несколькими способами.

  • В качестве управляемого удостоверения, назначаемого пользователем, поэтому вам не нужно самостоятельно управлять учетными данными бота.
  • Как однотенантное приложение.
  • В качестве мультитенантного приложения.

Запрос маркера доступа на основе типа приложения бота.

Чтобы запросить маркер доступа из службы входа, выполните следующий запрос, заменив microsoft-APP-ID и MICROSOFT-APP-PASSWORD идентификатором appID бота и паролем, полученными при регистрации бота в Служба Bot.

POST https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=MICROSOFT-APP-ID&client_secret=MICROSOFT-APP-PASSWORD&scope=https%3A%2F%2Fapi.botframework.com%2F.default

Шаг 2. Получение маркера JWT из ответа службы входа учетной записи идентификатора Microsoft Entra ID

Если приложение авторизовано службой входа, в тексте ответа JSON будет указан маркер доступа, его тип и срок действия (в секундах).

При добавлении маркера в Authorization заголовок запроса необходимо использовать точное значение, указанное в этом ответе, не экранируйте или не кодируйте значение маркера. Маркер доступа действителен до окончания срока его действия. Чтобы предотвратить влияние окончания срока действия маркера на производительность бота, маркер можно кэшировать и заранее обновить.

В этом примере показан ответ службы входа учетной записи Microsoft Entra ID:

HTTP/1.1 200 OK
... (other headers)

{
    "token_type":"Bearer",
    "expires_in":3600,
    "ext_expires_in":3600,
    "access_token":"eyJhbGciOiJIUzI1Ni..."
}

Шаг 3. Указание маркера JWT в заголовке авторизации запросов

При отправке запроса API в службу Bot Connector укажите маркер доступа в заголовке Authorization каждого запроса API, используя следующий формат:

Authorization: Bearer ACCESS_TOKEN

Все запросы, отправляемые в службу Bot Connector, должны содержать маркер доступа в заголовке Authorization. Если маркер правильно сформирован, срок действия истек и создан службой входа учетной записи идентификатора Microsoft Entra ID, служба бота Подключение or будет авторизовать запрос. Чтобы убедиться, что маркер принадлежит боту, который отправил запрос, выполняются дополнительные проверки.

В следующем примере показано, как указать маркер доступа в заголовке Authorization запроса.

POST https://smba.trafficmanager.net/teams/v3/conversations/12345/activities
Authorization: Bearer eyJhbGciOiJIUzI1Ni...

(JSON-serialized Activity message goes here)

Важно!

Маркер JWT следует задавать только в заголовке Authorization запросов, отправляемых в службу Bot Connector. Не отправляйте маркер через незащищенные каналы и не включайте его в HTTP-запросы, отправляемые в другие службы. Маркер JWT, полученный из службы входа учетной записи Microsoft Entra ID, похож на пароль и должен обрабатываться с большим вниманием. Пользователь, обладающий маркером, может использовать его для выполнения операций от имени вашего бота.

Запрос от бота к службе Bot Connector: пример компонентов JWT

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "https://api.botframework.com",
  iss: "https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/",
  nbf: 1481049243,
  exp: 1481053143,
  appid: "<YOUR MICROSOFT APP ID>",
  ... other fields follow
}

Примечание.

На практике могут использоваться другие поля. Создайте и проверьте все маркеры JWT, как указано выше.

Проверка подлинности запросов из службы Бота Подключение or в бот

Когда служба Bot Connector отправляет запрос боту, она указывает подписанный маркер JWT в заголовке Authorization запроса. Бот может проверить подлинность вызовов от службы Bot Connector, проверив подлинность подписанного маркера JWT.

Для проверки подлинности вызовов из службы бота Подключение or:

  1. Бот получает токен JWT из заголовка авторизации в запросах, отправленных из службы бота Подключение or.
  2. Бот получает документ метаданных OpenID для службы бота Подключение or.
  3. Бот получает список допустимых ключей подписывания из документа.
  4. Бот проверяет подлинность токена JWT.

Шаг 2. Получение документа метаданных OpenID

Документ метаданных OpenID указывает расположение второго документа, в котором приведены допустимые ключи подписи службы Bot Connector. Чтобы получить документ метаданных OpenID, выполните следующий запрос по протоколу HTTPS:

GET https://login.botframework.com/v1/.well-known/openidconfiguration

Совет

Это статический URL-адрес, который можно жестко задать в приложении.

В следующем примере показан документ метаданных OpenID, возвращаемый в ответ на запрос GET. Свойство jwks_uri указывает расположение документа, который содержит допустимые ключи подписи службы Bot Connector.

{
    "issuer": "https://api.botframework.com",
    "authorization_endpoint": "https://invalid.botframework.com",
    "jwks_uri": "https://login.botframework.com/v1/.well-known/keys",
    "id_token_signing_alg_values_supported": [
      "RS256"
    ],
    "token_endpoint_auth_methods_supported": [
      "private_key_jwt"
    ]
}

Шаг 3. Получение списка допустимых ключей подписывания

Чтобы получить список допустимых ключей подписи, отправьте запрос GET по протоколу HTTPS на URL-адрес, указанный в свойстве jwks_uri в документе метаданных OpenID. Например:

GET https://login.botframework.com/v1/.well-known/keys

В тексте ответа указан документ в формате JWK и также содержатся дополнительные свойства для каждого ключа: endorsements.

Совет

Список ключей является стабильным и может быть кэширован, но новые ключи могут быть добавлены в любое время. Чтобы бот получил актуальную копию документа до использования этих ключей, все экземпляры ботов должны обновлять локальный кэш документа по крайней мере один раз каждые 24 часа.

Свойство endorsements в каждом ключе содержит одну или несколько строк подтверждения, которые можно использовать для проверки подлинности идентификатора канала, указанного в channelId свойстве объекта Activity для входящего запроса. Список идентификаторов каналов, требующих подтверждения, настраивается в каждом боте. По умолчанию в список будут входить все опубликованные идентификаторы каналов, однако разработчики ботов могут переопределить выбранные значения идентификаторов.

Шаг 4. Проверка маркера JWT

Чтобы проверить подлинность маркера, отправленного службой Bot Connector, необходимо извлечь его из заголовка Authorization запроса, проанализировать, проверить его содержимое и подпись.

Библиотеки синтаксического анализа JWT доступны для многих платформ, и большинство из них реализуют безопасный и надежный синтаксический анализ для токенов JWT, хотя обычно эти библиотеки необходимо настроить, чтобы определенные характеристики маркера (его издатель, аудитория и т. д.) содержали правильные значения. При анализе маркера необходимо настроить библиотеку анализа или написать собственную процедуру проверки маркера, чтобы маркер соответствовал приведенным ниже требованиям.

  1. Маркер был отправлен в заголовке HTTP Authorization со схемой носителя.
  2. Маркер имеет допустимый формат JSON, соответствующий стандарту JWT.
  3. Маркер содержит утверждение "issuer" со значением https://api.botframework.com.
  4. Маркер содержит утверждение "audience" со значением, соответствующим идентификатору приложения Майкрософт для бота.
  5. Маркер является действующим. Отраслевая разница в показаниях часов составляет 5 минут.
  6. Маркер имеет допустимую криптографическую подпись с ключом, приведенным в документе с ключами OpenID, который был получен на шаге 3, и алгоритмом подписи, который указан в свойстве id_token_signing_alg_values_supportedдокумента метаданных OpenID, который был получен на шаге 2.
  7. Маркер содержит утверждение serviceUrl со значением, которое соответствует свойству serviceUrl в корне объекта Activity входящего запроса.

Если требуется подтверждение для идентификатора канала:

  • любой объект Activity, отправляемый в бот с этим идентификатором канала, должен сопровождаться маркером JWT, который подписан с использованием подтверждения для этого канала;
  • Если подтверждение отсутствует, бот должен отклонить запрос, возвращая код состояния HTTP 403 (запрещено ).

Важно!

Все эти требования являются важными, особенно требования 4 и 6. При невозможности выполнить все эти требования бот будет открыт для атак, что может привести к раскрытию его маркера JWT.

Разработчики не должны предоставлять способ отключения проверки маркера JWT, который отправляется боту.

Запрос от службы Bot Connector к боту: пример компонентов JWT

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "<YOU MICROSOFT APP ID>",
  iss: "https://api.botframework.com",
  nbf: 1481049243,
  exp: 1481053143,
  ... other fields follow
}

Примечание.

На практике могут использоваться другие поля. Создайте и проверьте все маркеры JWT, как указано выше.

Проверка подлинности запросов из эмулятора Bot Framework в бот

Bot Framework Emulator — это инструмент для настольных систем, используемый для тестирования работоспособности бота. Хотя эмулятор Bot Framework использует те же технологии проверки подлинности, что и описано выше, не удается олицетворить реальную службу бота Подключение or. Вместо этого он использует идентификатор приложения Майкрософт и пароль приложения Майкрософт, указанный при подключении эмулятора к боту для создания маркеров, идентичных создаваемым ботом. Когда эмулятор отправляет запрос боту, он указывает токен JWT в Authorization заголовке запроса, в сущности, используя собственные учетные данные бота для проверки подлинности запроса.

Если вы реализуете библиотеку проверки подлинности и хотите принять запросы из эмулятора Bot Framework, необходимо добавить этот дополнительный путь проверки. Путь структурно похож на путь проверки Подключение or —> путь проверки бота, но он использует документ OpenID MSA вместо документа OpenID бота Подключение or.

Для проверки подлинности вызовов из эмулятора Bot Framework:

  1. Бот получает токен JWT из заголовка авторизации в запросах, отправленных из эмулятора Bot Framework.
  2. Бот получает документ метаданных OpenID для службы бота Подключение or.
  3. Бот получает список допустимых ключей подписывания из документа.
  4. Бот проверяет подлинность токена JWT.

Шаг 2. Получение документа метаданных OpenID MSA

Документ метаданных OpenID указывает расположение второго документа, в котором перечислены допустимые ключи подписи. Чтобы получить документ метаданных OpenID MSA, отправьте следующий запрос по протоколу HTTPS:

GET https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

В следующем примере показан документ метаданных OpenID, возвращаемый в ответ на запрос GET. Свойство jwks_uri указывает расположение документа, который содержит допустимые ключи подписи.

{
    "authorization_endpoint":"https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
    "token_endpoint":"https://login.microsoftonline.com/common/oauth2/v2.0/token",
    "token_endpoint_auth_methods_supported":["client_secret_post","private_key_jwt"],
    "jwks_uri":"https://login.microsoftonline.com/common/discovery/v2.0/keys",
    ...
}

Шаг 3. Получение списка допустимых ключей подписывания

Чтобы получить список допустимых ключей подписи, отправьте запрос GET по протоколу HTTPS на URL-адрес, указанный в свойстве jwks_uri в документе метаданных OpenID. Например:

GET https://login.microsoftonline.com/common/discovery/v2.0/keys
Host: login.microsoftonline.com

В тексте ответа документ указывается в формате JWK.

Шаг 4. Проверка маркера JWT

Чтобы проверить подлинность маркера, отправленного эмулятором, необходимо извлечь маркер из Authorization заголовка запроса, проанализировать маркер, проверить его содержимое и проверить его подпись.

Библиотеки синтаксического анализа JWT доступны для многих платформ, и большинство из них реализуют безопасный и надежный синтаксический анализ для токенов JWT, хотя обычно эти библиотеки необходимо настроить, чтобы определенные характеристики маркера (его издатель, аудитория и т. д.) содержали правильные значения. При анализе маркера необходимо настроить библиотеку анализа или написать собственную процедуру проверки маркера, чтобы маркер соответствовал приведенным ниже требованиям.

  1. Маркер был отправлен в заголовке HTTP Authorization со схемой носителя.
  2. Маркер имеет допустимый формат JSON, соответствующий стандарту JWT.
  3. Маркер содержит утверждение "издателя" с одним из выделенных значений для неправительственных случаев. Проверка обоих значений издателя гарантирует, что вы проверка для значений издателя протокола безопасности версии 3.1 и версии 3.2.
  4. Маркер содержит утверждение "audience" со значением, соответствующим идентификатору приложения Майкрософт для бота.
  5. Эмулятор, в зависимости от версии, отправляет AppId через утверждение appid (версия 1) или авторизованное утверждение сторонне (версия 2).
  6. Маркер является действующим. Отраслевая разница в показаниях часов составляет 5 минут.
  7. Маркер имеет допустимый криптографическую подпись с ключом, приведенным в документе с ключами OpenID, который был получен на шаге 3.

Примечание.

Требование 5 относится к пути проверки эмулятора.

Если маркер не соответствует всем этим требованиям, бот должен завершить запрос, возвращая код состояния HTTP 403 (запрещено ).

Важно!

Все эти требования являются важными, особенно требования 4 и 7. При невозможности выполнить все эти требования бот будет открыт для атак, что может привести к раскрытию его маркера JWT.

Запрос от эмулятора к боту: пример компонентов JWT

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "<YOUR MICROSOFT APP ID>",
  iss: "https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/",
  nbf: 1481049243,
  exp: 1481053143,
  ... other fields follow
}

Примечание.

На практике могут использоваться другие поля. Создайте и проверьте все маркеры JWT, как указано выше.

Изменения протокола безопасности

Проверка подлинности бота в службе Bot Connector

URL-адрес входа OAuth

Версия протокола Допустимое значение
3.1 и 3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

Область OAuth

Версия протокола Допустимое значение
3.1 и 3.2 https://api.botframework.com/.default

Проверка подлинности службы Bot Connector в боте

Документ метаданных OpenID

Версия протокола Допустимое значение
3.1 и 3.2 https://login.botframework.com/v1/.well-known/openidconfiguration

Издатель JWT

Версия протокола Допустимое значение
3.1 и 3.2 https://api.botframework.com

Проверка подлинности эмулятора в боте

URL-адрес входа OAuth

Версия протокола Допустимое значение
3.1 и 3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

Область OAuth

Версия протокола Допустимое значение
3.1 и 3.2 Идентификатор приложения Майкрософт бота + /.default

Аудитория JWT

Версия протокола Допустимое значение
3.1 и 3.2 Идентификатор приложения Microsoft Bot

Издатель JWT

Версия протокола Допустимое значение
v3.1 1.0 https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/
v3.1 2.0 https://login.microsoftonline.com/d6d49420-f39b-4df7-a1dc-d59a935871db/v2.0
v3.2 1.0 https://sts.windows.net/f8cdef31-a31e-4b4a-93e4-5f571e91255a/
v3.2 2.0 https://login.microsoftonline.com/f8cdef31-a31e-4b4a-93e4-5f571e91255a/v2.0

См. также выделенные значения для неправительственных случаев.

Документ метаданных OpenID

Версия протокола Допустимое значение
3.1 и 3.2 https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

Дополнительные ресурсы