Вход через Vymi ID
Vymi ID — провайдер OpenID Connect: один аккаунт для сервисов Vymi и приложений, которые подключили вход через него. Подойдёт любая библиотека OIDC, умеющая Authorization Code с PKCE.
Начало
- Откройте dash.vymi.app → Vymi ID → Приложения и создайте приложение.
- Выберите тип. С сервером — у приложения есть бэкенд, он хранит client secret и сам меняет код на токены. Без сервера — SPA или мобильное приложение: секрета нет, вход подтверждает только PKCE.
- Впишите redirect URI — адрес, куда Vymi ID вернёт пользователя с кодом. Он сверяется целиком: https, http только для localhost, своя схема (
myapp://callback) — для нативных приложений. - Подключите библиотеку OIDC к issuer
https://id.vymi.app: остальные адреса она возьмёт из discovery.
Новое приложение получает тир 0: в него могут войти до 100 разных пользователей, доступны только openid и profile. Чтобы снять ограничения, отправьте приложение на проверку на вкладке «Проверка» — подробнее в разделе Scopes и тиры.
Адреса
| Issuer | https://id.vymi.app |
|---|---|
| Discovery | /.well-known/openid-configuration |
| Авторизация | GET /oauth/authorize |
| Токены | POST /oauth/token |
| Профиль | GET|POST /oauth/userinfo |
| Ключи (JWKS) | GET /oauth/jwks.json |
| Отзыв токена | POST /oauth/revoke (RFC 7009) |
| Проверка токена | POST /oauth/introspect (RFC 7662), только с секретом |
| Выход | GET|POST /oauth/logout |
Адреса указаны относительно issuer. Подпись токенов — EdDSA (Ed25519); ключи ротируются, поэтому берите их из JWKS по kid, а при незнакомом kid обновляйте JWKS.
id.vymi.app и id.vymi.ru
Vymi ID работает по двум адресам с общей базой аккаунтов и общими ключами подписи. Приложению нужен только id.vymi.app: куда отправить пользователя, Vymi ID решает сам по его IP. Вход из России проходит на id.vymi.ru, остальные остаются на id.vymi.app.
| id.vymi.app | id.vymi.ru | |
|---|---|---|
| Кто входит | IP не из России | IP из России |
| Регистрация и код из письма | любая почта | только российская почта |
| Вход через Steam и Discord | есть | нет, только привязка |
| Аккаунт без российской почты | — | войдёт паролем или Passkey и сначала привяжет российскую почту |
Так вход из России идёт только российскими способами, как требует статья 10 закона 149-ФЗ, и приложению не нужно ничего делать для этого. Что это значит для вас:
- и
issв redirect (RFC 9207), иissв ID-токене совпадают с адресом, к которому обратилось приложение, даже если сам вход прошёл на другом; - код меняйте на токены там же, где начали вход;
- сами экраны входа приложению не нужны: не встраивайте их во frame и не подставляйте адрес по своему определению страны — Vymi ID всё равно перенаправит;
logout_tokenподписывает экземпляр, на котором пользователь вышел, поэтому принимайте оба issuer —https://id.vymi.appиhttps://id.vymi.ru.
Страна по IP — геобаза IP Geolocation by DB-IP (CC BY 4.0).
Вход
Единственный поток — Authorization Code с PKCE (S256), он обязателен для всех приложений, в том числе с секретом. Implicit и пароль пользователя не поддерживаются.
Создайте случайный code_verifier (43–128 символов), сохраните его в сессии вместе с state и nonce и отправьте пользователя на:
https://id.vymi.app/oauth/authorize
?client_id=YOUR_CLIENT_ID
&redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fcallback
&response_type=code
&scope=openid%20profile
&state=RANDOM_STATE
&nonce=RANDOM_NONCE
&code_challenge=BASE64URL(SHA256(code_verifier))
&code_challenge_method=S256
| Параметр | Что это |
|---|---|
redirect_uri | Один из зарегистрированных, побайтно. Можно не передавать, если адрес у приложения один. |
scope | Через пробел, обязательно openid. Список — в разделе Scopes. |
state | Вернётся без изменений: сверьте его, чтобы отсечь CSRF. |
nonce | Попадёт в ID-токен: сверьте его, чтобы токен нельзя было подставить повторно. |
prompt |
none — без экранов: если пользователь не вошёл или не дал согласие, сразу вернётся ошибка login_required или consent_required;
login — войти заново, даже если сеанс есть;
consent — показать согласие ещё раз;
select_account — дать выбрать аккаунт;
create — сразу экран регистрации.
|
После входа Vymi ID вернёт пользователя на redirect_uri?code=…&state=…&iss=…. Код одноразовый и живёт 60 секунд. Если пользователь отказался, придёт error=access_denied.
Обмен кода на токены
С сервера, application/x-www-form-urlencoded. Приложение с секретом передаёт его через HTTP Basic (client_secret_basic) или в теле (client_secret_post); приложение без сервера — только client_id.
curl https://id.vymi.app/oauth/token \
-u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
-d grant_type=authorization_code \
-d code=CODE_FROM_REDIRECT \
-d redirect_uri=https://example.com/auth/callback \
-d code_verifier=CODE_VERIFIER
{
"access_token": "…",
"token_type": "Bearer",
"expires_in": 900,
"id_token": "eyJhbGciOiJFZERTQSIs…",
"refresh_token": "…",
"scope": "openid profile offline_access",
"iss": "https://id.vymi.app"
}
Access-токен непрозрачный и живёт 15 минут: им можно вызвать /oauth/userinfo с заголовком Authorization: Bearer …. refresh_token приходит только со scope offline_access.
ID-токен
JWT, подписанный EdDSA, живёт 15 минут. Перед тем как пускать пользователя, проверьте:
- подпись — ключом из JWKS с тем же
kid,alg=EdDSA; iss— ваш issuer (или один из двух, если используете и.ru);aud— ваш client_id;exp— не истёк;nonce— совпадает с отправленным.
Пользователя храните по sub: это UUID аккаунта Vymi, он не меняется. Имя и почта меняются, ключом они быть не должны.
| Claim | Scope | Значение |
|---|---|---|
sub | openid | UUID аккаунта |
account_tier | openid | full — обычный аккаунт, guest — гостевой |
preferred_username, name | profile | имя пользователя |
picture | profile | адрес аватарки, если она есть |
updated_at | profile | когда менялся профиль, unix-время |
email, email_verified | основная почта аккаунта | |
steam | identities:steam | {steamid64, persona_name, avatar_url, profile_url}, если Steam привязан |
discord | identities:discord | {id, username, global_name, avatar_url}, если Discord привязан |
Scopes и тиры
Что приложение может запросить, задаётся на вкладке «OAuth2» и ограничено его тиром. Пользователь видит запрошенный доступ на экране согласия.
| Scope | Что даёт | С какого тира |
|---|---|---|
openid | вход и sub | 0 |
profile | имя и аватарка | 0 |
email | почта | 1 |
identities:steam | привязанный Steam | 1 |
identities:discord | привязанный Discord | 1 |
offline_access | refresh-токен | 1 |
| Тир | Что значит |
|---|---|
| 0 · не проверено | Новое приложение. До 100 разных пользователей, согласие спрашивается при каждом входе, на экране — предупреждение. |
| 1 · проверено | Vymi убедился, что приложение бережёт данные и в нём нет грубых уязвимостей. Доступны все scopes, согласие запоминается. |
| 2 · верифицировано | Приложение, которому Vymi доверяет: значок на экране согласия. |
| 3 · Vymi | Сервисы Vymi и партнёров. Согласие не показывается. |
Перед заявкой на проверку заполните описание, сайт и хотя бы один redirect URI.
Refresh-токены
Со scope offline_access (тир 1 и выше) вместе с токенами приходит refresh_token на 30 дней. Новый access-токен:
curl https://id.vymi.app/oauth/token \
-u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
-d grant_type=refresh_token \
-d refresh_token=REFRESH_TOKEN
Каждое обновление выдаёт новый refresh-токен, а старый перестаёт работать — сохраняйте новый. Если старый токен предъявят повторно, Vymi ID сочтёт его украденным и отзовёт всю цепочку: пользователю придётся войти заново. Refresh-токены отзываются и тогда, когда пользователь завершает сеанс или выходит из приложения в кабинете.
Выход
Выход по кнопке в приложении
Завершите свою сессию и, если нужно выйти и из Vymi ID, отправьте пользователя на:
https://id.vymi.app/oauth/logout
?client_id=YOUR_CLIENT_ID
&post_logout_redirect_uri=https%3A%2F%2Fexample.com%2F
&state=RANDOM_STATE
post_logout_redirect_uri должен быть среди redirect URI приложения. Без него Vymi ID ответит 204 и никуда не вернёт.
Выход из кабинета Vymi ID (back-channel)
В кабинете id.vymi.app → Приложения пользователь видит, куда входил через Vymi ID, и может выйти из любого приложения. Vymi ID отзывает токены приложения и, если указан Back-channel logout URI (вкладка «OAuth2»), сообщает приложению по OpenID Connect Back-Channel Logout 1.0. Без этого адреса открытая сессия в приложении останется, и кабинет предупредит об этом пользователя.
Vymi ID отправляет один запрос сервер-сервер:
POST /auth/backchannel-logout HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
logout_token=eyJhbGciOiJFZERTQSIsInR5cCI6ImxvZ291dCtqd3Qi…
logout_token — JWT с заголовком typ: logout+jwt, подписан тем же ключом, что и ID-токены:
{
"iss": "https://id.vymi.app",
"aud": "YOUR_CLIENT_ID",
"sub": "dda83a0b-8adb-4c93-ac55-43992b60e7b9",
"iat": 1793300000,
"exp": 1793300120,
"jti": "5b0c2a3e-…",
"events": { "http://schemas.openid.net/event/backchannel-logout": {} }
}
Приложение должно:
- проверить подпись,
issиaudтак же, как у ID-токена; - убедиться, что
iatсвежий (несколько минут), вeventsесть ключhttp://schemas.openid.net/event/backchannel-logout, аnonceотсутствует — так logout_token не спутать с ID-токеном; - завершить все сессии пользователя
sub:sidVymi ID не передаёт; - ответить
200(или204) сCache-Control: no-store. На неверный токен —400.
Запрос отправляется один раз, ответа Vymi ID ждёт до 5 секунд и не следует редиректам. Адрес должен быть https и вести на публичный IP: localhost и внутренние сети не принимаются. Обработчик должен быть идемпотентным: повторный выход того же пользователя ничего не ломает.
Если сессии у вас в базе — удалите их по sub. Если сессия хранится в подписанной cookie, запомните время выхода для sub и отклоняйте cookie, выданные раньше него.
// Node.js, express + jose
const JWKS = createRemoteJWKSet(new URL('https://id.vymi.app/oauth/jwks.json'));
app.post('/auth/backchannel-logout', express.urlencoded({ extended: false }), async (req, res) => {
res.set('Cache-Control', 'no-store');
try {
const { payload } = await jwtVerify(req.body.logout_token, JWKS, {
issuer: ['https://id.vymi.app', 'https://id.vymi.ru'],
audience: process.env.VYMI_CLIENT_ID,
maxTokenAge: '5m',
});
const event = 'http://schemas.openid.net/event/backchannel-logout';
if (!payload.events?.[event] || payload.nonce !== undefined) return res.sendStatus(400);
await sessions.revokeAllForUser(payload.sub);
res.sendStatus(200);
} catch {
res.sendStatus(400);
}
});
Ошибки
Ошибки авторизации приходят в redirect как ?error=…&error_description=…&state=…, ошибки /oauth/token — JSON {"error", "error_description"}. Если client_id или redirect_uri неверны, Vymi ID не перенаправляет и показывает ошибку сам.
| Код | Когда |
|---|---|
invalid_request | не хватает параметра, нет PKCE, неверный redirect_uri или prompt |
invalid_scope | scope неизвестен, не включён у приложения или недоступен его тиру |
unsupported_response_type | response_type не code |
access_denied | пользователь отказал на экране согласия |
login_required, consent_required | при prompt=none нужен вход или согласие |
invalid_client | неверный client_id или секрет (401) |
invalid_grant | код истёк или уже использован, не сошёлся PKCE, refresh-токен отозван |
unauthorized_client | приложению не разрешён этот grant |
unsupported_grant_type | grant не поддерживается |
Запросы к /oauth/* ограничены по частоте с одного IP; при превышении придёт 429 — повторите позже.