Вход через Vymi ID

Vymi ID — провайдер OpenID Connect: один аккаунт для сервисов Vymi и приложений, которые подключили вход через него. Подойдёт любая библиотека OIDC, умеющая Authorization Code с PKCE.

Начало

  1. Откройте dash.vymi.app → Vymi ID → Приложения и создайте приложение.
  2. Выберите тип. С сервером — у приложения есть бэкенд, он хранит client secret и сам меняет код на токены. Без сервера — SPA или мобильное приложение: секрета нет, вход подтверждает только PKCE.
  3. Впишите redirect URI — адрес, куда Vymi ID вернёт пользователя с кодом. Он сверяется целиком: https, http только для localhost, своя схема (myapp://callback) — для нативных приложений.
  4. Подключите библиотеку OIDC к issuer https://id.vymi.app: остальные адреса она возьмёт из discovery.

Новое приложение получает тир 0: в него могут войти до 100 разных пользователей, доступны только openid и profile. Чтобы снять ограничения, отправьте приложение на проверку на вкладке «Проверка» — подробнее в разделе Scopes и тиры.

Адреса

Issuerhttps://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.appid.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 минут. Перед тем как пускать пользователя, проверьте:

  1. подпись — ключом из JWKS с тем же kid, alg = EdDSA;
  2. iss — ваш issuer (или один из двух, если используете и .ru);
  3. aud — ваш client_id;
  4. exp — не истёк;
  5. nonce — совпадает с отправленным.

Пользователя храните по sub: это UUID аккаунта Vymi, он не меняется. Имя и почта меняются, ключом они быть не должны.

ClaimScopeЗначение
subopenidUUID аккаунта
account_tieropenidfull — обычный аккаунт, guest — гостевой
preferred_username, nameprofileимя пользователя
pictureprofileадрес аватарки, если она есть
updated_atprofileкогда менялся профиль, unix-время
email, email_verifiedemailосновная почта аккаунта
steamidentities:steam{steamid64, persona_name, avatar_url, profile_url}, если Steam привязан
discordidentities:discord{id, username, global_name, avatar_url}, если Discord привязан

Scopes и тиры

Что приложение может запросить, задаётся на вкладке «OAuth2» и ограничено его тиром. Пользователь видит запрошенный доступ на экране согласия.

ScopeЧто даётС какого тира
openidвход и sub0
profileимя и аватарка0
emailпочта1
identities:steamпривязанный Steam1
identities:discordпривязанный Discord1
offline_accessrefresh-токен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": {} }
}

Приложение должно:

  1. проверить подпись, iss и aud так же, как у ID-токена;
  2. убедиться, что iat свежий (несколько минут), в events есть ключ http://schemas.openid.net/event/backchannel-logout, а nonce отсутствует — так logout_token не спутать с ID-токеном;
  3. завершить все сессии пользователя sub: sid Vymi ID не передаёт;
  4. ответить 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_scopescope неизвестен, не включён у приложения или недоступен его тиру
unsupported_response_typeresponse_type не code
access_deniedпользователь отказал на экране согласия
login_required, consent_requiredпри prompt=none нужен вход или согласие
invalid_clientневерный client_id или секрет (401)
invalid_grantкод истёк или уже использован, не сошёлся PKCE, refresh-токен отозван
unauthorized_clientприложению не разрешён этот grant
unsupported_grant_typegrant не поддерживается

Запросы к /oauth/* ограничены по частоте с одного IP; при превышении придёт 429 — повторите позже.