注記: Auth Web API で認証することもできます。EOS Web API リファレンスを参照してください。詳細は Auth Web API ドキュメントを参照してください。
Auth インターフェース
Auth インターフェースを使用して、プレイヤーはゲームから直接 Epic Games アカウントにサインインすることができます。プレイヤーの認証、アクセス トークンの取得、その他 Epic Online Services とのアカウント関連のやりとりを行うには、このインターフェーを使用します。プレイヤーが Epic Games アカウントにサインインすると、Friends、Presence、User Info、Ecom インターフェースなど、他の Epic Account Services へのアクセスを可能にします。
Connect インターフェースを使用しても、プレイヤーはサポートされている ID プロバイダ経由でゲームにサインインすることができます。Connect インターフェースの詳細については、「Connect インターフェースのドキュメント」を参照してください。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 に基づいてプレイヤーのトークンを定期的に更新します。 |
ユーザーレスのクライアント設定 (つまり、クライアント ポリシーがユーザーを要求しない 場合、client_credentials のみでクライアントを初期化することができます。ユーザー情報は必要ありません。
Auth インターフェースを使用するには、お使いのゲーム (製品) で Epic Account Services (EAS) が有効になっており、 基本プロファイル のデータへのアクセスに対して ユーザーの許可 を得る必要があります。EAS は Developer Portal 上で有効にすることができます。詳細は「Epic のドキュメント」を参照してください。EAS が有効になっておらず、ユーザーの許可を得ていない場合でも、EOS SDK と Auth インターフェースを初期化することはできます。ただし、バックエンド サービスへのすべての Auth インターフェースの関数呼び出しは失敗します。
認証関数
認証関数にアクセスするには、 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 型) で初期化する必要があります。
| プロパティ | 値 |
|---|---|
| ApiVersion | EOS_AUTH_CREDENTIALS_API_LATEST |
| Id | ログインしているユーザーの ID。ログインしているユーザーの ID。他の多くの関数とは異なり、メール アドレスや表示名など、ユーザーが理解しやすいものにする必要があります。 |
| Token | ユーザーのログイン資格情報または認証トークン。 |
| Type | このログイン試行で使用している資格情報のタイプ。EOS_ELoginCredentialType を使用すると、利用可能な資格情報の種類が一覧表示されます。 |
| SystemAuthCredentialsOptions | このフィールドは、システム固有のオプション用です。必要に応じて使用します。 |
| ExternalType | Type が EOS_LCT_ExternalAuth に設定されている場合、このフィールドは使用する外部認証方法を示します。使用可能なすべてのメソッドのリストについては、EOS_EExternalCredentialType を参照してください。 |
Auth インターフェース ハンドル、 EOS_Auth_LoginOptions 構造体、およびコールバック情報を関数に渡します。EOS_HPlatform ハンドルがティックしている場合、操作が終了すると、指定したコールバックが実行されます。
Epic アカウントの優先されるログイン タイプ
SDK 1.5 バージョン で優先されるプラットフォームごとのログイン タイプは次のとおりです。
| プラットフォーム | ログイン型 | 概要 |
|---|---|---|
| コンソール | EOS_LCT_ExternalAuth | 関連付けられた Epic アカウントにプラットフォーム ユーザーを自動ログインするために使用するプラットフォーム アクセス トークン。 |
| Steam クライアント | EOS_LCT_ExternalAuth | ローカルの Steam ユーザーを、関連付けられた Epic アカウントに自動ログインさせるために使用する Steam セッション チケット。 |
| Epic Games Launcher | EOS_LCT_ExchangeCode | ランチャーから受け取ってユーザーの自動ログインに使用される交換コード。 |
| PC およびモバイル デバイス上のその他のストア プラットフォームおよびスタンドアロン ディストリビューション | EOS_LCT_PersistentAuth での EOS_LCT_AccountPortal | ユーザーは、Epic アカウントの資格情報を使用してログインするように求められます。その後、長期間有効な更新トークンがローカルに保存され、アプリケーションを連続して実行しても自動ログインできるようになります。 |
コンソール
このゲームでは、ローカル ユーザー アカウントのアクセス トークンをプラットフォームから取得します。EOS_LCT_ExternalAuth ログイン タイプを使用して、プラットフォーム ユーザーが Epic アカウントにログインされます。ログイン フローの詳細については、「外部アカウント認証」を、プラットフォーム コードの統合についてはコンソール固有のドキュメントを参照してください。
PC またはモバイル デバイス
PC とモバイル デバイスは、通常、長期間有効な更新トークンによって有効化され、認証バックエンドによって付与された、デバイスとユーザー アカウントに固有の永続的なログインを使用します。これらのプラットフォームでは、SDK は必要に応じてこれらのトークンを自動的に格納、取得し、ログイン後に毎回、これらのトークンを更新します。詳細については、「永続的なログイン」セクションを参照してください。
Epic Games Launcher
Epic Games Launcher に関連付けられているアプリケーションが開始すると、ランチャーはいくつかのパラメータを持つコマンドラインを提供します。その形式は次のとおりです。
このコマンドラインでは次に挙げるフィールドが重要となります。
| プロパティ | 値 |
|---|---|
| AUTH_LOGIN | このフィールドにはユーザー ID が入りますが、現在は使用されていません。 |
| AUTH_PASSWORD | このフィールドには、ログイン中にトークンとして提供される必要がある交換コード自体が入ります。 |
| AUTH_TYPE | このタイプは「exchangecode」を読み取ります。EOS_Auth_LoginCredentials には EOS_LCT_ExchangeCode タイプを使用する必要があることを示しています。 |
この情報はアプリケーションによって解析され、 EOS_Auth_Credentials 構造体を介して EOS_Auth_Login に渡す必要があります。EOS_Auth_Credentials には、 Id 、 Token 、 Type の 3 つの変数があります。Id は空白にすることができます。このログイン メソッドでは ID は必要ないためです。Token には AUTH_PASSWORD コマンドライン パラメータの交換コードを指定します。最後に、 Type は EOS_LCT_ExchangeCode とします。
Auth スコープ
EOS SDK バージョン 1.5 では、EOS_Auth_LoginOptions には EOS_EAuthScopeFlags タイプ (API リンク) で ScopeFlags という名前の新しいフィールドが含まれます。スコープとは、アプリケーションが正しく機能するために必要な許可のセットです。たとえば、アプリケーションでユーザーのフレンド リストを表示する場合、 EOS_AS_FriendsList スコープを要求する必要があります。ユーザーはログイン フローの途中でこれに対する同意を求められます。ユーザーが要求されたスコープのいずれかに同意しない場合はログインが失敗します。同意を要求する場合、要求はデベロッパー ポータルで 製品 に対して構成されたスコープと厳密に一致している必要があります。
複数のユーザーが単一のローカル デバイスに同時にログインし、同じ共有されている EOS_HPlatform インスタンスを使用することができます。
Epic Games Launcher に関連付ける
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 として提供します。
Epic Games Launcher 以外からの Epic アカウントへのユーザー ログインを持続する
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 構造体を次のように初期化します。
| プロパティ | 値 |
|---|---|
| ApiVersion | EOS_AUTH_LOGOUT_API_LATEST |
| LocalUserId | The EOS_EpicAccountId |
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 プロバイダを設定する」を参照してください。
Game Launcher を Epic Games ストアと統合する
追加のローンチ オプション、プロモーション、ニュースなどを組み込むランチャーをゲームで提供する場合、ランチャーでログイン フローを管理しなければなりません。Epic Games Launcher で生成された Exchange codes は短時間で無効になりますので、Exchange code が無効にならないように注意する必要があります。Epic Games Launcher が直接ゲーム アプリケーションを起動しない場合、次のパターンを使用します。
- Epic Games Launcher は、上記に記したコマンドラインで Exchange code を
Associating With the Epic Games Launcherセクションに渡してサードパーティ ランチャーを開始します。 - サードパーティ ランチャーは、
EOS_Auth_Loginを使用してその Exchange Code でプレイヤーをログインします。EOS_Auth_ClientCredentials構造体のTypeフィールドとTokenフィールドをそれぞれEOS_LCT_ExchangeCodeとコマンドラインの Exchange Code に設定してEOS_Auth_LoginOptionsを初期化します。 - プレイヤーがゲームの起動を選択するときに、
EOS_Auth_CopyUserAuthTokenAPI を使用してトークン詳細のコピーを取得します。EOS_Auth_TokenからRefreshTokenをコピーし、EOS_Auth_Token_ReleaseAPI を呼び出して、SDK によって割り当てられたメモリを解放します。 - ゲームが起動時に読み取ることができる環境変数を設定することで、更新トークンをゲーム アプリケーションに渡します。サードパーティ ランチャーの終了時にプレイヤーをログアウトしないでください。更新トークンが無効になります。
- ゲーム プロセスの起動時に、ゲームは
EOS_Auth_LoginAPI を使用してプレイヤーをログインすることができます。EOS_Auth_ClientCredentials構造体のTypeフィールドとTokenフィールドをそれぞれEOS_LCT_RefreshTokenと環境変数の更新トークンに設定して、EOS_Auth_LoginOptionsを初期化します。
ID トークンを使用したユーザーの確認
ID トークンは、 OpenID Connect プロトコルの一部であり、サーバー側でユーザーの ID を確認するために使用することができます。ID トークンは、アカウント ID など、認証されたユーザーに関する情報を含む JSON Web トークン (JWT) です。ID トークンにより、バックエンド サービスおよびゲーム サーバーは、クライアントから受け取ったユーザー識別子を安全に確認することができます。
ID トークンを使用して、ユーザーの代わりにアクションを実行することはできません。ユーザー ID の確認のためにのみに使用されます。
ユーザーの 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 トークンは、ログインしたローカル ユーザーがいつでも使用できます。
SDK を使用してゲーム サーバーで 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 を使用して入力する必要があります。これは、サーバーのユーザー ハンドルは、クライアントのユーザー ハンドルとは異なるためです。
SDK を使用しないでバックエンドで ID トークンを検証する
バックエンド サービスは、公開されている標準的な JWT ライブラリのいずれかを使用して、ID トークンの有効性を検証し、トークン クレームを抽出することができます。この目的のためのライブラリのリストについては、https://jwt.io/ を参照してください。使用するライブラリは、最高のパフォーマンスを実現し、ネットワーク オーバーヘッドを削減するために、取得した JWKS 情報の自動キャッシュを可能にする必要があります。
EOS SDK およびその他のサポート ライブラリは、ID トークンを安全に検証するために必要な手順を実行し、ID トークンに含まれるクレームを安全に信頼できるようにします。実行する手順は、次のとおりです。
- トークンにシグネチャ アルゴリズム (「alg」) があり、「none」に設定されていないことを確認します。
- Epic Online Services がホストする JWKS エンドポイントを使用して、想定される公開証明書に対する JWT シグネチャを確認します。
- トークン発行者 (「iss」) が存在し、ベース URL の先頭が https://api.epicgames.dev であることを確認します。
- トークンの発行時刻 (「iat」) が過去の時刻であることを確認します。
- トークンの有効期限 (「exp」) が将来であることを確認します。
- クライアント ID (「aud」) が、ゲーム クライアントで EOS SDK を初期化する際や、Epic アカウント サービスでユーザーを認証する際に使用するクライアント ID と一致していることを確認します。
ID トークンの検証に成功した後は、Epic アカウント ID (「sub」) の値を信頼することができます。
ID トークンの構造
ID トークンは、次の JSON 構造が含まれています。
ヘッダ
| キー | 型 | 説明 |
|---|---|---|
| alg | 文字列 | シグネチャ アルゴリズム。 |
| kid | 文字列 | トークンの署名に使用されたキーの識別子。 |
| t | 文字列 | トークンのタイプ。常に、 id_token に設定されます。 |
ペイロード
| キー | 型 | 説明 |
|---|---|---|
| appid | 文字列 | EAS アプリケーション ID。 |
| aud | 文字列 | Epic アカウント サービスでユーザーを認証するために使用されるクライアント ID。 |
| dn | 文字列 | Epic アカウントの表示名。 |
| exp | 整数 | トークンの有効期限 (エポックからの秒数)。 |
| iat | 整数 | トークンの発行時刻 (エポックからの秒数)。 |
| iss | 文字列 | トークンの発行者。常に先頭が https://api.epicgames.dev です。 |
| pfdid | 文字列 | EOS デプロイメント ID。 |
| pfpid | 文字列 | EOS 製品 ID。 |
| pfsid | 文字列 | EOS サンドボックス ID。 |
| sub | 文字列 | 認証済みユーザーの Epic アカウント ID。 |
| eat | 文字列 | 外部アカウントのタイプ。このオプション クレームは、ユーザーが外部アカウントのクレデンシャルを使用して Epic アカウントにログインした場合に発生します (ローカル プラットフォーム認証を介してなど)。 |
| eadn | 文字列 | 外部アカウント表示名。 このクレームは常に存在するわけではありません。 |
| pltfm | 文字列 | ユーザーが接続しているプラットフォーム。eat クレームが存在する場合含まれます。使用可能な値には次のものがあります。 other playstation switch xbox 使用可能な値には次のものがあります。
|
脚注
リンク済の外部アカウントの詳細については「Auth インターフェース」ドキュメントを参照してください。 ↩
ID プロバイダの詳細については、「ID プロバイダを管理する」を参照してください。 ↩
Friends インターフェースの詳細については、「Friends インターフェース」ドキュメントを参照してください。 ↩
Presence インターフェースの詳細については、「Presence インターフェース」ドキュメントを参照してください。 ↩
Ecom インターフェースの詳細については、「Ecom インターフェース」ドキュメントを参照してください。 ↩
EOS ソーシャル オーバーレイの詳細については、「ソーシャル オーバーレイの概要」ドキュメントを参照してください。 ↩
EOS_Platform_Tick呼び出しの詳細については、「API リファレンス」ドキュメントを参照してください。 ↩期限切れ通知イベントの詳細については、「Connect インターフェース」ドキュメントを参照してください。 ↩