Требования безопасности для интерактивных сообщений в Office 365

Статья
04/08/2023

Важно!

Подключение новых поставщиков сообщений с действиями с глобальной область временно приостановлено до 30 июня 2024 г. из-за обновления служб. Существующие глобальные поставщики и подключение поставщиков область для организации и тестирования не затрагиваются. Дополнительные сведения см. в разделе Часто задаваемые вопросы о сообщениях с действиями.

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

Этап отправки: ниже перечислены условия, которые необходимо выполнить, чтобы ваша служба могла отправлять интерактивные сообщения.
- Если вы используете почту с действиями, вам необходимо включить проверку отправителя. Обратите внимание, что это не относится к сообщениям соединителя.
- Ваша служба должна быть зарегистрирована в корпорации Майкрософт.
- URL-адрес действия должен поддерживать протокол HTTPS.
Этап обработки действия: при обработке действия ваша служба должна выполнять указанные ниже операции.
- Проверять маркер носителя (веб-маркер JSON), включенный в заголовок запроса HTTP POST. Кроме того, проверку можно выполнить, используя примеры библиотек, предоставленные корпорацией Майкрософт.
- Включать специализированный маркер из вашей службы в качестве целевого URL-адреса, который ваша служба может использовать для корреляции URL-адреса службы с предполагаемым запросом и пользователем. Это необязательно, но настоятельно рекомендуется.

Проверка отправителя

Для отправки сообщений с действиями в Office 365 необходимо включить проверку отправителя. Сообщения с действиями должны отправляться с серверов, которые используют методы DomainKeys Identified Mail (DKIM) и Sender Policy Framework (SPF), или вы должны использовать подписанные карточки.

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

Использование методов DKIM и SPF

DKIM и SPF — стандартные способы подтверждения личности отправителя при отправке писем через SMTP. Многие компании уже используют эти стандарты для защиты отправляемых писем. Дополнительные сведения о методах SPF и DKIM и инструкции по их использованию:

Подписанные полезные данные карточек

Сообщения с действиями, отправляемые по электронной почте, поддерживают альтернативный метод проверки: подписывание полезных данных карточки с ключом RSA или сертификатом X509. Этот метод является обязательным в следующих сценариях:

Сбой SPF/DKIM, вызванный настройкой отправителя или пользовательскими службами безопасности, используемыми клиентом получателя, перед службами Office 365.
Требуется отправка из нескольких учетных записей электронной почты.

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

SignedCard

Подписанные карточки сообщений с действиями доступны при отправке по электронной почте. Используйте этот формат, чтобы включить подписанную карточку в тело HTML письма. Эти полезные данные сериализуются в формате Microdata и добавляются в конце основного текста HTML.

<section itemscope itemtype="http://schema.org/SignedAdaptiveCard">
    <meta itemprop="@context" content="http://schema.org/extensions" />
    <meta itemprop="@type" content="SignedAdaptiveCard" />
    <div itemprop="signedAdaptiveCard" style="mso-hide:all;display:none;max-height:0px;overflow:hidden;">[SignedCardPayload]</div>
</section>

Примечание: партнеры, которые предпочитают использование устаревшего объекта MessageCard, могут создать объект SignedMessageCard вместо SignedAdaptiveCard.

SignedCardPayload

SignedCardPayload - это строка, закодированная с помощью стандарта JSON Web Signature (JWS). RFC7515 описывает JWS, а RFC7519 описывает веб-маркер JSON (JWT). При условии, что для JWT не требуется каких-либо утверждений, библиотеки JWT могут использоваться для создания JWS подписи.

Примечание: термин «JWT» на практике является взаимозаменяемым. Тем не менее, в данном случае мы предпочитаем использование термина «JWS».

Ниже представлен пример SignedCardPayload. Зашифрованная адаптивная карточка отображается в следующем виде: [заголовок]. [полезные данные].[подпись] (согласно спецификации для JWS).

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZW5kZXIiOiJzZXJ2aWNlLWFjY291bnRAY29udG9zby5jb20iLCJvcmlnaW5hdG9yIjoiNjVjNjgwZWYtMzZhNi00YTFiLWI4NGMtYTdiNWM2MTk4NzkyIiwicmVjaXBpZW50c1NlcmlhbGl6ZWQiOiJbXCJqb2huQGNvbnRvc28uY29tXCIsXCJqYW5lQGNvbnRvc28uY29tXCJdIiwiYWRhcHRpdmVDYXJkU2VyaWFsaXplZCI6IntcIiRzY2hlbWFcIjpcImh0dHA6Ly9hZGFwdGl2ZWNhcmRzLmlvL3NjaGVtYXMvYWRhcHRpdmUtY2FyZC5qc29uXCIsXCJ0eXBlXCI6XCJBZGFwdGl2ZUNhcmRcIixcInZlcnNpb25cIjpcIjEuMFwiLFwiYm9keVwiOlt7XCJzaXplXCI6XCJsYXJnZVwiLFwidGV4dFwiOlwiSGVsbG8gQWN0aW9uYWJsZSBtZXNzYWdlXCIsXCJ3cmFwXCI6dHJ1ZSxcInR5cGVcIjpcIlRleHRCbG9ja1wifV0sXCJhY3Rpb25zXCI6W3tcInR5cGVcIjpcIkFjdGlvbi5JbnZva2VBZGRJbkNvbW1hbmRcIixcInRpdGxlXCI6XCJPcGVuIEFjdGlvbmFibGUgTWVzc2FnZXMgRGVidWdnZXJcIixcImFkZEluSWRcIjpcIjNkMTQwOGY2LWFmYjMtNGJhZi1hYWNkLTU1Y2Q4NjdiYjBmYVwiLFwiZGVza3RvcENvbW1hbmRJZFwiOlwiYW1EZWJ1Z2dlck9wZW5QYW5lQnV0dG9uXCJ9XX0iLCJpYXQiOjE1NDUzNDgxNTN9.BP9mK33S1VZyjtWZd-lNTTjvueyeeoitygw9bl17TeQFTUDh9Kg5cB3fB7BeZYQs6IiWa1VGRdiiR4q9EkAB1qDsmIcJnw6aYwDUZ1KY4lNoYgQCH__FxEPHViGidNGtq1vAC6ODw0oIfaTUWTa5cF5MfiRBIhpQ530mbRNnA0QSrBYtyB54EDJxjBF1vNSKOeVHAl2d4gqcGxsytQA0PA7XMbrZ8B7fEU2uNjSiLQpoh6A1tevpla2C7W6h-Wekgsmjpw2YToAOX67VZ1TcS5oZAHmjv2RhqsfX5DlN-ZsTRErU4Hs5d92NY9ijJPDunSLyUFNCw7HLNPFqqPmZsw

Заголовок в JWS выше имеет следующий вид:

{
  "alg": "RS256",
  "typ": "JWT"
}

Полезные данные в JWS ваше имеют следующий вид:

{
  "sender": "service-account@contoso.com",
  "originator": "65c680ef-36a6-4a1b-b84c-a7b5c6198792",
  "recipientsSerialized": "[\"john@contoso.com\",\"jane@contoso.com\"]",
  "adaptiveCardSerialized": "{\"$schema\":\"http://adaptivecards.io/schemas/adaptive-card.json\",\"type\":\"AdaptiveCard\",\"version\":\"1.0\",\"body\":[{\"size\":\"large\",\"text\":\"Hello Actionable message\",\"wrap\":true,\"type\":\"TextBlock\"}],\"actions\":[{\"type\":\"Action.InvokeAddInCommand\",\"title\":\"Open Actionable Messages Debugger\",\"addInId\":\"3d1408f6-afb3-4baf-aacd-55cd867bb0fa\",\"desktopCommandId\":\"amDebuggerOpenPaneButton\"}]}",
  "iat": 1545348153
}

Необходимые утверждения:

Утверждение	Описание
`originator`	НЕОБХОДИМО использовать идентификатор, предоставленный Майкрософт во время подключения.
`iat`	Время подписания полезных данных.
`sender`	Адрес электронной почты, который использовался для отправки этого сообщения с действиями.
`recipientsSerialized`	Представленный в виде строки список получателей сообщения электронной почты. Необходимо включить всех получателей/поставленных в копию для сообщения электронной почты.
`adaptiveCardSerialized`	Представленная в виде строки адаптивная карточка.

Карточка с подписью, генерирующая пример кода:

Проверка поступления запросов от Майкрософт

Все запросы на действия от Корпорации Майкрософт имеют маркер носителя в заголовке HTTP Authorization . Этот маркер является токеном JSON Web Token (JWT), подписанным корпорацией Майкрософт, и включает в себя важные утверждения, которые мы настоятельно рекомендуем проверять службой, обрабатывающей связанный запрос.

Имя утверждения	Значение
`aud`	Базовый URL-адрес целевой службы, например `https://api.contoso.com`
`iss`	Издатель маркера. Требуемое значение: `https://substrate.office.com/sts/`
`sub`	Удостоверение пользователя, выполнившего действие. Для интерактивных сообщений, отправляемых по электронной почте, утверждение `sub` будет представлять собой электронный адрес пользователя. Для соединителей утверждение `sub` будет представлять собой идентификатор objectID пользователя, выполнившего действие.
`sender`	Удостоверение отправителя сообщения, содержащего действие. Это значение присутствует, только если сообщение с действиями было отправлено по электронной почте. Сообщения с действиями отправленные через соединители не включают это утверждение в маркер носителя.

Обычно служба выполняет указанные ниже проверки.

Подписан ли маркер корпорацией Майкрософт. Метаданные OpenID находятся по адресу https://substrate.office.com/sts/common/.well-known/openid-configuration, который содержит сведения о ключах подписывания.
Соответствует ли утверждение aud базовому URL-адресу службы.

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

Изучите приведенные ниже примеры кода Майкрософт, в которых показано, как выполнять эти проверки для маркера JWT.

Заголовок Action-Authorization

Использование заголовка Authorization в сообщениях с действиями может помешать работе существующего механизма аутентификации и авторизации для целевой конечной точки. В этом случае разработчики могут задать для заголовка Authorization пустую строку в свойстве headersAction.Http действия. После этого сообщения с действиями будут отправлять тот же маркер носителя через заголовок Action-Authorization, а не через заголовок Authorization.

Совет

Служба приложения логики Azure возвращает HTTP 401 Unauthorized, если заголовок Authorization содержит маркер носителя, установленный сообщениями с действиями.

Пример Action.Http с заголовком Action-Authorization

{
  "type": "Action.Http",
  "title": "Say hello",
  "method": "POST",
  "url": "https://api.contoso.com/sayhello",
  "body": "{{nameInput.value}}",
  "headers": [
    { "name": "Authorization", "value": "" }
  ]
}

Проверка личности пользователя

Токен носителя, который включается во все запросы, включает идентификатор Azure AD пользователя Office 365, который выполнил действие. При необходимости вы можете включать в URL-адреса действий HTTP специальный токен, который представляет личность пользователя в вашей системе. Корпорация Майкрософт не дает никаких предписаний насчет конструкции специализированных маркеров или использования их службой. Этот маркер "непрозрачен" для корпорации Майкрософт, и она просто возвращает его обратно в службу.

Специальные токены можно использовать для сопоставления URL-адресов службы с конкретными сообщениями и пользователями. Майкрософт рекомендует включать специальный токен в целевой URL-адрес действия или в тело запроса, поступающего обратно в службу. Пример:

https://contoso.com/approve?requestId=abc&serviceToken=a1b2c3d4e5...

Специальные токены выступают в качестве идентификаторов корреляции (например, для хэшированных токенов, использующих userID, requestID и соль). Это позволяет поставщику услуг отслеживать URL-адреса действий, которые он создает и отправляет, и сопоставлять их с входящими запросами действий. Помимо корреляции поставщик услуг может использовать специальный токен для защиты от атак с повторением. Например, поставщик услуг может отклонить запрос, если действие было выполнено ранее с использованием того же токена.