1. Epic GamesDeveloper
  3. Auth インターフェース

Auth インターフェース

オンライン サービスでローカル ユーザーを認証および確認する

Auth インターフェース
Learn to use this Beta feature, but use caution when shipping with it.

Online Services Auth インターフェース は、オンライン サービスでローカル ユーザーを認証および確認するための API を提供します。ローカル ユーザーが認証されるとアカウント ID が返され、プロジェクトでその ID を使用して他の多くのオンライン サービス機能とやり取りできます。

API の概要

関数

Auth インターフェースに含まれている関数の概要を次の表に示しています。

関数 説明
Login ローカル ユーザーを認証します。
Logout ローカル ユーザーに対する認証セッションを終了します
ModifyAccountAttributes 認証済みアカウントと関連付けられている属性を変更します。
QueryExternalServerAuthTicket サインイン済みユーザーに代わってサーバー間の呼び出しを行うためにチケットをクエリします。チケットの使用は 1 回限りであるため、チケットが必要とされる呼び出しを繰り返し行う場合、ユーザーはこの API を毎回呼び出して新しいチケットを取得する必要があります。
QueryExternalAuthToken サービス アカウントを、サービス タイプが異なるサービス アカウントと結び付けるためのトークンを取得します。
QueryVerifiedAuthTicket 確認済み認証セッションをリモート クライアントで作成するためにチケットを取得します。
CancelVerifiedAuthTicket 確認済み認証セッションと関連付けられているチケットを取り消し、そのチケットと関連付けられているリソースをクリーンアップします。
セッション  
BeginVerifiedAuthSession リモート ユーザーに対する確認済み認証セッションを開始します。
EndVerifiedAuthSession リモートの確認済み認証セッションとそれに関連付けられているリソースをクリーンアップします。
ユーザーの取得  
GetLocalOnlineUserByOnlineAccountId オンライン アカウント ID を使用して、ログインしているユーザー アカウントを取得します。
GetLocalOnlineUserByPlatformUserId プラットフォーム ユーザー ID を使用して、ログインしているユーザー アカウントを取得します。
GetAllLocalOnlineUsers ログインしているすべてのユーザー アカウントを取得します。
Event Listening (イベントのリッスン)  
OnLoginStatusChanged ユーザーのログイン ステータスが変化した結果としてのイベント トリガー
OnPendingAuthExpiration まもなく期限切れになる認証トークンの結果としてのイベント トリガー
OnAccountAttributesChanged 認証済みアカウントと関連付けられている追加属性が変更された結果としてのイベント トリガー
ヘルパー  
IsLoggedIn ローカル ユーザーのログイン ステータスをクエリします。

列挙型クラス

Auth Interface では、ユーザーのログイン ステータス (ELoginStatus)、認証チケット オーディエンス (ERemoteAuthTicketAudience)、認証トークン メソッド (EExternalAuthTokenMethod)を表す 3 つの列挙型クラスが定義されています。

ELoginStatus

列挙子 説明
NotLoggedIn プレイヤーはログインしていないか、ローカル プロファイルを選択しています。
UsingLocalProfile プレイヤーはローカル プロファイルを選択しているが、ログインしていません。
LoggedInReducedFunctionality プレイヤーはログインしているが、オンライン サービスでの機能が低下している可能性があります。
LoggedIn プレイヤーはログインしており、プラットフォーム特有の認証サービスによって検証済みです。

ERemoteAuthTicketAudience

列挙子 説明
Peer ピアによる検証に適したチケットを生成します。
DedicatedServer 専用サーバーによる検証に適したチケットを生成します。

EExternalAuthTokenMethod

列挙子 説明
Primary Auth インターフェースで提供されているプライマリ認証方式を使用して、外部認証トークンを取得します。
Secondary Auth インターフェースで提供されているセカンダリ認証方式を使用して、外部認証トークンを取得します。

プライマリ構造体

ユーザーとそのログイン情報に関連付けられた主要な構造体は、FAccountInfo 構造体です。

FAccountInfo

メンバー 型 説明
AccountId FAccountId このユーザーのアカウント ID であり、ユーザーのオンライン プラットフォーム アカウントを表しています。
PlatformUserId FPlatformUserId このオンライン ユーザーと関連付けられているプラットフォーム ユーザー ID
LoginStatus ELoginStatus この現在のユーザーのログイン ステータス
Attributes TMap<FSchemaAttributeId, FSchemaVariant> 追加のアカウント属性

プロセス フロー

Login

Login は、選択されているオンライン サービスでローカル ユーザーを認証します。成功すると、Login は FAccountInfo 構造体を返します。FAccountInfo 構造体には、Auth インターフェースに含まれている他の多くの関数を使用するために必要な FAccountId が入っています。ログインに成功すると、そのユーザーの LoginStatus が ELoginStatus::LoggedIn に設定されます。ユーザーが自分のアカウントにログインした後に、他の条件に基づいてログイン ステータスが後から ELoginStatus::UsingLocalProfile または ELoginStatus::LoggedInReducedFunctionality に変わることがあります。

複数のローカル ユーザーがログインを必要としている場合、各ユーザーは個別にログインする必要があります。また、明示的なログインを必要としないプラットフォーム サービスもあります。そのようなサービスでは、アプリケーションの開始時にユーザーは暗黙的にログインしています。詳細については、個別のプラットフォーム サービスのドキュメントを参照してください。

外部サーバーで認証する

ゲームでは、ゲーム特有の機能を提供するカスタム Web サービスが使用されることがよくあります。そのようなサービスでは、アクセスを提供する前に、呼び出し元の身元を確認する必要があります。QueryExternalServerAuthTicket は、外部サーバーでユーザーを認証するための 1 回限りのチケットを取得します。

認証済みユーザーを別のオンライン サービスと結び付ける

多くのゲームでは複数のオンライン サービスを利用する必要があります。よくある例として、1 つのプラットフォーム サービスがその機能を拡張するもう 1 つのサービスと組み合わされていることがあります。QueryExternalAuthToken は、ユーザーが二次的なサービス用に別のログイン認証情報を提供しなくて済むように、別のオンライン サービスでの認証に適したトークンを返します。

このトークンは、ほとんどのプラットフォームでは OpenId トークンであり、それがユーザーの身元の保証を提供します。このトークンは、CredentialsType を ExternalAuth に設定し、トークンを CredentialsToken として渡すことで、二次的なサービスの Login メソッドに提供されます。

P2P または専用サーバーでユーザー ID を確認する

ユーザーは、ゲーム サーバーやピアツーピア ネットワークに接続するとき、自分の ID を提供し、認証セッションが追跡できるようにする必要があります。クライアント側では、QueryVerifiedAuthTicket を使用して、ユーザーの ID を提供するゲーム サーバーに送信される 1 回限りのチケットを取得します。ゲーム サーバーでプレイ セッションが終了したときに、CancelVerifiedAuthTicket を呼び出して、そのチケットを取り消します。

QueryVerifiedAuthTicket の呼び出しで取得されるチケットは 1 回限りのチケットであるため、ユーザーが新しい確認済みセッションを始めるごとに QueryVerifiedAuthTicket が呼び出される必要があります。CancelVerifiedAuthTicket にも同様のロジックが適用されるため、CancelVerifiedAuthTicket はユーザーが作成したチケットごとに呼び出される必要があります。

ゲーム サーバーは、クライアントが接続するときにそのクライアントが提供したチケットを使用して BeginVerifiedAuthSession を呼び出します。正常に完了すると、提供されたチケットと関連付けられているユーザーに対して確認済み認証セッションが始まります。そのゲームが終了したときに、EndVerifiedAuthSession を使用して関連リソースがクリーンアップされます。

リモート ゲーム サーバーに接続するユーザー クライアントでのこのプロセスの概要を以下に示します。

  • クライアントが、QueryVerifiedAuthTicket を呼び出してセッション認証チケットを取得します。
  • クライアントがセッション認証チケット、チケット ID、アカウント ID をサーバーに送信します。
  • サーバーがそれらの情報を受信し、それを使用して BeginVerifiedAuthSession を呼び出し、確認済み認証セッションを開始します。
  • そのセッションの終了時に、クライアントが CancelVerifiedAuthTicket を呼び出して認証チケットを取り消し、サーバーが EndVerifiedAuthSession を呼び出して認証セッションを終了させます。

ピアツーピア ネットワーク モデルでは、上記のプロセスとは異なります。各ユーザー クライアントが、接続している各リモート クライアント用の新しい認証チケットを作成します。その後に、ゲーム サーバーで認証するための手順が、各リモート ピアに対して次のように適用されます。

  • 各リモート ピアが QueryVerifiedAuthTicket を呼び出して、既存の他の各ピアで認証するための 1 回限りのチケットを取得します。
  • 既存の各ピアが BeginVerifiedAuthSession を呼び出して、新しいリモート ピアに対する確認済み認証セッションを開始します。

インターフェースの実装によっては、ピアツーピアがサポートされていないことがあります。詳細については、使用するプラットフォーム サービスのドキュメントを参照してください。

アカウント属性を変更する

ゲーム コードでは、ModifyAccountAttributes の呼び出しでの必要に応じて、追加のカスタム属性が FAccountInfo 構造体に格納されていることがあります。

変更された属性は、Logout が呼び出されるまでユーザーのデータに保持されます。These attributes will not persist after the auth session is ended. Logout destroys the user's FAccountInfo struct which contains these attributes.

Logout

Logout は、ローカル ユーザーに対する現在の認証セッションを終了させ、関連するリソースと構造体をクリーンアップします。

例

プラットフォーム サービスでログインする

	UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
	UE::Online::IAuthPtr AuthInterface = OnlineServices->GetAuthInterface();

	UE::Online::FAuthLogin::Params Params;
	Params.PlatformUserId = PlatformUserId;
	Params.CredentialsType = LoginCredentialsType::ExchangeCode;
	Params.CredentialsToken = TEXT("1234567890"); // Exchange code from command-line

	AuthInterface->Login(MoveTemp(Params)).OnComplete([](const UE::Online::TOnlineResult<UE::Online::FAuthLogin>& Result)
	{
		if(Result.IsOk())
		{
			const TSharedRef<UE::Online::FAccountInfo> AccountInfo = Result.GetOkValue().AccountInfo;
			// アカウント情報オブジェクトにアクセスできるようになりました
		}
		else
		{
			FOnlineError Error = Result.GetErrorValue();
			// エラーが処理できるようになりました
		}
	});

ウォークスルー

  1. GetServices をパラメータなしで呼び出してデフォルトのオンライン サービスを取得した後に、Auth インターフェースにアクセスします。

             UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
         UE::Online::IAuthPtr AuthInterface = OnlineServices->GetAuthInterface();

  2. ユーザーがログインするために必要なパラメータをインスタンス化します。

             UE::Online::FAuthLogin::Params Params;
         Params.PlatformUserId = PlatformUserId;
         Params.CredentialsType = LoginCredentialsType::ExchangeCode;
         Params.CredentialsToken = TEXT("1234567890"); // Exchange code from command-line

  3. Login.OnComplete コールバックでは、ログインに成功すればアカウント情報を登録し、そうでなければ、発生したエラーを処理します。

             AuthInterface->Login(MoveTemp(Params)).OnComplete([](const UE::Online::TOnlineResult<UE::Online::FAuthLogin>& Result)
         {
             if(Result.IsOk())
             {
                 const TSharedRef<UE::Online::FAccountInfo> AccountInfo = Result.GetOkValue().AccountInfo;
                 // アカウント情報オブジェクトにアクセスできるようになりました
             }
             else
             {
                 FOnlineError Error = Result.GetErrorValue();
                 // エラーが処理できるようになりました
             }
         });

Online Subsystem のコードを変換する

Online Services Auth インターフェースは、Online Subsystem Identity インターフェース が所有するすべてのコードに対応しています。

詳細情報

ヘッダ ファイル

詳細については、必要に応じて Auth.h ヘッダ ファイルで直接確認してください。Auth インターフェースのヘッダ ファイル「Auth.h」は次のディレクトリにあります。

Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online

UE のソース コードの入手方法については、「Unreal Engine のソース コードをダウンロードする」のドキュメントを参照してください。

関数パラメータおよび戻り型

関数パラメータおよび戻り型 (パラメータの渡し方、関数が戻す結果の処理など) については、「Online Services の概要」ページの「Functions (関数)」セクションを参照してください。

Ask questions and help your peers Developer Forums

Write your own tutorials or read those from others Learning Library

On this page
Related documents