Вход через TTAR

Если у вас есть сайт или приложение для любителей настольного тенниса — клуб, турниры, тренировки, магазин инвентаря, — подключите «Вход через TTAR». Игроки смогут авторизоваться у вас своим аккаунтом TTAR в один клик, как через Google или Telegram, без нового логина и пароля. А вы сразу узнаете, кто к вам пришёл и насколько сильно он играет.

Что это даёт вашему сервису:

• Больше регистраций. Не нужно заполнять анкету и подтверждать почту: игрок входит своим логином TTAR, поэтому меньше людей бросают регистрацию на полпути.
• Рейтинг игрока сразу. Вместе с авторизацией вы получаете рейтинг TTAR: по нему удобно посеять турнир, разбить участников на группы по силе, подобрать спарринг-партнёра или проверить допуск к соревнованию.
• Своя авторизация не нужна. Хранение паролей, восстановление доступа, вход через Google и Telegram — всё это уже работает в TTAR. Разработчикам достаточно подключить стандартный протокол OpenID Connect, для него есть готовые библиотеки для всех популярных языков программирования.
• Безопасно для игроков. Пароль от TTAR вы никогда не получаете: игрок вводит его только на странице TTAR. Вам передаются только те данные, которые вы запросили, — ID игрока, имя и аватар, email и рейтинг.

Ниже — техническое описание. Эту страницу можно сразу передать разработчикам.

Параметры сервера авторизации

Большинству OIDC-библиотек достаточно указать Issuer: остальные адреса они прочитают из discovery-документа.

Issuer          https://stage.api.ttar.app
Discovery       https://stage.api.ttar.app/.well-known/openid-configuration
Authorization   https://stage.api.ttar.app/connect/authorize
Token           https://stage.api.ttar.app/connect/token
UserInfo        https://stage.api.ttar.app/connect/userinfo
End session     https://stage.api.ttar.app/connect/logout
JWKS            https://stage.api.ttar.app/.well-known/jwks

Регистрация клиента

Каждому партнёру выдаётся client_id. Секрет не используется — поддерживается только PKCE (code_challenge_method=S256). Чтобы зарегистрироваться, напишите нам на kot@ttar.app.

При регистрации вы сообщаете один или несколько redirect_uri — адресов в вашем приложении, куда мы будем отправлять пользователя после авторизации. Мы вносим их в белый список. В каждом запросе вы указываете конкретный адрес, и сервер сверяет его с этим списком.

Дополнительно можно сообщить один или несколько post_logout_redirect_uri — куда вернуть пользователя после выхода через наш end-session endpoint /connect/logout (см. раздел «Выход» ниже). Это отдельный белый список: redirect_uri в качестве адреса возврата после выхода не принимается. Он нужен, только если вы пользуетесь этим выходом.

Вход: Authorization Code + PKCE

Шаг 1. Отправьте пользователя на авторизацию. Сформируйте ссылку и откройте её в браузере пользователя полным переходом, не в iframe:

GET https://stage.api.ttar.app/connect/authorize
  ?client_id=YOUR_CLIENT_ID
  &response_type=code
  &redirect_uri=https://yourapp.com/callback
  &scope=openid profile email ttar:rating
  &code_challenge=BASE64URL(SHA256(code_verifier))
  &code_challenge_method=S256
  &state=RANDOM_OPAQUE_VALUE

Если пользователь ещё не вошёл в TTAR в этом браузере, он попадает на страницу входа TTAR и входит. Если активная сессия TTAR уже есть, страница входа пропускается и код выдаётся сразу (single sign-on) — если только вы не запросили повторный вход через prompt=login. Необязательные параметры prompt и max_age описаны в разделе «Повторный вход и смена аккаунта» ниже.

Шаг 2. Примите ответ на redirect_uri. После успешного входа браузер пользователя автоматически перенаправляется на ваш redirect_uri с двумя параметрами:

GET https://yourapp.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_OPAQUE_VALUE

• code — одноразовый код авторизации. Он живёт около 60 секунд, используйте его сразу.
• state — то же значение, что вы передали в шаге 1. Обязательно сверьте его с сохранённым у себя: это защита от CSRF.

Если пользователь отказал или произошла ошибка, придёт:

GET https://yourapp.com/callback?error=access_denied&error_description=...&state=...

Шаг 3. Обменяйте код на токены. На сервере, не в браузере, отправьте POST с кодом из шага 2:

POST https://stage.api.ttar.app/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&code=AUTHORIZATION_CODE
&redirect_uri=https://yourapp.com/callback
&code_verifier=YOUR_CODE_VERIFIER

Ответ:

{
  "access_token": "...",
  "id_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600
}

• access_token — Bearer-токен для обращения к API, включая /connect/userinfo. Это JWT, подписанный RS256.
• id_token — JWT с базовой информацией о пользователе: sub, имя, email и т. д. Подпись проверяйте обязательно.
• refresh_token — чтобы получать новые токены без повторного входа. Выдаётся, только если запрошен scope offline_access.

Шаг 4. Обновляйте токены. Когда access token истекает, получите новые токены по refresh token:

POST https://stage.api.ttar.app/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=YOUR_CLIENT_ID
&refresh_token=REFRESH_TOKEN

Scopes

Claim ttar_rating

Если запрошен scope ttar:rating и у игрока есть рейтинг, в access token появляется claim ttar_rating. Это JSON-массив, по одному объекту на каждую руку — основную и неосновную:

[
  {
    "handType": "Main",
    "rating": 1456,
    "games": 120,
    "qualificationPoints": 85,
    "isRated": true
  },
  {
    "handType": "Weak",
    "rating": 1102,
    "games": 15,
    "qualificationPoints": 10,
    "isRated": false
  }
]

Остальные данные (имя, аватар, email) доступны через UserInfo endpoint /connect/userinfo или в id_token.

Повторный вход и смена аккаунта

TTAR держит в браузере пользователя сессию single sign-on (SSO) — cookie на домене TTAR API. Пока она активна, /connect/authorize выдаёт код для того же пользователя TTAR, не показывая страницу входа. Эта сессия не зависит от сессии вашего приложения: выход пользователя из вашего приложения её не завершает.

• prompt=login — всегда показывает страницу входа TTAR и требует войти заново, даже при активной сессии: существующая сессия TTAR не переиспользуется. Пользователь может войти под другим аккаунтом TTAR. Рекомендуется для привязки аккаунта.
• prompt=select_account — то же, что prompt=login. Выбора аккаунта в TTAR нет: пользователь выбирает аккаунт, входя в него.
• prompt=none — никогда не показывает интерфейс. Если активной сессии нет или она старше max_age, пользователь возвращается на ваш redirect_uri с error=login_required.
• prompt=consent — принимается и ни на что не влияет: зарегистрированные партнёры одобрены заранее, экрана согласия в TTAR нет.
• max_age=N — если пользователь входил больше N секунд назад, ему придётся войти снова. max_age=0 — то же, что prompt=login.

Некорректный prompt (неизвестное значение или none вместе с другим значением) TTAR отклоняет с HTTP 400 — браузер не возвращается на ваш redirect_uri.

Claim auth_time. В id_token есть auth_time — Unix-время в секундах последнего интерактивного входа пользователя в TTAR: по email и паролю, через Google или Telegram. При обновлении токенов он не меняется. Отсутствовать он может только у сессий TTAR, начатых до появления этой функции. Такая сессия никогда не удовлетворяет prompt=login и max_age и всегда устанавливается заново, поэтому с любым из этих параметров id_token обязательно содержит auth_time.

Привязка аккаунта TTAR:

1. Добавьте в запрос авторизации prompt=login и запомните момент, когда вы его начали.
2. После обмена кода проверьте, что auth_time не раньше этого момента, с запасом в несколько секунд на расхождение часов. Так вы убедитесь, что пользователь действительно вошёл в рамках этого запроса, а не была переиспользована существующая сессия.
3. Привязывайте по sub — ID игрока в TTAR.

Чтобы пользователь мог привязать другой аккаунт TTAR, выход не нужен — достаточно prompt=login.

Выход

Выход пользователя из вашего приложения не завершает его сессию TTAR. Если нужно завершить и её в этом браузере (например, «выйти везде» или общий компьютер), отправьте браузер пользователя на end-session endpoint /connect/logout полным переходом страницы. XHR и iframe не подойдут: cookie сессии принадлежит домену TTAR.

GET https://stage.api.ttar.app/connect/logout
  ?client_id=YOUR_CLIENT_ID
  &post_logout_redirect_uri=https://yourapp.com/logged-out
  &state=RANDOM_OPAQUE_VALUE
  &id_token_hint=ID_TOKEN

• TTAR удаляет свою cookie сессии и перенаправляет браузер на post_logout_redirect_uri, добавив к нему state.
• post_logout_redirect_uri должен быть зарегистрирован заранее. Совпадение точное, и это отдельный список, не redirect_uri (см. «Регистрация клиента»). С незарегистрированным адресом TTAR отклоняет весь запрос с HTTP 400 — и сессия не завершается.
• Без post_logout_redirect_uri сессия завершается, но пользователь не возвращается в ваше приложение.
• id_token_hint необязателен. Если передаёте его, это должен быть id_token, выданный вашему client_id. Просроченный тоже подходит.
• Выход завершает сессию TTAR пользователя в этом браузере для всех сервисов, где подключён «Вход через TTAR», а не только для вашего.

Проверка токенов

Токены подписаны RS256. Публичные ключи — по стандартному адресу JWKS:

https://stage.api.ttar.app/.well-known/jwks

Любая стандартная OIDC-библиотека подхватит их автоматически через discovery endpoint. Проверяйте:

• подпись: alg=RS256, ключ из JWKS;
• iss = https://stage.api.ttar.app;
• aud = ваш client_id;
• exp: токен не истёк;
• auth_time, если вы используете prompt=login или max_age (см. «Claim auth_time» выше).

Важно для staging

• Staging — тестовая среда, для ваших экспериментов.
• Аккаунт для тестов предоставляется отдельно.
• После перехода на прод client_id останется тем же, изменится только Issuer — на https://api.ttar.app.