Auth インターフェース

注記: Auth Web API で認証することもできますEOS Web API リファレンスを参照してください。詳細は Auth Web API ドキュメントを参照してください。

Auth インターフェースを使用して、プレイヤーはゲームから直接 Epic Games アカウントにサインインすることができます。プレイヤーの認証、アクセス トークンの取得、その他 Epic Online Services とのアカウント関連のやりとりを行うには、このインターフェーを使用します。プレイヤーが Epic Games アカウントにサインインすると、Friends、Presence、User Info、Ecom インターフェースなど、他の Epic Account Services へのアクセスを可能にします。

Connect インターフェースを使用しても、プレイヤーはサポートされている ID プロバイダ経由でゲームにサインインすることができます。Connect インターフェースの詳細については、「Connect インターフェースのドキュメント」を参照してください。Auth インターフェースと Connect インターフェースの違いを以下の表にまとめました。

Auth インターフェースを使用するには、お使いのゲーム (製品) で Epic Account Services (EAS) が有効になっており、 基本プロファイル のデータへのアクセスに対して ユーザーの許可 を得る必要があります。EAS は Developer Portal 上で有効にすることができます。EAS が有効になっておらず、ユーザーの許可を得ていない場合でも、EOS SDK と Auth インターフェースを初期化することはできます。ただし、バックエンド サービスへのすべての Auth インターフェースの関数呼び出しは失敗します。

注記: ** Epic Online Services (EOS) SDK を使用するには、ローカル ネットワーク、ルーター、ファイアウォールが指定されたホスト アドレスにアクセス可能でなければなりません。ホスト アドレスの一覧は、ドキュメント「ファイアウォール考慮事項」を参照してください。

認証関数にアクセスするには、 EOS_HAuth ハンドルが必要です。このハンドルは、 Platform インターフェース の関数である EOS_Platform_GetAuthInterface を呼び出すことで取得できます。このハンドルは、Auth インターフェースの関数がユーザー情報にアクセスするために必要です。

EAS のオンライン機能とのインタラクションを開始するには、プレイヤーは始めに有効なEpic アカウントでログインする必要があります。プレイヤーがログインできるように設定するには、ローカル プレイヤーの アカウント 資格情報を含む EOS_Auth_LoginOptions 構造体を使用して EOS_Auth_Login 関数を呼び出します。完了時には、ログイン試行の成否にかかわらず、EOS_Auth_OnLoginCallback 型のコールバック関数が実行されます。

ブランド レビュー プロセスでは、Epic Games がゲームのブランドを検証します。認証されると、組織 以外のプレイヤーは、ゲームに統合されている Epic Account Services を使用できるようになります。ブランド レビューの前に、プレイヤーが外部アカウントでゲームにログインしようとすると、エラーが発生します。詳細については、「ブランド レビュー アプリケーション プロセス」ドキュメントを参照してください。

EOS_Auth_LoginOptions は、EOS_AUTH_LOGIN_API_LATEST に設定した ApiVersion 変数と、次の情報を含む Credentials 変数 (EOS_Auth_Credentials 型) で初期化する必要があります。

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

各プラットフォームで優先されるログイン タイプは以下のとおりです。

Epic Games Launcher に関連付けられているアプリケーションが開始すると、ランチャーはいくつかのパラメータを持つコマンドラインを提供します。その形式は次のとおりです。

このコマンドラインでは次に挙げるフィールドが重要となります。

この情報はアプリケーションによって解析され、 EOS_Auth_Credentials 構造体を介して EOS_Auth_Login に渡す必要があります。EOS_Auth_Credentials には、 Id 、 Token 、 Type の 3 つの変数があります。Id は空白にすることができます。このログイン メソッドでは ID は必要ないためです。Token には AUTH_PASSWORD コマンドライン パラメータの交換コードを指定します。最後に、 Type は EOS_LCT_ExchangeCode とします。

ご使用のゲームは、ゲーム セッション中における自動ログイン用に、長時間有効な Epic リフレッシュ トークンをローカル デバイスに保存します。詳細については、「永続的なログイン」セクションを参照してください。

このゲームでは、ローカル ユーザー アカウントのアクセス トークンをプラットフォームから取得します。EOS_LCT_ExternalAuth ログイン タイプを使用して、プラットフォーム ユーザーが Epic アカウントにログインされます。ログイン フローの詳細については、「外部アカウント認証」を、プラットフォーム コードの統合についてはコンソール固有のドキュメントを参照してください。

適切な権限を持っている場合のみ、コンソールのドキュメントにアクセスすることができます。コンソール用 EOS SDK およびその関連ドキュメントへのアクセス方法については、「使用開始の手順：EOS SDK ダウンロードのタイプ 」ドキュメントを参照してください。

PC とモバイル デバイスは、通常、長期間有効な更新トークンによって有効化され、認証バックエンドによって付与された、デバイスとユーザー アカウントに固有の永続的なログインを使用します。これらのプラットフォームでは、SDK は必要に応じてこれらのトークンを自動的に格納、取得し、ログイン後に毎回、これらのトークンを更新します。詳細については、「永続的なログイン」セクションを参照してください。

EOS SDK バージョン 1.5 では、EOS_Auth_LoginOptions には EOS_EAuthScopeFlags タイプ (API リンク) で ScopeFlags という名前の新しいフィールドが含まれます。スコープとは、アプリケーションが正しく機能するために必要な許可のセットです。たとえば、アプリケーションでユーザーのフレンド リストを表示する場合、EOS_AS_FriendsList スコープを要求する必要があります。ユーザーはログイン フローの途中でこれに対する同意を求められます。ユーザーが要求されたスコープのいずれかに同意しない場合はログインが失敗します。同意を要求する場合、要求は Developer Portal で 製品 に対して構成されたスコープと厳密に一致している必要があります。

Epic Games Launcher に関連付けられているアプリケーションが開始すると、ランチャーはいくつかのパラメータを持つコマンドラインを提供します。その形式は次のとおりです。

このコマンドラインでは次に挙げるフィールドが重要となります。この情報はアプリケーションによって解析され、 EOS_Auth_Login に EOS_Auth_Credentials 構造体を介して提供される必要があります。EOS_Auth_Credentials には 3 つの変数があります。Id 、 Token 、 Type の 3 つの変数があります。Type には EOS_LCT_ExchangeCode を使用します。

フィールド Id はこのログイン型では使用しないため、空白にしておきます。最後に、AUTH_PASSWORD の交換コードを Token として提供します。

PC およびモバイル プラットフォームでは、Epic Games Launcher 外で永続的なユーザー ログインをサポートするには、 EOS_LCT_AccountPortal ログイン タイプを使用します。

ユーザーが Epic Account に正常にログインすると、SDK は認証バックエンドから自動的に更新トークンを受け取ります。そして、デバイスにローカルでログインしているユーザーのローカルキーチェーンに更新トークンを保存します。ローカル キーチェーンの場合、SDK はデバイスのオペレーティング システムにより提供される安全な資格情報ストアを使用します。

自動的にローカル ユーザーをログインさせる場合、ゲームはまず EOS_LCT_PersistentAuth ログイン型を使用して EOS_Auth_Login を呼び出します。SDK が長期間有効な資格情報を管理するため、Id および Token 入力フィールドは NULL に設定する必要があります。SDK はローカル ユーザーのキーチェーンで更新トークンの有無を確認し、見つかった場合は Epic アカウントにユーザーがログインするために自動的に使用します。プラットフォームへのログインに成功すると、SDK はローカル キーチェーンの更新トークンを自動的に更新します。

EOS_Auth_Login が何らかの理由で失敗する場合は、プラットフォームのデフォルトのログイン方法で続行してください。EOS_Auth_Login が更新トークンを見つけても、サーバーがトークンを拒否するためにログインに失敗する場合 (つまり、トークンの欠如、接続またはサーバーの問題、操作の取り消し、リトライの待機以外の理由で呼び出しが失敗する場合)、そのトークンは使用できないものであり、以降のセッションで失敗し続けるため、アプリケーションはトークンを削除します。EOS_Auth_DeletePersistentAuth を呼び出して、ユーザーのローカル キーチェーンに格納されている資格情報をすべて明示的に削除します。その後アプリケーションはプラットフォームのデフォルト ログイン フローを進めます。

ユーザーがログインした後に自動ログインを無効にするには、 EOS_Auth_Logout を呼び出してログアウトし、 EOS_Auth_DeletePersistentAuth を呼び出して認証バックエンドのユーザーの長時間有効なログイン セッションを無効にします。また、これによりローカル ユーザーのキーチェーンから長時間有効な更新トークンが削除されます。

ログアウトするには、 EOS_Auth_LogoutOptions データ構造体を使用して EOS_Auth_Logout 関数を呼び出します。操作が完了すると、 EOS_Auth_OnLogoutCallback タイプのコールバック関数が実行されます。EOS_Auth_LogoutOptions 構造体を次のように初期化します。

Auth インターフェース ハンドル、EOS_Auth_LogoutOptions 構造体、およびコールバック関数を EOS_Auth_Logout に渡します。EOS_HPlatform ハンドルがティックしている場合、操作が終了すると、指定したコールバックが実行されます。

EOS_LCT_PersistentAuth ログイン タイプを使用している場合、 EOS_Auth_DeletePersistentAuth 関数も呼び出して、認証バックエンド上の長時間有効なログオン セッションを無効にする必要があります。これにより、ローカル デバイス上のローカル ユーザー ログインを永久に消去します。

アプリケーションの存続期間中、EOS SDK はローカル ユーザーの認証ステータスを定期的に確認します。これは、そのユーザーが他の場所でサインインしていないことを確認するうえで有効であり、アプリケーション自体の原因以外でアクセスできなくなることを防ぐのに役立ちます。ユーザーの認証ステータスが変化したときは必ずアプリケーションに通知するために、Auth インターフェースでは、ローカル プレイヤーの認証ステータスが変化したときに、EOS_Auth_OnLoginStatusChangedCallback 型のコールバックを実行します。EOS_Auth_AddNotifyLoginStatusChanged 関数を使用して、このプロセスに独自のコールバック関数をアタッチできます。

アプリケーション存続期間中に接続が失われたとしても、それがユーザーがログアウトしたことを示すわけではありません。EOS バックエンドは、ログアウト イベントが発生すると、Auth インターフェイスに明示的に通知します。これは、ユーザーが正式にオフラインと見なされていると見なすことができる唯一のケースです。サービス障害などのユーザー接続の問題やローカル ハードウェアの不具合によって、さまざまな API 機能が失敗する場合があります。それらのインタラクションなしでゲームが続行できる場合に推奨する一連の行動は、ユーザーがログアウトすることなく最終的に接続が回復すると想定してプレイを続行することです。

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

外部アカウントを使用して**EOS_Auth_Login** でログインするには、 EOS_Auth_Credentials の Type を EOS_LCT_ExternalAuth に、 ExternalType を外部資格情報タイプ (使用可能なすべてのメソッドについては、「EOS_EExternalCredentialType」を参照) に、そして Token を外部認証トークンに設定します。たとえば、Steam でログインするときに EOS_ECT_STEAM_APP_TICKET を ExternalType として使用し、 Token は Steam Encrypted Application Ticket になります。

関連付けられていない外部アカウントが原因で外部認証ログインが失敗すると EOS_InvalidUser が返されます。EOS_ContinuanceToken が EOS_Auth_LoginCallbackInfo データに設定されます。外部アカウント ログインを継続し外部アカウントを関連付けるために EOS_ContinuanceToken と LinkAccountFlags を EOS_LA_NoFlags に設定して EOS_Auth_LinkAccount を呼び出します (多くの場合、アカウント ポータルまたはピンの付与を使用した同意が必要)。その後、外部アカウントはユーザーの Epic アカウントにリンクされます。その後、外部アカウントはユーザーの Epic アカウントに関連づけられます。

外部アカウント認証を使用してプロバイダの関連付けを可能にするには、Developer Portal の ID プロバイダ を製品に対して設定する必要があります。詳細については、「ID プロバイダを設定する」を参照してください。

追加のローンチ オプション、プロモーション、ニュースなどを組み込むランチャーをゲームで提供する場合、ランチャーでログイン フローを管理しなければなりません。Epic Games Launcher で生成された Exchange codes は短時間で無効になりますので、Exchange code が無効にならないように注意する必要があります。Epic Games Launcher が直接ゲーム アプリケーションを起動しない場合、次のパターンを使用します。

1. Epic Games Launcher は、上記に記したコマンドラインで Exchange code を Associating With the Epic Games Launcher セクションに渡してサードパーティ ランチャーを開始します。
2. サードパーティ ランチャーは、 EOS_Auth_Login を使用してその Exchange Code でプレイヤーをログインします。EOS_Auth_ClientCredentials 構造体の Type フィールドと Token フィールドをそれぞれ EOS_LCT_ExchangeCode とコマンドラインの Exchange Code に設定して EOS_Auth_LoginOptions を初期化します。
3. プレイヤーがゲームの起動を選択するときに、 EOS_Auth_CopyUserAuthToken API を使用してトークン詳細のコピーを取得します。EOS_Auth_Token から RefreshToken をコピーし、 EOS_Auth_Token_Release API を呼び出して、SDK によって割り当てられたメモリを解放します。
4. ゲームが起動時に読み取ることができる環境変数を設定することで、更新トークンをゲーム アプリケーションに渡します。サードパーティ ランチャーの終了時にプレイヤーをログアウトしないでください。リフレッシュ トークンが無効になってしまいます。
5. ゲーム プロセスの起動時に、ゲームは EOS_Auth_Login API を使用してプレイヤーをログインすることができます。EOS_Auth_ClientCredentials 構造体の Type フィールドと Token フィールドをそれぞれ EOS_LCT_RefreshToken と環境変数の更新トークンに設定して、 EOS_Auth_LoginOptions を初期化します。

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

ゲーム クライアントは、ユーザーがログインした後に EOS_Auth_CopyIdToken SDK API を呼び出し、ユーザーの EOS_EpicAccountId を含む EOS_Auth_CopyIdTokenOptions 構造体を渡すことで、ローカル ユーザーの ID トークンを取得できます。

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

取得したら、ゲーム クライアントが別のユーザーにその ID トークンを提供することができます。ID トークンは、ログインしたローカル ユーザーがいつでも使用できます。

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

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

バックエンド サービスは、公開されている標準的な 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 を初期化する際や、Epic アカウント サービスでユーザーを認証する際に使用するクライアント ID と一致していることを確認します。

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

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

ヘッダ

ペイロード

脚注

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

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

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

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

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

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

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

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