Logowanie przez TTAR

Jeśli prowadzisz stronę lub aplikację dla amatorów tenisa stołowego — klub, turnieje, treningi, sklep ze sprzętem — dodaj „Logowanie przez TTAR”. Zawodnicy zalogują się u ciebie swoim kontem TTAR jednym kliknięciem, tak jak przez Google czy Telegram, bez zakładania nowego loginu i hasła. A ty od razu wiesz, kto do ciebie przyszedł i jak mocno gra.

Co to daje twojemu serwisowi:

• Więcej rejestracji. Nie trzeba wypełniać formularza ani potwierdzać adresu e-mail: zawodnik loguje się swoim loginem TTAR, więc mniej osób porzuca rejestrację w połowie.
• Ranking zawodnika od razu. Razem z logowaniem dostajesz ranking TTAR: łatwo na jego podstawie rozstawić turniej, podzielić uczestników na grupy według siły gry, dobrać partnera do sparingu albo sprawdzić, czy ktoś może wziąć udział w zawodach.
• Nie musisz budować własnego logowania. Przechowywanie haseł, odzyskiwanie dostępu, logowanie przez Google i Telegram — to wszystko już działa w TTAR. Programistom wystarczy podłączyć standardowy protokół OpenID Connect, do którego są gotowe biblioteki dla wszystkich popularnych języków programowania.
• Bezpiecznie dla zawodników. Nigdy nie dostajesz hasła do TTAR: zawodnik wpisuje je wyłącznie na stronie TTAR. Przekazujemy ci tylko dane, o które poprosisz — ID zawodnika, imię i nazwisko, awatar, e-mail i ranking.

Poniżej znajdziesz opis techniczny. Tę stronę możesz od razu przekazać programistom.

Parametry serwera autoryzacji

Większości bibliotek OIDC wystarczy podać Issuer: pozostałe adresy odczytają z dokumentu 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

Rejestracja klienta

Każdy partner otrzymuje client_id. Sekret nie jest używany — obsługiwane jest wyłącznie PKCE (code_challenge_method=S256). Aby się zarejestrować, napisz do nas na kot@ttar.app.

Przy rejestracji podajesz jeden lub kilka adresów redirect_uri — adresów w twojej aplikacji, na które będziemy kierować użytkownika po autoryzacji. Dodajemy je do białej listy. W każdym żądaniu wskazujesz konkretny adres, a serwer sprawdza go z tą listą.

Dodatkowo możesz podać jeden lub kilka adresów post_logout_redirect_uri — dokąd odesłać użytkownika po wylogowaniu przez nasz end-session endpoint /connect/logout (zob. sekcję „Wylogowanie” poniżej). To osobna biała lista: redirect_uri nie jest akceptowany jako adres powrotu po wylogowaniu. Jest potrzebna tylko wtedy, gdy korzystasz z tego wylogowania.

Logowanie: Authorization Code + PKCE

Krok 1. Skieruj użytkownika do autoryzacji. Zbuduj link i otwórz go w przeglądarce użytkownika jako pełne przejście na stronę, nie w 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

Jeśli użytkownik nie jest jeszcze zalogowany do TTAR w tej przeglądarce, trafia na stronę logowania TTAR i się loguje. Jeśli aktywna sesja TTAR już istnieje, strona logowania jest pomijana, a kod wydawany od razu (single sign-on) — chyba że zażądasz ponownego logowania przez prompt=login. Opcjonalne parametry prompt i max_age opisano w sekcji „Ponowne logowanie i zmiana konta” poniżej.

Krok 2. Odbierz odpowiedź na redirect_uri. Po udanym logowaniu przeglądarka użytkownika zostaje automatycznie przekierowana na twój redirect_uri z dwoma parametrami:

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

• code — jednorazowy kod autoryzacji. Jest ważny około 60 sekund, użyj go od razu.
• state — ta sama wartość, którą przekazano w kroku 1. Koniecznie porównaj ją z wartością zapisaną u siebie: to ochrona przed CSRF.

Jeśli użytkownik odmówił lub wystąpił błąd, otrzymasz:

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

Krok 3. Wymień kod na tokeny. Na serwerze, nie w przeglądarce, wyślij POST z kodem z kroku 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

Odpowiedź:

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

• access_token — token Bearer do wywołań API, w tym /connect/userinfo. To JWT podpisany RS256.
• id_token — JWT z podstawowymi informacjami o użytkowniku: sub, imię i nazwisko, e-mail itd. Podpis koniecznie weryfikuj.
• refresh_token — pozwala pobierać nowe tokeny bez ponownego logowania. Jest wydawany tylko wtedy, gdy zażądano scope offline_access.

Krok 4. Odświeżaj tokeny. Gdy access token wygaśnie, pobierz nowe tokeny za pomocą refresh tokena:

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

Jeśli zażądano scope ttar:rating i zawodnik ma ranking, w access tokenie pojawia się claim ttar_rating. To tablica JSON z jednym obiektem na każdą rękę — główną i słabszą:

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

Pozostałe dane (imię i nazwisko, awatar, e-mail) są dostępne przez UserInfo endpoint /connect/userinfo lub w id_token.

Ponowne logowanie i zmiana konta

TTAR utrzymuje w przeglądarce użytkownika sesję single sign-on (SSO) — cookie w domenie TTAR API. Dopóki jest aktywna, /connect/authorize wydaje kod dla tego samego użytkownika TTAR, nie pokazując strony logowania. Ta sesja nie zależy od sesji twojej aplikacji: wylogowanie użytkownika z twojej aplikacji jej nie kończy.

• prompt=login — zawsze pokazuje stronę logowania TTAR i wymaga ponownego zalogowania, nawet przy aktywnej sesji: istniejąca sesja TTAR nie jest ponownie wykorzystywana. Użytkownik może zalogować się na inne konto TTAR. Zalecane przy powiązywaniu konta.
• prompt=select_account — działa tak samo jak prompt=login. W TTAR nie ma wyboru konta: użytkownik wybiera konto, logując się na nie.
• prompt=none — nigdy nie pokazuje interfejsu. Jeśli nie ma aktywnej sesji lub jest starsza niż max_age, użytkownik wraca na twój redirect_uri z error=login_required.
• prompt=consent — jest akceptowany i na nic nie wpływa: zarejestrowani partnerzy są zatwierdzeni z góry, w TTAR nie ma ekranu zgody.
• max_age=N — jeśli użytkownik logował się ponad N sekund temu, będzie musiał zalogować się ponownie. max_age=0 działa tak samo jak prompt=login.

Nieprawidłowy prompt (nieznana wartość albo none razem z inną wartością) TTAR odrzuca z HTTP 400 — przeglądarka nie wraca na twój redirect_uri.

Claim auth_time. W id_token jest auth_time — czas Unix w sekundach ostatniego interaktywnego logowania użytkownika do TTAR: e-mailem i hasłem, przez Google lub Telegram. Przy odświeżaniu tokenów się nie zmienia. Może go brakować tylko w sesjach TTAR rozpoczętych przed wprowadzeniem tej funkcji. Taka sesja nigdy nie spełnia warunków prompt=login ani max_age i zawsze jest zakładana od nowa, dlatego przy każdym z tych parametrów id_token na pewno zawiera auth_time.

Powiązanie konta TTAR:

1. Dodaj do żądania autoryzacji prompt=login i zapamiętaj moment rozpoczęcia żądania.
2. Po wymianie kodu sprawdź, czy auth_time nie jest wcześniejszy niż ten moment, z zapasem kilku sekund na rozbieżność zegarów. W ten sposób upewnisz się, że użytkownik rzeczywiście zalogował się w ramach tego żądania, a nie została ponownie wykorzystana istniejąca sesja.
3. Wiąż konta po sub — ID zawodnika w TTAR.

Aby użytkownik mógł powiązać inne konto TTAR, wylogowanie nie jest potrzebne — wystarczy prompt=login.

Wylogowanie

Wylogowanie użytkownika z twojej aplikacji nie kończy jego sesji TTAR. Jeśli chcesz zakończyć także ją w tej przeglądarce (np. „wyloguj wszędzie” albo komputer współdzielony), wyślij przeglądarkę użytkownika na end-session endpoint /connect/logout jako pełne przejście na stronę. XHR i iframe się nie nadają: cookie sesji należy do domeny 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 usuwa swoje cookie sesji i przekierowuje przeglądarkę na post_logout_redirect_uri, dołączając do niego state.
• post_logout_redirect_uri musi być wcześniej zarejestrowany. Dopasowanie jest dokładne, a to osobna lista, nie redirect_uri (zob. „Rejestracja klienta”). Przy niezarejestrowanym adresie TTAR odrzuca całe żądanie z HTTP 400 — i sesja nie zostaje zakończona.
• Bez post_logout_redirect_uri sesja zostaje zakończona, ale użytkownik nie wraca do twojej aplikacji.
• id_token_hint jest opcjonalny. Jeśli go przekazujesz, musi to być id_token wydany dla twojego client_id. Wygasły też się nada.
• Wylogowanie kończy sesję TTAR użytkownika w tej przeglądarce we wszystkich serwisach, w których podłączono „Logowanie przez TTAR”, a nie tylko w twoim.

Weryfikacja tokenów

Tokeny są podpisane RS256. Klucze publiczne są pod standardowym adresem JWKS:

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

Każda standardowa biblioteka OIDC pobierze je automatycznie przez discovery endpoint. Sprawdzaj:

• podpis: alg=RS256, klucz z JWKS;
• iss = https://stage.api.ttar.app;
• aud = twój client_id;
• exp: token nie wygasł;
• auth_time, jeśli używasz prompt=login lub max_age (zob. „Claim auth_time” wyżej).

Ważne dla stagingu

• Staging to środowisko testowe do twoich eksperymentów.
• Konto testowe udostępniamy osobno.
• Po przejściu na produkcję client_id pozostanie ten sam, zmieni się tylko Issuer — na https://api.ttar.app.