ウェブ

TTARでログイン

あなたのサイトやアプリでTTARアカウントによる認証を利用できます。選手はワンクリックでログインでき、あなたはすぐに選手のレーティングを確認できます。

卓球愛好家向けのサイトやアプリ（卓球場、大会、練習、用具ショップなど）を運営しているなら、「TTARでログイン」を導入しましょう。選手はGoogleやTelegramと同じように、新しいログイン名やパスワードを作らずに、TTARアカウントでワンクリックであなたのサービスにログインできます。さらに、誰が来たのか、どのくらいの実力なのかもすぐにわかります。

あなたのサービスにとってのメリット：

登録数が増えます。フォームへの入力やメールアドレスの確認は不要です。選手はTTARのログイン情報でログインするので、登録を途中でやめてしまう人が減ります。
選手のレーティングがすぐにわかります。認証と同時にTTARのレーティングを受け取れます。大会のシード決め、実力別のグループ分け、練習相手探し、大会への参加資格の確認に便利です。
独自の認証は不要です。パスワードの保管、アカウントの復旧、GoogleやTelegramでのログイン。これらはすべてTTARですでに動いています。開発者は標準のOpenID Connectプロトコルを接続するだけで済み、主要なプログラミング言語すべてに対応したライブラリが用意されています。
選手にとって安全です。TTARのパスワードがあなたに渡ることはありません。選手はTTARのページでのみパスワードを入力します。あなたに渡されるのは、リクエストしたデータ（選手ID、名前とアバター、メールアドレス、レーティング）だけです。

導入方法

パートナーになるのは簡単で、無料です。kot@ttar.app宛てにメールを送り、あなたのサービスについて教えてください。導入に必要なものをすべてお送りします。あなたのサービスの選手に「アクセスを許可しますか？」という画面は表示されません。パートナーは私たちが直接接続するため、あらかじめ承認されています。

以下は技術的な説明です。このページはそのまま開発者に渡せます。

認可サーバーのパラメーター

ほとんどの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宛てにメールでご連絡ください。

登録時には、1つ以上のredirect_uri（認証後に私たちがユーザーを送る、あなたのアプリ内のアドレス）を伝えてください。私たちはそれをホワイトリストに登録します。各リクエストでは具体的なアドレスを指定し、サーバーがそのリストと照合します。

さらに、1つ以上の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セッションがすでにある場合は、ログインページが省略され、すぐにコードが発行されます（シングルサインオン）。ただし、prompt=loginで再ログインを求めた場合は除きます。省略可能なパラメーターpromptとmax_ageについては、下の「再ログインとアカウントの切り替え」で説明しています。

ステップ2. redirect_uriで応答を受け取ります。ログインに成功すると、ユーザーのブラウザーは2つのパラメーター付きで、あなたのredirect_uriへ自動的にリダイレクトされます：

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

code — 1回限りの認可コードです。有効期間は約60秒なので、すぐに使ってください。
state — ステップ1で渡したものと同じ値です。自分で保存しておいた値と必ず照合してください。CSRF対策になります。

ユーザーが拒否した場合やエラーが発生した場合は、次のように返されます：

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

ステップ3. コードをトークンと交換します。ブラウザーではなくサーバーから、ステップ2のコードを付けて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は、ステップ1で渡したものと一致している必要があります。サーバーはこれを追加のチェックに使用します。

応答：

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

access_token — /connect/userinfoを含むAPIへのアクセスに使うBearerトークンです。RS256で署名されたJWTです。
id_token — ユーザーの基本情報（sub、名前、メールアドレスなど）を含むJWTです。署名は必ず検証してください。
refresh_token — 再ログインせずに新しいトークンを取得するためのものです。スコープ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

スコープ

スコープ	返される内容
`openid`	`sub`（TTARでの選手ID）。必須です。
`profile`	`name`、`picture`（アバターのURL）
`email`	`email`、`email_verified`
`offline_access`	token endpoint `/connect/token`の応答に`refresh_token`を追加します。このスコープがないと、refresh tokenは発行されません。
`ttar:rating`	access tokenに含まれる`ttar_rating`クレーム。選手のレーティングの配列です（下記参照）。

ttar_ratingクレーム

スコープttar:ratingがリクエストされ、選手にレーティングがある場合、access tokenにttar_ratingクレームが含まれます。これはJSON配列で、利き手と逆の手のそれぞれについて1つずつオブジェクトが入ります：

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

その他のデータ（名前、アバター、メールアドレス）は、UserInfo endpoint /connect/userinfoまたはid_tokenから取得できます。

再ログインとアカウントの切り替え

TTARは、ユーザーのブラウザーにシングルサインオン（SSO）のセッションを保持します。これはTTAR APIのドメインのcookieです。セッションが有効な間、/connect/authorizeはログインページを表示せずに、同じTTARユーザーのコードを発行します。このセッションはあなたのアプリのセッションとは独立しており、ユーザーがあなたのアプリからログアウトしても終了しません。

prompt=login — セッションが有効でも、常にTTARのログインページを表示して再ログインを求めます。既存のTTARセッションは再利用されません。ユーザーは別のTTARアカウントでログインすることもできます。アカウント連携におすすめです。
prompt=select_account — prompt=loginと同じです。TTARにはアカウントの選択画面がありません。ユーザーはログインすることでアカウントを選びます。
prompt=none — 画面を一切表示しません。有効なセッションがない場合、またはセッションがmax_ageより古い場合、ユーザーはerror=login_required付きであなたのredirect_uriに戻されます。
prompt=consent — 受け付けますが、何の効果もありません。登録済みのパートナーはあらかじめ承認されており、TTARには同意画面がありません。
max_age=N — ユーザーがN秒より前にログインしていた場合は、再ログインが必要になります。max_age=0はprompt=loginと同じです。

不正なprompt（不明な値、またはnoneと他の値の組み合わせ）は、TTARがHTTP 400で拒否します。この場合、ブラウザーはあなたのredirect_uriに戻されません。

auth_timeクレーム。id_tokenにはauth_timeが含まれます。これは、ユーザーが最後にTTARへ対話的にログインした時刻（メールアドレスとパスワード、Google、Telegramのいずれか）を表すUnix時間（秒）です。トークンを更新しても変わりません。これが含まれない可能性があるのは、この機能の導入前に開始されたTTARセッションだけです。そのようなセッションはprompt=loginとmax_ageを決して満たさず、常に新たに確立されます。そのため、これらのパラメーターのいずれかを指定した場合、id_tokenには必ずauth_timeが含まれます。

TTARアカウントの連携：

認可リクエストにprompt=loginを追加し、リクエストを開始した時刻を記録します。
コードを交換した後、時計のずれを考慮して数秒の余裕を持たせたうえで、auth_timeがその時刻より前でないことを確認します。これにより、既存のセッションが再利用されたのではなく、ユーザーがこのリクエストの中で実際にログインしたことを確認できます。
連携にはsub（TTARでの選手ID）を使います。

補足

Googleでログインする場合、ユーザーがこのブラウザーですでにGoogleにログインしていれば、Google自体がパスワードを求めないことがあります。それでもTTARにとっては新たな対話的ログインであり、auth_timeにもそれが反映されます。

ユーザーが別のTTARアカウントを連携できるようにするために、ログアウトは必要ありません。prompt=loginだけで十分です。

ログアウト

ユーザーがあなたのアプリからログアウトしても、TTARのセッションは終了しません。このブラウザーで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を削除し、stateを付加して、ブラウザーをpost_logout_redirect_uriにリダイレクトします。
post_logout_redirect_uriは事前に登録しておく必要があります。完全一致で照合され、redirect_uriとは別のリストです（「クライアントの登録」を参照）。未登録のアドレスの場合、TTARはリクエスト全体をHTTP 400で拒否し、セッションも終了しません。
post_logout_redirect_uriを指定しない場合、セッションは終了しますが、ユーザーはあなたのアプリに戻りません。
id_token_hintは省略可能です。渡す場合は、あなたのclient_idに発行されたid_tokenでなければなりません。有効期限切れのものでも構いません。
ログアウトすると、このブラウザーでのユーザーの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を使用する場合。上の「auth_timeクレーム」を参照）

stagingに関する注意点

stagingは、実験用のテスト環境です。
テスト用のアカウントは別途提供します。
本番環境に移行してもclient_idは変わりません。変わるのはIssuerだけで、https://api.ttar.appになります。