Skype Бот, Документация (REST API): Аутентификация

Оригинал на английском Skype Bot Rest API (Authentication)

Введение и обзор

Этот документ описывает безопасные технологии и требования для бота, для отправления и получения сообщений из Bot connector’a . Он (гайд) предназначен для разработчиков, которые пишут свой код  для аутентификации.

Замечание: Если вы используете Bot Builder SDK для C# или Bot Builder SDK для Node.js, все шаги указанные в этом документе делаются автоматически SDK. В SDK есть все, чтобы настраивать его со своим bot ID и паролем.

Ваш бот общается с сервисом Bot Connector используя HTTP через безопасный канал (SSL/TLS). Через этот канал, бот и  сервис Bot Connector должны проверять подлинность запросов которые отправляют  друг-друг. После аутентифиции бота и Bot Connector’а, им можно обмениваться сообщениями. Эта страница описывает аутентификацию, которая происходит на уровне сервиса; но она не описывает аутентификацию на уровне пользователя (такую как авторизация пользователя в боте).

Замечание: если вы не используете Bot Builder SDK, вы должны реализовать безопасные процедуры в соотвествии с этим документом. Заметьте это ОЧЕНЬ ВАЖНО чтобы вы реализовали все процедуры корректно. Если вы это не сделаете, это позволит злоумышленникам читать и сообщения отправленные вашему боту, красть секретные ключи, и отпавлять сообщения от вашего бота.

Технологии аутентификации

технологии аутентификации используются для проверки подлинности между ботом и  Bot Connector’ом.

  1. SSL/TLS используются на всех service-to-service соединениях. X.509v3 сертификаты используются чтобы устанавливать подиланность всех HTTPS запросов. Клиентам следует всегда  внимательно проверять сертификаты запросов, чтобы удостовериться что они валидные. (Заметьте: клиентские сертификаты не используются как часть этой схемы).
  2. OAuth 2.0 авторизация в Microsoft Account (MSA), сервер авторизации используется чтобы генерерировать секретный токен, который  может быть использовать бот для отправки сообщений. Этот токен использует service-to-service; авторизация пользователя не требуется.
  3. JSON Web Tokens (JWT) используются чтобы кодировать токены отправленные и полученные от бота. Клиентам следует полностью проверять все JWT токены, которые они получили, согласно требованиям изложенных ниже.
  4. Метаданные OpenId хорошо известны, жестко запрограммированная рабочая станци для сервиса Bot connector для публикации списка валидных токенов, он использует для авторизации собственные JWT Токены.Этот гайд описывает как использовать все перичисленные технологии используя технологии HTTPS и JSON. Особые SDK’s не требуются, хотя помощь для OpenId и т.д. могла бы быть полезной.

Этот гайд описывает как использовать все перичисленные технологии используя технологии HTTPS и JSON. Особые SDK’s не требуются, хотя помощь для OpenId и т.д. могла бы быть полезной.

Аутентификация запросов из бота в сервис Bot Connector

 Когда бот отправляет вызов в сервис Bot Connector, например когда отправляет сообщение пользователю, для этого нужно первым делом получить токен из MSA сервиса. Этот токен может быть кэширован пока не истичет (прим. переводчика:срок хранения кэша) (обычно один час). Чтобы аутентифицироваться в MSA сервисе, вы должны предоставить свои Microsoft app ID (доступен в панели управления разроботки бота) и ваш Microsoft app пароль (виден только один раз когда генерируется ваше app). Эти параметры используются в шаге 1.

1. Получить MSA логин сервис
2. JSON который содержит JWT token
3. JWT тоекн в загаловке Авторизации

(Бот -> Connector) Шаг 1: POST запрос в сервис MSA login чтобы получить токен

HTTPS POST запрос в https://login.microsoftonline.com/common/oauth2/v2.0/token со следующеими значениями

Пример запроса в MSA сервер:

(Бот -> Connector) Шаг 2: Получение JSON, которая содержит JWT токен из MSA login service

Если приложение авторизовано MSA сервером, оно вернет ответ JSON содержащи ваш токен, его тип, и срок окончания (в секундах). В случае использвания существующей формы, без дальнейшего экранирования или кодирования. Токен может быть использван пока срок его действия не истек, но мы рекомендуем разработчиката бота кэшировать и преждевременно обновлять этот токен чтобы хранить его сжатым для более высокой производительности вашего бота

Пример ответа от MSA сервера:

(Бот -> Connector)  Шаг 3: Отправка токена в Bot connector

Когда ты отправляешь запрос в Bot connector, просто добавляй заголовок Авторизации с «Bearer» схемой и JWT токеном как авторизационным значением. Этот заголовок должен быть присоеденем ко всем вызовам отправленным в Bot connector. Bot connector авторизует запрос если токен корректный, и не истек срок его действия, и был сгенерирован MSA login service.  Дальнейшие проверки выполняются чтобы удостоверистя что токен принадлежит боту выполняещему запрос.

Пример запроса:

Замечание: НЕ ВКЛЮЧАТЕ этот заголовок в HTTP запросы к другим службам. JWT токен из MSA service как пароль — он позволяет владельцу этого токена выполнять операции от имени бота. Не отправляйте JWT токен через небезопасные каналы, и не отправляет его в другие сервисы Bot connector’а.

Авторизация вызовов из Bot Connector’a  боту

Когда Bot Connector отправляет запросы боту, они включают JWT токен, который был подписан Bot Connector’ом. Чтобы подтвердить аутентификацию этого токена, ваш бот может загрузить метаданные документа OpenId из общеизвестной рабочей станции и удостовериться что JWT токен подписан ключем внесенным в список в документе.


1: JWT токен в заголовке авторизации
2: GET OpenId document
3: GET jwks_uri

(Bot Connector -> Бота) Шаг 1: Загрузка методанны документа OpenId

Вызовите HTTPS GET запрос, чтобы загрузить JSON документ  который находится по ссылке https://api.aps.skype.com/v1/.well-known/openidconfiguration. Жестко запрограмируйте этот URL в вашем приложении. Этот документ содержит ссылку на второй документ содержащий валидные подписанные ключи, используемые Bot FrameWork‘ом. URL этого документа  внутри свойства «jwks_uri».

Пример запроса:

Пример ответа:

(Bot Connector -> бот) Шаг2: Загрузка списка валидных подписывающих ключей

Повторите  HTTPS GET запрос к документу со списком валидных подписанных ключей. Документ в JWK формате (для подробностей смотрите ссылки ). Список ключей относительно стабилен и может быть кэширован на долгие периоды времени (по умолчанию, 5 дней у Bot Builder SDK).

(Bot Connector -> бот) Шаг 3: Верификация JWT токена

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

Когда токен распарсится, вы должны настроить библиотеки парсина и напсать вашу собственную валидацию, чтобы удостовермтся что токен обеспечивает следующие требования:

  1. Токен был отправлен в загаловке HTTP авторизации с “Bearer” схемой
  2. Токен с валидным JSON, который соотвествует JWT стндарту (смотрите по ссылке )
  3. Токен содержит issuer  со значенем из https://api.botframework.com
  4. Токен содержит audience со значением эквивалетным вашему Microsoft App ID бота
  5. Срок давности токена не истёк. Стандартное время истечения — 5 минут
  6. У токена есть валидная зашифрованная подпись с ключем  из списка ключей документа OpenId полученным из шага 1

Если токен полученный Bot Connector‘ом не соотвествует 5 требованиям, тогда боту следует отклонить запрос. Обычно по стандарту возвращается код ответа HTTP 403 (Forbidden).

Замечание: Все 6 требований важны, особенно 4 и 6. Неудачная реализация всех требований верификации сделает бота уязвимым к атака, которые могут стать причиной  разглашения его JWT токенов.

Замечение: Реализаторам не следует отключать валидацию JWT токена отправленного боту.

Включение аутентификации из эмулятора Bot Framework

Эмулятор Bot Framework‘а —  инструмент рабочего стола, разработчики могут его использоватья для тестирования функциональности бота. Эмулятор Bot Framework‘а использует такие же технологии аутентификации перечисленные выше, но неспособные осуществлять реальное соединение с Bot Connector. Взамен, он использует Microsoft App ID и Microsoft App пароль предоствленный разработчиком (обычно введенный в поля App ID и Пароль в пользовательском интерфейсе эмулятора, если используется Windows версия эмулятора) и он создает токены такие-же как у бота. Когда он аутентифицирует бота, он посылает токен боту внутри структуры, она использует  собственные полномочия бота когда соеденяется с ним.

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

Этот путь верификации структурно похож на Bot Connector -> бот путь верификации, но он использует документ OpenId MSA вместо документа OpenId Bot Connector‘a

(Эмулятор -> бот) Шаги 1 и 2: Загрузка методанных документа MSA OpenId

Следующие шаги делают HTTPS GET запрос на https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Находят свойство “jwks_uri” и повторяют HTTPS GET запрос и парсяи список валидных ключей подписей.

Пример запроса:

Ключевой процесс верификации описан раннее для Бот -> Bot Connector

 

(Эмулятор -> Бот) Шаг 3: Верификация JWT токена

Извлеките токен как вы это делали с JWT токеном отправленным Bot Connector’ом. Однако, используйте эти требования вместо тех, что описывались для аутентификации (Bot Connector -> бот):

  1. Токен был отправлен в загаловке HTTP авторизации по схеме “Bearer”
  2. Токен является валидным JSON и JWT конверт соотвествует стндарту (смотрите ссылки)
  3. Токен содержит поле «isser» со значением из https://sts.windows.net/72f988bf-86f1-41af-91ab-2d7cd011db47/
  4. Токен содердит поле «audience» со значением из https://graph.microsoft.com 
  5. Токен содержит «appid» из issuer выше, значение которого совпадает с Microsoft app ID бота.
  6. У токена не истек срок давности. Стандарт — 5 минут.
  7. У токена валидная зашифрованная подпист с ключем из списка в документе OpenId полученным из шага 1, выше.

Замечание: Требование 5 — новое требование, необходимое конкретно для пути верификации эмулятора.

Такие-же меры предосторожности должны быть соблюдены для парсинга этого токена, как и при парсике токена из Bot Connector’a. Неудачная реализация всех тревоний валидации оставит бота открытым для атак.

Ссылки

  1. JSON Web Token (JWT) draft-jones-json-web-token-07
  2. JSON Web Signature (JWS) draft-jones-json-web-signature-04
  3. JSON Web Key (JWK) RFC 7517

 

Debian + Postfix + Dovecot + Roundcube + DKIM + SPF

Postfix

Первым делом устанавливаем postfix:

В /etc/postfix/main.cf добавляем:

Dovecot

Устанавливаем dovecot:

Заходим в директорию /etc/dovecot
Редактируем  следующий параметр в файле conf.d/10-mail.conf:

Редактируем секцию service auth в файле conf.d/10-master.conf:

Шифрование

Необходимо создать ключ и сертификат для использования шифрования.
Как это сделать можно посмотреть в другой статье — OpenSSL CA

После создания ключа и сертификата, добавляем их в конфигурации postfix и dovecot

Если ключ был создан с паролем то придется его расшифровать, так как postfix зашифрованные ключи не понимает:

В /etc/postfix/main.cf добавляем:

В /etc/dovecot/conf.d/10-ssl.conf добавляем:

Roundcube

Скачиваем roundcube

Создаем директорию для roundcube и распаковываем туда roundcube:

Создаем базу данных mysql и пользователя для roundcube:

Инициализируем базу данных roundcube:

Копируем  конфигурационный файл:

Правим файл config.inc.php:

DKIM

Хорошая статья на эту тему

Правим файл /etc/opendkim.conf:

  • AutoRestart: автоматический перезапуск фильтра при сбоях
  • AutoRestartRate: Указывает максимальный темп перезапуска фильтра. Если перезапуски начали случаться быстрее чем этот темп, фильтр будет выключен; 10/1h — максимум возможны 10 перезапусков/в час
  • UMask: даёт все доступные права для пользователя и группы определынные в параметре UserID  и позволяет остальым пользователям читать и выполнять файлы, в данном случае это позволит создавать и изменять Pid файл.
  • Syslog, SyslogSuccess, *LogWhy: эти параметры включают подробное логирование через вызовы syslog.
  • Canonicalization: defines the canonicalization methods used at message signing, the simplemethod allows almost no modification while the relaxed one tolerates minor changes such as
    whitespace replacement; relaxed/simple — the message header will be processed with therelaxed algorithm and the body with the simple one
  • ExternalIgnoreList: specifies the external hosts that can send mail through the server as one of the signing domains without credentials
  • InternalHosts: defines a list of internal hosts whose mail should not be verified but signed instead
  • KeyTable: maps key names to signing keys
  • SigningTable: lists the signatures to apply to a message based on the address found in the From:header field
  • Mode: declares operating modes; in this case the milter acts as a signer (s) and a verifier (v)
  • PidFile: the path to the Pid file which contains the process identification number
  • SignatureAlgorithm: selects the signing algorithm to use when creating signatures
  • UserID: the opendkim process runs under this user and group
  • Socket: the milter will listen on the socket specified here, Posfix will send messages to opendkim for signing and verification through this socket; 12301@localhost defines a TCP socket that listens on localhost, port 12301

Правим файл /etc/default/opendkim:

Правим файл /etc/postfix/main.cf

Создаем директорию для opendkim

Определяем доверенные хосты в файле /etc/opendkim/TrustedHosts:

Создаем таблицу ключей:

Таблица ключей содержит пару селектор/домен и путь к их закрытому ключу. Любая буквенно-цифровая строка может быть использована как селектор, в данном примере используется mail и нет необходимости его изменять.

Создаем таблицу подписей:

Этот файл используется для  объявления доменов/почтовых адресов и их селекторов.

Создаем открытый и закрытый ключи:

Создаем директорию для ключей:

Генерируем ключи:

-s селектор и -d домен, эта соманда создаст два файла, mail.private - закрытый ключ и mail.txt — содердащий открытый ключ.

Меняем  владельца и группы владельца файла закрытого ключа:

Открытый ключ который нахоится в файле mail.txt, необходимо добваить в DNS запись домена:

Также RFC5617 определяет запись TXT, для создания собственных правил касающихся подписания сообщений. Запись называется ADSP, и распологается в специальном поддомене _adsp._domainkey. Внутри записи содержится выражение dkim= , которое объявляет правила подписания сообщений:

  • all — для доменов подписывающие все исходящие сообшения электронной почты;
  • unknown — для доменов, которые могут подписывать некоторые сообщения;
  • discardable — для доменов, подписывающих все сообщения электронной почты и рекомендующих получателям игнорировать сообщения, подписи которых не прошли верификацию.

Также есть старая форма записи, которая использовалась до RFC5617.
_domainkey, и имела другой синтаксис:

  • o=~ — некоторые сообщения должны быть подписаны.
  • o=- — все сообщения должны быть подписаны.

В моем случае я указыаю такие записи:

SPF

Добавляем в DNS следующую запись:

Говорит почтовым серверам отвергать письма, которые были отправлены не от адресов находящихся в записях DNS A или MX.

Проверка

Перезапустите postfix, dovecot, opendkim:

 

Отправьте сообщение на адрес check-auth@verifier.port25.com:
В ответ вернется сообщение:

pass — значит прошло проверку.

 

Gnome 3. Настройка отображения времени

На момент написания этой статьи у меня установлен gnome 3 версии 3.16 на операционной системе Fedora 22

Для настройки отображения секунд в системных часах gnome 3 необходимо параметру clock-show-seconds присвоить значение true в схеме org.gnome.desktop.interface. Для этого используется утилита gsettings из пакета glib2. Получить текущее значение параметра можно с помощью команды:

Установить значение true:

После этого секунды появятся на системных часах:
e7878

Могут заинтересовать другие параметры.
Посмотреть все схемы:

Посмотреть все ключи указанной схемы:

 

Установка scout_realtime на Debian 8/7 (Jessie/wheezy)

Создаем пользователя

В /etc/sudoers добавляем следующее разрешение:

Устанавливаем rvm, ruby, scout_realtime

Логинимся под созданным пользователем

Перелогиниваемся

Смотрим список доступных версий ruby

Ставим последнюю версию

Устанавливаем scout_realtime

Сейчас вы можете проверить и посмотреть как он работает. Достаточно просто набрать

Тогда запуститься scout_realtime прослушивая 5555 порт на всех сетевых инетрфейсах. Откройте браузер и наберите там http://ip_address_servera:5555. 

Настройка доступа

Должен быть установлен и настроен nginx

Регстрируем поддомен scout.example.com. Создаем конфиг /etc/nginx/sites-available/scout.example.com.conf примерно такого содержания:

Заводим пользователя для http-авторизации:

Активируем конфиг nginx

Настраиваем службу и автоматический запуск

Создаем /etc/systemd/system/scout-realtime.service со следующим содержанием:

Создаем файл /etc/default/scout_realtime со следующим содержимым:

Перечитываем конфигурационные файлы

Активируем сервис

Запускаем

Смотрим статус запуска

 

 

Redmine + passenger + nginx or apache

Все команды вводятся от обычного пользователя на Debian 8
Качаем redmine, я выбрал версию 3.0.
Как описано в http://www.redmine.org/projects/redmine/wiki/Download

Устанавливаем rvm как описано на главной странице проекта https://rvm.io/

Создаем базу данных и пользователя в mysql

Заходим в папку redmine-3.0\config, и копируем database.yml.example в database.yml.
В файле database.yml, остальное можно удалить

Подробности в http://www.redmine.org/projects/redmine/wiki/RedmineInstall

Устанавливаем ruby. Например я поставил 2.0.0

Для этого он может запросить права на выолнения apt-get под sudo. Лучше временно их настроить

Далее http://www.redmine.org/projects/redmine/wiki/HowTo_Install_Redmine_on_Debian_8_with_Apache2-Passenger

Если не находит команду gem то попробуй перелогинеться. Если все равно не находит то скорее всего при логине не запустился скрипт $HOME/.rvm/bin/rvm. Проверь bash_profile, на наличие подключения этого скрипта. А сейчас просто с командуй:

на всякий случай запустите which gem. Должен выдать путь в директории пользователя. Например:

Генерируем секретный токен

Подготавливаем базу данных и устанавливаем все таблицы

Тестируем работоспособность:

Переходим по адресу http://$IP:3000