Connect インターフェース

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

20 分で読めます

Connect インターフェース

Connect インターフェースを使用すると、プレイヤーはサポートされている ID プロバイダ経由でゲームにサインインすることができます。サポートされている ID プロバイダと設定の詳細については、「ID プロバイダを管理する」を参照してください。

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

  • Epic Online Services (EOS) ゲーム サービスにアクセスできる。
  • クロスプラットフォーム サービス内で、共通の一意のユーザー識別子を生成する。
  • 外部 ID プロバイダのアカウントを Epic Games のサービスにリンクさせる。

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

Auth インターフェースを使用しても、プレイヤーはゲームから直接 Epic Games アカウントにサインインすることができます。Auth インターフェースの詳細については、「Auth インターフェースのドキュメント」を参照してください。Auth インターフェースと Connect インターフェースの違いを以下の表にまとめました。

Auth インターフェースConnect インターフェース
プレイヤー IDプレイヤーの Epic Games アカウント ID。プレイヤーはメールとパスワードの組み合わせ、またはリンクされた外部アカウント1 でサインインすることができます。1 つ以上のサポートされた ID プロバイダ2にリンクしているプレイヤーの製品ユーザー ID (PUID)。 PUID は単一の製品に固有であることに注意してください。
アクセスプレイヤーはすべての PC (Windows、Mac、Linux) プラットフォームおよびストアフロントにおいて Epic Account Services にサインインすることができます。注記： ゲーム コンソールとモバイル プラットフォームへは将来的にアクセスできるようになります。プレイヤーは自分のゲーム内でアカウントを認証して、あらゆるプラットフォーム (PC (Windows、Mac、Linux)、コンソール、モバイル) やストアフロントで EOS ゲーム サービスにアクセスすることができます。
サポートされているサービスプレイヤーは Friends3, Presence4 インターフェースと Ecom5 インターフェース、および EOS ソーシャル オーバーレイ6 にアクセスすることができます。プレイヤーは、マルチプレイヤー、プログレッション、モデレーション、オペレーションなどのゲーム サービスを利用することができます。
アクセス トークンの存続時間EOS_Platform_Tick7 を呼ぶ間、ゲームは自動的にトークンを更新します。ゲームは期限切れ通知イベント 8 に基づいてプレイヤーのトークンを定期的に更新します。

ユーザーを管理する

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

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

実行すること：

  • ユーザーが外部アカウント プロバイダで引き続き有効であることを確認する
  • ユーザーが Epic のサービスにアクセスできる期間を延長する

実行しないこと：

  • 暗黙的にトークンを更新する
  • 長時間のアクセス権を付与する

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

Connect Interface Account Flow

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

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

ユーザー認証

EOS Connect で認証するには、次の手順に従ってください。

  1. サポートされているプラットフォームの外部認証情報を含む EOS_Connect_LoginOptions を使用して EOS_Connect_Login を呼び出します。提供された　ID プロバイダ (Steam, Xbox, or Nintendo など)　でサインインすることができます。対応する ID プロバイダの完全リストについては、「ID プロバイダの管理」ドキュメントを参照してください。たとえば、Epic Games アカウントで認証するには、ローカル Epic ユーザーの ID トークンを EOS_Auth_CopyIdToken から取得して EOS_EExternalCredentialType を EOS_ECT_EPIC_ID_TOKEN に設定します。

  2. EOS_HConnect ハンドル、 EOS_Connect_LoginOptions 構造体、およびコールバック情報を EOS_Connect_Login に渡します。

認証後、これらの追加のアクションが発生する場合があります。

  • EOS_HPlatform ハンドルがティックしている場合、操作が終了すると、指定したコールバックが実行されます。
  • 結果が成功の場合、アプリケーションは認証を必要とするその他のインターフェースへのアクセスに進むことができます。
  • ユーザーが存在しない場合、ログイン API は EOS_InvalidUser という結果を EOS_ContinuanceToken と一緒に返します。トークンはログイン試行の詳細を提供するため、ログイン フローの次のステップで必要になります。

クロスプラットフォーム対応のゲームの場合、初回ログイン時に、他のプラットフォームでプレイしたことがあるかどうかを確認します。その場合、プレイヤーはそのプラットフォームの外部アカウントを使用して認証し、既存のゲーム進行に接続し、その現在のプラットフォーム アカウントを既存の EOS ユーザーにリンクさせることができます (アカウントをリンクする を参照してください)。そうでない場合は、新しい EOS ユーザーを作成して再出発するかどうかを尋ねることができます (ユーザーを作成する を参照してください)。

ユーザー認証更新通知

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

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

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

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

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_ContinuanceToken で EOS_InvalidUser という結果が返されます。外部アカウントが他の製品ユーザー ID と関連付けられている場合、この操作は、現在ログインしている製品ユーザー ID から外部アカウントを削除しますが、キーチェーンからは外部アカウントを削除しません。つまり、外部アカウントはその製品のクエリ API で返されなくなりますが、外部アカウントは残りの製品ユーザー ID で使用することができます。

アカウントのリンク操作と同様に、リンク解除操作の履歴は、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_Login が EOS_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 パラメータを設定します。

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

他のインターフェースは、リモート ユーザーまたはその他の外部ユーザー (同一サーバー上のフレンド、プレイヤーなど) では 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 を返します。

一般的な使用例は、ローカルユーザーと同じアカウント システムを介して接続している他のユーザーにクエリを実行することです (例えば、Steam 上のプレイヤーが Steam 上にいる他のプレイヤーにマッチメイキングを問い合わせる)。別のアカウント システムの外部アカウント ID によるクエリは絶対に使用できません。例えば、Xbox をプレイしている人は別のプレイヤーの Steam 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 の確認のためにのみに使用されます。

OpenId プロバイダが返す ID トークンには、ヘッダーに kid パラメータを設定する必要があります。

ユーザーの 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。
pfsid文字列EOS サンドボックス ID。
sub文字列認証済みユーザーの製品ユーザー ID。
actjson オブジェクト接続されたユーザーの認証に使用された外部アカウントを識別します。
外部アカウント情報 (act)
キー型説明
eat文字列外部アカウントのタイプを識別します。使用可能な値には次のものがあります。apple, discord, epicgames, gog, google, itchio, nintendo_id, nintendo_nsa_id, oculus, openid, psn, steam, xbl
eaid文字列外部アカウント ID。
pltfm文字列ユーザーが接続しているプラットフォーム。使用可能な値には次のものがあります。other、playstation、steam、switch、xbox`
dty文字列デバイス タイプ。ユーザーが接続しているデバイスを識別します。ユーザーが実際のコンソール デバイスから接続していることを安全に確認するために使用できます。使用可能な値には次のものがあります。PSVITA, PS3, PS4, PS5, Switch, Xbox360, XboxOne

脚注

  1. リンク済の外部アカウントの詳細については「Auth インターフェース」ドキュメントを参照してください。 ↩

  2. ID プロバイダの詳細については、「ID プロバイダを管理する」を参照してください。 ↩

  3. Friends インターフェースの詳細については、「Friends インターフェース」ドキュメントを参照してください。 ↩

  4. Presence インターフェースの詳細については、「Presence インターフェース」ドキュメントを参照してください。 ↩

  5. Ecom インターフェースの詳細については、「Ecom インターフェース」ドキュメントを参照してください。 ↩

  6. EOS ソーシャル オーバーレイの詳細については、「ソーシャル オーバーレイの概要」ドキュメントを参照してください。 ↩

  7. EOS_Platform_Tick 呼び出しの詳細については、「API リファレンス」ドキュメントを参照してください。 ↩

  8. 期限切れ通知イベントの詳細については、「Connect インターフェース」ドキュメントを参照してください。 ↩