Dasturchilar uchun · 10 daqДля разработчиков · 10 мин
Mars ID ni loyihangizga ulangПодключи Mars ID к своему проекту
Telegram orqali avtorizatsiya. 15 daqiqada. Parolsiz, registratsiyasiz — bitta bosish va foydalanuvchi tizimda.Авторизация через Telegram за 15 минут. Без паролей, без регистрации — один клик и пользователь в системе.
Foydalanuvchi haqida ma'lumotlarДанные пользователя
Mars ID foydalanuvchi tizimga kirganda JWT-token beradi. Ichida quyidagi ma'lumotlar bor:Когда пользователь логинится через Mars ID, ты получаешь JWT-токен с данными:
MaydonПоле
TavsifОписание
sub
Foydalanuvchi UUIDUUID пользователя
name
Ism (Telegram dan)Имя (из Telegram)
handle
Unikal nom, masalan azizУникальный хэндл, напр. aziz
role
student / mentor / admin
tg
Telegram ID
email
handle@marshub.uz
Qanday ishlaydiКак это работает
Cookie orqali SSOSSO через cookie
Foydalanuvchi Mars ID ga kirganda, brauzerga __mars_id cookie o'rnatiladi — butun .marshub.uz domenida. Sizning xizmatingiz bu cookie ni avtomatik oladi.Когда пользователь логинится через Mars ID, в браузер ставится cookie __mars_id на весь домен .marshub.uz. Твой сервис получает эту cookie автоматически.
👤
Foydalanuvchi saytingizga kiradiПользователь заходит на твой сайт
↓
🔍
Server __mars_id cookie ni tekshiradiСервер проверяет cookie __mars_id
↓
❌
Cookie yo'q? → id.marshub.uz/login ga yo'naltirishНет cookie? → Редирект на id.marshub.uz/login
↓
🤖
Telegram orqali kirish → cookie o'rnatiladiВход через Telegram → cookie установлен
↓
✅
Foydalanuvchi saytingizga qaytadi. Tayyor!Пользователь возвращается на твой сайт. Готово!
Usulni tanlangВыбери способ
3 ta ulash usuli3 способа подключения
JWT Cookie
OsonЛегко
*.marshub.uz dagi xizmatlar uchun. Cookie avtomatik keladi.Для сервисов на *.marshub.uz. Cookie приходит автоматически.
OAuth2 / OIDC
O'rtachaСредне
Tashqi xizmatlar uchun. Standart protokol.Для внешних сервисов. Стандартный протокол.
Caddy Forward Auth
KodsizБез кода
Statik saytlar uchun. Faqat sozlash — kodlash kerak emas.Для статических сайтов. Только настройка — код не нужен.
1-usul: JWT CookieСпособ 1: JWT Cookie
Node.js bilan ulashПодключение на Node.js
1
Paketlarni o'rnatingУстанови пакеты
npm install express cookie-parser
2
Hech qanday kalit kerak emasНикакой ключ не нужен
Tokenni Mars ID ning o'zidan tekshiramiz — /api/verify so'rovi orqali. AUTH_SECRET so'ramang: u butun ekotizimning bosh kaliti, faqat Mars ichki xizmatlariga beriladi.Токен проверяем у самого Mars ID — запросом на /api/verify. AUTH_SECRET не проси: это мастер-ключ всей экосистемы, его выдают только внутренним сервисам Mars.
3
server.js yaratingСоздай server.js
Quyidagi kodni nusxalang:Скопируй код ниже:
server.js
importexpressfrom'express';
importcookieParserfrom'cookie-parser';
constapp=express();
app.use(cookieParser());
// Middleware: Mars ID tekshirishasync functionrequireAuth(req, res, next) {
consttoken=req.cookies['__mars_id'];
consttoLogin= () => {
constback=encodeURIComponent(
`https://${req.headers.host}${req.originalUrl}`
);
res.redirect(
`https://id.marshub.uz/login?next=${back}`
);
};
if (!token) returntoLogin();
// Mars ID o'zi tekshiradi — kalit kerak emasconstr=awaitfetch(
'https://id.marshub.uz/api/verify',
{ headers: { Authorization: `Bearer ${token}` } }
);
if (!r.ok) returntoLogin();
req.user=awaitr.json(); // { id, name, role, tg }next();
}
app.get('/', requireAuth, (req, res) => {
res.send(`
<h1>Salom, ${req.user.name}!</h1>
<p>Role: ${req.user.role}</p>
<a href="https://id.marshub.uz/logout">
Chiqish
</a>
`);
});
app.listen(3000);
💡
Tokenni o'zingiz ochib ko'rmang./api/verify 200 qaytarsagina foydalanuvchi haqiqiy. Kim ekanligini faqat serverda aniqlang — brauzerdan kelgan role yoki id ga ishonmang.Не разбирай токен сам. Пользователь настоящий только если /api/verify ответил 200. Кто это — определяй только на сервере: role и id, присланные браузером, ничего не доказывают.
▶Python (Flask) da ham ko'ringПример на Python (Flask)
Avval o'rnatingСначала установи
$pip install flask requests
app.py
fromflaskimportFlask, request, redirect, gfromfunctoolsimportwrapsimportrequestsapp=Flask(__name__)
defrequire_auth(f):
@wraps(f)
defdecorated(*args, **kwargs):
token=request.cookies.get("__mars_id")
login=redirect(
f"https://id.marshub.uz/login"
f"?next={request.url}"
)
if nottoken:
returnlogin# Mars ID o'zi tekshiradi — kalit kerak emasr=requests.get(
"https://id.marshub.uz/api/verify",
headers={"Authorization": f"Bearer {token}"},
timeout=5,
)
if notr.ok:
returnloging.user=r.json() # { id, name, role, tg }returnf(*args, **kwargs)
returndecorated@app.route("/")
@require_authdefindex():
returnf"""
<h1>Salom, {g.user['name']}!</h1>
<p>Role: {g.user['role']}</p>
"""
Qo'shimchaБонус
Rollarni tekshirishПроверка ролей
Foydalanuvchining roli student, mentor yoki admin bo'lishi mumkin. Buni cheklash uchun:У пользователя роль student, mentor или admin. Чтобы ограничить доступ:
Rol tekshirishПроверка роли
// Faqat mentorlar va adminlar / Только менторы и админыfunctionrequireRole(...roles) {
return (req, res, next) => {
if (!roles.includes(req.user.role)) {
returnres.status(403).send('Ruxsat yo\'q');
}
next();
};
}
app.get('/admin',
requireAuth,
requireRole('mentor', 'admin'),
(req, res) =>res.send('Admin panel')
);
2-usul: OAuth2 / OIDCСпособ 2: OAuth2 / OIDC
Tashqi xizmatlar uchunДля внешних сервисов
Agar loyihangiz *.marshub.uz da emas — Mars ID ni OIDC Provider sifatida ishlatishingiz mumkin. Bu standart protokol, ko'pchilik freymvorklar qo'llab-quvvatlaydi.Если твой проект не на *.marshub.uz — используй Mars ID как OIDC Provider. Это стандартный протокол, который поддерживают большинство фреймворков.
1
Klientni ro'yxatdan o'tkazingЗарегистрируй клиент
Mars administratoriga murojaat qiling. Ular sizga client_id va client_secret berishadi.Обратись к администратору Mars. Он выдаст client_id и client_secret.
OIDC Discovery: ko'pchilik freymvorklar (Next-Auth, Django-Allauth, Passport.js) faqat https://id.marshub.uz issuer URL ni kiritishni talab qiladi — qolganini avtomatik topadi.OIDC Discovery: большинство фреймворков (Next-Auth, Django-Allauth, Passport.js) требуют только указать https://id.marshub.uz как issuer — остальное найдут автоматически.
Statik saytingiz bormi? Caddy server avtomatik himoyalaydi — bitta so'rov bilan.Есть статический сайт? Caddy защитит автоматически — одним запросом.
1
Saytni MarshHub ga deploy qilingЗадеплой сайт на MarshHub
npx marshub deploy
2
Administratorga yozingНапиши администратору
Sayt nomini va kirishi mumkin bo'lgan foydalanuvchilarning Telegram ID larini bering.Сообщи имя сайта и Telegram ID пользователей, которым нужен доступ.
3
Tayyor!Готово!
Endi ruxsatsiz foydalanuvchilar Mars ID login sahifasiga yo'naltiriladi.Теперь неавторизованные пользователи будут перенаправлены на страницу логина Mars ID.
🛡️
Forward Auth — Caddy har bir so'rovni tekshiradi: cookie bormi? Telegram ID ruxsat berilganlar ro'yxatidami? Agar yo'q — foydalanuvchini login sahifasiga yo'naltiradi.Forward Auth — Caddy проверяет каждый запрос: есть cookie? Telegram ID в списке доступа? Если нет — редирект на страницу логина.
DeployДеплой
MarshHub ga deploy qilishДеплой на MarshHub
Loyihangizni npx marshub deploy bilan bir buyruqda joylashtiring:Опубликуй проект одной командой через npx marshub deploy:
Birinchi marta? Avval npx marshub login buyrug'ini bajaring — Telegram orqali avtorizatsiya qilasiz. Keyin npx marshub deploy ishlaydi.Первый раз? Сначала выполни npx marshub login — авторизуешься через Telegram. После этого npx marshub deploy заработает.
DebuggingОтладка
Tekshirish va xatolarni topishПроверка и поиск ошибок
API
# Tokenni tekshirish / Проверить токен$curl -H "Authorization: Bearer TOKEN" \
https://id.marshub.uz/api/verify{"id":"...","name":"Aziz","role":"student","tg":123}# O'z ma'lumotlaringiz / Свои данные (нужна cookie)$curl -b "__mars_id=TOKEN" https://id.marshub.uz/api/me{"id":"...","name":"Aziz","role":"student","tg":123}# Health check$curl https://id.marshub.uz/health{"ok":true,"users":245}
FAQ
Ko'p beriladigan savollarЧастые вопросы
?
Nega AUTH_SECRET berilmaydi?Почему не дают AUTH_SECRET?
Bu kalit hamma xizmatlar uchun umumiy: u bilan istalgan foydalanuvchi — hatto adminning — tokenini yasash mumkin, va uni Mars pochtasi, Git, panellar ham qabul qiladi. Shuning uchun u faqat Mars ichki xizmatlarida qoladi. Sizga kerak emas: /api/verify hech qanday kalitsiz javob beradi.Этот ключ общий для всех сервисов: им можно подписать токен любого пользователя, включая админа, и такой токен примут почта Mars, Git, панели. Поэтому он остаётся только у внутренних сервисов Mars. Тебе он и не нужен: /api/verify отвечает без всякого ключа.
?
localhost da ishlayaptimi?Работает ли на localhost?
Cookie .marshub.uz domeniga o'rnatiladi, shuning uchun localhost da yo'q. Sinash uchun tokenni brauzerdan nusxalang (DevTools → Cookies) va Authorization: Bearer <token> sarlavhasi bilan yuboring. Doimiy ish uchun — OAuth2 (localhost callback bilan).Cookie ставится на домен .marshub.uz, поэтому на localhost её нет. Для пробы скопируй токен из браузера (DevTools → Cookies) и шли заголовком Authorization: Bearer <token>. Для постоянной разработки — OAuth2 с callback на localhost.
?
Token muddati qachon tugaydi?Когда истекает токен?
30 kundan keyin. jwt.verify() xato qaytaradi — foydalanuvchini login sahifasiga yo'naltiring, Mars ID yangi token beradi.Через 30 дней. jwt.verify() выбросит ошибку — перенаправь на логин, Mars ID выдаст новый токен.
?
JavaScript cookie ni o'qiy oladimi?Может ли JavaScript читать cookie?
Yo'q. __mars_id — httpOnly cookie. Faqat server tomonda ishlaydi. Bu XSS hujumlardan himoya.Нет. __mars_id — httpOnly cookie. Работает только на сервере. Это защита от XSS-атак.
Deploy oldidan checklistЧеклист перед деплоем
✓
Token /api/verify orqali tekshiriladi (umumiy kalitsiz)Токен проверяется через /api/verify (без общего ключа)
✓
Rol va huquqlar faqat serverda tekshiriladiРоль и права проверяются только на сервере
✓
Login ga redirect: ?next=URL bilanРедирект на логин: с ?next=URL
Rollar serverda tekshiriladi (frontendga ishonmang!)Роли проверяются на сервере (не доверяй фронтенду!)
🚀
Tayyor!Готово!
Endi sizning loyihangizda Mars ID avtorizatsiya ishlaydi. Foydalanuvchilar Telegram orqali kirishadi.Теперь в твоём проекте работает авторизация Mars ID. Пользователи входят через Telegram.