Если вас заинтересовала тема авторизации, подразумеваю, что вы уже итак знаете что такое 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 и сервисы. Но это уже тема для других статей.
