Создание телеграм бота с гугл авторизацией, обратными вызовами и уведомлениями об обновлении через сервер-маршрутизатор

 TELEGRAM INLINE WEBHOOK BOT 

ОГЛАВЛЕНИЕ

0. ВМЕСТО ПРЕДИСЛОВИЯ
   • Пример решаемой задачи
   • Последовательность настройки
   • Полезные ссылки
1. 1С REST СЕРВЕР
   • Инструкция настройки IIS 8.5 для 1Сv8.3
   • Проброс портов
   • Выделенный IP
   • Поднятие http сервисов (REST) в 1С
2. НАСТРОЙКА ПРОКСИ СЕРВЕРА
   • Аренда VPS сервера
   • Socks5 прокси с 3proxy
   • MTProxy
   • Создание сертификата
   • Проксирование запросов с nginx
   • Настроим брандмауэр
3. ТЕЛЕГРАМ БОТ
   • Создадим бота
   • Протестируем бота
   • Вебхуки
4. OAUTH2, GOOGLE ПРИЛОЖЕНИЕ
   • О трехногой авторизации
   • Алгоритм авторизации
   • Заведем приложение
5. АРХИТЕКТУРА API
   • Архитектура в общих чертах
   • Процедура-обработчик запроса
   • Разбор запроса
   • Фасовка запроса
6. ПОЛУЧЕНИЕ СООБЩЕНИЙ
7. ОТПРАВКА СООБЩЕНИЙ
8. ОТРИСОВКА КЛАВИАТУРЫ
9. РЕАЛИЗАЦИЯ АВТОРИЗАЦИИ
10. ОТПРАВКА ФАЙЛОВ
11. ИСПРАВЛЕНИЕ СООБЩЕНИЙ
12. ОБРАТНЫЕ ЗАПРОСЫ
13. ВСТРОЕННЫЕ ЗАПРОСЫ

ЧАСТЬ 0. ВМЕСТО ПРЕДИСЛОВИЯ

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

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

Например зачастую люди пытаются “слушать обновления” бота и для этого они могут крутить метод getUpdates в цикле, регламентным заданием, планировщиком, еще каким извращением. В лучшем случае они знают про существование “long polling”. Но все равно это является очень и очень спорным решением.

Возможно кто то хотел использовать webhook’и, но столкнулся с недоступностью использования портов, поддерживаемых телеграммом.

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

В рамках серии статей я подробно разберу как сделать отличный inline webhook бот с постоянным доступом к api телеграмма. А бонусом вы получите собственный прокси сервер для сотрудников и друзей.

Статья будет дополнятся по мере возникновения вопросов, рекомендаций и спорных моментов.

Пример решаемой задачи

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

Итак, давайте не будем рассматривать голые методы телеграмма (у него и без этого отличная документация), а рассмотрим решение некоторой задачи с помощью бота в контексте которой будет рассмотрен следующий функционал бота:

• Рассылка сообщений в группы и авторизовавшимся пользователям
• Получение уведомлений RESTful интерфейсом ИБ от серверов телеграмма
• Отправка файлов
• Редактирование сообщений
• Создание клавиатуры (кнопки расположенные в несколько рядов и прикрепленные к сообщению)
• Встроенные запросы и ответы на них
• Авторизация в боте с помощью Google OAuth2 и сопоставление телеграмм аккаунта, почты и пользователя информационной базы
• Некоторые хитрости архитектуры и оформления сообщений

А задачей будет удобное визирование заявок на оплату через мессенджер в cash flow подсистеме ИБ (казначействе). Ожидаемый порядок действий при визировании:

1. Пользователь создает и подготавливает заявку на оплату

• уведомляются авторизованные следующие звенья с возможностью принять или отклонить заявку из мессенджера
• информация о созданной заявке отправляется в группу с прикрепленным документом

2. Заявка согласовывается с держателем бюджета

• уведомляются авторизованные следующие звенья с возможностью принять или отклонить заявку из мессенджера
• обновляется информация в ранее отправленных сообщениях

3. Заявка согласовывается с финансовым менеджером

• уведомляются авторизованные следующие звенья с возможностью принять или отклонить заявку из мессенджера
• обновляется информация в ранее отправленных сообщениях

4. Утверждается казначеем

• обновляется информация в ранее отправленных сообщениях

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

Итак, что же нам потребуется для реализации?

• VPS хостинг с любой операционкой (Я советую Debian или Ubuntu, тк по ним куча документации)
  • Цена вопроса 1-2$/мес это единственное за что придется платить, но как по мне, это мизерная цена для обхода любых блокировок и запуска удобного бота (нагрузка на сервер не ощущается даже при 50 активных клиентов http/socks5 прокси и проксирующего nginx)
  • putty
  • 3proxy
  • nginx
  • самоподписанный SSL сертификат (разберу получение)
• Настроить web приложение 1С
  • Веб сервер (буду разбирать на примере iis)
  • http сервисы (можно и в расширении, если автоматизируете бухгалтерию или зуп на поддержке, ничего не придется снимать с последней)
  • Пробросить 1 любой порт для взаимодействия с телеграммом (опционально, если будет VPN тунель с хостингом)
• Телеграмм бот
  • Включенный inline режим
  • Включенный webhook
• Google OAuth2 приложение для веб сервера
  • client id
  • redirect url
  • secret key
  • scopes
• 1С бэкэнд (в расширении)
  • restful api
  • общие модули и обработки по желанию
  • регистры сведений

Полезные ссылки

// API Telegram
https://core.telegram.org/bots/api

// Google OAuth2
https://console.cloud.google.com/apis/credentials/oauthclient/
https://developers.google.com/identity/protocols/OAuth2WebServer
https://developers.google.com/oauthplayground

// Putty
https://www.putty.org/
https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys-on-debian-9
https://habr.com/post/127521/

// Nginx
https://nginx.org/ru/
https://wiki.archlinux.org/index.php/Nginx_(%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9)

// 3proxy socks5 proxy server
https://www.3proxy.ru/

// MTProxy
https://github.com/TelegramMessenger/MTProxy

// Сервис для отладки проксирования webhook'ов телеграма:
https://www.webhookapp.com/

ЧАСТЬ 1. 1С REST СЕРВЕР

Инструкция настройки IIS 8.5 для 1Сv8.3

Основные шаги хорошо описаны тут: //infostart.ru/public/275820/

От себя хотелось бы добавить очевидное, при установке платформы 1с не забывайте выбирать установку web компонентов.

Естественно, вместо IIS вы можете использовать и Apache

Проброс портов

Необходимо пробросить один, произвольный порт для приема webhook уведомлений и публиковать по нему базу. Не обязательно, если организуем доступ к серверу через тунель. Распишу поподробнее, если возникнут проблемы.

Телеграм API может отсылать вебхуки только на порты 443, 80, 88, 8443, но используя проксирующий nginx это ограничение нам не важно.

Выделенный IP

Нам потребуется организовать доступ к нашему серверу. Если у нас есть выделенный ip и мы пробросили порт, то тут “все”.

Если выделенного ip у нас нет, то надо или организовать тунель (VPN) между сервером 1с и nginx сервером или использовать такие сервисы как https://www.noip.com/.

Опционально, для красоты (ну или если вам захочется в дальнейшем не самоподписанный сертификат, а бесплатный от lets encrypt) покупаем симпатичный домен и привязываем либо к 1с серверу, либо к nginx (зависит от планируемой архитектуры).
Это около 300 рублей/год.

Распишу подробнее если возникнут вопросы.

Поднятие http сервисов (REST) в 1С

Для того, чтоб опубликовать наш rest интерфейс из 1C Я советую придерживаться следующей последовательности:

1. Запустить конфигуратор от имени администратора
2. Создадим пользователя, от имени которого будут запускаться http сервисы если в вашей базе организован доступ по паре логин/пароль
3. Создадим в расширении или основной конфигурации http сервис с названием “api” (название может быть произвольным), Я буду показывать на примере расширения
4. Администрирование > Публикация на веб-сервисе
5. В открывшемся окне выбираем имя публикации, веб-сервер, каталог публикации (убедитесь в достаточных правах доступа для веб службы)
6. Отмечаем необходимые галочки, если необходимо публиковать что-то помимо http сервисов.
7. На вкладке “HTTP сервисы” отмечаем галочкой либо “api” если создавали напрямую в конфигурации, либо “Публиковать HTTP сервисы расширений по умолчанию” если создавали http сервис в расширении.
8. (опционально) На вкладке “Прочие” задаем размер пула соединений и время жизни соединения (можно поставить подольше, чтоб первое обращение к вебсерверу не было долгим), включаем отладку.
9. Нажимаем кнопку “Опубликовать”

После этого в каталоге публикации (по умолчанию это “C:inetpubwwwroot{base_name}”) появится файл default.vrd

Можем подредактировать его блокнотом.

Перед изменением и после него советую делать бэкапы этого файла: {yyММdd}_default.vrd.src

А также ставить пометку readonly на сам файл default.vrd

Вот как, примерно, он будет выглядеть:

<?xml version="1.0" encoding="UTF-8"?>
<point xmlns="http://v8.1c.ru/8.2/virtual-resource-system"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
base="/YOUR_BASE_NAME_URL"
ib="Srvr=&quot;localhost&quot;;Ref=&quot;YOUR_BASE_NAME&quot;;Usr=&quot;YOUR_HTTP_USER_NAME&quot;;Pwd=&quot;YOUR_HTTP_PASSWORD&quot;;"
enable="false"
allowexecutescheduledjobs="">
<debug enable="true"
protocol="http"
url=""/>
<ws enable="false" pointEnableCommon="false" />
<httpServices publishExtensionsByDefault="true">
<service name="api"
rootUrl="api"
enable="true"
reuseSessions="dontuse"
sessionMaxAge="20"
poolSize="10"
poolTimeout="20"/>
</httpServices>
<standardOdata enable="false"
reuseSessions="autouse"
sessionMaxAge="20"
poolSize="10"
poolTimeout="5"/>
</point>

Прошу обратить внимание на тэг “httpServices” и организацию анонимного доступа (чтоб не требовало ввода логина/пароля и заходило через определенного пользователя) с помощью атрибута “ib”. Атрибутом “base” задается URL вашей базы.

ЧАСТЬ 2. НАСТРОЙКА ПРОКСИ СЕРВЕРА

Если прям сейчас не возможно арендовать VPS, можете временно пропустить эту часть и для отладки проксирования webhook’ов телеграма использовать предложенный pallid сервис:
https://www.webhookapp.com/

Советую логиниться на купленном сервере по сертификату, а не по паролю. Это и гораздо надежнее и удобнее и быстрее:
https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys-on-debian-9
https://habr.com/post/127521/

Аренда VPS сервера

Для дальнейшей настройки нам потребуется выделенный сервер (VPS). Нам не нужна мощная зверь-машина, достаточно самой минимальной комплектации за 1-3$/мес.

Найдем не лояльного к царской верхушке ограничениям роскомнадзора и соблюдениям “законодательства” хостера в белой стране (советую посмотреть в сторону Швеции, Нидерланд, Германии и тому подобных). Арендуем сервер, выбрав осью Ubuntu Server (можете и любую другую с чем привыкли работать, лично я предпочитаю Debian).

Если работаете под виндой, скачиваем putty, в противном случае у Вас уже наверняка есть ssh клиент.

Соединяемся с сервером по выбранному логину/паролю или сертификату.

Дальнейшие команды будут подразумевать наличие прав супер пользователя (su) или умение говорить от его имени (su do). И знакомство с управлением пакетами в вашей оси (apt, apt-get, pacman, yum)

Обновляем пакеты:

apt update && apt upgrade

Ставим необходимые пакеты, проводим нужную вам настройку.

Например я первым делом ставлю: ufw, zsh, mc, git, wget, htop, tmux

Socks5 прокси с 3proxy

apt install 3proxy

Правим конфиг:

nano /etc/3proxy/3proxy.cfg

nserver 8.8.8.8
nserver 77.88.8.8
nscache 65536
timeouts 1 5 30 60 180 1800 15 60
users $/etc/3proxy/.proxyauth
daemon
log /var/log/3proxy/3proxy.log D
logformat "- +_L%t.%. %N.%p %E %U %C:%c %R:%r %O %I %h %T"
auth cache strong
proxy -n -p8080 -a
socks -p1080
admin -p8088

Добавляем логины и пароли авторизации:

nano /etc/3proxy/.proxyauth

{YourLogin1}:CL:{YourPassword1}
{YourLogin2}:CL:{YourPassword2}
{YourLogin3}:CL:{YourPassword3}

MTProxy

Вся настройка расписана в репозитории MTProxy телеграмма:

https://github.com/TelegramMessenger/MTProxy

Поставим зависимости

apt install git curl build-essential libssl-dev zlib1g-dev

Клонируем репу и переходим в полученный каталог

git clone https://github.com/TelegramMessenger/MTProxy
cd MTProxy

Собираем

make && cd objs/bin

Получаем секрет

curl -s https://core.telegram.org/getProxySecret -o proxy-secret

Получим конфигурацию

curl -s https://core.telegram.org/getProxyConfig -o proxy-multi.conf

Генерируем секрет для пользователей

head -c 16 /dev/urandom | xxd -ps

Запускаем

./mtproto-proxy -u nobody -p 8888 -H 443 -S <secret> --aes-pwd proxy-secret proxy-multi.conf -M 1

Желательно установить данное приложение как службу в вашем init или systemd.

Создание сертификата

SSL для работы применяет сочетание закрытого ключа и открытого сертификата. Ключ находится на сервере и доступа к нему нет. Сертификат же доступен всем пользователям, которые загружают контент с сервера. Для создания самоподписанного SSL и ключа нам нужно набрать в командной строке:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/nginx-selfsigned.key -out /etc/ssl/certs/nginx-selfsigned.crt

На экране вы увидите несколько вопросов. Из компонентов команды можно выделить:

• Openssl – это базовый инструмент командной строки. Он нужен для создания и управления сертификатами, а также файлами OpenSSL и ключами;

• Подкоманда req показывает, что требуется запрос для подписи сертификата X.509 (CSR). Это стандарт инфраструктуры для открытых ключей, для управления сертификатами;

• Опция –x509 способна вносить поправки в предыдущую команду. Они сообщает о том, что нужно создать самоподписанный сертификат вместо запроса на его подпись;

• -nodes служит для пропуска опции защиты SSL-сертификата с помощью пароля. Это необходимо для тог, чтобы Nginx при запуске считывал файл без необходимости вмешательства пользователя. Если поставить пароль – его нужно будет вводить после каждой перезагрузки;

• Опция -days365 поможет задать срок действия сертификата;

• Параметр -newkey rsa:2048 дает возможность сделать одновременно сертификат и ключ, ведь он не был создан ранее. Число 2048 значит, что ключ будет на 2048 бит;

• Строка -keyout показывает, куда OpenSSL переместит полученный файл ключа;

• Опция -out делает то же самое, но для сертификата. С помощью вышеописанных опций вы сможете сгенерировать одновременно сертификат с ключом. Вам нужно лишь указать данные сервера, отображающиеся в SSL.

Строка common name очень важна. В нее нужно написать свое имя или полное доменное имя вашего сервера. Простыми словами: она нужна для связи с сервером доменного имени. Если его нет, укажите IP сервера. Поля будут выглядеть как-то так:

Common Name (e.g. server FQDN or YOUR name) []:{YOUR_PROXY_ADDRESS}

Обратите внимание, что файлы сертификата и ключа будут перемещены в папку /etc/nginx/ssl.

Если применять OpenSSL, вам предстоит также сделать специальные ключи Диффи-Хеллмана для поддержки PFS. Чтобы это сделать, наберите в командной строке:

openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048

Подождите несколько минут пока сгенерируются ключи. Они будут размещены в каталоге /etc/ssl/certs/dhparam.pem.

Проксирование запросов с nginx

Созданные нами ключи хранятся в папке: /etc/ssl. Теперь нам нужно будет внести правки в настройки веб-сервера Nginx

Установим сам nginx

apt install nginx

1. В первую очередь – создать сниппет, показывающий папку, в которой хранятся SSL и ключ. Новый сниппет для Nginx создаем в папке /etc/nginx/snippets. Мы советуем вам отразить его назначение в названии. Наберите в консоли:

nano /etc/nginx/snippets/self-signed.conf

В файл добавим правило ssl_sertificate, указывающее путь к нашему сертификату. Кроме того, нам потребуется директива ssl_sertificate_key для пути к ключу:

ssl_certificate /etc/ssl/certs/nginx-selfsigned.crt;
ssl_certificate_key /etc/ssl/private/nginx-selfsigned.key;

2. Теперь потребуется добавить настройки сертификата с помощью еще одного сниппета. Это позволит нам получить надежный механизм шифрования с помощью дополнительных возможностей безопасности. Заданные параметры получится применять в будущих конфигурациях веб-сервера Nginx. Дайте файлу какое-нибудь общее имя:

sudo nano /etc/nginx/snippets/ssl-params.conf

Настроим DNS-распознаватель для запросов с восходящего канала, а также добавим ssl_dhparam для поддержки ключей Диффи-Хеллмана. Получится вот так:

ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_prefer_server_ciphers on;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
ssl_ecdh_curve secp384r1;
ssl_session_cache shared:SSL:10m;
ssl_session_tickets off;
ssl_stapling on;
ssl_stapling_verify on;
resolver 8.8.8.8 8.8.4.4 valid=300s;
resolver_timeout 5s;
add_header Strict-Transport-Security "max-age=63072000; includeSubdomains; preload";
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
ssl_dhparam /etc/ssl/certs/dhparam.pem;

Учтите, что из-за самоподписанности сертификата, не будет использоваться SSL stapling. При этом сервер Nginx покажет предупреждение, выключит stapling для этого SSL и продолжит работать. Теперь сохраним изменения и закроем файл.

3. И последнее: настроить обслуживание запросов SSL и их редирект. Эти настройки хранится в папке /etc/nginx/sites-available.

Создадим конфиг нового сайта (поменяйте адреса на свои):

nano /etc/nginx/sites-available/telegram.conf

server {
listen 8443 ssl http2 default_server;
listen [::]:8443 ssl http2 default_server;
server_name {YOUR_PROXY_ADDRESS};
include snippets/self-signed.conf;
include snippets/ssl-params.conf;
location /base1s/hs/api/telegram {
proxy_pass https://{YOUR_BASE_ADDRESS}:{YOUR_BASE_PORT}/{YOUR_BASE_NAME}/hs/api/telegram;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
client_max_body_size 100M;
}
}

Активируем сайт:

ln -s /etc/nginx/sites-available/telegram.conf /etc/nginx/sites-enabled/telegram.conf

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

nginx -t

Если все правильно, на экране вы увидите:

nginx: [warn] "ssl_stapling" ignored, issuer certificate not found
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

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

После этого потребуется перезапуск веб-сервера Nginx с помощью:

systemctl restart nginx

Настроим брандмауэр

Если используете брандмауэр ufw, то тут все просто, разрешаем порты:

ufw allow 8443
ufw allow 1080
ufw allow 443

ЧАСТЬ 3. ТЕЛЕГРАМ БОТ

Создадим бота

Для начала нам необходимо зарегистрировать в Telegram нашего будущего бота. Это делается следующим образом:

• Необходимо установить приложение Telegram на телефон или компьютер. Скачать приложение можно тут

• Добавляем к себе в контакт-лист бота с именем @BotFather

• Запускаем процедуру "общения" с ботом нажатием кнопки Start. Далее перед нами предстанет список команд точно как на скриншоте.

• Для того, чтобы создать нового бота необходимо выполнить команду /newbot и следовать инструкциям. Обратите внимание, что username для бота должен всегда содержать в конце слово bot. Например, OnesBot или Ones_bot.

• После создания бота, обратите внимание на строку с текстом:

  Use this token to access the HTTP API:

  За которой следует т.н. token по которому мы будем манипулировать нашим ботом. Помимо функции создания telegram бота, BotFather также имеет ряд других возможностей:

  • Присвоить боту описание
  • Установить аватар
  • Поменять token

• С помощью меню включаем для бота Inline mode

• Если необходимо — включаем для бота возможность работать с групами

Протестируем бота

Добавим бота к себе в контакт лист и инициируем с ним общение нажатием кнопки “start”

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

Напишем боту произвольную фразу.

Для работы с http запросами я крайне рекомендую софтину postman, но для определенной унификации запросы буду писать с синтаксисом утилиты curl

Затем вобьём в адресную строку браузера (или с помощью curl на своем новом хосте) следующий запрос:

curl https://api.telegram.org/bot{YOUR_TOKEN}/getUpdates

В полученном JSON мы увидим свое сообщение.

Ответим себе от имени бота:

curl https://api.telegram.org/bot{YOUR_TOKEN}/sendMessage?chat_id={YOUR_ID_FROM_JSON}&text=TEST

От бота вам придет сообщение.

Таким образом можно проверять сообщения боту (long polling) и делать рассылку или реакцию на запрос.

Но long polling это не лучшее решение в плане надежности и нагрузки, да и вряд ли вам нужно бесконечное регламентное задание и хранение offset’а и прочих возможных точек отказа.

Вебхуки

Следующей командой научим нашего бота обращаться к настроенному proxy серверу по определенному порту. А также скормим наш сертификат. С помощью curl’a выполним запрос:

curl -F "url=https://{YOUR_PROXY_ADDRESS}:8443" -F "certificate=@/etc/ssl/certs/nginx-selfsigned.crt" "https://api.telegram.org/bot{YOUR_TOKEN}/setWebhook"

Затем выполним еще один запрос для того,чтоб получить информацию об успешности наших действий:

curl "https://api.telegram.org/bot{YOUR_TOKEN}/getWebhookInfo"

Ответ мы должны получить в JSON формате следующий:

{
"ok": true,
"result": {
"url": "https://{YOUR_PROXY_ADDRESS}:8443",
"has_custom_certificate": true,
"pending_update_count": 0,
"max_connections": 40
}
}

Если получили нечто другое — разруливаем ошибку.

Если все сделали правильно — теперь телеграм будет самостоятельно отправлять запросы на указаный URL. А в нашем случае nginx будет пересылать эти запросы 1С.

В случае если ваш сервер будет лежать или неотвечать, телеграм неоднакратно сделает попытку доставить сообщение. Но пока, советую отложить бота в сторонку.

ЧАСТЬ 4. OAUTH2, GOOGLE ПРИЛОЖЕНИЕ

О трехногой авторизации

Для нашего бота не помешает сделать трехногую oauth2 авторизацию.

Это хорошее решение, в случае если нам нужно устанавливать личность пользователя.

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

Тк у моей компании есть корпоративный домен с gmail ящиками, а в базах у пользователей указаны email’ы (это поле есть практически в любой конфигурации) — мной было принято решение использовать OAuth2 Google для идентификации пользователя по цепочке:

Telegram ID <=> Gmail <=> Пользователь ИБ

При успешной аутентификации записывать в регистр сведений “ТокеныПользователей” с измерением “Токен“ и ресурсом ”Пользователь”. Опционально можно добавить измерение “Тип”, если вы будете хранить access/refresh токен для Gmail или другие токены и “Дату”, если ваш токен имеет время жизни.

Алгоритм авторизации

Как же для пользователя будет выглядеть аутентификация?

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

1. Пользователь пишет боту, инициирует общение или выполняет некую “приватную” команду.
2. Бот заявляет, что необходимо авторизоваться и отправляет пользователю предложение авторизоваться, например “Для авторизации наберите: /login”.
3. Если пользователь хочет авторизоваться — нажимает на команду /login.
4. Бот видит, что новый для него пользователь хочет авторизоваться и возвращает кнопки с вариантами авторизации через различные сервисы (таким образом можно сделать и свою веб форму входа с собственным алгоритмом, но для примера мы будем использовать трехногую серверную аутентификацию через гугл).
5. Пользователь нажимает кнопку и у него отрывается браузер с предложением выбрать аккаунт для аутентификации.
6. Выбрав аккаунт запрос отправляется в гугл.
7. Гугл перенаправляет запрос нашему http сервису указаному при формировании кнопки в параметре “redirect_uri”, некий код в параметре “code”, а также идентификатор пользователя телеги переданный в параметре “state”.
8. Обмениваем у гугла “code” на “access token” и основные данные о пользователе (включая email).
9. Пытаемся найти пользователя с заданым емэйлом в базе. Если удается — пишем в регистр сведений сопоставление telegram id и пользователя, отправляем поздравления в телегу. Если не удается — сообщаем о неудачи.

Заведем приложение

Создадим новое веб приложение, для этого перейдем по ссылке:

https://console.cloud.google.com/apis/credentials

Учетные данные > Создать учетные данные > Идентификатор клиента OAuth > Веб-приложение

Название: Произвольное (Например Web OAuth)

Разрешенные источники JavaScript: Ваш домен и порт (Например https://domen.ru:12345)

Разрешенные URI перенаправления: Введите url мест куда будет перенаправлять ваше приложение. (Тут стоит указать https://domen.ru:12345/urbase/hs/api/telegram/)

Запишите секрет и идентификатор клиента, они вам понадобятся на этапе программирования авторизации. Если не верно указали настройки перенаправления или решите изменить путь — позже можно будет исправить.

Сохраните идентификатор клиента.

Во второй вкладке “Окно запроса доступа” заполните настройки окна доступа.

Области действия для API Google: email и profile

Авторизованные домены: ваш домен

Все остальное произвольно.

В третьей вкладке “Подтверждение прав на домен” добавьте свой домен.

Подробно тут останавливаться не буду, подскажу лишь то, что если у вас нет прямого доступа к корню домена, а только 1с‘ка, то можно подтвердить домен с помощью http сервиса вернув гуглу ожидаемые им параметры.

На этом создание OAuth приложения закончено. Поэкспериментировать с ним можете с помощью следующей площадки: https://developers.google.com/oauthplayground

ЧАСТЬ 5. АРХИТЕКТУРА API

Архитектура в общих чертах

 Итак, все приготовления завершены, наступает время открывать конфигуратор. На схеме нарисована предлагаемая упрощенная схема разбора ответа. Постараюсь в общих словах обрисовать архитектуру:

1. Некое уведомление/webhook от телеграмма (в нашем случае пересылается с проксирующего nginx) приходит на http-сервис “api” (корневой url — api), на шаблон “telegram” (/telegram/), на произвольный http метод ANY с обработчиком “telegram”.

   Итого наш url для всех методов telegram’а: https://{YourDomen}:{YourPort}/{YourBase}/hs/api/telegram — на этот url ссылается настроенный ранее в части 2 проксирующий nginx.

2. В процедуре-обработчике “telegram”:

   • Опционально устанавливаем Привилегированный режим
   • Опционально подключаем попытку/исключение и в случае исключения возвращаем 400 или 500 код и описание ошибки в теле (возможно в json с дополнительными параметрами, но сейчас не будем усложнять).
   • Разбираем в общем модуле “REST” параметры запроса и возвращаем структуру (это очень удобный подход для разработки http сервисов, тут можно записать все передаваемые в заголовках, url, application/json, text/plain, application/x-www-form-urlencoded, multipart/form-data в единую структуру и далее бизнес логикой приложения уже работать с этой структурой не задумываясь о парсинге и способе передачи параметров). Телеграм всегда присылает JSON, его довольно легко распарсить и превратить в структуру парой строчек кода.
   • Передаем полученную структуру в общий модуль телеграм в некую процедуру-фасовщик.
   • Возвращаем некое сообщение с кодом 200 об успешном завершении (также можно будет возвращать некую страницу уведомляющую об успешной oauth авторизации, но об этом далее)

3. В процедуре-фасовщике (у меня это Телеграм.РазобратьЗапрос(ДанныеЗапроса) ) на основании полученных данных можем совершить следующее:

   • Закончить процесс начатой авторизации (возможно вы захотите вообще вынести эту процедуру в отдельный шаблон вашего api сервиса, например в hs/api/auth)
   • Отказать в дальнейшем выполнении (например если переданы данные не в json или запрос пришел не с нашего прокси-сервера или нехватает некоторых ожидаемых параметров или пользователь неавторизован и тп и тд)
   • Разобрать запрос как встроенный запрос (inline_query)
   • Разобрать запрос как обратный запрос (callback_query)
   • Разобрать запрос как сообщение от пользователя (message)

Процедура-обработчик запроса

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

Функция telegram(request)
Попытка
УстановитьПривилегированныйРежим(Истина);
requestData = REST.getRequestData(request);
Телеграм.РазобратьЗапрос(requestData);
Возврат REST.jsonResponse(Новый Структура, 200);
Исключение
Возврат REST.errorResponse(ОписаниеОшибки(), 500);
КонецПопытки;
КонецФункции

Разбор запроса

Вот примерно таким образом можно разобрать запрос и привести его к единой структуре параметров:

// REST.getRequestData(request);
Функция getRequestData(Знач request) Экспорт
requestData  = Новый Структура("Метод,ПутьБазовый,ПутьОтносительный,Параметры"
, request.HTTPМетод
, НРег(request.БазовыйURL)
, НРег(request.ОтносительныйURL)
, Новый Соответствие);

ИсточникиПараметров  = СтрРазделить("Заголовки,ПараметрыURL,ПараметрыЗапроса", ",", Ложь);
Для Каждого Источник Из ИсточникиПараметров Цикл
Для Каждого КлючИЗначение Из request[Источник] Цикл
requestData.Параметры.Вставить(НРег(КлючИЗначение.Ключ), КлючИЗначение.Значение);
КонецЦикла;
КонецЦикла;

// Разбор тела для POST запроса
cType  = requestData.Параметры["content-type"];
Если cType = Неопределено Или ПустаяСтрока(cType) Тогда
// ...
ИначеЕсли СтрНайти(requestData.Параметры["content-type"], "text/plain") Тогда
// ...
ИначеЕсли СтрНайти(requestData.Параметры["content-type"], "application/x-www-form-urlencoded") Тогда
// ...
ИначеЕсли СтрНайти(requestData.Параметры["content-type"], "application/json") Тогда
body    = request.ПолучитьТелоКакСтроку();
paramArr  = Сериализация.ДесериализоватьJSON(body);
Если ТипЗнч(paramArr) <> Тип("Структура") Тогда
ВызватьИсключение "В JSON надо передавать структуру (map) параметров.";
КонецЕсли;
Для Каждого param Из paramArr Цикл
requestData.Параметры.Вставить(НРег(param.Ключ), param.Значение);
КонецЦикла;
ИначеЕсли СтрНайти(requestData.Параметры["content-type"], "multipart/form-data") Тогда
// ...
КонецЕсли;

ВыполнитьПриведениеТипов(requestData.Параметры); // Тут можно привести простые типы к более сложным по наименованию параметров

Возврат requestData;
КонецФункции

Если вдруг кто не умеет, JSON сериализуется и десериализуется довольно просто:

#Область JSON
Функция СериализоватьJSON(Данные) Экспорт
ПриведениеКПростымТипам.Привести(Данные);
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
НастройкиСериализации = Новый НастройкиСериализацииJSON();
НастройкиСериализации.СериализовыватьМассивыКакОбъекты = Ложь;
НастройкиСериализации.ФорматСериализацииДаты = ФорматДатыJSON.ISO;
НастройкиСериализации.ВариантЗаписиДаты = ВариантЗаписиДатыJSON.ЛокальнаяДатаСоСмещением;
ЗаписатьJSON(ЗаписьJSON, Данные, НастройкиСериализации);
Возврат ЗаписьJSON.Закрыть();
КонецФункции // СериализоватьJSON()

Функция ДесериализоватьJSON(СтрокаJSON) Экспорт
ЧтениеJSON = Новый ЧтениеJSON();
ЧтениеJSON.УстановитьСтроку(СтрокаJSON);
Возврат ПрочитатьJSON(ЧтениеJSON);
КонецФункции // ДесериализоватьJSON()
#КонецОбласти

Фасовка запроса

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

Целиком код приводить не буду, но подскажу, что тут нужно куча условий.

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

// Телеграм.РазобратьЗапрос(Данные)
Данные.Параметры["referer"] // А вдруг пришло от accounts.google.com?
Данные.Параметры["inline_query"] // РазобратьВстроенныйЗапрос
Данные.Параметры["callback_query"] // РазобратьОбратныйЗапрос
Данные.Параметры["message"] // РазобратьСообщение

Если вдруг побежите реализовывать дальнейший разбор сообщений самостоятельно — хочу обратить внимание, что могут приходить сообщения не вписывающиеся в изложенную логику работы. Необходимо внимательно обрабатывать все ошибки и в случае если вас не устраивает полученные от телеграма параметры — все равно возвращать ему 200 код (иначе вы потоните под горой спама от тележки, тк она будет упорно вновь и вновь слать вам сообщения на которые вы ей возвращаете код ошибки).

Например “сообщение” может не всегда содержать отправителя, необходимо предусматривать такие моменты либо через попытку-исключение, либо смотреть в содержание структуры:

Если Не Данные.Параметры["message"].Свойство("chat") Тогда Возврат КонецЕсли;

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

ЧАСТЬ 6. ПОЛУЧЕНИЕ СООБЩЕНИЙ

ЧАСТЬ 7. ОТПРАВКА СООБЩЕНИЙ

ЧАСТЬ 8. ОТРИСОВКА КЛАВИАТУРЫ

ЧАСТЬ 9. РЕАЛИЗАЦИЯ АВТОРИЗАЦИИ

ЧАСТЬ 10. ОТПРАВКА ФАЙЛОВ

ЧАСТЬ 11. ИСПРАВЛЕНИЕ СООБЩЕНИЙ

ЧАСТЬ 12. ОБРАТНЫЕ ЗАПРОСЫ

ЧАСТЬ 13. ВСТРОЕННЫЕ ЗАПРОСЫ