Делаем авторизацию в Telegram Mini Apps правильно / Habr

Если вас заинтересовала тема авторизации, подразумеваю, что вы уже итак знаете что такое Telegram Mini Apps. Поэтому не буду долго размусоливать вступление и перейду сразу к делу.

Поехали!

Принцип работы

Так как Telegram Mini Apps — это обычные веб‑приложения, то сценарии аутентификации и авторизации мы будем использовать привычные для веб‑приложений.

Аутентификация

Напомню, это процесс, когда клиент подтверждает, что действительно является тем, за кого себя выдает. В случае с Telegram Mini Apps пользователь аутентифицируется в самом Telegram, и мессенджер самостоятельно передает в наше Mini App данные о пользователе. Однако они могут быть скомпрометированы, и мы не можем им доверять — об этом сказано в документации Telegram Mini Apps.

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

Хочу отметить, что в качестве механизма аутентификации не обязательно использовать концепцию пары JWT‑токенов — иногда лучшим решением могут оказаться обычные сессии. Всё зависит от архитектуры вашего проекта.

Процесс выглядит следующим образом:

При запуске нашего Mini App Telegram передает в него initData — строку с данными о пользователе и прочей информацией.
Mini App делает запрос на аутентификацию к серверу, передавая ему initData.
Сервер проверяет подлинность initData с помощью bot_token (токена Telegram‑бота, к которому привязан Mini App) посредством сравнения хэшей (далее разберем это подробно).
Из initData извлекается id пользователя в Telegram. По этому id запрашивается пользователь в БД (если он уже есть в системе) или создается новый (если пользователь зашел впервые).
БД возвращает пользователя.
Генерируются access‑ и refresh‑токены. При необходимости в них добавляются данные о пользователе (роли, id и т. д.).
Сервер отвечает на запрос Mini App, устанавливая пару токенов в http‑only secure cookies.

Авторизация

Напомню, это процесс проверки прав пользователя на выполнение им действия в системе. Здесь все как обычно.

Mini App выполняет запрос к серверу (в cookies лежит пара токенов).
Сервер извлекает из cookies пару токенов, проверяет их валидность и расшифровывает.
Если время жизни access-токена истекло, а refresh-токен еще актуален, сервер обновляет токены клиенту.
Сервер авторизует запрос (по ролям, id пользователя или другим атрибутам).
Запрос и получение данных из БД.
Ответ клиенту (если токены обновились — обновляются cookies).

С теорией разобрались, теперь пойдем кодить!

Пример реализации

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

Frontend реализуем с помощью React, а backend на Nest.js.

Frontend

Сперва нужно подключить Telegram SDK. Для этого нужно добавить скрипт в head страницы:

<script src="https://telegram.org/js/telegram-web-app.js"></script>

Теперь создадим простой React-компонент, который будет отправлять запрос на аутентификацию, передавая initData, и отображать статус сессии:

import axios from 'axios';
import { useState, useEffect } from 'react';

// Кастомный хук для аутентификации
const useAuth = () => {
  // Состояние, указывающее, авторизован ли пользователь
  const [isAuth, setIsAuth] = useState(false);

  // Функция для отправки данных на сервер и получения статуса аутентификации
  const signIn = async (initData: string) => {
    const { data } = await axios.post<boolean>(
      'https://example.com/auth/signin', // URL эндпоинта аутентификации
      { initData }, // Передаем данные для входа
    );
    setIsAuth(data); // Устанавливаем статус аутентификации
  };

  return { isAuth, signIn };
};

export const App = () => {
  const { isAuth, signIn } = useAuth();

  useEffect(() => {
    // Вызываем signIn при монтировании компонента,
    // передавая initData из Telegram WebApp API
    signIn(window.Telegram.WebApp.initData);
  }, []);

  // Если пользователь аутентифицирован, показываем соответствующее сообщение
  if (isAuth) {
    return <h1>Authenticated</h1>;
  }

  // Если не аутентифицирован, показываем другое сообщение
  return <h1>Not Authenticated</h1>;
};

Backend

Для валидации initData на сервере воспользуемся пакетом @telegram-apps/init-data-node.

JWT-токены будем генерировать с помощью пакета jsonwebtoken.

Сделаем небольшой контроллер, который при обращении будет валидировать initData и выдавать пару токенов:

import { FastifyReply, FastifyRequest } from 'fastify';
import { Controller, HttpStatus, Post, Req, Res, BadRequestException } from '@nestjs/common';
import { parse, isValid } from '@telegram-apps/init-data-node';
import * as jwt from 'jsonwebtoken';
import { getUserByTgId } from './user.service';

@Controller('/auth')
export class AuthController {
  // Эндпоинт аутентификации
  @Post('/signin')
  async signin(@Req() req: FastifyRequest, @Res() res: FastifyReply) {
    const { initData } = req.body as { initData: string }; // Достаем данные из запроса

    // Валидируем initData с помощью токена бота (он фейковый)
    const isInitDataValid = isValid(
      initData,
      '1234567890:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
    );

    if (!isInitDataValid) {
      throw new BadRequestException('AUTH__INVALID_INITDATA'); // Ошибка, если initData некорректна
    }

    // Парсим initData и достаем Telegram ID пользователя
    const tgId = parse(initData).user?.id;

    if (!tgId) {
      throw new BadRequestException('AUTH__INVALID_INITDATA'); // Ошибка, если ID отсутствует
    }

    // Допустим, что тут мы достаем пользователя из базы
    const user = await getUserByTgId({ tg_id: tgId });

    if (!user) {
      throw new BadRequestException('AUTH__USER_NOT_FOUND'); // Ошибка, если пользователь не найден
    }

    const { id, tg_id, roles } = user; // Достаем нужные данные

    // Создаем access и refresh токены, зашивая в них данные пользователя
    const accessToken = jwt.sign(
      { id, tg_id, roles },
      'jwt_at_secret', // Секрет для access-токена
      { expiresIn: '5m' }, // Время жизни токена
    );

    const refreshToken = jwt.sign(
      { id, tg_id, roles },
      'jwt_rt_secret', // Секрет для refresh-токена
      { expiresIn: '7d' }, // Время жизни токена
    );

    // Опции для установки cookies
    const cookiesOptions = {
      httpOnly: true, // Доступно только через HTTP (JS не может прочитать)
      secure: true, // Передается только по HTTPS
      path: '/', // Доступно во всем домене
      sameSite: 'strict', // Защита от CSRF-атак
    };

    // Устанавливаем токены в cookies
    res.cookie('ACCESS_TOKEN', accessToken, cookiesOptions);
    res.cookie('REFRESH_TOKEN', refreshToken, cookiesOptions);

    res.status(HttpStatus.OK).send(true); // Отправляем успешный ответ
  }
}

Теперь рассмотрим реализацию авторизации запроса.

Добавим эндпоинт, который:

Возвращает true, если access-токен валиден.
Если access-токен недействителен, пытается обновить его с помощью refresh-токена.
Если обновление не удается, возвращает ошибку 401.

import { FastifyReply, FastifyRequest } from 'fastify';
import { Controller, Get, HttpStatus, Req, Res, UnauthorizedException } from '@nestjs/common';
import * as jwt from 'jsonwebtoken';

@Controller('/auth')
export class AuthController {
  // Эндпоинт для проверки авторизации
  @Get('/protected')
  async protected(@Req() req: FastifyRequest, @Res() res: FastifyReply) {
    const accessToken = req.cookies.ACCESS_TOKEN; // Достаем access-токен из cookies
    const refreshToken = req.cookies.REFRESH_TOKEN; // Достаем refresh-токен из cookies

    if (!accessToken || !refreshToken) {
      throw new UnauthorizedException(); // Ошибка, если нет токенов
    }

    try {
      jwt.verify(accessToken, 'jwt_at_secret'); // Валидируем access-токен
      return true; // Если токен валиден — отправляем успешный ответ
    } catch {
      try {
        // Валидируем refresh-токен
        const { id, tg_id, roles } = jwt.verify(refreshToken, 'jwt_rt_secret') as {
          id: number;
          tg_id: number;
          roles: string[];
        };

        // Создаем новые access и refresh токены
        const accessToken = jwt.sign(
          { id, tg_id, roles },
          'jwt_at_secret', // Секрет для access-токена
          { expiresIn: '5m' }, // Время жизни токена
        );

        const refreshToken = jwt.sign(
          { id, tg_id, roles },
          'jwt_rt_secret', // Секрет для refresh-токена
          { expiresIn: '7d' }, // Время жизни токена
        );

        // Опции для установки cookies
        const cookiesOptions = {
          httpOnly: true, // Доступно только через HTTP (JS не может прочитать)
          secure: true, // Передается только по HTTPS
          path: '/', // Доступно во всем домене
          sameSite: 'strict', // Защита от CSRF-атак
        };

        // Устанавливаем токены в cookies
        res.cookie('ACCESS_TOKEN', accessToken, cookiesOptions);
        res.cookie('REFRESH_TOKEN', refreshToken, cookiesOptions);

        return true; // Отправляем успешный ответ
      } catch {
        throw new UnauthorizedException(); // Ошибка, если refresh-токен недействителен
      }
    }
  }
}

Надеюсь, общий принцип вам понятен. Конечно, в реальных приложениях на стороне Frontend потребуется реализовать более сложный хук авторизации, добавить роутинг и защищенные маршруты, а в Nest.js — выносить логику из контроллера в Guards и сервисы. Но это уже тема для других статей.