Подключение к Mallaev IDMallaev ID работает по стандарту OpenID Connect. Пакет @mallaev/id делает всё сам: PKCE, проверку подписи и сеанс сайта. Сайт никогда не видит пароль человека.
Вход через Mallaev ID на вашем сайте: приложение в кабинете, пакет из npm, три маршрута и кнопка.
Создайте приложение
Название, иконка, адрес сайта и куда вернуть человека после входа — обычно
Создать приложение/auth/callback. После подтверждения домена и проверки вы получите номер приложения и секрет.Свой продукт Mallaev?
Свои продукты администратор подключает на сервере ID скриптом
deploy/id-provider/add-product.sh— без приложения в кабинете и проверки домена. В коде добавьтеaccount: true: придут номер аккаунта, логин и права. Стороннему сайту с этой строкой Mallaev ID откажет.Установите пакет
npm install @mallaev/idЕсть типы TypeScript. Работает в Node.js 20+, Bun, Deno и на edge.
Добавьте ключи в окружение
MALLAEV_ID_CLIENT_ID=mid_… # номер приложения из кабинета MALLAEV_ID_CLIENT_SECRET=… # секрет — показывается один раз MALLAEV_ID_REDIRECT_URI=https://example.com/auth/callback MALLAEV_ID_SESSION_SECRET=… # 32+ случайных знаков: openssl rand -base64 48Готовый .env с вашими значениями кабинет показывает, когда выдаёт секрет.
Подключите вход
import { createMallaevId, createAuthRoutes } from '@mallaev/id'; const redirectUri = process.env.MALLAEV_ID_REDIRECT_URI!; export const mallaevId = createMallaevId({ clientId: process.env.MALLAEV_ID_CLIENT_ID!, clientSecret: process.env.MALLAEV_ID_CLIENT_SECRET, redirectUri, }); export const auth = createAuthRoutes({ client: mallaevId, secret: process.env.MALLAEV_ID_SESSION_SECRET!, redirectUri, });// app/auth/login/route.ts import { auth } from '@/lib/mallaev-id'; export const GET = auth.login; // app/auth/callback/route.ts import { auth } from '@/lib/mallaev-id'; export const GET = auth.callback; // app/auth/logout/route.ts import { auth } from '@/lib/mallaev-id'; export const POST = auth.logout;import { cookies } from 'next/headers'; import { redirect } from 'next/navigation'; import { auth } from '@/lib/mallaev-id'; const session = await auth.getSession((await cookies()).get(auth.cookieNames.session)?.value); if (!session) redirect('/auth/login?returnTo=/orders'); session.user.sub; // номер человека для вашего сайта session.user.email; // почта, если человек согласилсяМаршруты принимают стандартный Request и возвращают Response. mallaev-id.ts — как во вкладке Next.js.
import { Hono } from 'hono'; import { auth } from './mallaev-id'; const app = new Hono(); app.get('/auth/login', (c) => auth.login(c.req.raw)); app.get('/auth/callback', (c) => auth.callback(c.req.raw)); app.post('/auth/logout', (c) => auth.logout(c.req.raw)); app.get('/me', async (c) => { const session = await auth.getSession(c.req.raw); return session ? c.json(session.user) : c.redirect('/auth/login'); });import { mallaevId } from './mallaev-id.js'; // createMallaevId, как во вкладке Next.js app.get('/auth/login', async (req, res) => { const { url, transaction } = await mallaevId.startLogin({ returnTo: req.query.returnTo }); req.session.mallaevId = transaction; // express-session или своё хранилище res.redirect(url); }); app.get('/auth/callback', async (req, res) => { const back = `${req.protocol}://${req.get('host')}${req.originalUrl}`; const { user, returnTo } = await mallaevId.finishLogin(back, req.session.mallaevId); req.session.mallaevId = null; req.session.user = user; res.redirect(returnTo ?? '/'); });Если на сайте уже Auth.js — пакет не нужен, хватит провайдера OIDC.
// auth.ts — Auth.js (NextAuth v5) import NextAuth from 'next-auth'; export const { handlers, auth, signIn, signOut } = NextAuth({ providers: [ { id: 'mallaev-id', name: 'Mallaev ID', type: 'oidc', issuer: 'https://id.mallaev-dev.ru', clientId: process.env.MALLAEV_ID_CLIENT_ID, clientSecret: process.env.MALLAEV_ID_CLIENT_SECRET, checks: ['pkce', 'state', 'nonce'], idToken: false, // почта приходит из userinfo, а не из ID-токена authorization: { params: { scope: 'openid email' } }, }, ], }); // Адрес возврата в приложении: https://ваш-сайт/api/auth/callback/mallaev-idПодойдёт любая библиотека OpenID Connect: PHP, Python, Go, Java.
- Discovery
https://id.mallaev-dev.ru/.well-known/openid-configuration- Поток
- Authorization Code + PKCE S256, state и nonce
- Секрет
client_secret_basic- Данные
openid email— почта приходит из userinfo
Поставьте кнопку
import { MallaevIdButton } from '@mallaev/id/button'; <MallaevIdButton href="/auth/login" />Без React —
mallaevIdButtonHtml({ href: '/auth/login' })из@mallaev/id/buttonотдаёт ту же кнопку строкой HTML. Выход — обычная форма:<form action="/auth/logout" method="post">.Проверьте перед запуском
- Вход. Кнопка → экран Mallaev ID → возврат на сайт уже вошедшим.
- Возврат на нужную страницу. /auth/login?returnTo=/cart после входа открывает /cart.
- Отказ. «Отказать» на экране согласия возвращает с ?mallaev_id_error=access_denied — покажите понятное сообщение.
- Выход. Форма POST /auth/logout завершает сеанс на сайте.
- Тот же человек. При повторном входе user.sub не меняется — по нему и храните аккаунт на своей стороне.
Что получит сайт
user.sub- Постоянный номер человека для вашего сайта. Другие сайты видят другой номер — по нему людей не сопоставить.
user.email- Подтверждённая почта — если приложение её просит и человек согласился на экране согласия.
user.mfa- Вход подтверждён вторым фактором или ключом доступа.
user.authTime- Когда человек последний раз подтвердил себя в Mallaev ID.
Пароль, коды и второй фактор сайт не видит никогда.
Безопасность
- Пакет проверяет state, срок начатого входа, подпись ID-токена по ключам Mallaev ID, издателя, получателя и nonce.
- Сеанс сайта — запечатанная cookie (AES-256-GCM), HttpOnly, SameSite=Lax, Secure. По умолчанию живёт сутки.
- Секреты — только в окружении сервера. Новый секрет в кабинете сразу отменяет прежний.
- returnTo принимается только как путь этого же сайта — чужой адрес подставить нельзя.
Без пакета: протокол по шагам
- Создайте на сервере случайные state, nonce и code_verifier и сохраните их в короткой сессии браузера.
- Отправьте браузер на
/oidc/authorize: response_type=code, client_id, точный redirect_uri, scope=openid email, state, nonce, code_challenge=BASE64URL(SHA256(code_verifier)), code_challenge_method=S256. - При возврате сверьте state и обработайте error. Обменяйте code на сервере: POST
/oidc/tokenс code_verifier, аутентификация — client_secret_basic. - Проверьте ID-токен: подпись по JWKS (RS256), issuer, audience, exp, nonce. Почта — в
/oidc/userinfo. - Связывайте человека по паре issuer + sub, не по почте.
- Access-токен действует 5 минут. Refresh-токен одноразовый: новую пару сохраняйте сразу, повторное использование старого отзывает весь вход. При выходе отзовите токен через
/oidc/revoke.