Логин через Telegram по-новому: разбираем OIDC-флоу oauth.telegram.org и собираем его на Python

• кнопка вставляется на любой http://-сайт;
  
• Telegram возвращает поля юзера прямо в URL или в JS-callback;
  
• подлинность проверяется HMAC-SHA256 от токена бота;
  
• в BotFather вы прописываете домен через /setdomain.

• Telegram стал полноценным OpenID-провайдером;
  
• есть /.well-known/openid-configuration, есть JWKS;
  
• ID-токен — настоящий JWT, подписанный публичным ключом из JWKS Telegram;
  
• бэкенд проверяет подпись по этому ключу, аудиторию (aud), издателя (iss), exp/iat;
  
• bot-token при авторизации не используется — он только для Bot API. Не путать его с Client Secret: BotFather в Web Login выдаёт пару Client ID + Client Secret, и Client Secret нужен для manual OIDC code flow. В popup-варианте бэк его не видит, но в полном flow он есть.

• Login library — браузерный popup через telegram-login.js. Telegram внутри popup-а сам делает Authorization Code Flow с PKCE и возвращает нам уже готовый id_token через postMessage. Бэк только проверяет JWT — никакого Client Secret, никакого PKCE на нашей стороне.
  
• Manual OIDC — обычный Authorization Code Flow: вы сами редиректите юзера на oauth.telegram.org/auth, ловите code в своём callback’е и меняете его на токены через /token (Basic Auth с Client ID + Client Secret).

from jwt import PyJWKClient
jwks_client = PyJWKClient(
    "https://oauth.telegram.org/.well-known/jwks.json",
    cache_keys=True,
    lifespan=600,  # 10 минут
)

def _verify_telegram_id_token(id_token: str, jwks_client, client_id, issuer):
    if not id_token:
        raise ValueError("Empty id_token")
    signing_key = jwks_client.get_signing_key_from_jwt(id_token).key
    return jwt.decode(
        id_token,
        signing_key,
        algorithms=["RS256", "ES256"],
        audience=client_id,                       # ваш Client ID из BotFather
        issuer=issuer,                            # "https://oauth.telegram.org"
        options={"require": ["iss", "aud", "exp", "iat", "sub"]},
        leeway=30,                                # на рассинхрон часов
    )

• Ищу TelegramAccount по telegram_id → если есть, переиспользую его юзера и обновляю мутабельные поля.
  
• Иначе ищу User по phone_number → если есть, прикрепляю новый TelegramAccount к нему.
  
• Иначе создаю и User, и TelegramAccount.

• Trusted Origins — добавьте сюда https://<ваш-ngrok-домен>.ngrok-free.app. Только origin: ни пути, ни слеша на конце. Origin’ов можно несколько (например, localhost через прокси и прод).
  
• Redirect URIs — для нашего флоу через telegram-login.js оставьте пустым. Это поле нужно только если вы сами реализуете server-side обмен code → token.

ngrok http 8000

APP_TG_CLIENT_ID=8506301481      # ваш Client ID из BotFather
APP_SECRET_KEY=<32 байта в hex>  # ключ AES для подписи cookie-сессии
APP_DB_URL=sqlite+aiosqlite:///./tg_auth.db

python3 -c "import secrets; print(secrets.token_hex(16))"  # 32 hex-символа = 32-байтная строка для AES-ключа

<script async src="https://oauth.telegram.org/js/telegram-login.js?3"
        data-client-id="8506301481"
        data-onauth="onTelegramAuth(data)"
        data-request-access="write phone"></script>
<button class="tg-auth-button" data-style="shine">Sign In with Telegram</button>

async function onTelegramAuth(data) {
  if (!data || data.error) return;
  const res = await fetch("/api/v1/auth/telegram", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    credentials: "include",
    body: JSON.stringify({ id_token: data.id_token }),
  });
  if (res.ok) window.location.href = "/app";
}

make develop      # создаёт .venv, ставит зависимости через uv
make migrate      # применяет alembic-миграции
make run          # python -m tg_auth → uvicorn на :8000

sess_user = request.session.get("user")
if not sess_user:
    return Redirect(path="/")
user = await fetch_user_by_id.execute(UserID(UUID(sess_user["id"])))
if user is None:
    request.clear_session()  # self-heal
    return Redirect(path="/")

{
  "user": { "id": "...", "name": "Jane", "phone_number": "+7..." },
  "tokens": {
    "access_token": "eyJ...",
    "refresh_token": "eyJ...",
    "token_type": "Bearer",
    "expires_in": 900
  }
}