TTAR ile giriş

Masa tenisi severler için bir siteniz veya uygulamanız varsa (kulüp, turnuvalar, antrenmanlar, ekipman mağazası), «TTAR ile giriş» özelliğini bağlayın. Oyuncular Google veya Telegram gibi tek tıkla TTAR hesaplarıyla sizde oturum açabilir; yeni kullanıcı adı ve parola gerekmez. Siz de kimin geldiğini ve ne kadar güçlü oynadığını hemen öğrenirsiniz.

Bu, hizmetinize şunları sağlar:

• Daha çok kayıt. Form doldurmaya ve e-posta onaylamaya gerek yoktur: oyuncu TTAR kullanıcı adıyla girer, bu yüzden daha az kişi kaydı yarıda bırakır.
• Oyuncunun reytingi hemen elinizde. Yetkilendirmeyle birlikte TTAR reytingini alırsınız: turnuvada tohumlama yapmak, katılımcıları güce göre gruplara ayırmak, antrenman partneri bulmak veya yarışmaya katılım koşulunu denetlemek için kullanışlıdır.
• Kendi yetkilendirmenize gerek yok. Parola saklama, erişimi kurtarma, Google ve Telegram ile giriş; hepsi TTAR'da zaten çalışıyor. Geliştiricilerin standart OpenID Connect protokolünü bağlaması yeterlidir; tüm popüler programlama dilleri için hazır kütüphaneler vardır.
• Oyuncular için güvenli. TTAR parolasını asla almazsınız: oyuncu onu yalnızca TTAR sayfasında girer. Size yalnızca istediğiniz veriler iletilir: oyuncu kimliği, ad ve avatar, e-posta ve reyting.

Aşağıda teknik açıklama yer alıyor. Bu sayfa doğrudan geliştiricilere iletilebilir.

Yetkilendirme sunucusu parametreleri

Çoğu OIDC kütüphanesi için Issuer'ı belirtmek yeterlidir: diğer adresleri discovery belgesinden okurlar.

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

İstemci kaydı

Her ortağa bir client_id verilir. Gizli anahtar kullanılmaz; yalnızca PKCE desteklenir (code_challenge_method=S256). Kayıt olmak için kot@ttar.app adresine yazın.

Kayıt sırasında bir veya birkaç redirect_uri bildirirsiniz: yetkilendirmeden sonra kullanıcıyı göndereceğimiz, uygulamanızdaki adresler. Bunları beyaz listeye ekleriz. Her istekte belirli bir adres verirsiniz ve sunucu onu bu listeyle karşılaştırır.

Ek olarak bir veya birkaç post_logout_redirect_uri da bildirebilirsiniz: kullanıcı end-session endpoint'imiz /connect/logout üzerinden çıkış yaptıktan sonra nereye döndürüleceği (aşağıdaki «Çıkış» bölümüne bakın). Bu ayrı bir beyaz listedir: redirect_uri çıkıştan sonra dönüş adresi olarak kabul edilmez. Yalnızca bu çıkışı kullanıyorsanız gerekir.

Giriş: Authorization Code + PKCE

Adım 1. Kullanıcıyı yetkilendirmeye gönderin. Bir bağlantı oluşturun ve kullanıcının tarayıcısında iframe'de değil, tam sayfa geçişiyle açın:

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

Kullanıcı bu tarayıcıda henüz TTAR'a girmediyse TTAR giriş sayfasına düşer ve giriş yapar. Etkin bir TTAR oturumu varsa giriş sayfası atlanır ve kod hemen verilir (single sign-on); yalnızca prompt=login ile yeniden giriş istemediyseniz. İsteğe bağlı prompt ve max_age parametreleri aşağıdaki «Yeniden giriş ve hesap değiştirme» bölümünde açıklanmıştır.

Adım 2. redirect_uri üzerindeki yanıtı alın. Başarılı girişten sonra kullanıcının tarayıcısı otomatik olarak redirect_uri adresinize iki parametreyle yönlendirilir:

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

• code: tek kullanımlık yetkilendirme kodu. Yaklaşık 60 saniye geçerlidir, hemen kullanın.
• state: 1. adımda verdiğiniz değerin aynısı. Mutlaka kendi sakladığınızla karşılaştırın: bu, CSRF'ye karşı korumadır.

Kullanıcı reddederse veya bir hata oluşursa şu gelir:

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

Adım 3. Kodu token'larla değiştirin. Sunucuda, tarayıcıda değil, 2. adımdaki kodla bir POST gönderin:

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

Yanıt:

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

• access_token: /connect/userinfo dahil API'ye erişim için Bearer token. RS256 ile imzalanmış bir JWT'dir.
• id_token: kullanıcı hakkında temel bilgi içeren JWT: sub, ad, e-posta vb. İmzayı mutlaka doğrulayın.
• refresh_token: yeniden giriş yapmadan yeni token almak için. Yalnızca offline_access scope'u istenmişse verilir.

Adım 4. Token'ları yenileyin. Access token'ın süresi dolduğunda refresh token ile yeni token'lar alın:

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

Scope'lar

ttar_rating claim'i

ttar:rating scope'u istenmişse ve oyuncunun reytingi varsa access token'da ttar_rating claim'i belirir. Bu, her el için bir nesne içeren bir JSON dizisidir: ana ve yan el:

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

Diğer veriler (ad, avatar, e-posta) UserInfo endpoint'i /connect/userinfo üzerinden veya id_token içinde mevcuttur.

Yeniden giriş ve hesap değiştirme

TTAR, kullanıcının tarayıcısında bir single sign-on (SSO) oturumu tutar: TTAR API alan adındaki bir cookie. O etkin olduğu sürece /connect/authorize, giriş sayfasını göstermeden aynı TTAR kullanıcısı için kod verir. Bu oturum uygulamanızın oturumundan bağımsızdır: kullanıcının uygulamanızdan çıkması onu sonlandırmaz.

• prompt=login: etkin oturum olsa bile her zaman TTAR giriş sayfasını gösterir ve yeniden girmeyi ister: mevcut TTAR oturumu yeniden kullanılmaz. Kullanıcı başka bir TTAR hesabıyla girebilir. Hesap bağlama için önerilir.
• prompt=select_account: prompt=login ile aynıdır. TTAR'da hesap seçimi yoktur: kullanıcı, o hesaba girerek hesabı seçer.
• prompt=none: hiçbir zaman arayüz göstermez. Etkin oturum yoksa veya max_age'den eskiyse kullanıcı redirect_uri adresinize error=login_required ile döner.
• prompt=consent: kabul edilir ve hiçbir şeyi etkilemez: kayıtlı ortaklar önceden onaylıdır, TTAR'da onay ekranı yoktur.
• max_age=N: kullanıcı N saniyeden daha önce girdiyse yeniden girmesi gerekir. max_age=0, prompt=login ile aynıdır.

Geçersiz bir prompt (bilinmeyen değer veya başka bir değerle birlikte none) TTAR tarafından HTTP 400 ile reddedilir: tarayıcı redirect_uri adresinize dönmez.

auth_time claim'i. id_token içinde auth_time bulunur: kullanıcının TTAR'a son etkileşimli girişinin saniye cinsinden Unix zamanı (e-posta ve parola, Google veya Telegram ile). Token'lar yenilendiğinde değişmez. Yalnızca bu özellik gelmeden önce başlamış TTAR oturumlarında bulunmayabilir. Böyle bir oturum prompt=login ve max_age koşullarını asla karşılamaz ve her zaman yeniden kurulur; bu yüzden bu parametrelerden biriyle id_token mutlaka auth_time içerir.

TTAR hesabını bağlama:

1. Yetkilendirme isteğine prompt=login ekleyin ve başlattığınız anı not edin.
2. Kodu değiştirdikten sonra auth_time'ın bu andan önce olmadığını, saat farkı için birkaç saniyelik payla kontrol edin. Böylece kullanıcının gerçekten bu istek kapsamında girdiğinden, mevcut bir oturumun yeniden kullanılmadığından emin olursunuz.
3. sub ile bağlayın: TTAR'daki oyuncu kimliği.

Kullanıcının başka bir TTAR hesabı bağlayabilmesi için çıkış gerekmez; prompt=login yeterlidir.

Çıkış

Kullanıcının uygulamanızdan çıkışı TTAR oturumunu sonlandırmaz. Onu da bu tarayıcıda sonlandırmak gerekiyorsa (örneğin «her yerden çık» veya ortak bilgisayar), kullanıcının tarayıcısını end-session endpoint'i /connect/logout adresine tam sayfa geçişiyle gönderin. XHR ve iframe uygun değildir: oturum cookie'si TTAR alan adına aittir.

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 kendi oturum cookie'sini siler ve tarayıcıyı post_logout_redirect_uri adresine yönlendirir, ona state ekler.
• post_logout_redirect_uri önceden kayıtlı olmalıdır. Eşleşme tamdır ve bu ayrı bir listedir, redirect_uri değil («İstemci kaydı» bölümüne bakın). Kayıtsız bir adresle TTAR tüm isteği HTTP 400 ile reddeder; oturum da sonlanmaz.
• post_logout_redirect_uri olmadan oturum sonlanır, ancak kullanıcı uygulamanıza dönmez.
• id_token_hint isteğe bağlıdır. Verirseniz, client_id'nize verilmiş bir id_token olmalıdır. Süresi dolmuş olan da uygundur.
• Çıkış, kullanıcının bu tarayıcıdaki TTAR oturumunu, «TTAR ile giriş»in bağlı olduğu tüm hizmetler için sonlandırır, yalnızca sizinki için değil.

Token doğrulama

Token'lar RS256 ile imzalanır. Genel anahtarlar standart JWKS adresindedir:

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

Her standart OIDC kütüphanesi bunları discovery endpoint'i üzerinden otomatik alır. Şunları doğrulayın:

• imza: alg=RS256, anahtar JWKS'ten;
• iss = https://stage.api.ttar.app;
• aud = sizin client_id'niz;
• exp: token'ın süresi dolmamış;
• auth_time, prompt=login veya max_age kullanıyorsanız (yukarıdaki «auth_time claim'i»ne bakın).

Staging için önemli

• Staging bir test ortamıdır, denemeleriniz içindir.
• Test hesabı ayrıca sağlanır.
• Prod'a geçtikten sonra client_id aynı kalır, yalnızca Issuer değişir: https://api.ttar.app.