Xsolla-logo

概要

このセクションでは、ログイン を操作するための API 呼び出しについて説明します。リクエストを送信する前に、パブリッシャー アカウント でログイン プロジェクトを セットアップ してください。

API定義をダウンロードする

API定義を2つの形式でダウンロードできます:

用語集

アドミンページでは、次のログインプロジェクトタイプにアクセスできます:

  • 標準ログインプロジェクト
  • シャドウログインプロジェクト

詳細については、クロスプラットフォームアカウント機能を参照してください。

標準ログインプロジェクト

メインアカウントを保存するために使用されるログインプロジェクトです。

シャドウログインプロジェクト

プラットフォームアカウントを保存するために使用されるログインプロジェクトです。

メインアカウント

標準ログインプロジェクトで作成され、プラットフォームアカウントにリンクされているアカウントタイプです。メインアカウントは、異なるプラットフォームでプレーヤーを識 別するために使用されます。

プラットフォームアカウント

シャドウログインプロジェクトで作成され、確定したパブリッシングプラットフォームに接続されるアカウントタイプです。プラットフォームアカウントは、他のプラットフォー ムアカウントとリンクすることはできません。また、メインアカウントからアカウントのリンクを解除することもできません。

パブリッシングプラットフォーム

ゲームの配布に使用されるゲームプラットフォームです(Steam、PlayStation、Xboxなど)。

認証

Login APIは、以下のトークンタイプをサポートしています:

ユーザートークンの取得

トークンを取得するには、次のいずれかのリクエストを送信します:

JWT認証後、ユーザーはクエリパラメータにトークンを含むコールバックURLにリダイレクトされます:<Callback URL>?token=<User token (JWT)>

OAuth 2.0プロトコルベースの認証後、JWTを生成するリクエストをエクソーラログインサーバーに送信して、受信したcodeパラメータをユーザートークン(access_token)と交換します。

サーバートークンの取得

To get a server token:

  1. Set up server OAuth 2.0 client.
  2. Generate server JWT.

サーバーOAuth 2.0クライアントをセットアップする

  1. Open your project in Publisher Account and go to the Login section.
  2. Click Configure in the panel of a Login project.
  3. Go to the Security block and select the OAuth 2.0 section.
  4. Click Add OAuth 2.0.
  5. Specify OAuth 2.0 redirect URIs.
  6. Check the Server (server-to-server connection) box.
  7. Specify Token lifetime.
  8. Click Connect.
  9. Copy and save the client ID and secret key.

Generate server JWT

On the back end of your application, implement a method to get the server JWT using the Generate JWT API call. The request must contain the following parameters:

JWT構造

すべてのトークンにはJWTフォーマットがあり、ペイロードに明確な情報が含まれています。

ユーザーJWT

ユーザーJWTは、認証または登録の結果として受け取ったトークンです。トークンのペイロードには、ユーザーと認証のコールに関する情報が含まれています。

OAuth 2.0プロトコルでユーザートークンを取得するには、OAuth 2.0クライアントが必要です。ユーザートークンは、Authorization: Bearer <JWT>ヘッダで渡されます。

主な要求

トークンには、認証またはメールアドレス確認後の主な要求が含まれます。これらの要求の有無は、ユーザーデータベースや認証コールに依存しません。

 
クレーム タイプ 必須 説明
exp Unixタイムスタンプ はい トークンの有効期限を設定する日時。デフォルトの有効期限は24時間です。有効期限は、ログインプロジェクトごとに変更できます。
iss 文字列 はい トークンに署名したサービス:https://login.xsolla.com
iat Unixタイムスタンプ はい トークンを発行した日時。
sub 文字列(UUID) はい エクソーラログインサーバー側に書き込まれたユーザーID。
groups 配列 はい

ユーザーが所属しているグループのリスト。各グループは以下のフォーマットで書かれます:

  • id — グループID
  • name — グループ名
  • is_default — グループがデフォルトであるかどうかを示します(trueまたはfalseの値)。

デフォルトグループは1つしか存在できません。このグループには、異なるグループに分散される前のすべてのユーザーが初期状態で含まれています。

xsolla_login_project_id 文字列(UUID) はい ログインプロジェクトID。
type 文字列

Authentication option:

  • xsolla_login — login via username/email and password.
  • social — social login
  • email — passwordless login via one-time code received by email.
  • phone — passwordless login via one-time code received by SMS.
  • firebase — login via username/email and password when the user data storage is Firebase.
  • playfab — login via username/email and password when the user data storage is PlayFab.
  • proxy — login via username/email and password when the user data storage is custom.
  • device — login with device ID.
  • server_custom_id — login with custom ID.

デフォルトグループは1つしか存在できません。このグループには、異なるグループに分散される前のすべてのユーザーが初期状態で含まれています。

avatar 文字列 User avatar URL.
username 文字列 ユーザー名。
publisher_id integer ログインプロジェクトを所有するマーチャントのID。
email 文字列 ユーザーのメールアドレス。
payload 文字列 認証時にペイロードパラメータで渡される追加情報。
promo_email_agreement ブール型

次のいずれかの値になります:

  • true ユーザーがニュースレターの受信に同意した場合。
  • false それ以外の場合。
デフォルトはtrueの値になります。

ログインウィジェットの登録フォームに機能を追加するには:

  • Widget 2.0を使用している場合は、アカウントマネージャーまでお問い合わせください。
  • 旧バージョンのウィジェットを使用する場合は、初期化コードpromo_email_agreement値を持つfieldsパラメータを追加してください。

connection_information 文字列 ユーザーが生年月日を確認したかどうかを表示します。確認はoknameサービスを通じて行われます。

PlayFabストレージ

PlayFabストレージを使用する場合、認証後にトークンに含まれる要求。

クレーム タイプ 必須 説明
external_account_id 文字列 はい ユーザーPlayFab ID。
session_ticket 文字列 はい

PlayFab APIへの認証リクエストまたはリクエストの間に受け取ったSessionTicketパラメータです。

OAuth 2.0プロトコルを経由でユーザーを認証し、playfab値をscopeパラメータに渡す場合、トークンには要求が含まれます。

entity_token 文字列 はい EntityToken.EntityTokenパラメータ。
entity_type 文字列 はい EntityToken.Entity.Typeパラメータ。 title_player_accountの値のみを持つことができます。
entity_id 文字列 はい EntityToken.Entity.Idパラメータ。

カスタムストレージ

カスタムストレージを使用する場合、認証後にトークンに含まれる要求。

クレーム タイプ 必須 説明
provider 文字列 はい 認証に使用されるソーシャルネットワークの名前。ユーザーがユーザー名とパスワード経由で認証する場合、要求にはxsolla値が含まれます。
external_account_id 文字列 サーバー側のユーザーID。
partner_data 認証時にサーバーからレスポンスボディに返される任意のタイプのデータ。

ソーシャル認証

ソーシャルネットワーク経由の認証後、トークンに含まれる要求。これらの要求の存在は、ユーザーデータベースに依存しません。

クレーム タイプ 必須 説明
provider 文字列 はい 認証に使用されるソーシャルネットワークの名前。
id 文字列 はい ソーシャルネットワークにおけるユーザーID。
is_cross_auth ブール型 サイレント認証のリクエストが進行中であることを示します。
social_access_token 文字列 認証に使用するソーシャルネットワークアカウントのaccess_tokenパラメータ。この機能をセットアップするには、アカウントマネージャーにお問い合わせください。
picture 文字列(URL) ソーシャルネットワークにおけるユーザープロフィール画像へのリンク。
birthday 日付(RFC3339 ソーシャルネットワークにおけるユーザーの誕生日。
gender 文字列 ソーシャルネットワークにおけるユーザー性別。
name 文字列 ソーシャルネットワークにおけるユーザーニックネーム。

OAuth2.0プロトコル経由の認証

OAuth 2.0認証後のトークンに含まれる要求。

クレーム タイプ 必須 説明
jti 文字列 はい 一意のトークンID。

電話番号経由の認証

電話番号経由の認証後、トークンに含まれる要求。

クレーム タイプ 必須 説明
phone_number 文字列 はい 認証に使用されるユーザーの電話番号。電話番号は、国番号、市外局番、回線番号からなる区切りのない形式です。

サーバーJWT

サーバートークンは、X-SERVER-AUTHORIZATIONヘッダーで渡されます。

トークンのペイロードには、OAuth 2.0クライアントが所有するリソースに関する情報が含まれています。トークンは、これらのリソースに対するサーバーベースの認証によるコールにアクセスできます。

クレーム タイプ 必須 説明
xsolla_login_project_id 文字列(UUID) はい OAuth 2.0クライアントを所有するログインプロジェクトのID。
resources 配列 はい

OAuth 2.0クライアントが所有するリソースのリスト。可能なリソースのタイプ:

  • publisher_id — ログインプロジェクトを所有するマーチャントのリソース
  • publisher_project_idアドミンページでのプロジェクトのリソース。

各グループは以下のフォーマットで書かれます:

  • name — リソースタイプ
  • value — リソースID

jti 文字列 はい 一意のトークンID。

JWT検証

認証に成功すると、すべてのユーザーに対してJWTが生成されます。生成されたJWTは秘密鍵で署名されていま す。JWTが適切であり、ログインプロジェクトのユーザーに属していることを確認するために、その値を検証する必要があります。

JWTを検証するには:

  1. Open your project in Publisher Account and go to the Login section.
  2. Click Configure in the panel of a Login option.
  3. On the navigation page, go to the Security block and select the JWT Signature section.
  4. Select your encryption method and copy the value of the Secret key or New public JSON Web Key field, depending on the selected method.
  5. Choose the library and connect it on the server side of your application.
  6. Pass the value, copied in the step 4, to the validation function entry.

通知

秘密鍵は他人に教えないでください。漏洩した場合は、更新してください。

エラー

エラー応答の場合、エクソーラログインサーバーは以下のフィールドを持つJSONオブジェクトを返します:

フィールド タイプ 説明
code 文字列 エクソーラログインサーバーのエラーコード。
説明 文字列 エラーの説明。テキストは常に英語です。値は将来変更される可能性があるため、エラーの場合はこのテキストを使用しないでください。
{
  "error": {
    "code": "000-000",
    "description": "description"
  }
}

400 無効なリクエスト

コード 説明
0 リクエストに無効なパラメータがあります。
010-019 クライアント認証に失敗しました(例:不明なクライアント、クライアント認証が含まれていない、またはサポートされていない認証方法)。
010-022 8文字未満であるため、パラメータの状態が欠落しているか、弱すぎます。
010-023 認可付与またはリフレッシュトークンが無効、期限切れ、取り消し、認可リクエストで使用されたリダイレクトURIと一致しない、または別のクライアントに対して発行されています。

401 未認証

コード 説明
002-016 無効なトークン。
002-040 禁止されたユーザーを認証できません。
003-001 ユーザー名またはパスワードが間違っています。
003-007 ユーザーアカウントが確認されていません。
003-025 OAuth2.0アクセストークンの取得中にエラーが発生しました。
003-040 未認証のユーザー。
010-026 エクソーラログインサーバーまたはリソース所有者がリクエストを拒否しました。

403 禁止

コード 説明
1901-0001 無効なトークン。

404 見つかりませんでした

コード 説明
003-002 ユーザーが見つかりません。
003-019 プロジェクトが見つかりませんでした。
003-061 オブジェクトが見つかりませんでした。

418 私はティーポットです

コード 説明
004-001 問題が発生しました。

422 処理できないエンティティです

コード 説明
0 ニックネームがクエリで見つかりませんでした。
002-050 ユーザーの二要素認証設定は変更されていません。
003-003 指定されたユーザー名を持つユーザーは既に存在しています。
003-020 このログインプロジェクトではコールを利用できません。
003-022 このログインプロジェクトは間違って構成されています。エクソーラアドミンページでこのログインプロジェクトの設定を変更するか、アカウントマネージャーにお問い合わせください。
003-033 プロジェクトタイプが一致しません。
006-003 OAuth 2.0クライアントで、client_credentialsグラントタイプのみ、アクセスリストを持つことができます。
010-015 ソーシャルネットワーク認証に失敗しました:SERVICE_NAME。
010-016 このソーシャルアカウントは既に別のユーザーとリンクしています。
010-032 このログインプロジェクトでは、このソーシャルネットワークを介した認証が有効になっていません。エクソーラアドミンページ > ログイン > あなたのログインプロジェクト > ソーシャルコネクションで有効にしてください。
030-024 このログインプロジェクトではパスワードのリセットが無効になっています。
2002-0001 属性が重複しています。

429 リクエストの回数が多すぎます

コード 説明
002-054 許容される検索回数を超えました。次のリクエストまで1秒お待ちください。
010-005 許可されたリクエスト数を超えました。
1900-0001 許可されたリクエスト数を超えました。