«Войти через Blyk» — сервер авторизации OAuth 2.0 (RFC 6749). Ваш сайт или
приложение отправляет человека на страницу Blyk, человек входит и
разрешает доступ, а вы получаете токен и по нему — профиль: id, имя, тег
и фото. Пароль от Blyk вашему приложению не достаётся никогда.
Что поддерживается
- Authorization Code (RFC 6749 §4.1) с PKCE (RFC 7636, только
S256) и обновление по refresh-токену (§6). Других потоков нет:
ни implicit, ни password, ни client credentials, ни device flow.
- Метаданные сервера — RFC 8414 (
/.well-known/oauth-authorization-server).
- Отзыв токенов — RFC 7009 (
/oauth/revoke).
- Профиль —
/oauth/userinfo по Bearer-токену (RFC 6750).
- Параметр
iss в ответе авторизации — RFC 9207.
- OpenID Connect не поддерживается: нет
id_token, нет
/.well-known/openid-configuration, нет JWKS и права openid. Токены —
непрозрачные строки, а не JWT: проверять их подпись нечем и незачем,
кто владелец токена — спрашивайте у /oauth/userinfo.
- Нет и эндпоинта интроспекции (RFC 7662), и динамической регистрации
клиентов (RFC 7591): приложения заводятся только вручную, в приложении Blyk.
Адреса
| что |
адрес |
издатель (issuer) |
https://gateway.blyk.chat |
| вход и согласие |
GET https://app.blyk.chat/oauth/authorize |
| токены |
POST https://gateway.blyk.chat/oauth/token |
| отзыв |
POST https://gateway.blyk.chat/oauth/revoke |
| профиль |
GET https://gateway.blyk.chat/oauth/userinfo |
| метаданные |
GET https://gateway.blyk.chat/.well-known/oauth-authorization-server |
Страница входа живёт в веб-приложении (app.blyk.chat), всё остальное — на
шлюзе (gateway.blyk.chat). Тестовый стенд — те же пути на
test-app.blyk.chat и test-gateway.blyk.chat; приложения и аккаунты у
стендов свои.
Регистрация приложения
Приложения заводятся только в веб-версии Blyk (app.blyk.chat): в
мобильных приложениях этих экранов нет.
- Откройте вкладку «Вы» → «Разработка» → «Мои приложения» и нажмите
«Создать приложение».
- Заполните, «как его увидят»: название (1–64 знака), описание
(необязательно, до 500 знаков), сайт (
https://…) и значок.
Название, значок и сайт человек увидит на экране «Войти через Blyk».
- Добавьте адреса возврата — от 1 до 10, каждый до 512 знаков.
Сравниваются они посимвольно, поэтому указывайте ровно тот адрес, который
будете передавать в
redirect_uri:
https:// — любой;
http:// — только на свой компьютер: localhost, 127.0.0.1,
[::1] (для разработки и настольных приложений). Порт — тоже часть
адреса: http://localhost:3000/cb и http://localhost:5173/cb —
разные адреса, зарегистрируйте нужные;
- своя схема мобильного приложения — только с точкой в имени, например
com.example.app:/oauth/cb (RFC 8252 §7.1);
- без
#фрагмента; javascript:, data:, file: и подобные запрещены.
- Выберите тип клиента — потом его не поменять:
- Конфиденциальный — для сайта со своим сервером: код обменивается
на токен с секретом, PKCE — по желанию (но мы советуем его всегда).
- Публичный — для SPA и мобильных приложений, где секрет не
спрятать: секрета нет, PKCE (
S256) обязателен.
- Нажмите «Сохранить». В разделе «Ключи» появятся
client_id (вида
blyk_ + 24 hex-знака) и — у конфиденциального клиента —
client_secret (blyk_cs_…). Секрет показывается один раз,
показать его снова нельзя. Потеряли — «Сгенерировать новый секрет»:
старый перестанет работать сразу.
У одного аккаунта — до 20 приложений. Удаление приложения необратимо: вход
перестаёт работать у всех, выданные токены гаснут сразу.
Поток входа по шагам
- Сгенерируйте случайные
state (защита от CSRF) и code_verifier
(PKCE), посчитайте code_challenge и сохраните state и
code_verifier у себя — в сессии сервера или в sessionStorage.
- Отправьте браузер на
https://app.blyk.chat/oauth/authorize?response_type=code&client_id=…&redirect_uri=…&scope=profile&state=…&code_challenge=…&code_challenge_method=S256.
- Человек входит в Blyk (если ещё не вошёл), выбирает аккаунт и видит
экран согласия: название и значок вашего приложения и список прав.
Если этот аккаунт уже давал вашему приложению те же права, экран
согласия не показывается — Blyk сразу возвращает человека к вам.
- Blyk возвращает браузер на
redirect_uri:
?code=blyk_ac_…&state=…&iss=https://gateway.blyk.chat — или
?error=access_denied&state=…&iss=…, если человек нажал «Отмена».
- Проверьте
state (совпадает с сохранённым) и iss (равен
https://gateway.blyk.chat). Не совпало — прервите вход.
- Обменяйте код на токены:
POST /oauth/token с
grant_type=authorization_code, code, тем же redirect_uri и
code_verifier. У кода 60 секунд и одна попытка.
- Узнайте, кто вошёл:
GET /oauth/userinfo с
Authorization: Bearer <access_token>. Привязывайте аккаунт к полю
sub — оно постоянно; имя и тег человек может сменить.
- Обновляйте access-токен по
refresh_token, когда он истекает (через
час), — POST /oauth/token с grant_type=refresh_token. Каждый раз
сохраняйте новый refresh-токен.
- При выходе отзовите refresh-токен:
POST /oauth/revoke.
Когда человек впервые разрешает вашему приложению вход (или даёт новые
права), Blyk пишет ему об этом в служебный чат — со ссылкой на
«Подключённые приложения», где доступ можно отозвать.
PKCE
PKCE (RFC 7636) не даёт воспользоваться перехваченным кодом: обменять код
может только тот, кто знает code_verifier, а в адресе ходит лишь его
хеш — code_challenge.
code_verifier — 43–128 знаков из A–Z a–z 0–9 - . _ ~, криптостойко
случайный.
code_challenge = BASE64URL(SHA256(code_verifier)) без = — от
сырых 32 байт хеша, ровно 43 знака. Не hex-строка и не base64 от hex.
code_challenge_method — только S256. plain не принимается ни от
кого.
- Публичному клиенту PKCE обязателен, конфиденциальному — по желанию. Но
если
code_challenge был в запросе авторизации, code_verifier обязан
быть при обмене; и наоборот — code_verifier без code_challenge
отвергается (invalid_grant).
// Браузер или Node 18+: Web Crypto.
function base64url(bytes) {
let s = '';
for (const b of new Uint8Array(bytes)) s += String.fromCharCode(b);
return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}
// 32 случайных байта → 43 знака base64url.
const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
const challenge = base64url(
await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier)),
);
const state = base64url(crypto.getRandomValues(new Uint8Array(16)));
То же в shell:
VERIFIER=$(openssl rand -base64 48 | tr '+/' '-_' | tr -d '=\n')
CHALLENGE=$(printf %s "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=\n')
Права (scope)
| право |
что даёт |
profile |
id, имя, тег и фото профиля (/oauth/userinfo). Чаты, контакты и почта остаются закрыты. |
Сейчас право одно. scope — список через пробел; не передан или пуст —
profile. Неизвестное право — invalid_scope. Согласие запоминается
объединением: разрешив однажды больше, человек не увидит экран согласия,
когда попросят меньше.
Сроки и пределы
| что |
значение |
| код авторизации |
60 секунд, одноразовый |
| access-токен |
1 час (expires_in: 3600) |
| refresh-токен |
30 дней с момента выдачи; каждое обновление выдаёт новый на те же 30 дней |
picture в профиле |
подписанная ссылка, живёт сутки |
| метаданные |
кешируются на 5 минут (Cache-Control: public, max-age=300) |
тело запроса к /oauth/token, /oauth/revoke |
до 16 КБ |
state |
до 1024 знаков |
| приложений на аккаунт |
20 |
| адресов возврата у приложения |
1–10, каждый до 512 знаков |
Префиксы делают токены Blyk узнаваемыми в журналах и для сканеров утечек:
blyk_ac_ — код, blyk_at_ — access, blyk_rt_ — refresh, blyk_cs_ —
секрет клиента. Длину и устройство остальной части не закладывайте в код.
Ротация refresh-токенов и защита от повторов
- Каждое обновление гасит предъявленный refresh-токен и выдаёт новую пару.
- Предъявить уже использованный refresh-токен — признак кражи: Blyk
отвечает
invalid_grant и отзывает всю цепочку — все access- и
refresh-токены, выданные по этому входу, включая самые свежие. Человеку
придётся войти заново.
- Два одновременных обновления одним refresh-токеном выглядят так же, как
повтор: одно пройдёт, второе погасит цепочку. Обновляйте токен строго
по одному (очередь или блокировка на пользователя).
- Код авторизации, предъявленный второй раз, тоже отзывает всё, что по
нему уже выдано.
Токены перестают работать и тогда, когда человек отключил ваше приложение
(«Разработка» → «Подключённые приложения»), удалил аккаунт или был
заблокирован, а также при удалении приложения.
Безопасность
- Всегда передавайте и проверяйте
state; проверяйте iss в ответе
авторизации.
- Используйте PKCE и в конфиденциальном клиенте.
- Секрет клиента — только на сервере. Не кладите его в SPA, мобильное
приложение или репозиторий; утёк — сгенерируйте новый.
- Храните токены как пароли: на сервере, в зашифрованном хранилище или в
защищённом хранилище ОС. Ответы с токенами приходят с
Cache-Control: no-store.
- Страницу входа нельзя открыть внутри
<iframe> (защита от
clickjacking): используйте переход на всю страницу или всплывающее окно.
/oauth/token, /oauth/revoke, /oauth/userinfo и метаданные отвечают
с Access-Control-Allow-Origin: * и не читают куки: публичный клиент
может обменивать код прямо из браузера.
- Access-токен в адресе (
?access_token=) не принимается — только в
заголовке Authorization или в теле POST.
Ошибки
Ошибки — по RFC 6749 §5.2 и RFC 6750 §3: JSON {"error": "<код>"}. Поля
error_description нет: код и HTTP-статус — всё, что говорит сервер. На
/oauth/authorize ошибка приходит параметрами адреса возврата.
| код |
HTTP |
когда |
invalid_request |
400 |
нет обязательного параметра, параметр передан дважды, секрет и в Authorization, и в теле, не тот HTTP-метод (тогда 405); на /authorize — нет response_type, нет PKCE у публичного клиента, метод не S256, code_challenge не 43 знака base64url, state длиннее 1024 |
invalid_client |
401 |
неизвестный client_id, неверный или отсутствующий секрет у конфиденциального клиента, секрет у публичного |
invalid_grant |
400 |
код или refresh-токен неизвестен, истёк, уже использован или выдан другому клиенту; redirect_uri или code_verifier не те; приложение отключено; аккаунт удалён или заблокирован |
unsupported_grant_type |
400 |
grant_type не authorization_code и не refresh_token |
invalid_scope |
400 |
неизвестное право; при обновлении — право шире выданного |
unsupported_response_type |
— |
/authorize: response_type не code |
access_denied |
— |
/authorize: человек нажал «Отмена» |
invalid_token |
401 |
/userinfo: токена нет, он истёк, отозван или неизвестен |
server_error |
500 |
сбой у Blyk |
temporarily_unavailable |
503 |
служба авторизации не ответила вовремя — повторите позже |
Если client_id неизвестен или redirect_uri не зарегистрирован, Blyk
не возвращает человека к вам (адрес не подтверждён) — ошибка
показывается на странице входа.