Выбрать ветку (тег)
Найти файл
Клонировать
README.md

English version

Беспарольный вход через MAX для Python, Node.js, Go, PHP и ASP.NET Core — OpenID Connect (OIDC)

Вход через MAX без пароля для приложения на Python, Node.js, Go, PHP или ASP.NET Core: вход по QR-коду вместо пароля или кода из SMS. Ваш пользователь сканирует QR-код на странице входа (а на телефоне — нажимает кнопку) и подтверждает вход в MAX.

Пример — стандартный OpenID Connect (OIDC) провайдер плюс минимальное клиентское приложение на каждом из этих языков.

Вход на компьютере через MAX: в окне входа QR-код, камера телефона его сканирует, пользователь нажимает «Подтвердить» в чате MAX, бот отвечает «Вход подтверждён».
На компьютере: QR-код, камера телефона, одно касание в MAX.

Вход на телефоне: пользователь нажимает «Войти через MAX», подтверждает вход в чате MAX, бот отвечает «Вход подтверждён».
На телефоне: кнопка канала, одно касание в MAX. Снимок с демо, где включены все каналы; этот стенд предлагает только MAX.

Что вы получите

Откройте клиентское приложение — оно отправит вас на страницу входа. На компьютере вы сканируете QR-код телефоном; на самом телефоне — нажимаете кнопку. MAX открывает вашего бота, вы подтверждаете вход одним нажатием — и возвращаетесь в приложение уже вошедшим, со списком claims, которые выдал провайдер. Без пароля, без формы, без SMS-кода.

Провайдер — Veriqa: OpenID Connect-сервер с открытым исходным кодом на базе OpenIddict, который подтверждает вход в мессенджерах — среди них MAX, Telegram, WhatsApp, Instagram*, Messenger*, WeChat, Viber и Email. Клиенты ничего не знают о Veriqa: каждый использует обычную библиотеку OpenID Connect для своего языка (Authorization Code + PKCE), поэтому та же схема работает на любом стеке, где есть OIDC-библиотека.

Каждая папка рядом с clients/ — отдельный способ подключить MAX со своим стендом; клиентские приложения в clients/ у них общие. built-in/ использует встроенный в Veriqa канал MAX.

built-in/            the stand with the MAX channel built into Veriqa
  docker-compose.yml   Veriqa from the published image, MAX channel only
  .env.example         the values you fill in
clients/             the client app, one per language - run any of them
  python/              Flask, Authlib
  node/                Express, openid-client, in TypeScript
  go/                  net/http, go-oidc
  php/                 jumbojett/openid-connect-php
  dotnet/              ASP.NET Core, Microsoft.AspNetCore.Authentication.OpenIdConnect

Перед началом

  • Docker с Compose: стенд запускается в нём для простоты. Veriqa работает и без Docker, службой ОС
  • среда выполнения выбранного клиента: Python 3.10+, Node.js 24.5+, Go 1.26+, PHP 8.2+ с Composer или .NET SDK 10
  • бот MAX и его токен. Боты создаются на партнёрской платформе MAX, для которой нужен верифицированный профиль организации, ИП или самозанятого, — см. документацию MAX по ботам. Используйте бота, которого не опрашивает никакой другой сервер.

Публичный адрес не нужен: стенд запускает MAX в режиме long polling, бот сам забирает свои обновления.

Запуск

1. Заполните настройки.

cd built-in
cp .env.example .env

Впишите токен бота в MAX_BOT_TOKEN и придумайте любой пароль для CERT_PASSWORD.

2. Создайте HTTPS-сертификат. OpenID Connect требует HTTPS даже локально: провайдер отвечает на https://localhost:8443.

Для клиентов на Python, Node.js, Go и PHP самоподписанный сертификат создаст сам стенд:

docker compose run --rm certificate

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

Для клиента на ASP.NET Core возьмите сертификат разработки .NET, на нём же клиент отвечает на https://localhost:7020:

dotnet dev-certs https --trust
dotnet dev-certs https -ep certs/localhost.pfx -p <CERT_PASSWORD from .env>
chmod 644 certs/localhost.pfx

--trust делает сертификат доверенным на вашей машине; на Linux следуйте тому, что выведет команда. chmod (Linux и macOS) позволяет пользователю контейнера без прав root прочитать файл; на Windows пропустите его и пишите путь как certs\localhost.pfx.

Стенд хранит один сертификат. Чтобы перейти с одного вида на другой, сначала удалите certs/ (на Linux через sudo, папку создал контейнер) и пересоздайте провайдер: docker compose up -d --force-recreate.

3. Запустите провайдер.

docker compose up -d
docker compose ps

Дождитесь статуса healthy, затем проверьте готовность: https://localhost:8443/health/ready отвечает 200.

4. Запустите клиент.

Python:

cd ../clients/python
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python main.py

На Windows запускайте python -m venv .venv, а программы виртуального окружения лежат в .venv\Scripts\.

Node.js:

cd ../clients/node
npm install
npm start

Go:

cd ../clients/go
go run .

PHP:

cd ../clients/php
composer install
php -S localhost:7020 index.php

ASP.NET Core:

dotnet run --project ../clients/dotnet -- --Oidc:Channel max

5. Войдите. Откройте http://localhost:7020 (https:// для клиента на ASP.NET Core), отсканируйте QR-код телефоном и подтвердите вход в MAX. Вы вернётесь в клиент со списком своих claims. /signout сбрасывает локальную сессию, чтобы можно было пройти вход ещё раз.

Как это устроено

  • clients/dotnet/ запрашивает у провайдера вход с acr_values=channel:max, поэтому страница входа сразу ведёт в MAX. Без --Oidc:Channel она предлагает все включённые каналы. Остальные клиенты берут то же значение из переменной VERIQA_CHANNEL; на этом стенде включён один канал, поэтому они работают и без неё.
  • built-in/docker-compose.yml регистрирует клиент (rp, redirect http://localhost:7020/signin-oidc и https://localhost:7020/signin-oidc), задаёт издателя https://localhost:8443 и включает канал MAX.
  • Стенд работает в окружении Development: сессии живут в памяти, а токены подписываются сертификатами разработки, поэтому после перезапуска всё забывается. Именно это позволяет обойтись одним контейнером — это локальный стенд, а не развёртывание.

Что дальше

  • Настройки канала MAX, включая режим вебхука для развёрнутого сервера: Каналы → MAX.
  • Продакшен-конфигурация с базой данных, настоящими сертификатами и reverse proxy: Быстрый старт: self-hosted.
  • Сама Veriqa — исходный код, другие примеры и документация: gitlab.com/veriqa/veriqa · veriqa.app.

Лицензия

Этот пример распространяется под лицензией MIT — свободно копируйте его в свой код. Сама Veriqa — open source под MPL-2.0.

* Instagram и Messenger — продукты компании Meta, признанной в России экстремистской организацией; её деятельность в стране запрещена.