Auth インターフェース

ログイン / ログアウト機能など、ユーザー アカウントの確認を処理するインターフェースです。

Auth インターフェース

Auth インターフェースでは、ローカル ユーザーが Epic アカウントを使用してログインすることができます。これにより、Friends インターフェース、Presence インターフェース、UserInfo インターフェース、Ecom インターフェースなどの Epic Account Services (EAS) が提供する各種機能にアクセスできます。Auth インターフェース は、EOS との Epic アカウント関連のインタラクションを処理し、ユーザーを認証してアクセス トークンを取得する機能を提供します。

Auth インターフェースを使用するには、お使いの製品で Epic アカウント サービス (EAS) が有効になっており、 基本プロファイル のデータにアクセスすることに関して [ユーザーの許可] を得る必要があります。EAS は [Developer Portal (デベロッパー ポータル)] で有効にできます。詳細については、「[Epic のドキュメント]」を参照してください。EAS が有効になっておらず、ユーザーの許可を得ていない場合でも、EOS SDK と Auth インターフェースを初期化することはできます。ただし、バックエンド サービスへのすべての Auth インターフェースの関数呼び出しは失敗します。

認証関数

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

ログインする

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

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

TypeEOS_LCT_ExternalAuth に設定されている場合、このフィールドは使用する外部認証方法を示します。使用可能なすべてのメソッドのリストについては、[EOS_EExternalCredentialType] を参照してください。

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

Epic アカウントの優先されるログイン タイプ

SDK 1.5 バージョン で優先されるプラットフォームごとのログイン タイプは次のとおりです。

プラットフォーム

ログイン型

概要

コンソール

EOS_LCT_ExternalAuth

関連付けられた Epic アカウントにプラットフォーム ユーザーを自動ログインするために使用するプラットフォーム アクセス トークン。

PC またはモバイル デバイス

EOS_LCT_PersistentAuth を使用する EOS_LCT_AccountPortal

ローカルに格納されている長期間有効なアクセストークンを使用した Web ログイン フロー。

Epic Games Launcher

EOS_LCT_ExchangeCode

ランチャーから受け取ってユーザーの自動ログインに使用される交換コード。

コンソール

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

PC またはモバイル デバイス

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

Epic Games Launcher

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

-AUTH_LOGIN=unused -AUTH_PASSWORD=<password> -AUTH_TYPE=exchangecode -epicapp=<appid> -epicenv=Prod -EpicPortal  -epicusername=<username> -epicuserid=<userid> -epiclocale=en-US

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

プロパティ

AUTH_LOGIN

このフィールドにはユーザー ID が入りますが、現在は使用されていません。

AUTH_PASSWORD

このフィールドには、ログイン中にトークンとして提供される必要がある交換コード自体が入ります。

AUTH_TYPE

このタイプは「exchangecode」を読み取ります。EOS_Auth_LoginCredentials には EOS_LCT_ExchangeCode タイプを使用する必要があることを示しています。

この情報はアプリケーションによって解析され、 EOS_Auth_Credentials 構造体を介して EOS_Auth_Login に渡す必要があります。EOS_Auth_Credentials には、 IdTokenType の 3 つの変数があります。Id は空白にすることができます。このログイン メソッドでは ID は必要ないためです。Token には AUTH_PASSWORD コマンドライン パラメータの交換コードを指定します。最後に、 TypeEOS_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 に関連付けられているアプリケーションが開始すると、ランチャーはいくつかのパラメータを持つコマンドラインを提供します。その形式は次のとおりです。

-AUTH_LOGIN=unused -AUTH_PASSWORD=<password> -AUTH_TYPE=exchangecode -epicapp=<appid> -epicenv=Prod -EpicPortal -epicusername=<username>-epicuserid<userid> -epiclocale=en-US

このコマンドラインでは次に挙げるフィールドが重要となります。この情報はアプリケーションによって解析され、 EOS_Auth_LoginEOS_Auth_Credentials 構造体を介して提供される必要があります。EOS_Auth_Credentials には 3 つの変数があります。IdTokenType の 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_OnLoginStatusChangedCallback コールバック関数は、ローカル ユーザーの認証ステータスが変化したときに実行されます。認証ステータスの変化には、Auth インターフェースを使用した明示的なログインとログアウトが含まれます。つまり、ログイン (またはログアウト) イベントのコールバックと、このコールバックの両方を受け取ることになります。

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

現在の認証ステータスをチェックする

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

外部アカウント認証

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

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

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

![drawing](https://docs.google.com/drawings/d/12345/export/png)

Game Launcher を Epic Games ストアと統合する

追加のローンチ オプション、プロモーション、ニュースなどを組み込むランチャーをゲームで提供する場合、ランチャーでログイン フローを管理しなければなりません。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 トークンを使用したユーザーの確認

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 トークンに含まれるクレームを安全に信頼できるようにします。実行する手順は、次のとおりです。

  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 トークンの構造

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。