StaticGram Login
StaticGram Login позволяет сайту или приложению авторизовать пользователя его аккаунтом StaticGram. Пользователь подтверждает вход в приложении StaticGram или по номеру телефона, а сайт получает его id, имя, username, аватар и, если пользователь согласится, номер телефона. Провайдер входа работает на https://oauth.staticgram.top.
Вход всегда привязан к боту. Бот выступает OIDC-клиентом: Client ID равен id бота, адреса сайта регистрируются в @BotFather. Есть три способа подключения:
| Способ | Что получает сайт | Когда выбирать |
|---|---|---|
Виджет staticgram-widget.js | поля id, first_name, …, hash (классический формат) или id_token | готовая кнопка «Войти через StaticGram», минимум кода |
JS SDK staticgram-login.js | id_token (JWT), по желанию также классические поля | своя кнопка, запрос телефона и права писать от бота |
| OpenID Connect (authorization code + PKCE) | id_token через серверный обмен кода | серверная авторизация, готовые OIDC-библиотеки, нативные приложения |
Кроме того, бот может отправить пользователю кнопку login_url: вход на сайт по нажатию в чате, без виджета.
Адреса
| Назначение | Адрес |
|---|---|
Issuer (iss) | https://oauth.staticgram.top |
| Discovery | https://oauth.staticgram.top/.well-known/openid-configuration |
| Ключи подписи (JWKS) | https://oauth.staticgram.top/.well-known/jwks.json |
| Авторизация (страница входа) | GET https://oauth.staticgram.top/auth |
| Обмен кода | POST https://oauth.staticgram.top/token |
| Проверка сессии | POST https://oauth.staticgram.top/introspect |
| Виджет | https://oauth.staticgram.top/staticgram-widget.js (также https://staticgram.top/js/staticgram-widget.js) |
| JS SDK | https://oauth.staticgram.top/staticgram-login.js (также https://staticgram.top/js/staticgram-login.js) |
Раньше провайдер входа работал на https://staticgram.top (/auth, /token и т.д.). Эти адреса сохранены для совместимости, но в новом коде используйте oauth.staticgram.top. Проверяйте iss по значению issuer из discovery: в новых токенах это https://oauth.staticgram.top.
Настройка бота в @BotFather
- Создайте бота (
/newbot) или возьмите существующего. - Отправьте
/setloginи выберите бота. При первом запуске BotFather включит вход и пришлёт Client ID (это id бота) и Client Secret. Секрет показывается один раз, сохраните его. Сервер хранит только хеш, восстановить секрет нельзя, можно только выпустить новый. - В том же диалоге зарегистрируйте адреса командами (по одной или до 32 строк в одном сообщении) и закончите
/done. Изменения применяются сразу,/cancelзакрывает диалог без отката уже применённых команд.
add origin https://example.com
add redirect https://example.com/auth/callback
add ios com.example.app ABCDE12345 exampleapp://sglogin Example iOS App
add android com.example.app AA:BB:...:FF exampleapp://staticgram-login Example Android App
remove origin https://example.com
remove redirect https://example.com/auth/callback
remove app 12
algorithm RS256|ES256|EdDSA|ES256K
enable
disable| Команда | Значение |
|---|---|
add origin <origin> | Origin сайта (https://host[:port] без пути), на котором работают виджет, JS SDK и кнопки login_url. Сравнивается точно: https://example.com и https://www.example.com регистрируются отдельно. |
add redirect <url> | Точный адрес возврата для серверного OIDC (redirect_uri). Без логина/пароля и фрагмента, без параметров code, state, error, error_description в query. Пустой путь приводится к /, порт 443 отбрасывается, хост переводится в нижний регистр. |
add ios <bundle_id> <team_id> <callback> <название> | Нативное iOS-приложение: Bundle ID, 10-символьный Team ID, адрес возврата и отображаемое название (до 128 символов). См. Нативные приложения. |
add android <package> <sha256> <callback> <название> | Android-приложение: имя пакета и SHA-256 отпечаток сертификата подписи (64 hex-символа, двоеточия допускаются). |
remove origin|redirect <url>, remove app <id> | Удаление адреса или приложения (номер приложения есть в /logininfo). |
algorithm <alg> | Алгоритм подписи новых id_token. По умолчанию RS256. Сейчас на сервере есть ключи для RS256, ES256 и EdDSA (список в id_token_signing_alg_values_supported); ES256K принимается командой, но без ключа BotFather ответит, что алгоритм недоступен. С EdDSA (и ES256K) разрешён только scope openid, то есть без профиля и телефона. |
enable / disable | Включить или выключить вход. После disable новые запросы отклоняются, а незавершённые нельзя подтвердить или обменять. |
Остальные команды:
/logininfo: Client ID, статус, алгоритм подписи, версия секрета, зарегистрированные адреса и приложения./resetloginsecret: выпустить новый Client Secret. Старый перестаёт действовать сразу, новый показывается один раз.
Адреса http:// на сервере не принимаются. Для локальной разработки используйте туннель с HTTPS.
Как пользователь входит
Виджет, JS SDK и серверный OIDC ведут пользователя на страницу входа https://oauth.staticgram.top/auth. Заголовок страницы: «Вход на {домен}», под ним «{имя бота} запрашивает доступ через StaticGram». Войти можно тремя способами.
- На телефоне. Кнопка «Открыть StaticGram» открывает приложение сразу на окне подтверждения. Пользователь нажимает «Разрешить», и страница завершает вход сама.
- На компьютере, по номеру. Пользователь вводит номер телефона StaticGram в международном формате (
+888…,+1…и т.д.). Если номер зарегистрирован, от официального аккаунта StaticGram приходит сообщение «Запрос на вход на {домен} ({бот}) с IP …, страна, браузер …» с кнопками «Подтвердить» и «Отклонить». После подтверждения страница входит автоматически. Запрос можно подтвердить и в окне подтверждения приложения. - По QR-коду. Кнопка «Показать QR-код» выводит код, который сканируют камерой телефона или сканером в StaticGram; дальше подтверждение как на телефоне.
- Страница не сообщает, существует ли введённый номер: ответ одинаковый в обоих случаях.
- Запрос на вход действует 5 минут и одноразовый. Частота запросов ограничена по IP и по номеру телефона.
- В окне подтверждения пользователь видит бота, домен (или приложение), браузер, платформу, IP и страну устройства, с которого начат вход. Если запрошены телефон или право писать от бота, их можно разрешить или не разрешить отдельно.
- Каждый подтверждённый вход попадает в Настройки → Устройства (раздел «Активные сайты»): домен, бот, браузер, платформа, IP, регион, дата входа. Там вход можно завершить по одному или все сразу. Сайт узнаёт об этом через /introspect (
authorization_active: false), а кнопкиlogin_urlснова потребуют подтверждения.
Виджет: кнопка «Войти через StaticGram»
Вставьте скрипт в то место страницы, где должна появиться кнопка. Скрипт добавит после себя обычную кнопку <button> (не iframe) с логотипом StaticGram и текстом «Войти через StaticGram» (на английском «Log in with StaticGram»), а по нажатию откроет окно входа.
<script async src="https://oauth.staticgram.top/staticgram-widget.js"
data-staticgram-login="example_bot"
data-size="large"
data-radius="10"
data-request-access="write"
data-onauth="onStaticGramAuth(user)"></script>
<script>
function onStaticGramAuth(user) {
// user: {id, first_name, last_name, username, photo_url, auth_date, hash}
// Отправьте объект на сервер и проверьте hash (см. ниже).
fetch("/login/staticgram", {method: "POST", headers: {"content-type": "application/json"}, body: JSON.stringify(user)});
}
</script>Вместо callback можно указать адрес, на который браузер перейдёт с данными в query-строке (GET):
<script async src="https://oauth.staticgram.top/staticgram-widget.js"
data-staticgram-login="example_bot"
data-auth-url="/login/staticgram"></script>
<!-- переход на /login/staticgram?id=…&first_name=…&auth_date=…&hash=… -->Атрибуты
| Атрибут | Значение |
|---|---|
data-staticgram-login | Username бота без @. Скрипт сам узнаёт Client ID через POST /staticgram-widget/resolve; это сработает, только если origin страницы зарегистрирован у бота (add origin). Нужен этот атрибут или data-client-id. |
data-client-id | Client ID (id бота). Без data-auth-url включает режим OIDC: callback получает {id_token, user}. |
data-onauth | Глобальная функция, например onStaticGramAuth(user), onStaticGramAuth или app.auth.done(user). Произвольный JavaScript не выполняется. |
data-auth-url | Адрес для перехода с классическими полями в query. Должен быть на том же origin, что и страница (относительный путь или полный адрес своего сайта), иначе кнопка не сработает. |
data-legacy | 1 или 0: принудительно включить или выключить классический формат. По умолчанию классический формат включён, если нет data-client-id или задан data-auth-url. |
data-request-access | write: попросить у пользователя разрешение на сообщения от бота (scope staticgram:bot_access). Другие значения игнорируются; телефон через виджет не запрашивается, используйте JS SDK. |
data-size | small, medium или large (по умолчанию). |
data-radius | Скругление углов в пикселях, 0-64 (по умолчанию 8). |
data-lang | Язык кнопки: ru (по умолчанию, «Войти через StaticGram») или en («Log in with StaticGram»). |
Атрибута data-userpic нет; кнопку можно дооформить своим CSS. Если вход не удался, кнопка снова становится активной, а причина видна в её подсказке (title). В классическом режиме callback при ошибке не вызывается; в режиме OIDC он получает {error: "…"}.
Данные пользователя в классическом формате
| Поле | Тип | Описание |
|---|---|---|
id | Integer | id пользователя StaticGram |
first_name | String | имя, есть всегда |
last_name | String | фамилия, если указана |
username | String | username, если есть |
photo_url | String | публичная ссылка на аватар; есть, только если у пользователя есть и фото, и username |
auth_date | Integer | Unix-время подтверждения входа |
hash | String | подпись, см. следующий раздел |
Отсутствующие поля в объект не попадают. У объекта, переданного в data-onauth, есть ещё неперечисляемое свойство id_token (JWT того же входа): в Object.keys и JSON.stringify оно не видно, поэтому код, который строит строку проверки из всех ключей объекта, продолжает работать.
Проверка авторизации (hash)
Классические данные StaticGram подписаны токеном бота. Проверяйте их только на сервере:
data_check_string: все полученные поля, кромеhash, в видеkey=value, отсортированные по ключу и соединённые символом\n(0x0A). Например:auth_date=1760000000\nfirst_name=Anna\nid=1780244143\nusername=anna.secret_key = SHA256(bot_token): именно SHA-256 от токена бота (сырые 32 байта), а не HMAC с"WebAppData", как в Mini Apps.- Подпись верна, если
hex(HMAC_SHA256(key=secret_key, msg=data_check_string))совпадает сhash. Сравнивайте за постоянное время. - Проверьте свежесть
auth_date: например, отклоняйте данные старше суток, а для чувствительных действий старше нескольких минут. Сама подпись не устаревает.
Подпись зависит от текущего токена бота: после смены токена (/revoke в @BotFather) проверяйте новым токеном. Для кнопок login_url подпись делается токеном бота, указанного в кнопке. В примерах токен берётся из переменной окружения STATICGRAM_BOT_TOKEN.
import hashlib, hmac, os, time
STATICGRAM_BOT_TOKEN = os.environ["STATICGRAM_BOT_TOKEN"]
def verify_staticgram_auth(data: dict, bot_token: str = STATICGRAM_BOT_TOKEN,
max_age: int = 86400) -> dict:
data = {k: str(v) for k, v in data.items()}
received = data.pop("hash", "")
check_string = "\n".join(f"{k}={data[k]}" for k in sorted(data))
secret = hashlib.sha256(bot_token.encode()).digest()
expected = hmac.new(secret, check_string.encode(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, received):
raise ValueError("bad hash")
if time.time() - int(data["auth_date"]) > max_age:
raise ValueError("auth_date is too old")
return dataimport crypto from "node:crypto";
export function verifyStaticGramAuth(data, botToken = process.env.STATICGRAM_BOT_TOKEN, maxAge = 86400) {
const { hash = "", ...fields } = data;
const checkString = Object.keys(fields).sort()
.map((k) => `${k}=${fields[k]}`).join("\n");
const secret = crypto.createHash("sha256").update(botToken).digest();
const expected = crypto.createHmac("sha256", secret).update(checkString).digest("hex");
const a = Buffer.from(expected), b = Buffer.from(String(hash));
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) throw new Error("bad hash");
if (Date.now() / 1000 - Number(fields.auth_date) > maxAge) throw new Error("auth_date is too old");
return fields;
}function verifyStaticGramAuth(array $data, string $botToken, int $maxAge = 86400): array {
$hash = (string)($data['hash'] ?? '');
unset($data['hash']);
ksort($data, SORT_STRING);
$lines = [];
foreach ($data as $key => $value) {
$lines[] = $key . '=' . $value;
}
$secret = hash('sha256', $botToken, true);
$expected = hash_hmac('sha256', implode("\n", $lines), $secret);
if (!hash_equals($expected, $hash)) {
throw new Exception('bad hash');
}
if (time() - (int)$data['auth_date'] > $maxAge) {
throw new Exception('auth_date is too old');
}
return $data;
}
// $user = verifyStaticGramAuth($_GET, getenv('STATICGRAM_BOT_TOKEN'));import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"errors"
"net/url"
"sort"
"strconv"
"strings"
"time"
)
// botToken: os.Getenv("STATICGRAM_BOT_TOKEN")
func VerifyStaticGramAuth(q url.Values, botToken string, maxAge time.Duration) error {
keys := make([]string, 0, len(q))
for k := range q {
if k != "hash" {
keys = append(keys, k)
}
}
sort.Strings(keys)
lines := make([]string, len(keys))
for i, k := range keys {
lines[i] = k + "=" + q.Get(k)
}
secret := sha256.Sum256([]byte(botToken))
mac := hmac.New(sha256.New, secret[:])
mac.Write([]byte(strings.Join(lines, "\n")))
expected := hex.EncodeToString(mac.Sum(nil))
if !hmac.Equal([]byte(expected), []byte(q.Get("hash"))) {
return errors.New("bad hash")
}
authDate, err := strconv.ParseInt(q.Get("auth_date"), 10, 64)
if err != nil || time.Since(time.Unix(authDate, 0)) > maxAge {
return errors.New("auth_date is too old")
}
return nil
}JS SDK: staticgram-login.js
SDK даёт программный интерфейс StaticGram.Login и всегда возвращает подписанный id_token. Подключение:
<script src="https://oauth.staticgram.top/staticgram-login.js"></script>
<button id="login">Войти через StaticGram</button>
<script>
StaticGram.Login.init({client_id: 1780244143, request_access: ["phone", "write"]}, function (data) {
if (data.error) { console.warn(data.error); return; }
// data.id_token: JWT, отправьте на сервер и проверьте подпись (см. «Проверка id_token»)
// data.user: расшифрованный payload без проверки подписи, только для интерфейса
fetch("/login/oidc", {method: "POST", headers: {"content-type": "application/json"},
body: JSON.stringify({id_token: data.id_token})});
});
document.getElementById("login").onclick = function () { StaticGram.Login.open(); };
</script>Методы
| Метод | Описание |
|---|---|
StaticGram.Login.init(options, callback) | Сохраняет параметры и callback. Сам вход не начинает. |
StaticGram.Login.open([callback]) | Открывает окно входа с параметрами из init. Вызывайте из обработчика клика, иначе браузер заблокирует всплывающее окно. |
StaticGram.Login.auth(options, callback) | То же без предварительного init. |
StaticGram.Login.close() | Закрывает окно; callback получит {error: "popup_closed"}. |
Элементы с классом sg-auth-button вызывают StaticGram.Login.open() по клику. Инициализировать SDK можно атрибутами самого скрипта: data-client-id, data-request-access="phone write", data-lang, data-onauth="onAuth(data)" (строго в форме имяФункции(data)).
<script src="https://oauth.staticgram.top/staticgram-login.js"
data-client-id="1780244143"
data-request-access="phone write"
data-onauth="onAuth(data)"></script>
<button class="sg-auth-button">Войти через StaticGram</button>Параметры (options)
| Поле | Описание |
|---|---|
client_id | Обязательно. Client ID (id бота). |
request_access | Массив дополнительных прав: phone (номер телефона), write (бот сможет писать пользователю). Используется, если не задан scope; к нему всегда добавляются openid profile. |
scope | Явный список scope (строка через пробел или массив): openid, profile, phone, staticgram:bot_access (синоним write). openid добавляется автоматически. |
nonce | Строка до 1024 символов, сгенерированная вашим сервером. Вернётся в claim nonce; сверяйте её, чтобы токен нельзя было подставить из другого входа. |
legacy | true: дополнительно вернуть классические поля в data.auth_data (см. «Проверка авторизации»). |
lang | Зарезервировано для языка интерфейса; страница входа сейчас всегда на русском. |
Результат
Успех: {id_token, user, auth_data?}, где user это payload токена (claims из раздела Claims), auth_data есть только при legacy: true. Ошибка: {error}. Возможные значения:
error | Причина |
|---|---|
access_denied | пользователь отклонил вход |
temporarily_unavailable | запрос истёк (5 минут) или сервер перегружен |
popup_blocked, popup_closed | окно заблокировано браузером или закрыто до подтверждения |
login_in_progress | вход уже идёт |
not_initialized | open() без init() |
invalid_request, invalid_scope | неверные параметры запроса. Если origin страницы не зарегистрирован или вход для бота выключен, окно показывает страницу ошибки, а callback получит popup_closed, когда пользователь его закроет |
Как проходит вход во всплывающем окне
- SDK открывает окно 550×650 с
/auth?client_id=…&redirect_uri=<origin+путь страницы>&response_type=post_message&scope=…. Origin страницы должен быть зарегистрирован командойadd origin; регистрироватьredirectдля этого режима не нужно. - Окно показывает страницу входа: кнопку «Открыть StaticGram» (ссылка
sg://oauth?token=…), вход по номеру телефона и QR-код (см. Как пользователь входит). - Пользователь подтверждает вход в приложении или кнопкой «Подтвердить» в сообщении от StaticGram.
- Окно передаёт результат странице через
postMessageстрого на зарегистрированный origin и закрывается. Если браузер потерял связь с окном (мобильные браузеры), страница сама опрашивает/auth/status; ответ доступен только этому origin.
Если страница с SDK открыта как Mini App внутри StaticGram, SDK не открывает окно, а просит подтверждение прямо в приложении. Origin Mini App тоже должен быть зарегистрирован как origin.
OpenID Connect (серверный поток)
Стандартный authorization code flow с обязательным PKCE (S256). Все параметры берутся из discovery, поэтому подойдёт любая OIDC-библиотека, умеющая PKCE: укажите issuer https://oauth.staticgram.top, Client ID, Client Secret и redirect URI, зарегистрированный командой add redirect. В примерах ниже Client ID и Client Secret берутся из переменных окружения STATICGRAM_CLIENT_ID и STATICGRAM_CLIENT_SECRET.
{
"issuer": "https://oauth.staticgram.top",
"authorization_endpoint": "https://oauth.staticgram.top/auth",
"token_endpoint": "https://oauth.staticgram.top/token",
"jwks_uri": "https://oauth.staticgram.top/.well-known/jwks.json",
"scopes_supported": ["openid", "profile", "phone", "staticgram:bot_access"],
"response_types_supported": ["code"],
"response_modes_supported": ["query"],
"grant_types_supported": ["authorization_code"],
"subject_types_supported": ["public"],
"id_token_signing_alg_values_supported": ["RS256", "ES256", "EdDSA"],
"token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"],
"claims_supported": ["iss", "aud", "sub", "iat", "exp", "nonce", "id", "name", "given_name",
"family_name", "preferred_username", "picture", "phone_number", "phone_number_verified"],
"code_challenge_methods_supported": ["S256"],
"introspection_endpoint": "https://oauth.staticgram.top/introspect",
"introspection_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"]
}userinfo_endpoint нет: все данные пользователя приходят в id_token. Refresh-токенов нет.
Scopes
| Scope | Что даёт |
|---|---|
openid | Обязателен. sub (id пользователя) и служебные claims. |
profile | id, name, given_name, family_name, preferred_username, picture. |
phone | phone_number и phone_number_verified, если пользователь согласился поделиться номером на экране подтверждения. Если не согласился, вход всё равно проходит, но без этих claims. |
staticgram:bot_access | Просьба разрешить боту писать пользователю. Пользователь может снять галочку; claim об этом не выдаётся, проверяйте результатом отправки сообщения ботом. В запросе можно писать write. |
В scope от 1 до 4 значений без повторов. Если бот подписывает токены EdDSA, допустим только openid.
1. Запрос авторизации
Сгенерируйте state, nonce и code_verifier (43-128 символов A-Z a-z 0-9 - . _ ~), сохраните их в сессии и отправьте пользователя на:
https://oauth.staticgram.top/auth?client_id=1780244143
&redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fcallback
&response_type=code
&scope=openid%20profile%20phone
&state=af0ifjsldkj
&nonce=n-0S6_WzA2Mj
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256| Параметр | Описание |
|---|---|
client_id | Обязательно. Client ID. |
redirect_uri | Обязательно. Должен совпасть с зарегистрированным redirect после нормализации. |
response_type | Обязательно, code. |
scope | Обязательно, через пробел, с openid. |
code_challenge, code_challenge_method | Обязательно. BASE64URL(SHA256(code_verifier)) без =; метод только S256. |
state | Рекомендуется (защита от CSRF), до 2048 символов. Возвращается без изменений. |
nonce | Рекомендуется, до 1024 символов. Попадает в claim nonce. |
Каждый параметр передаётся не больше одного раза. Пользователь видит страницу «Вход на example.com» (см. Как пользователь входит). Запрос действует 5 минут. После подтверждения страница перенаправит браузер на:
https://example.com/auth/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkjПри отказе или ошибке вместо code придёт error (и state): access_denied (пользователь отклонил), temporarily_unavailable (запрос истёк), invalid_request, invalid_scope, unsupported_response_type, server_error. Если неверны сами client_id или redirect_uri, редиректа не будет: сервер покажет страницу с ошибкой (HTTP 400), чтобы не стать открытым редиректом.
2. Обмен кода на токены
Код одноразовый и живёт 2 минуты. Обменяйте его с сервера запросом application/x-www-form-urlencoded. Клиент аутентифицируется одним способом: заголовком Authorization: Basic base64(client_id:client_secret) (client_secret_basic) или полями client_id и client_secret в теле (client_secret_post); оба сразу нельзя.
curl -s https://oauth.staticgram.top/token \
-u "$STATICGRAM_CLIENT_ID:$STATICGRAM_CLIENT_SECRET" \
-d grant_type=authorization_code \
-d code="$CODE" \
-d redirect_uri=https://example.com/auth/callback \
-d code_verifier="$CODE_VERIFIER"{
"access_token": "q0v1…",
"token_type": "Bearer",
"expires_in": 3600,
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6…"
}access_token выдаётся для совместимости с библиотеками, но ни к одному API не подходит: используйте id_token. Ошибки: 401 invalid_client (неверный Client ID/Secret или вход выключен), 400 invalid_grant (код неверный, истёк, уже использован, не совпали redirect_uri или PKCE), 400 unsupported_grant_type, 400 invalid_request. Лимит: 60 запросов в минуту на IP и на клиента.
3. Проверка id_token
id_token это JWT. Перед тем как доверять данным, проверьте:
- подпись ключом из JWKS (
https://oauth.staticgram.top/.well-known/jwks.json) поkidиз заголовка; алгоритм (RS256,ES256илиEdDSA) задан в @BotFather для бота, принимайте только его. JWKS кэшируется на 5 минут; при неизвестномkidперечитайте набор ключей; issравенhttps://oauth.staticgram.top;audсодержит ваш Client ID (в токене это массив из одного элемента);expне прошёл (токен живёт 1 час),iatразумный;nonceсовпадает с отправленным.
| Claim | Scope | Описание |
|---|---|---|
iss, aud, iat, exp | openid | стандартные |
sub | openid | id пользователя строкой, например "1780244143" |
nonce | openid | если был передан |
sid | openid | идентификатор этого входа (сессии) для /introspect |
id | profile | id пользователя числом |
name | profile | имя и фамилия |
given_name | profile | имя |
family_name | profile | фамилия, если указана |
preferred_username | profile | username без @, если есть |
picture | profile | ссылка на аватар, если у пользователя есть фото и username |
phone_number | phone | номер в международном формате без +, только цифры, например "79991234567" |
phone_number_verified | phone | всегда true, если номер передан |
Данные профиля фиксируются в момент подтверждения. Связывайте аккаунт по sub, а не по username или телефону.
import os
import jwt # pip install "pyjwt[crypto]"
STATICGRAM_ISSUER = "https://oauth.staticgram.top"
STATICGRAM_CLIENT_ID = os.environ["STATICGRAM_CLIENT_ID"] # id бота
jwks = jwt.PyJWKClient(STATICGRAM_ISSUER + "/.well-known/jwks.json")
def verify_staticgram_id_token(id_token: str, nonce: str | None = None) -> dict:
key = jwks.get_signing_key_from_jwt(id_token)
claims = jwt.decode(id_token, key, algorithms=["RS256"], # алгоритм вашего бота
audience=STATICGRAM_CLIENT_ID, issuer=STATICGRAM_ISSUER,
options={"require": ["exp", "iat", "sub"]})
if nonce is not None and claims.get("nonce") != nonce:
raise ValueError("nonce mismatch")
return claimsimport { createRemoteJWKSet, jwtVerify } from "jose";
const STATICGRAM_ISSUER = "https://oauth.staticgram.top";
const JWKS = createRemoteJWKSet(new URL(STATICGRAM_ISSUER + "/.well-known/jwks.json"));
export async function verifyStaticGramIdToken(idToken, nonce) {
const { payload } = await jwtVerify(idToken, JWKS, {
issuer: STATICGRAM_ISSUER,
audience: process.env.STATICGRAM_CLIENT_ID, // id бота
algorithms: ["RS256"], // алгоритм вашего бота
});
if (nonce !== undefined && payload.nonce !== nonce) throw new Error("nonce mismatch");
return payload;
}import (
"os"
"github.com/coreos/go-oidc/v3/oidc"
)
provider, err := oidc.NewProvider(ctx, "https://oauth.staticgram.top")
if err != nil {
return err
}
verifier := provider.Verifier(&oidc.Config{ClientID: os.Getenv("STATICGRAM_CLIENT_ID")})
token, err := verifier.Verify(ctx, rawIDToken) // подпись, iss, aud, exp
if err != nil {
return err
}
var claims struct {
Sub string `json:"sub"`
Name string `json:"name"`
Username string `json:"preferred_username"`
Nonce string `json:"nonce"`
}
err = token.Claims(&claims)Проверка активности входа: /introspect
Пользователь может в любой момент завершить вход на сайте в приложении (Настройки → Устройства). Чтобы узнать об этом, отправьте полученный id_token на /introspect с теми же способами аутентификации, что у /token (Client Secret обязателен):
curl -s https://oauth.staticgram.top/introspect \
-u "$STATICGRAM_CLIENT_ID:$STATICGRAM_CLIENT_SECRET" \
-d token="$ID_TOKEN"{
"active": true,
"authorization_active": true,
"client_id": "1780244143",
"sub": "1780244143",
"iss": "https://oauth.staticgram.top",
"token_type": "id_token",
"sid": "pQ0uVY4a8l2wO1dCkJ3XxA",
"iat": 1760000000,
"exp": 1760003600
}authorization_active: вход (поsid) ещё не отозван пользователем. Остаётся осмысленным и после истечения токена, поэтому по нему удобно продлевать или завершать сессию сайта.active:authorization_activeи токен не истёк (как в RFC 7662).- Для чужого, повреждённого или подделанного токена ответ
{"active": false}без остальных полей. Неверный Client Secret даёт401 invalid_client.
Работает для токенов из любого способа входа (виджет, JS SDK, OIDC). Лимит: 120 запросов в минуту на IP и 600 на клиента; проверяйте периодически (например, раз в несколько минут на активную сессию), а не на каждый запрос.
Кнопки login_url в боте
Бот может отправить inline-кнопку с LoginUrl: по нажатию пользователь подтверждает вход в приложении и открывает сайт уже авторизованным. На адрес из кнопки добавляются классические поля id, first_name, last_name, username, photo_url, auth_date, hash; проверка такая же, как для виджета, токеном бота из кнопки.
{"inline_keyboard": [[{"text": "Войти на сайт",
"login_url": {"url": "https://example.com/login", "request_write_access": true}}]]}- Origin адреса должен быть зарегистрирован у бота (
add origin), а вход включён; иначе отправка сообщения вернётBUTTON_URL_INVALIDилиBUTTON_INVALID. bot_usernameпозволяет авторизовать через другого бота; тогда origin регистрируется у него, и подпись делается его токеном.- Если у пользователя уже есть неотозванный вход на этот домен через этого бота с теми же правами, повторное нажатие пускает без подтверждения.
Нативные приложения
Для iOS и Android используется тот же authorization code + PKCE, но без Client Secret (публичный клиент, token_endpoint_auth_method=none). Готовых SDK нет, протокол простой:
- Зарегистрируйте приложение в
/setlogin:add ios <bundle_id> <team_id> <callback> <название>илиadd android <package> <sha256> <callback> <название>.callback: точная HTTPS-ссылка (universal/app link) или своя схема видаexampleapp://host, без query и фрагмента; служебные схемы самого мессенджера запрещены. - Запросите ссылку:
GET https://oauth.staticgram.top/crossapp?client_id=…&redirect_uri=<callback>&response_type=code&scope=openid%20profile&state=…&nonce=…&code_challenge=…&code_challenge_method=S256&ios_sdk=1(для Androidandroid_sdk=1). Ответ:{"url": "sg://oauth?token=…"}.openidдобавляется автоматически. - Откройте эту ссылку: запустится StaticGram, пользователь подтвердит вход, и приложение StaticGram откроет
<callback>?code=…&state=…. - Обменяйте код на
/tokenсclient_idв теле, безclient_secret, с тем жеredirect_uriиcode_verifier. Проверьтеid_tokenкак обычно.
Название приложения из регистрации показывается пользователю вместо домена только для ботов с галочкой верификации; для остальных показываются бот и идентификатор приложения.
Рекомендации по безопасности
- Проверяйте
hashили подписьid_tokenтолько на сервере.data.userиз JS SDK и параметры в адресе не доказывают ничего, пока подпись не проверена. - Храните токен бота и Client Secret только на сервере (например, в
STATICGRAM_BOT_TOKENиSTATICGRAM_CLIENT_SECRET). При утечке секрета выполните/resetloginsecret, при утечке токена бота/revoke. - Проверяйте
auth_date(классический формат) иexp,aud,iss,nonce(OIDC). Принимайте только алгоритм, выбранный для бота. - В серверном потоке всегда передавайте и сверяйте
state, хранитеcode_verifierв сессии пользователя. - Регистрируйте только нужные origin и точные redirect URI; удаляйте неиспользуемые. Ответы окна входа и
/auth/statusотдаются только зарегистрированному origin. - Периодически проверяйте
/introspectи завершайте сессию сайта, если пользователь отозвал вход. - Не встраивайте страницу входа во фрейм: она запрещает это (
frame-ancestors 'none').
Особенности и совместимость
- Настройка. Домены регистрируются в
/setlogin(add origin/add redirect). Без зарегистрированного origin не работают ни виджет, ни кнопкиlogin_url. - Виджет рисует собственную кнопку, а не iframe; нет
data-userpic, телефон через виджет не запрашивается (используйте JS SDK). - id_token: алгоритмы
RS256(по умолчанию),ES256,EdDSA; сEdDSAтолько scopeopenid.phone_numberбез знака+. Есть claimsidи эндпоинт/introspect. - Нет
userinfo_endpointи refresh-токенов;access_tokenни к чему не подходит. - Совместимость. Протокол совместим с распространёнными клиентами OpenID Connect; классический формат полей с
hashподдерживается для простых сайтов.