Auth Web API で認証することもできます。EOS Web API リファレンスを参照してください。詳細は Auth Web API ドキュメントを参照してください。
Epic Games のサービスは、認証と承認に OAuth 2.0 プロトコルを使用し、Web サーバーとクライアントサイド アプリケーションの一般的なユースケースをサポートします。Epic は、特定のユースケース向けにカスタムのグラント種別も導入しました。
始める前に、Epic から OAuth 2.0 クライアント資格情報を取得する必要があります。これらはクライアント ID とクライアント シークレットの形式で提供され、Epic 承認サーバーからアクセス トークンをリクエストする際に使用されます。詳細については「Epic アカウント サービス入門」を参照してください。
シナリオ
Epic Games ストアのゲーム クライアント
Epic Games ストアから起動したゲーム クライアントは、1 回限りの交換コードを使用して Epic の承認サーバーで認証されます。この交換コードは Epic Launcher によって生成され、コマンドライン引数としてその ゲーム クライアント に渡されます。
ゲーム クライアントが起動すると、クライアント資格情報と交換コードを含めた Epic トークン エンドポイントへのリクエストを送信します。応答には、アクセス トークン 、認証されたクライアントと アカウント に関する情報、オプションの 更新トークン が含まれます。
ゲーム クライアントは、Epic サービスへのリクエストに毎回アクセストークンを添付します。アクセス トークンは、信頼されたゲーム サーバーに渡して検証したり、サービス間のリクエストで使用することもできます。
含めるべき更新トークンがある場合は、それも併せてトークンの応答に添付されます。ゲーム クライアントは、アクセス トークンの有効期限 (通常 2 時間) が切れたら更新トークンを使用する必要があります。これは通常、アクセス トークンが発行されてから 2 時間以内に発生します。
Epic Games Launcher の認証フローについての説明図。画像を拡大するにはクリックします。クリックして拡大表示。
Web サーバー アプリケーション
サーバーサイド アプリケーションの場合、まずユーザーは 承認コード を取得するために Web ブラウザーの Epic 承認フローに誘導されます。ユーザーは、Epic Games アカウントを使用してログインするよう求められます。さらに、アプリケーションの承認を求められる場合があります。承認されると、ユーザー エージェントはクエリ パラメータとして添付した承認コードとともに Web アプリケーションにリダイレクトします。
リダイレクト後、Web サーバーは、クライアント資格情報と承認コードを含めた Epic トークン エンドポイントへのリクエストを送信します。応答には、アクセス トークンと、認証されたクライアントとアカウントに関する情報が含まれます。
Web サーバーは、Epic サービスへのリクエストに毎回アクセストークンを添付します。
認証
認証フローの最初のステップとして、ユーザーは Epic アカウント サービスを使って認証手続きをしなければなりません。OAuth 2.0 による認証と、追加のカスタムグラント種別のみをサポートします。
クライアントが、トークンをリクエストするために必要な情報 (交換コード、承認コード、ユーザー資格情報など) を取得すると、アクセス トークンのリクエストを開始します。
アクセス トークンをリクエストする
アクセス トークンをリクエストするには、クライアントはクライアント資格情報 (クライアント ID とクライアント シークレット) とユーザー資格情報を渡して Epic トークン エンドポイントに HTTP リクエストを発行します。
Epic トークン エンドポイントは https://api.epicgames.dev/epic/oauth/v1/token です。アクセス トークンは必要ではなくなったことを表示するには、https://api.epicgames.dev/epic/oauth/v1/revoke を使用します。このエンドポイントは、RFC 7009 - OAuth 2.0 Token Revocation を実行します。
クライアント資格情報は Basic 承認を使用して Authorization ヘッダに渡されます。このエンドポイントは以下の POST パラメータをサポートします。
| パラメータ名 | 説明 |
grant_type |
使用されているグラント タイプ。exchange_code, password, refresh_token または client_credentials。 |
deployment_id |
クライアントが認証を試みているデプロイメント ID。この ID は、デプロイを必要とする他のサービスとのやり取りに影響します。 デプロイが公開されていない場合、資格の与えられたユーザーのみがログインできます。デプロイおよびデプロイメント ID の詳細については、「製品、サンドボックス、およびデプロイメント ID」を参照してください。 注記：Ecommerce API を使用したり、ゲーム クライアントが使用するアクセス トークンをリクエストしたりするためには、この一意の識別子を使用する必要があります。 |
scope |
ユーザーが要求するスコープ (アクセス許可) のスペース区切りのリスト。例: basic profile、 friends_list、 および presence | password グラント タイプ向け |
password のグラント タイプは開発中に使用できますが、この製品が関連付けられている組織のメンバーであるアカウントに対してのみ許可されます。注記 password グラント タイプは、2FA を有効にすると機能しません。 | |
username |
グラント タイプでのみ使用される、アカウントのユーザー名 (メールアドレス)。 |
password |
password グラント タイプでのみ使用される、アカウントのパスワード。 | exchange_code グラント タイプ向け |
exchange_code |
ランチャーがゲーム クライアントに渡す交換コード。 exchange_code グラント タイプでのみ使用されます。 | authorization_code グラント タイプ向け |
code |
承認サーバーから受信した承認コード。 | client_credentials グラント タイプ向け (「Web アプリケーション」を参照してください ) |
client_id |
アプリケーションの OAuth クライアント ID。 |
client_secret |
アプリケーションの OAuth クライアント シークレット。 |
なお、これらのパラメータはリクエスト ボディに含める必要があります。クエリ パラメータは無視されます。
以下のスニペットはリクエストの例です ( password グラントタイプを使用)
応答には以下のフィールドが含まれます。
| 応答 | 説明 |
|---|---|
access_token | アクセス トークン。プレフィックスを含む場合があります (例：eg1~[token]) 。Epic サービスに対するすべてのリクエストで、この値は Bearer タイプを使用して、そのままの形で Authorization ヘッダに渡される必要があります。 |
expires_in | トークンの有効期限切れまでの秒数。 |
expires_at | ISO 8601 形式での有効期限日付。 |
account_id | トークンが発行されるユーザーの Epic アカウント ID。 |
client_id | このトークンを発行するために使用されるクライアント ID。 |
application_id | クライアントが関連付けられるアプリケーション ID。 |
token_type | 発行されるトークンのタイプ。値は常に bearer です。 |
refresh_token | クライアントの設定に応じ、オプションでリフレッシュ トークンが返されます。このリフレッシュ トークンを使用して、有効期限の前または後でセッションを延長することができます。 |
refresh_expires | リフレッシュ トークンが有効期限になるまでの秒数。 |
refresh_expires_at | リフレッシュ トークン の ISO 8601 形式での有効期限日付。 |
以下のスニペットはリクエストの例です。
このアクセス トークンは、Epic サービスへの Authorization ヘッダに常にそのままの形で渡される必要があります。例: Authorization:Bearer eyJraWQiOiJ0RkM...`
Web アプリケーション
Web アプリケーションおよびサーバーサイド アプリケーションの場合は、アクセス トークンを要求する前に承認コードを取得する必要があります。Web 承認を使用する前に、Epic OAuth クライアント をリダイレクト URL を使用して構成する必要があります。
ユーザーレスのクライアント設定 (つまり、クライアント ポリシーがユーザーを要求しない 場合、ユーザー情報を取得する必要はありません。したがって以下のリダイレクト命令をスキップすることができます。client_credentials のみでクライアントを初期化することができます。
フローを開始するには、アプリケーションがユーザーを承認ページにリダイレクトする必要があり、ユーザーはそこで Epic Games アカウントへのログインを要求されます。承認 URL は以下のとおりです。
追加パラメータ redirect_uri={redirect_uri} を使って複数のリダイレクト URL を定義することができます。2 つ以上のリダイレクトに対する認証 URL は以下になります。
ユーザーはログイン後、承認コードとともに設定したリダイレクト URL にリダイレクトされます。アプリケーションは「アクセス トークンのリクエスト」で解説したように、このコードを利用して authorization_code グラント種別が使用されるアクセス トークンを取得します。
また Epic では、リクエストとコールバック間の状態の維持を可能にしたり、 クロスサイト リクエスト フォージェリ攻撃 の防止に使用される、オプションの state パラメータをサポートしています。
以下はユーザーの認証後のリダイレクト先の例です。
アクセス トークンの検証
オフライン検証
アクセス トークンは、トークンの信頼性を検証するために使用されるヘッダーと署名を含む JWT (JSON Web トークン) です。
シグネチャを検証する前に、Epic のサービスから JSON Web キー (JWK) として公開された 公開鍵 を取得してください。Epic は現在のすべての公開鍵を格納する JWK セット 形式を使用した単一のエンドポイントを用意しています。キーは頻繁には変更されませんが、予告なくローテーションする可能性があります。
JWK のエンドポイントはこちらです。https://api.epicgames.dev/epic/oauth/v1/.well-known/jwks.json
公開鍵をフェッチするクライアントは、妥当な期間、それらをキャッシュしなければなりません。鍵がローテーションしても、与えられた鍵の ID のキーは変わりません。
以下のスニペットは公開鍵のエンドポイントからの応答例です。
オンライン検証
オフライン検証が選択できない場合、有効なアクセス トークンを使用してトークン情報のエンドポイントを呼び出すこで、オンラインでの検証が実行可能です。このエンドポイントは、 トークン イントロスペクション の仕様を実装しています。
トークン情報エンドポイントはこちらです。https://api.epicgames.dev/epic/oauth/v1/tokenInfo
以下のスニペットはトークンを検証するリクエストの例です。
以下のスニペットはトークン情報エンドポイントからの応答例です。
このエンドポイントを使用すれば、アクセス トークンと更新トークンの両方を検証できます。
Epic Games ストアのゲーム クライアント
Epic Games Store を介して接続されたゲーム クライアントを使用する場合、ゲーム クライアントは exchange_code グラント種別を使用して、クライアント資格情報と、ランチャーからゲームに渡されたコードを転送することで、アクセス トークンを取得します。
開発中は password グラント種別を使用することもできます。これにより、ランチャーと統合しなくても Epic Services はゲーム クライアントを認証することができるようになります。
ゲームが Epic Games Launcher によって開始されるとき、以下のコマンドライン パラメータで起動されます。
| パラメータ | 説明 |
|---|---|
AUTH_LOGIN | 交換コードでは使用されません。 |
AUTH_PASSWORD | ゲーム クライアントで使用される資格情報。認証サーバーに渡される交換コードが含まれます。 |
epicapp | 内部アプリケーション名。 |
epicenv | (常に Prod) で起動される環境。 |
epicusername | ランチャーで認証されるアカウントの表示名。 |
epicuserid | ランチャーで認証される Epic アカウント ID。 |
epiclocale | ユーザー設定に基づいた、または、システム言語に基づいた優先ロケール。 |
epicovt | 所有権検証トークン情報が記述されたファイルへの完全パス。 |
epicsandboxid | アプリケーションが実行されるサンドボックス。たとえば、Live、Stage、Dev のサンドボックスに関連づいた ID。 |
以下は、ランチャーが渡すコマンド ライン パラメータの例です。
アカウント情報
アクセス トークンを取得すると、ユーザーを代理して Epic サービスにリクエストを送信することができます。例えば、この機能を使用して、ユーザーやフレンドの表示名が取得できます。
アクセス トークン経由
アクセス トークンから直接情報を取得することもできます。アクセス トークンは、JSON Web Token (JWT) としてエンコードされ、ヘッダーにはトークンと署名の種類、ユーザー、クライアント、セッションおよび署名などのペイロードについての情報を記述されます。ライブラリを使用して JWT をデコードすることを推奨しますが、できない場合は、仕様を参照してください。
ペイロードには以下のアイテムが含まれます。
| クレーム | 型 | 説明 |
|---|---|---|
| iss | 文字列 | トークンを発行した Epic Games 認証サーバーのベース URI。 |
| sub | 文字列 | このクレームは、 client_credentials グラント種別の使用時は存在しません。 |
| aud | 文字列 | 承認リクエストで指定されたクライアント ID。 |
| iat | 整数 | トークンが発行された時刻を示す UNIX タイムスタンプ。 |
| exp | 整数 | トークンの有効期限を示す UNIX タイムスタンプ。 |
| jti | 文字列 | このトークン固有の ID。 |
| t | 文字列 | トークンの種類。常に epic_id となります。これにより、EG1 トークンのバージョン プレフィックスが置き換えられます。 |
| scope | 文字列 | ユーザーに承認されたスコープのスペース区切りのリスト。 |
| dn | 文字列 | ユーザーの表示名。 |
| appid | 文字列 | 承認リクエストで指定されたアプリケーション ID。 |
| pfpid | 文字列 | トークン リクエストで指定されたデプロイメント対象の製品 ID。 |
| pfsid | 文字列 | トークン リクエストで指定されたデプロイ対象のサンドボックス ID。 |
| pfdid | 文字列 | トークン リクエストで指定されたデプロイ ID。 |
前の例のトークンを使用して、ペイロードをデコードすると、以下の内容が確認できます。
アカウントの取得
アクセス トークンの情報に加えて、ログインしたアカウント、またはアプリケーションとやり取りした他のアカウントについての同様の情報を要求することもできます。
プライバシーへの懸念から、こちら側からの事前申請に同意済みのユーザーに対してのみアカウント情報をリクエストできます。
アカウント情報エンドポイントは「https://api.epicgames.dev/epic/id/v1/accounts」です。このエンドポイントを呼び出す際は、解決したいアカウントに対して 1 つ以上の accountId クエリ パラメータを指定する必要があります。リクエスト 1 回 あたり 50 アカウントに制限されています。
以下のスニペットは複数アカウントを取得するリクエストの例です。
次のスニペットは、このリクエストからの応答例です。