Connect インターフェース

Connect インターフェースは、異なる ID プロバイダのユーザー アカウント間の接続を処理します。

Connect インターフェース

Connect インターフェース を使用すると、外部 ID プロバイダEpic Online Services (EOS) エコシステムを統合して使用することができます。

Connect インターフェースでは、次のことを行うことができます。

  • Epic Online Services (EOS) ゲーム サービスにアクセスできる。

  • クロスプラットフォーム サービス内で、共通の一意のユーザー識別子を生成する。

  • 外部 ID プロバイダのアカウントを Epic Games のサービスにリンクさせる。

プレイヤーは、1 つまたは複数の外部ユーザー アカウントを、自分の 製品ユーザー ID (一意のプレイヤー ID) と関連付けることができます。

この製品ユーザー ID は、同一組織のすべての製品に適用されます。

サポートされている ID プロバイダと設定の詳細については、「ID プロバイダを管理する」を参照してください。

ユーザーを管理する

ユーザーは一連の外部資格情報を使用してログインします。該当製品にユーザーがすでに存在する場合は、一定期間 (現在は 1 時間) 存続する アクセス トークン が付与されます。トークンの有効期限前になるとゲームに通知されます。ゲームはその時点で有効な外部資格情報が付与されている既存のトークンを更新しなければなりません。

Epic Online Services インターフェースでは外部プロバイダのアクセス権限を制御することはできません。このため、 Connect インターフェース では、次のように機能します。

実行すること:

  • ユーザーが外部アカウント プロバイダで引き続き有効であることを確認する

  • ユーザーが Epic のサービスにアクセスできる期間を延長する

実行しないこと:

  • 暗黙的にトークンを更新する

  • 長時間のアクセス権を付与する

外部アカウント プロバイダにアプリケーションへのアクセスに対する権限があることが前提となります。

Connect Interface Account Flow

このユーザー識別子で使用可能なサービスへのアクセスには、 EOS_ProductUserId データ構造体を使用した外部アカウント ID が必要です。すべてのインターフェースで、この構造体の使用方法を明確に指定して、タイプ セーフであることを保証する必要があります。この構造体は、Epic アカウント サービスで提供される Auth インターフェースに関連付けられている EOS_EpicAccountId とは異なります。

サポートされているどのタイプの外部アカウントでも使用できる Connect インターフェース を使用する際には、Epic Games アカウントは必要ありません。

ログインする

ログインするには、サポートされているプラットフォームの外部認証情報を含む EOS_Connect_LoginOptions を使用して EOS_Connect_Login を呼び出します。

Epic Games アカウントの場合、EOS_Auth_CopyUserAuthToken から現在の認証トークンを取得して、EOS_EExternalCredentialTypeEOS_ECT_EPIC に設定するだけです。

EOS_HConnect ハンドル、 EOS_Connect_LoginOptions 構造体、およびコールバック情報を EOS_Connect_Login に渡します。EOS_HPlatform ハンドルがティックしている場合、操作が終了すると、指定したコールバックが実行されます。

結果が成功の場合、アプリケーションは認証を必要とするその他のインターフェースへのアクセスに進むことができます。ユーザーが存在しない場合、ログイン API は EOS_InvalidUser という結果を返します。これには EOS_ContinuanceToken も含まれています。ログイン試行の詳細が提供されているので、このトークンはログイン フローの次のステップで必要になります。

この時点で、次のことを決定する必要があります。サービスに登録済みであることが判明している一連の他の外部資格情報があるか (「外部アカウントをリンクする」を参照)、あるいは新しいアカウントを作成する必要があるか (「ユーザーを作成する」を参照) をユーザーに確認します。

ユーザー認証更新通知

EOS_Connect_AddNotifyAuthExpiration に指定されたコールバック関数は、既存のアクセス トークンの有効期限が近づくたびに実行されます。このコールバック関数の実行は、有効期限が近づくたびにアプリケーションが他の外部アクセス トークンを取得して、EOS_Connect_Login 関数を使用して SDK に取得したトークンを提供できるタイミングで行われる必要があります。

認証トークンの更新通知のリッスンを停止するには、EOS_Connect_RemoveNotifyAuthExpiration 関数を使用します。

ユーザー認証ステータス変更通知

ユーザーの認証ステータスが変化されたら必ずアプリケーションに通知できるように、Connect インターフェースでは、ステータス変更通知のコールバックを提供しています。

EOS_Connect_AddNotifyUserLoginStatusChanged に対して指定したコールバック関数は、ローカル ユーザーの認証ステータスが変更されるたびに実行されます。このコールバック関数の実行は、有効期限通知が無視された場合、外部プロバイダの認証情報がアクセス トークンを更新できない場合、または管理上の理由によりバックエンド サービスによってアクセスが明示的に取り消された場合にのみ行われます。このコールバックは、EOS エコシステムの他の呼び出しがこの認証トークンが無効であることを検知した場合のみ実行されます。例外の場合に自動的に実行されることはありません。

認証が原因で失敗する可能性のある特定のコールのすべてのメッセージを処理する必要があります。EOS_Connect_Login を呼び出して、元のコールを再試行し成功することで回復可能な場合が多いです。

ステータス変更通知のリッスンを停止するには、EOS_Connect_RemoveNotifyUserLoginStatusChanged 関数を使用します。

現在のユーザー認証ステータスを確認する

必要に応じて、プレイヤーの現在のステータスを確認するには、EOS_Connect_GetLoginStatus 関数を使用します。この関数はオンライン サービスとの前回の通信に基づいて認証ステータスを特定するので瞬時に結果が返されます。そのため、コールバック関数は使用しません。

新しいユーザーを作成する

ユーザーを作成すると、ログイン時に使用した外部資格情報を指定したユーザーには、製品ユーザー ID が生成されます。ほとんどの場合、新しいユーザーを作成する前に、ユーザーにプロンプトを表示して、他にログインする手段があるかどうかを確認する必要があります。この確認を行うことで、クロスプラットフォーム環境での混乱やユーザーのゲームの進行状況の結合に関する問題が軽減されます。

アプリケーションの目的がユーザーの新しい製品ユーザー ID の作成である場合は、単に、EOS_Connect_Login に対する前の呼び出しの EOS_ContinuanceToken を含む EOS_Connect_CreateUserOptions を使用して EOS_Connect_CreateUser を呼び出します。

EOS_HConnect ハンドル、EOS_Connect_CreateUserOptions 構造体、およびコールバック情報を関数に渡します。EOS_HPlatform ハンドルがティックしている場合、操作が終了すると、指定したコールバックが実行されます。

外部アカウントをリンクする

アプリケーションへのログインのフローで、ユーザーが他の外部認証情報セットでログインできると特定されている場合は、最初のログイン呼び出しの EOS_ContinuanceToken を格納して、EOS_Connect_Login を使用してログインを再試行し、ログインに成功したら、直ちに EOS_Connect_LinkAccount を呼び出します。この操作により、2 つの外部アカウントが 1 つの製品ユーザー ID に関連付けられます。Epic Games のサービスの機能は拡大しているため、3 つ以上のアカウントを関連づけることができます。

アプリケーションの目的が既存の製品ユーザー ID に新しい外部アカウントをリンクすることである場合は、EOS_Connect_Login に対する前の呼び出しの EOS_ContinuanceToken を含む EOS_Connect_LinkAccountOptions および EOS_Connect_Login に対する成功した呼び出しでログインしたユーザーの製品ユーザー ID を使用して EOS_Connect_LinkAccount を呼び出します。

EOS_HConnect ハンドル、EOS_Connect_LinkAccountOptions 構造体、およびコールバック情報を関数に渡します。EOS_HPlatform ハンドルがティックしている場合、操作が終了すると、指定したコールバックが実行されます。

EOS Connect ユーザーは、外部アカウント ID で、または [Developer Portal (デベロッパー ポータル)] の [Account] ダッシュボードを介して製品ユーザー ID を使用することで、検索できます。プレイヤーのリンク済みの外部アカウントのキーチェーンは組織レベルで管理されるため、[Account] ダッシュボードは [Organization management (組織管理)] メニュー項目の隣にあります。[Account] ダッシュボードではプレイヤーを検索できるため、カスタマー サポートがプレイヤーのリクエストに応じてアカウント リンクを削除する際に役立ちます。このダッシュボードを使用すると、SDK 統合テスト時に EOS Connect ユーザーまたはリンク済みのアカウントを削除することもできます。これに合わせて、Epic Games では、既存の内部ダッシュボードに EOS のユーザー管理機能を組み込むための Web REST API をデベロッパーに提供する予定です。

外部アカウントのリンクを解除する

ユーザー ログイン フローを初めて使用する場合、別のプラットフォームでプレイしたり、別の外部アカウントの資格情報を使用したりすることで、ユーザーがすでに持っている可能性のある既存のゲームの進行状況を再利用するのではなく、ログインしたアカウント (通常はローカル プラットフォーム アカウント) に対して、新しい製品ユーザー ID を誤って作成してしまう可能性があります。ユーザーはゲームのクロスプレイ機能を認識していない可能性があります。

このようなシナリオでは、ユーザーは初期のログイン ダイアログをスキップして、ユーザーのデフォルト プラットフォームのアカウント認証情報 (ログイン アカウント) で続行し、EOS_Connect_Login API と EOS_Connect_CreateUser API のフローに従って新しい EOS_ProductUserId を作成します。その結果、ゲームの開始時に EOS_Connect_Login で使用されたのログイン アカウントが意図しない製品ユーザー ID と結びつけられるようになります。この状態から回復するには、ユーザーが初めてユーザー ログイン フローに再度入れるように、ユーザーは新しく作成されたキーチェーンからログイン アカウントのリンクの解除ができなければなりません。

ログインアカウントのリンクを解除すると、別の既存のキーチェーンにリンクされた別の外部アカウント資格情報のセットを使用してログインすることができます。ログインが成功したら、上記の 外部アカウントをリンクする セクションで説明しているフローを使用して、デフォルトのログイン アカウントを目的の既存のキーチェーンにリンクします。

別の状況もあります。ユーザーは、プラットフォーム間でゲームの進行状況を分離したり、別の方法で別のキーチェーンにリンクしたりするために、ログインアカウントを現在のキーチェーンから分離したい場合があります。

現在ログインしている製品ユーザー ID を所有するキーチェーンから外部アカウントのリンクを解除するには、 EOS_Connect_UnlinkAccountOptions を指定して EOS_Connect_UnlinkAccount を呼び出し、 EOS_Connect_Login への前の呼び出しで返された EOS_ProductUserId として LocalUserId を指定します。操作が正常に完了すると、外部アカウントはキーチェーンに関連付けられなくなります。つまり、同じ外部アカウントに関連付けられた資格情報を使用して EOS_Connect_Login で次回ログインしようとすると、 EOS_ContinuanceTokenEOS_InvalidUser という結果が返されます。

アカウントのリンク操作と同様に、リンク解除操作の履歴は、Developer Portal のアカウント ダッシュボードで監査することができます。

外部アカウントのリンク解除に関する制限事項

アカウントを盗難から保護するために、キーチェーンからアカウントのリンクを解除できるのは、ローカル ユーザーが現在ログインしているアカウントのみです。これにより、悪意のある人物がリンクされたアカウントの 1 つにアクセスし、それを使用してキーチェーンにリンクされた他のすべてのアカウントを削除することを防止します。また、リンク解除操作により、既存の認証セッションを使用して、キーチェーンの他のリンクされたアカウントのいずれかを使用した認証なしにエントリを再リンクおよび上書きすることはできないため、悪意のある人物が、リンクされていないアカウントを同一プラットフォーム上の対応するアカウントに置き換えることも防止できます。

これらの制限事項は、アカウント盗難の状況に関連する潜在的な攻撃対象領域を制限するために設けられました。

デバイス ID を使用する

この機能は、個人用のモバイル デバイスと PC デスクトップにのみ適用されます。 デバイス ID は、外部アカウントが必要な Anti-Cheat インターフェースでは使用できません。

ユーザーが、新規アカウントを作成したり、既存のアカウントをリンクするほどの段階ではないとアプリケーションが判断した場合、アプリケーションは EOS Connect のデバイス ID 機能を使用して新しい永続的な疑似アカウントを作成することができます。この機能を使用すると、アプリケーションでは、外部ログイン資格情報を使用することなく、ローカル ユーザーの永続的なアクセス資格情報を作成できます。これにより、バックエンド サービスでは複数のゲーム セッションを通じてそのローカル デバイスの現在のユーザーを記憶できます。デバイス ID 機能は特に個人用のモバイル デバイスで使用されます。この機能を使用すると、アカウント資格情報の入力を求められることなく、ユーザーが自動的にログインできたり、ゲームの進行状況データを保持するために直ちにログインを求められることなく、ゲーム プレイを開始したりできます。

ただし、デバイス ID は実際のユーザー アカウントに関連付けられておらず、ローカル デバイスを一意に識別するためのみに使用できるため、初期の進行マイルストーンまで進んだら、資格情報やアカウントの喪失を防止できるように、外部認証方法をデバイス ID アカウントにリンクするようユーザーに求めることを強く推奨します。

最終的にはデバイス ID アカウントを実際のユーザー ID にリンクしないと、デバイス自体に問題等が発生した場合、すべての進行状況とゲーム データが永久に失われます。EOS SDK では、ローカル デバイスの現在ログインしているユーザーのキーチェーンにデバイス ID の資格情報をローカルに格納します。ローカル ユーザーのプロファイルがリセットされたり、失われたりした場合、それ以降に失われたデバイス ID を回復することはできません。

新しいデバイス ID を作成するには、アプリケーションで、ユーザーの DeviceModel を含む有効な EOS_Connect_CreateDeviceIdOptions 構造体を指定して EOS_Connect_CreateDeviceId 関数を呼び出す必要があります。この呼び出しにより、最終的には EOS_Connect_OnCreateDeviceIdCallback にバインドされた関数へのコールバックがトリガーされます。新しいデバイス ID が正常に作成され、ローカル デバイスのログイン ユーザーのキーチェーンに格納された場合、コールバック パラメータの ResultCode パラメータが EOS_EResult::EOS_Success に設定されます。既存のデバイス ID が既に存在する場合は、EOS_EResult::EOS_DuplicateNotAllowed が返されます。その他の場合は、ResultCode パラメータで操作が失敗した理由が特定されます。

一意のデバイス ID を使用してローカル ユーザーをログインさせるには、EOS_EExternalCredentialType::EOS_ECT_DEVICEID_ACCESS_TOKEN 外部認証情報型を使用して EOS_Connect_Login API を呼び出します。SDK では格納されたデバイス ID 認証情報を自動的に管理するため、EOS_Connect_Credentials 入力構造体の Token パラメータを null に設定する必要があります。ただし、デバイス ID は実際のユーザー ID に関連付けられていないため、 EOS_Connect_UserLoginInfo 入力構造体にユーザーの有効な DisplayName を指定する必要があります。

ローカルのデバイス ID を実際の外部ユーザー アカウントにリンクするには、まず、ゲームで、通常、デバイス ID タイプの資格情報を使用しているローカル ユーザーをログインさせます。次に、ユーザーに本物の ID でログインするように求め、EOS_Connect_LoginEOS_ContinuanceToken とともに返されたら、EOS_Connect_Link API を使用して外部アカウントをリンクして、ローカル デバイスをユーザーの実際のアカウントに関連付けます。この操作により、ゲームを開始するたびにユーザーが自動的にログインできるようになります。外部ユーザー アカウントの認証情報の入力を求められることなく、ユーザーが自動的にログインできるように、デバイス ID を引き続き使用できるためです。

Device ID 資格情報の削除

EOS_Connect_DeleteDeviceId API を呼び出して、ローカル デバイスの現在のユーザー プロファイルのデバイス ID を削除することもできます。削除は永続的な操作であるため、元に戻すことはできません。ただし、新しいデバイス ID を作成して、既存の外部ユーザー アカウントにその ID をリンクさせると、いつでも自動ログイン機能を復元できます。

Android および iOS デバイスでは、アプリケーションを削除すると、そのアプリケーションによって作成されたすべてのローカル デバイス ID 資格情報は自動的に削除されます。

デスクトップ プラットフォーム (Linux, macOS, Windows) では、デバイス ID 資格情報は自動的に削除はされません。アプリケーションは、アプリケーションの再インストール時にローカル OS ユーザーの既存のデバイス ID 資格情報を再利用するか、または初回の実行時に EOS_Connect_DeleteDeviceId API を呼び出してユーザーが新しく起動できるようにします。

デバイス ID に基づくゲームの進行状況を関連付けられた既存のアカウント キーチェーンに関連付ける

デバイス ID 疑似アカウントを実際の外部ユーザー アカウントに関連付ける一般的な方法を使用できない特殊なケースがあります。この場合、ログインされた実際のユーザー アカウントは同じ EOS 組織の下の既存のキーチェーンにすでに属しています。そのようなケースでは、ゲームがまずローカル Device ID ログイン タイプを使って自動的にユーザーをログインさせ、その後にユーザーが本物のユーザー アカウント認証情報を使ってログインすると、EOS_Connect_Login API は EOS_ContinuanceToken の代わりに既存の EOS_ProductUserId を返します。この特別なシナリオに対処するために、EOS_Connect_TransferDeviceIdAccount API が使用されます。

EOS_Connect_TransferDeviceIdAccount API は EOS_ContinuanceToken の使用が求められるため、デバイス ID 疑似アカウントを既存のキーチェーンに関連づけることができません。さらに、プレイヤーには異なる 2 つの EOS_ProductUserIds が存在することになるため、ゲームはプレイヤーに対して、一方の EOS_ProductUserIds (ゲーム プロファイルなど) を廃止として破棄し、もう一方の EOS_ProductUserIds でプレイを継続するかどうかを選択させる必要があります。プレイヤーが一方のプロファイルの破棄を選択した場合、ゲームはバックエンドで永続的である、関連付けられたアカウントの既存のキーチェーンにローカル デバイス ID を関連付けることができます。

2 つの EOS_ProductUserIds が存在する場合に対処するには、ゲームがいつ Device ID ログイン タイプを使用してローカル ユーザーをログインさせ、その後ユーザーが同じゲーム セッションで既存のアカウントを使ってログインし、かつそれに対してもう 1 つの EOS_ProductUserId セッションを受け取るのかをゲームが認識する必要があります。これにより、ゲームは一方の EOS_ProductUserIds に有意義なゲームの進行状況をもたないことをバックエンドで自動的に確認しようとします。このケースでは、ゲームはそれを自動的に破棄し、ローカルのデバイス ID 疑似アカウントを本物の外部ユーザー アカウントの既存のキーチェーンに関連づけます。

ユーザーの代わりにゲームがこのケースを判断することができないと、ゲームはユーザーに進行方法についての選択を求めます。この選択ダイアログにおいて、プレイヤーはそれぞれの EOS_ProductUserId を比較することでゲームの進行状況を見直し、どちらを保持するか選択します。破棄されたゲームの進行状況は永久に失われ、破棄後の回復はできないことをユーザーが明確に認識できるようにする必要がありますゲームはユーザーにいずれのプロファイルも破棄せずに、いずれかを選択して現在のゲーム セッションでプレイを継続することを選択するオプションを提供する場合があります。

ユーザーがゲーム プロファイルの一方を破棄して、もう一方に永久に切り替えることを選択する場合、ゲームは ローカル デバイス ID 疑似アカウントを本物の外部ユーザー アカウントに関連づいたキーチェーンに転送するために EOS_Connect_TransferDeviceIdAccount API を呼び出します。API で、デバイス ID 転送オペレーションに保持するための正しい EOS_ProductUserId 値を指定するために、構造体 EOS_Connect_TransferDeviceIdAccountOptions を入力し ProductUserIdToPreserve パラメータを設定します。

外部アカウントのマッピングを取得する

他のインターフェースは、リモート ユーザーまたはその他の外部ユーザー (同一サーバー上のフレンド、プレイヤーなど) では EOS_ProductUserId を必要とします。マッピング API を使用して、外部ユーザー アカウント識別子を EOS_ProductUserId に変換することができます。

EOS_Connect_QueryExternalAccountMappings は、外部アカウント ID を SDK 表現に変換する非同期呼び出しです。EOS_EExternalAccountType を設定して、外部アカウント ID の隣接リストを文字列形式で提供します。

EOS_HConnect ハンドル、EOS_Connect_QueryExternalAccountMappingsOptions 構造体、およびコールバック情報を関数に渡します。EOS_HPlatform ハンドルがティックしている場合、操作が終了すると、指定したコールバックが実行されます。

コールバックが正常に返されたら、 EOS_Connect_GetExternalAccountMapping を使用してマッピングを取得できます。この関数は、これまでと同じように EOS_EExternalAccountType を取り、文字列形式で外部アカウント ID を提供する呼び出しごとに 1 つの EOS_ProductUserId を返します。

一般的な使用例は、ローカルユーザーと同じアカウント システムを介して接続している他のユーザーにクエリを実行することです。アカウント システムの仕様によっては、別のアカウント システムの外部アカウント ID によるクエリを使用できない場合があります。

製品ユーザー ID のマッピングを取得する

特定の製品ユーザー ID の外部マッピングを取得できるように、外部アカウントの製品ユーザー ID のマッピングも取得できます。

EOS_Connect_QueryProductUserIdMappings は非同期呼び出しで、表示名、最終ログイン時刻を含む追加のアカウント データとともに、特定のプラットフォーム上の外部の該当要素に EOS_ProductUserIds を変換します。製品ユーザー ID の隣接リストの指定のみを行います。

EOS_HConnect ハンドル、 EOS_Connect_QueryProductUserIdMappingsOptions 構造体、およびコールバック情報を関数に渡します。EOS_HPlatform ハンドルがティックしている場合、操作が終了すると、指定したコールバックが実行されます。

コールバックが正常に返されたら、

EOS_Connect_GetProductUserIdMapping を使用してマッピングを取得できます。この関数は、EOS_EExternalAccountType と、外部アカウント ID を入力するための入力バッファおよびバッファ長を取ります。バッファが小さすぎる場合、バッファの適切なサイズが返されます。

EOS_Connect_GetProductUserExternalAccountCount を使用すると、製品ユーザーにリンクされている外部アカウントの数を取得します。

EOS_Connect_CopyProductUserExternalAccountByIndex を使用すると、インデックスを使用して製品ユーザーにリンクされた外部アカウントに関する情報を取得します。

EOS_Connect_CopyProductUserExternalAccountByAccountType を使用すると、製品ユーザーにリンクされた特定のタイプの外部アカウントに関する情報を取得します。

EOS_Connect_CopyProductUserExternalAccountByAccountId を使用すると、アカウント ID を使用して製品ユーザーにリンクされた外部アカウントに関する情報を取得します。

EOS_Connect_CopyProductUserInfo を使用すると、前回ログインした外部アカウントを参照として使用して、製品ユーザーに関する情報を取得します。

製品ユーザー ID が特定の外部プラットフォームにマップされていない場合は、上記に対して返された結果にデータは含まれません。つまり、ユーザーがそのタイプの外部アカウントを製品ユーザー ID に関連付けたことがないことを意味します。

ID トークンを使用したユーザーの確認

ID トークンは、 OpenID Connect プロトコルの一部であり、サーバー側でユーザーの ID を確認するために使用することができます。ID トークンは、製品ユーザー ID など、認証されたユーザーに関する情報を含む JSON Web トークン (JWT) です。ID トークンにより、バックエンド サービスおよびゲーム サーバーは、クライアントから受け取ったユーザー識別子を安全に確認することができます。

ID トークンを使用して、ユーザーの代わりにアクションを実行することはできません。ユーザー ID の確認のためにのみに使用されます。

ユーザーの ID トークンを取得する

ゲーム クライアントは、ユーザーが EOS Connect で認証された後に EOS_Connect_CopyIdToken SDK API を呼び出し、ユーザーの EOS_ProductUserId を含む EOS_Connect_CopyIdTokenOptions 構造体を渡すことで、ローカル ユーザーの ID トークンを取得できます。

出力される EOS_Connect_IdToken 構造体には、ユーザーの EOS_ProductUserId と、ID トークン データを表す JWT が含まれます。なお、ID トークンの構造体の処理が完了したら、 EOS_Connect_IdToken_Release を呼び出して、ID トークンの構造体を解放する必要があります。

取得したら、ゲーム クライアントが他のユーザーにその ID トークンを提供することができます。EOS_Connect_Login 呼び出しが成功するたびに、新しい ID トークンが提供されます。

ID トークンは、ローカル ユーザーの EOS Connect 認証セッションの存続期間中は有効です。ゲーム クライアントが認証セッションを更新する際には、以前使用していた ID トークンの期限がすぐに切れ、必要に応じて新しい ID トークンが使用されることを想定する必要があります。

SDK を使用してゲーム サーバーで ID トークンを検証する

EOS Connect ID トークンの JSON Web キー セット (JWKS) エンドポイントは、https://api.epicgames.dev/auth/v1/oauth/jwks です。

ゲーム サーバーは、 EOS_Connect_VerifyIdToken SDK API を呼び出して、 EOS_Connect_IdToken を含む EOS_Connect_VerifyIdTokenOptions を渡すことで、ID トークンを検証することができます。なお、ゲーム サーバーは、verify を呼び出す前に EOS_Connect_IdToken 構造体の EOS_ProductUserId 部分を、 EOS_ProductUserId_FromString を使用して入力する必要があります。これは、サーバーのユーザー ハンドルは、クライアントのユーザー ハンドルとは異なるためです。

SDK を使用しないでバックエンドで ID トークンを検証する

バックエンド サービスは、公開されている標準的な JWT ライブラリのいずれかを使用して、ID トークンの有効性を検証し、トークン クレームを抽出することができます。この目的のためのライブラリのリストについては、https://jwt.io/ を参照してください。使用するライブラリは、最高のパフォーマンスを実現し、ネットワーク オーバーヘッドを削減するために、取得した JWKS 情報の自動キャッシュを可能にする必要があります。

EOS SDK およびその他のサポート ライブラリは、ID トークンを安全に検証するために必要な手順を実行し、ID トークンに含まれるクレームを安全に信頼できるようにします。実行する手順は、次のとおりです。

  1. トークンにシグネチャ アルゴリズム (「alg」) があり、「none」に設定されていないことを確認します。

  2. Epic Online Services がホストする JWKS エンドポイントを使用して、想定される公開証明書に対する JWT シグネチャを確認します。

  3. トークン発行者 (「iss」) が存在し、ベース URL の先頭が https://api.epicgames.dev であることを確認します。

  4. トークンの発行時刻 (「iat」) が過去の時刻であることを確認します。

  5. トークンの有効期限 (「exp」) が将来であることを確認します。

  6. クライアント ID (「aud」) が、ゲーム クライアントで EOS SDK を初期化する際や、EOS Connect でユーザーを認証する際に使用するクライアント ID と一致していることを確認します。

ID トークンの検証に成功した後は、製品ユーザー ID (「sub」) の値を信頼することができます。

ID トークンの構造

ID トークンは、次の JSON 構造が含まれています。

ヘッダ

キー

説明

alg

文字列

シグネチャ アルゴリズム。

kid

文字列

トークンの署名に使用されたキーの識別子。

ペイロード

キー

説明

aud

文字列

EOS Connect でユーザーを認証するために使用されるクライアント ID。

exp

整数

トークンの有効期限 (エポックからの秒数)。

iat

整数

トークンの発行時刻 (エポックからの秒数)。

iss

文字列

トークンの発行者。常に先頭が https://api.epicgames.dev です。

pfdid

文字列

EOS デプロイメント ID。

pfpid

文字列

EOS 製品 ID。

pfside

文字列

EOS サンドボックス ID。

sub

文字列

認証済みユーザーの製品ユーザー ID。

act

json オブジェクト

接続されたユーザーの認証に使用された外部アカウントを識別します。

外部アカウント情報 (`act`)

キー

説明

eat

文字列

外部アカウントのタイプを識別します。使用可能な値には次のものがあります。apple, discord, epicgames, gog, google, itchio, nintendo_id, nintentdo_nsa_id, oculus, openid, psn, steam, xbl

eaid

文字列

外部アカウント ID。

pltfm

文字列

ユーザーが接続しているプラットフォーム。使用可能な値には次のものがあります。other, playstation,steam, switch, xbox

dty

文字列

デバイス タイプ。ユーザーが接続しているデバイスを識別します。ユーザーが実際のコンソール デバイスから接続していることを安全に確認するために使用できます。使用可能な値には次のものがあります。PSVITA, PS3, PS4, PS5, Switch, Xbox360, XboxOne