Đăng nhập bằng TTAR

Nếu bạn vận hành một website hoặc ứng dụng cho người chơi bóng bàn — câu lạc bộ, giải đấu, huấn luyện, cửa hàng dụng cụ — hãy thêm “Đăng nhập bằng TTAR”. Người chơi sẽ có thể đăng nhập vào dịch vụ của bạn bằng tài khoản TTAR chỉ với một lần bấm, giống như với Google hay Telegram, không cần tên đăng nhập và mật khẩu mới. Và bạn biết ngay ai đã đến với mình và trình độ của họ mạnh đến đâu.

Dịch vụ của bạn nhận được gì:

• Nhiều lượt đăng ký hơn. Không phải điền biểu mẫu và không cần xác nhận email: người chơi đăng nhập bằng tài khoản TTAR, nên ít người bỏ dở giữa chừng khi đăng ký hơn.
• Có ngay rating của người chơi. Cùng với việc xác thực, bạn nhận được rating TTAR: dùng nó để xếp hạt giống cho giải đấu, chia người tham gia thành các bảng theo trình độ, tìm bạn tập hoặc kiểm tra điều kiện tham dự một cuộc thi.
• Không cần tự xây dựng hệ thống xác thực. Lưu trữ mật khẩu, khôi phục tài khoản, đăng nhập bằng Google và Telegram — TTAR đã lo hết. Lập trình viên của bạn chỉ cần kết nối giao thức OpenID Connect chuẩn, với các thư viện có sẵn cho mọi ngôn ngữ lập trình phổ biến.
• An toàn cho người chơi. Bạn không bao giờ nhận được mật khẩu TTAR: người chơi chỉ nhập mật khẩu trên trang của TTAR. Bạn chỉ nhận đúng dữ liệu đã yêu cầu — ID người chơi, tên và ảnh đại diện, email và rating.

Dưới đây là phần mô tả kỹ thuật. Bạn có thể chuyển trang này trực tiếp cho lập trình viên của mình.

Các endpoint của máy chủ xác thực

Hầu hết các thư viện OIDC chỉ cần Issuer: chúng đọc các địa chỉ còn lại từ tài liệu 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

Đăng ký client

Mỗi đối tác nhận được một client_id. Không có client secret — chỉ hỗ trợ PKCE (code_challenge_method=S256). Để đăng ký, hãy viết cho chúng tôi theo địa chỉ kot@ttar.app.

Khi đăng ký, bạn cung cấp một hoặc nhiều giá trị redirect_uri — các URL trong ứng dụng của bạn mà chúng tôi sẽ chuyển hướng người dùng đến sau khi xác thực. Chúng tôi thêm chúng vào danh sách cho phép. Trong mỗi yêu cầu, bạn chỉ định chính xác URI muốn dùng, và máy chủ đối chiếu nó với danh sách đó.

Tùy chọn, bạn cũng cung cấp một hoặc nhiều giá trị post_logout_redirect_uri — nơi chúng tôi đưa người dùng quay lại sau khi đăng xuất qua endpoint kết thúc phiên /connect/logout của chúng tôi (xem “Đăng xuất” bên dưới). Đây là một danh sách cho phép riêng biệt: redirect_uri không được chấp nhận làm đích sau đăng xuất. Bạn chỉ cần nó nếu dùng kiểu đăng xuất này.

Đăng nhập: Authorization Code + PKCE

Bước 1. Chuyển hướng người dùng đến authorization endpoint. Tạo URL dưới đây và điều hướng trình duyệt của người dùng đến đó bằng điều hướng toàn trang, không dùng 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

Nếu người dùng chưa đăng nhập TTAR trong trình duyệt này, họ sẽ thấy trang đăng nhập TTAR và đăng nhập. Nếu họ đã có phiên TTAR đang hoạt động, trang đăng nhập sẽ được bỏ qua và mã được cấp ngay (đăng nhập một lần) — trừ khi bạn yêu cầu đăng nhập mới bằng prompt=login. Các tham số tùy chọn prompt và max_age được mô tả trong “Xác thực lại và chuyển đổi tài khoản” bên dưới.

Bước 2. Nhận phản hồi tại redirect_uri của bạn. Sau khi đăng nhập thành công, trình duyệt tự động được chuyển hướng đến redirect_uri của bạn kèm hai tham số truy vấn:

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

• code — mã xác thực dùng một lần. Mã có hiệu lực khoảng 60 giây, vì vậy hãy đổi ngay.
• state — chính giá trị bạn đã gửi ở bước 1. Luôn kiểm tra nó khớp với giá trị bạn đã lưu phía mình: điều này bảo vệ khỏi CSRF.

Nếu người dùng từ chối truy cập hoặc xảy ra lỗi, bạn nhận được:

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

Bước 3. Đổi mã lấy token. Từ máy chủ của bạn, không phải từ trình duyệt, gửi một yêu cầu POST với mã từ bước 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

Phản hồi:

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

• access_token — Bearer token để gọi API, bao gồm /connect/userinfo. Đây là JWT được ký bằng RS256.
• id_token — JWT chứa danh tính cơ bản của người dùng: sub, tên, email, v.v. Hãy xác minh chữ ký của nó trước khi tin dùng.
• refresh_token — để lấy token mới mà không phải yêu cầu người dùng đăng nhập lại. Chỉ được cấp khi bạn yêu cầu scope offline_access.

Bước 4. Làm mới token. Khi access token hết hạn, hãy lấy token mới bằng 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

Scope

Claim ttar_rating

Khi yêu cầu ttar:rating và người chơi có rating, access token chứa claim ttar_rating. Đó là một mảng JSON với mỗi tay một phần tử — tay thuận và tay không thuận:

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

Các trường người dùng bổ sung (tên, ảnh đại diện, email) có sẵn từ UserInfo endpoint /connect/userinfo hoặc bên trong id_token.

Xác thực lại và chuyển đổi tài khoản

TTAR giữ một phiên đăng nhập một lần (SSO) trong trình duyệt của người dùng — một cookie trên miền API của TTAR. Khi phiên còn hoạt động, /connect/authorize trả về mã cho cùng người dùng TTAR mà không hiển thị trang đăng nhập. Phiên này độc lập với phiên của ứng dụng của bạn: đăng xuất người dùng khỏi ứng dụng của bạn không kết thúc nó.

• prompt=login — luôn hiển thị trang đăng nhập TTAR và buộc người dùng đăng nhập lại, ngay cả khi có phiên đang hoạt động: phiên TTAR hiện có không bao giờ được dùng lại. Người dùng có thể đăng nhập bằng tài khoản TTAR khác. Khuyến nghị cho việc liên kết tài khoản.
• prompt=select_account — giống prompt=login. TTAR không có bộ chọn tài khoản: người dùng chọn tài khoản bằng cách đăng nhập với nó.
• prompt=none — không bao giờ hiển thị giao diện nào. Nếu không có phiên đang hoạt động, hoặc phiên cũ hơn max_age, người dùng được gửi lại redirect_uri của bạn kèm error=login_required.
• prompt=consent — được chấp nhận, không có tác dụng: các đối tác đã đăng ký được phê duyệt trước, TTAR không hiển thị màn hình đồng ý.
• max_age=N — nếu người dùng đã đăng nhập cách đây hơn N giây, họ phải đăng nhập lại. max_age=0 tương đương prompt=login.

prompt không hợp lệ (giá trị không xác định, hoặc none kết hợp với giá trị khác) bị từ chối với HTTP 400 ở phía TTAR — trình duyệt không được chuyển hướng ngược về redirect_uri của bạn.

Claim auth_time. id_token chứa auth_time — thời gian Unix tính bằng giây của lần đăng nhập tương tác gần nhất của người dùng vào TTAR: email và mật khẩu, Google hoặc Telegram. Giá trị này không đổi khi làm mới token. Nó chỉ có thể thiếu đối với các phiên TTAR bắt đầu trước khi tính năng này được phát hành. Phiên như vậy không bao giờ thỏa mãn prompt=login hay max_age và luôn được thiết lập lại, nên khi bạn gửi một trong hai tham số, id_token luôn chứa auth_time.

Liên kết tài khoản TTAR:

1. Thêm prompt=login vào yêu cầu xác thực và ghi nhớ thời điểm bạn bắt đầu.
2. Sau khi đổi mã, hãy kiểm tra rằng auth_time không sớm hơn thời điểm đó, cho phép lệch đồng hồ vài giây. Điều này xác nhận người dùng thực sự đã đăng nhập trong yêu cầu này, chứ không phải một phiên có sẵn được dùng lại.
3. Liên kết theo sub — ID người chơi TTAR.

Bạn không cần đăng xuất để cho phép người dùng liên kết một tài khoản TTAR khác — prompt=login là đủ.

Đăng xuất

Đăng xuất người dùng khỏi ứng dụng của bạn không kết thúc phiên TTAR của họ. Nếu bạn muốn kết thúc cả phiên đó trong trình duyệt này (ví dụ “đăng xuất khỏi mọi nơi” hoặc máy tính dùng chung), hãy chuyển trình duyệt của người dùng đến end-session endpoint /connect/logout bằng điều hướng toàn trang. XHR hoặc iframe sẽ không hoạt động: cookie phiên thuộc về miền 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 xóa cookie phiên của mình và chuyển hướng trình duyệt đến post_logout_redirect_uri kèm state được nối thêm.
• post_logout_redirect_uri phải được đăng ký trước. Việc so khớp là chính xác tuyệt đối, và đây là danh sách riêng so với redirect_uri (xem “Đăng ký client”). Giá trị chưa đăng ký khiến TTAR từ chối toàn bộ yêu cầu với HTTP 400 — và phiên không bị kết thúc.
• Nếu không có post_logout_redirect_uri, phiên vẫn bị kết thúc, nhưng người dùng không được đưa quay lại ứng dụng của bạn.
• id_token_hint là tùy chọn. Nếu bạn gửi nó, đó phải là id_token được cấp cho client_id của bạn. Token đã hết hạn cũng không sao.
• Việc này kết thúc phiên TTAR của người dùng trong trình duyệt này cho mọi dịch vụ có “Đăng nhập bằng TTAR”, không chỉ của bạn.

Xác thực token

Token được ký bằng RS256. Khóa công khai có tại URL JWKS chuẩn:

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

Bất kỳ thư viện OIDC chuẩn nào cũng sẽ tự động lấy chúng qua discovery endpoint. Hãy kiểm tra:

• chữ ký: alg=RS256, khóa từ JWKS;
• iss = https://stage.api.ttar.app;
• aud = client_id của bạn;
• exp: token chưa hết hạn;
• auth_time, khi bạn dùng prompt=login hoặc max_age (xem “Claim auth_time” ở trên).

Ghi chú về môi trường staging

• Staging là môi trường thử nghiệm để bạn thử nghiệm.
• Tài khoản thử nghiệm sẽ được cung cấp riêng.
• Khi chuyển sang production, client_id của bạn giữ nguyên — chỉ Issuer thay đổi, thành https://api.ttar.app.