カスタム認証
デフォルトではアプリケーションには認証メカニズムがなく、匿名ユーザーの接続が許可されます。 Photonアプリケーションにはカスタム認証を実装するオプションがあります。
Photonでのカスタム認証は非常に柔軟性が高く、 サードパーティーの認証プロバイダや完全にカスタマイズされたソリューションに対応しています。
- Exit GamesがホスティングするFacebook認証プロバイダ。 このページを参照してください
- ユーザーが独自に構築し、ホスティングしているカスタム認証プロバイダ。 弊社はGitレポジトリで認証プロバイダの実装例を提供しています。 ぜひレポジトリをフォークし、プルリクエストを送信してください。 GitHubでソースを確認してください。
目次
認証フロー
以下に、認証プロセスの一般的なフローを記載します。
- クライアントは、使用する認証プロバイダについての情報や必要な認証データを
Connect()を使用してPhoton Serverに渡します。 - Photon Serverは、必要な認証プロバイダをアプリケーションに取得し、以下の手順のいずれかへと進みます。
- 認証プロバイダ設定を検出された場合 -> 認証は手順3に進みます。
- 認証プロバイダ設定が検出されない場合 -> アプリケーションの設定に応じて、クライアントは接続を許可されるか、または拒否されます
- Photon Serverは
Connect()で渡された認証情報で、認証プロバイダを呼び出します。- 認証プロバイダがオンラインの場合 -> 認証は手順4に進みます。
- 認証プロバイダがオフラインの場合 -> 該当するプロバイダの設定に応じて、クライアントは接続を許可されるか、または拒否されます。
- 認証プロバイダが認証情報を処理し、Photon Serverに結果を返します。
- 認証の結果に応じて、クライアントは正常に認証されるか、または拒否されます。
実装
クライアント側
クライアント側ではLoadBalancing APIでカスタム認証を処理します。 関連するパラメータと対象のカスタム認証サービスの設定は、1回のみ必要です。 セットアップが完了すると、接続してその後のエラーが処理されます。
例:
AuthenticationValues authValues = new AuthenticationValues();
authValues.AuthType = CustomAuthenticationType.Custom;
authValues.AddAuthParameter("user", userId);
authValues.AddAuthParameter("pass", pass);
authValues.UserId = userId; // this is required when you set UserId directly from client and not from web service
PhotonNetwork.AuthValues = authValues;
// connectデモ
Unity向けのPUN FreeとPUN+パッケージには、カスタム認証を使用するデモが含まれています。
パッケージを新規の空のプロジェクトにインポートし、実行してください。「Demo Hub」に利用できるデモが表示されます。 「Friends & Custom Auth Demo」を参照してみましょう。
「DemoFriends-Scene」はユーザーログイン用の単純な入力フォームを表示しています。
「GUICustomAuth.cs」でOnGUI()を確認してください。
「Login with Custom Authentication」ボタンのコードは、AuthValuesと接続を設定します。
これによって、設定したサービスへのカスタム認証リクエストが自動的にトリガーされます。
同じファイル内のコールバックメソッドOnCustomAuthenticationFailedに留意してください。 このメソッドには、ユーザーの認証が失敗した場合の反応が実装されています。
サーバー側
Webサーバーが認証リクエストを受信した場合、クエリパラメータを確認し有効化する必要があります。 たとえば、現在の証明書とデータベース内に保存された既存の証明書を比較できます。
受信したパラメータが見つからない場合や無効の場合、返される結果は{ "ResultCode": 3}となります。
有効化が完了すると、以下が返されます：
- 成功:
{ "ResultCode": 1, "UserId": <userId>} - 失敗:
{ "ResultCode": 2}
高度な機能
ユーザー認証以外にも、認証プロバイダから補足情報を返すことができます。 この設定をおこなうには、ユーザーは「認証者」の役割を担うWebサービスとクライアント間にプロトコルのようなものを設定する必要があります。
サーバーにデータを送信
もっとも簡単かつ簡潔なのは、「全か無か」という方式です： クライアントに変数の静的な数を返すかどうか、選択してください。 一部のユースケースでは、クライアントのリクエストへの「オンデマンド」ベースでWebサービスがデータを返す、さらに複雑なアプローチが必要になります。 このサブセクションでは、クライアントからWebサービスにデータを送信する方法を説明します。 このデータは、認証に必要な証明書や補足のパラメータです。 補足のパラメータは、認証レスポンスで返されるサーバー側から利用可能になるデータをリクエストするのに使用されます。 これは非常に有用で、余分なAPIコールが不要となりログインワークフローが単純化されます。
まれに、認証が多くのデータを必要とする場合があります。
一方、ほとんどのWebサーバーにはクエリ文字列で使用される文字数の上限や、URLの長さの閾値があります。
このため、Photonではクライアントから明示的に AuthenticationValues.AuthPostDataフィールドに値を設定してHTTPメソッドをPOSTに変更できるようにしました。
後者には、string型またはbyte[]型を設定することが可能です。
Dictionary<string, object>の場合、ペイロードはJSON文字列に変換されHTTPリクエストのContent-Typeは「applicaton/json」に設定されます。
C# SDKではAuthenticationValuesクラスは、セッターにサポート対象の型ごとのメソッドを提供します。
これが要件や制約となる場合があるため、WebサービスからPOSTメソッドとして認証リクエストを受信したいユーザー向けにPOSTメソッドオプションも提供されています。
つまり、認証パラメータを送信する際にはクエリ文字またはPOSTデータ、もしくはその両方を自由に使用できます。 下表に、設定可能な組み合わせを示します。
| AuthPostData | AuthGetParameters | HTTP methodメソッド |
|---|---|---|
| null | * | GET |
| 空の文字列 | * | GET |
| 文字列（nullではなく、空ではない） | * | POST |
| バイト[]（nullではなく、空も可能） | * | POST |
| Dictionary<string, object> （nullではなく、空も可能） | * | POST (Content-Type="application/json") |
クライアントにデータを返送
Photon ServerはクライアントとWebサービス間のプロキシなので、Photon Serverが処理できる変数に留意してください。
Photon Serverが受信するすべてのHTTP受信レスポンスと同様に、WebサーバはResultCodeと任意のMessageを含むJSONオブジェクトを返す必要があります。
また、Photon Serverが認証時にWebサービスから受信可能なものを以下に記載します：
UserId: これは、認証自体のパラメータとして使用することができますが、クライアント側からリクエストすることも可能です。 Photon Serverが受信すると必ずクライアントに転送されます。AuthenticationValues.UserIdが最初に設定されていない場合は、 ランダムに生成されたUserIdがクライアントに返送されます。 これによってクライアント内のUserIdの値が上書きされ、以降は変更できなくなります。 これはResultCode値が1の場合にのみ返す必要があります。 例：{ "ResultCode": 1, "UserId": "SomeUniqueStringId" }Nickname: これは、認証自体のパラメータとして使用することができますが、クライアント側からリクエストすることも可能です。 これがWebサービスから返されると、クライアント内のNicknameの値が上書きされます。Nicknameは、その後もクライアント側からアップデート可能です。 これはResultCode値が1の場合にのみ返す必要があります。 例：{ "ResultCode": 1, "UserId": "SomeUniqueStringId", "Nickname": "SomeNiceDisplayName" }AuthCookie: セキュアデータとも呼ばれます。Webサービスによって返されるJSONオブジェクトですが、受信した暗号化トークンに埋め込まれるので、クライアント側からアクセスすることはできません。 WebhookまたはWebRPC HTTPリクエストとともに、後で送信することが可能です。 これはResultCode値が1の場合にのみ返す必要があります。 例：{ "ResultCode": 1, "UserId": "SomeUniqueStringId", "AuthCookie": { "SecretKey": "SecretValue", "Check": true, "AnotherKey": 1000 } }Data:クライアントに返すべきその他の値が含まれているJSONオブジェクト。 ネストされた配列やオブジェクトはサポートされない点に留意してください。 これはResultCode値が0または1の場合にのみ返す必要があります。 例：{ "ResultCode": 0, "Data": { "S": "Vpqmazljnbr=", "A": [ 1, -5, 9 ] } }
ResultCodeは唯一必須となっている戻り変数で、他の変数は任意です。
以下の表に、Webサーバーが返すことが可能なものを示します。
| ResultCode | 説明 | UserId | Nickname | AuthCookie | Data |
|---|---|---|---|---|---|
| 0 | 認証が不完全、データのみが返されました* | ||||
| 1 | 認証が成功。 | (任意) | (任意) | (任意) | (任意) |
| 2 | 認証が失敗。証明書が誤っています。 | ||||
| 3 | 無効なパラメータ。 |
*: インスタンスまたは2段階の検証にOAuth 2.0を実装するのに有用です。
クライアントからデータを読み込み
以下は、レスポンスから返された値を取得する方法を示すコードスニペットです：
認証時に返されたカスタムの任意のData をカスタムサーバーで取得するコールバック（v1.66から利用可能）は以下のとおりです：
void OnCustomAuthenticationResponse(Dictionary<string, object> data)
{
// here you can access the returned data
}データ型の変換
このセクションでは、Photonクラウドとウェブサービスの間で交換されるデータ型のみが説明されています。クライアントとPhotonサーバ間のデータ型の詳細はphotonページのシリアル化を参照してください。
Photon Cloud -> ウェブサービス
| C# / .NET (Photonが対応するタイプ) | JavaScript / JSON |
|---|---|
byte
|
number |
short
|
|
int
|
|
long
|
|
double
|
|
bool
|
bool |
string
|
string |
byte[] (byte array length < short.MaxValue)
|
string (Base64 encoded) |
T[] (array of supported type T, length < short.MaxValue)
|
array |
Hashtable (対応されているタイプの, カウント < short.MaxValue, Photon実装が望ましい)
|
object |
Dictionary (対応されているタイプのキーや値, カウント < short.MaxValue)
|
object |
null
|
null
|
サンプルリクエストデータ（タイプは連結されます）
Photonクラウドから送信：
ウェブサーバによって読み込み：
ウェブサービス - >Photon Cloud
各JavaScript/JSONタイプをC#/.Netの同等のものに照らし合わせる表：
| JavaScript / JSON | C# / .Net |
|---|---|
| object |
Dictionary
|
| array |
object[] (array of objects)
|
| number (integral) |
long
|
| number (floating) |
double
|
| string |
string
|
| boolean |
bool
|
null (タイプではない)
|
null
|
undefined（送信時）
|
null
|
サンプルのレスポンスデータ（タイプは連結されています）
Webサーバーから送信：
Photon Cloudから読み込み：
トラブルシューティング
カスタム認証に失敗すると、以下のコールバックがトリガーされます：
void OnCustomAuthenticationFailed(string debugMessage)
{
// The `debugMessage` could be what the authentication provider returned.
}ダッシュボードで設定した認証URLがHTTPエラーを返す場合、Photonサーバーは負荷を避けるため短い時間、認証コールを一時停止します。 URLを設定またはテストする際には、この「バックオフ」時間を考慮するようにしてください。
ベストプラクティス
- 特に、失敗した場合に備えるため認証プロバイダから返される結果には、読解可能な
Messageを含める必要があります。これによって、デバッグの手間を大幅に省くことができます。 - クライアント側からではなくダッシュボードで、静的なキー/値のセットを設定してください。 これにより、結果のクエリ文字列でキーが重複するのを防ぎます。
- セキュリティ上の理由から、プレーンテキストのパスワードを認証パラメータとして送信しないでください。
- Photonダッシュボードでクエリ文字列パラメータを設定することを推奨します。 これによって、リクエストの起源を確認できます。
- パラメータの設定には
AuthenticationValuesメソッドを使用し、AuthGetParametersの値を直接変更しないでください。 こうすることで、クエリ文字列の変形を防ぐことができます。 - 認証プロバイダから返される結果には、特にエラーの場合に備えて読解可能な
メッセージを含める必要があります、 これにより、デバッグの手間が大幅に軽減されます。
ユースケース例：古いクライアントバージョンをブロック
カスタム認証を使用して、古いバージョン（または予期せぬバージョン）を使用しているクライアントから受信した接続を拒否することができます。この場合、特定のエラーを返してユーザーにアップデートを依頼することが可能です。 これを実現するには、カスタム認証リクエスト内で該当のバージョンを送信する必要があります。クエリ文字列パラメータでおこなうか、またはPOSTデータ引数としておこなうかはユーザー自身が決めることができます。 以下の例では、クエリ文字列パラメータを使用しています：
string version = PhotonNetwork.gameVersion;
// string version = Application.version; // if you use the version from Unity
PhotonNetwork.AuthValues = new AuthenticationValues();
PhotonNetwork.AuthValues = CustomAuthenticationType.Custom;
PhotonNetwork.AuthValues.AddAuthParameter("version", version); // HTTP GET
PhotonNetwork.ConnectUsingSettings(version);カスタム認証のURLがhttps://example.comの場合、リクエストはhttps://example.com?version={version}として送信されます。
認証プロバイダ実装から受信するバージョンを取得し、比較してください。
バージョンが許可された場合、{ "ResultCode": 1 }を返してください。
もし許可されない場合には、任意のカスタム値（1以外）でResultCodeを返し、できる限りメッセージも送信してください。
例： { "ResultCode": 5, "Message": "Version not allowed." }。