ვები

შესვლა TTAR-ით

ავტორიზაცია TTAR-ის ანგარიშით თქვენს საიტზე ან აპლიკაციაში: მოთამაშეები ერთი დაწკაპუნებით შედიან, თქვენ კი მაშინვე ხედავთ მათ რეიტინგს.

თუ მაგიდის ჩოგბურთის მოყვარულებისთვის გაქვთ საიტი ან აპლიკაცია — კლუბი, ტურნირები, ვარჯიშები თუ ინვენტარის მაღაზია — დაამატეთ „შესვლა TTAR-ით“. მოთამაშეები შეძლებენ, ერთი დაწკაპუნებით გაიარონ თქვენთან ავტორიზაცია თავიანთი TTAR-ის ანგარიშით — ისევე, როგორც Google-ით ან Telegram-ით, ახალი ლოგინისა და პაროლის გარეშე. თქვენ კი მაშინვე გაიგებთ, ვინ მოვიდა თქვენთან და რამდენად ძლიერი მოთამაშეა.

რას მოუტანს ეს თქვენს სერვისს:

მეტი რეგისტრაცია. აღარ არის საჭირო ანკეტის შევსება და ელფოსტის დადასტურება: მოთამაშე თავისი TTAR-ის ლოგინით შედის, ამიტომ ნაკლები ადამიანი მიატოვებს რეგისტრაციას შუა გზაზე.
მოთამაშის რეიტინგი — მაშინვე. ავტორიზაციასთან ერთად TTAR-ის რეიტინგსაც იღებთ: მის მიხედვით მოსახერხებელია ტურნირზე მოთამაშეების განთესვა, მონაწილეების დონის მიხედვით ჯგუფებად დაყოფა, სპარინგ-პარტნიორის შერჩევა ან შეჯიბრებაზე დაშვების შემოწმება.
საკუთარი ავტორიზაცია არ დაგჭირდებათ. პაროლების შენახვა, წვდომის აღდგენა, შესვლა Google-ითა და Telegram-ით — ეს ყველაფერი TTAR-ში უკვე მუშაობს. დეველოპერებს მხოლოდ სტანდარტული OpenID Connect პროტოკოლის ინტეგრაცია დასჭირდებათ, რისთვისაც პროგრამირების ყველა პოპულარულ ენაზე არსებობს მზა ბიბლიოთეკები.
უსაფრთხოა მოთამაშეებისთვის. TTAR-ის პაროლს თქვენ არასოდეს იღებთ: მოთამაშე მას მხოლოდ TTAR-ის გვერდზე შეიყვანს. თქვენ გადმოგეცემათ მხოლოდ ის მონაცემები, რომლებიც მოითხოვეთ — მოთამაშის ID, სახელი და ავატარი, email და რეიტინგი.

როგორ დავაკავშიროთ

პარტნიორობა მარტივი და უფასოა: მოგვწერეთ მისამართზე kot@ttar.app და მოგვიყევით თქვენი სერვისის შესახებ — ჩვენ მოგაწვდით ყველაფერს, რაც დასაკავშირებლად გჭირდებათ. თქვენს მოთამაშეებს ეკრანი „დაუშვებთ წვდომას?“ არ გამოუჩნდებათ: პარტნიორებს ჩვენ თავად ვაკავშირებთ, ამიტომ ისინი წინასწარ არიან დამტკიცებული.

ქვემოთ მოცემულია ტექნიკური აღწერა. ეს გვერდი შეგიძლიათ პირდაპირ გადასცეთ დეველოპერებს.

ავტორიზაციის სერვერის პარამეტრები

OIDC-ბიბლიოთეკების უმეტესობისთვის საკმარისია Issuer-ის მითითება: დანარჩენ მისამართებს ისინი discovery document-იდან წაიკითხავენ.

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-ს. Client secret არ გამოიყენება — მხარდაჭერილია მხოლოდ 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 — იგივე მნიშვნელობა, რომელიც პირველ ნაბიჯში გადასცით. აუცილებლად შეადარეთ იგი თქვენთან შენახულს: ეს CSRF-ისგან დაცვაა.

თუ მომხმარებელმა უარი თქვა ან შეცდომა მოხდა, მიიღებთ:

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

ნაბიჯი 3. გაცვალეთ კოდი ტოკენებზე. სერვერიდან და არა ბრაუზერიდან გაგზავნეთ POST-მოთხოვნა მეორე ნაბიჯში მიღებული კოდით:

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

მნიშვნელოვანია

redirect_uri აქ უნდა ემთხვეოდეს პირველ ნაბიჯში გადაცემულს: სერვერი მას დამატებითი შემოწმებისთვის იყენებს.

პასუხი:

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

access_token — Bearer ტოკენი API-ზე მოთხოვნებისთვის, მათ შორის /connect/userinfo-ზე. ეს არის RS256-ით ხელმოწერილი JWT.
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

Scope	რას აბრუნებს
`openid`	`sub` (მოთამაშის ID TTAR-ში). სავალდებულოა.
`profile`	`name`, `picture` (ავატარის URL)
`email`	`email`, `email_verified`
`offline_access`	ამატებს `refresh_token`-ს token endpoint-ის `/connect/token` პასუხში. ამ scope-ის გარეშე refresh token არ გაიცემა.
`ttar:rating`	Claim `ttar_rating` access token-ში — მოთამაშის რეიტინგების მასივი (იხ. ქვემოთ).

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 — მომხმარებლის TTAR-ში ბოლო ინტერაქტიული შესვლის Unix-დრო წამებში: email-ითა და პაროლით, Google-ით ან Telegram-ით. ტოკენების განახლებისას ის არ იცვლება. ის შეიძლება მხოლოდ იმ TTAR-ის სესიებს აკლდეს, რომლებიც ამ ფუნქციის გამოჩენამდე დაიწყო. ასეთი სესია არასოდეს აკმაყოფილებს არც prompt=login-ს, არც max_age-ს და ყოველთვის ხელახლა იქმნება, ამიტომ ამ პარამეტრებიდან რომელიმეს გამოყენებისას id_token აუცილებლად შეიცავს auth_time-ს.

TTAR-ის ანგარიშის მიბმა:

ავტორიზაციის მოთხოვნას დაამატეთ prompt=login და დაიმახსოვრეთ მომენტი, როცა ის დაიწყეთ.
კოდის გაცვლის შემდეგ შეამოწმეთ, რომ auth_time ამ მომენტზე ადრე არ არის, საათების აცდენისთვის რამდენიმე წამის მარაგით. ასე დარწმუნდებით, რომ მომხმარებელი მართლაც ამ მოთხოვნის ფარგლებში შევიდა და არსებული სესია ხელახლა არ იქნა გამოყენებული.
ანგარიში მიაბით sub-ის მიხედვით — ეს მოთამაშის ID-ია TTAR-ში.

შენიშვნა

Google-ით შესვლისას თავად Google-მა შეიძლება პაროლი არ მოითხოვოს, თუ მომხმარებელი ამ ბრაუზერში Google-ში უკვე შესულია. TTAR-ისთვის ეს მაინც ახალი ინტერაქტიული შესვლაა და auth_time მას ასახავს.

იმისათვის, რომ მომხმარებელმა 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 სატესტო გარემოა თქვენი ექსპერიმენტებისთვის.
სატესტო ანგარიში ცალკე გადმოგეცემათ.
Production-ზე გადასვლის შემდეგ client_id იგივე დარჩება, შეიცვლება მხოლოდ Issuer: ის გახდება https://api.ttar.app.