Custom Authentication

默認情況下,所有應用程序都允許匿名用戶連接,沒有任何認証機制。 Photon提供了為Photon應用執行自定義認証的選項。

Photon的自定義認証很靈活。 它支持已知的第三方認証供應商,也支持完全個性化的解決方案。

  • Facebook認証供應商,由Exit Games托管。查看教程
  • 自定義認証提供者,由您建立-也許由您托管。 我們通過Git倉庫提供認証提供者的示例執行。 您可以自由地分叉這個倉庫,並向我們發送您的拉動請求。 您可以在GitHub上找到來源。

Contents

認証流程

下面的步驟描述了認証過程的基本流程:

Photon Cloud: Custom Authentication Flow Diagram
Custom authentication flow diagram

  1. 您的客戶端通過Connect()向Photon伺服器傳遞關於使用哪個認証提供者的信息和必要的認証數據。{% if Bolt %}這是由Photon Bolt和Photon Cloud整合的內部處理。
  2. Photon伺服器為您的應用程序獲取所需的認証提供者,並採取以下步驟之一
    • 找到認証提供者的配置 --> 認証繼續進行第三步。
    • 沒有找到認証提供者的配置 -> 客戶端將被允許連接或拒絕,這取決於您的應用程序的設置。
  3. Photon伺服器用Connect()傳遞的認証信息來調用認証提供者。
    • 認証提供者在線 -> 認証繼續進行第四步。
    • 認証提供者離線 -> 客戶端被允許連接或被拒絕,這取決於相應的提供者設置。
  4. 認証提供者處理認証信息並將結果返回給Photon伺服器。
  5. 根據認証結果,客戶端將被成功認証或拒絕。

Back To Top

Photon Cloud設置

您可以從您的Photon應用程序介面設置所有的認証供應商。 進入應用程序的詳細信息頁面,打開自定義認証部分。

。 當配置自定義認証時,提醒您,變化可能需要一段時間來傳遞。

Back To Top

添加一個認証提供者

配置自定義認証提供者很簡單,可以在幾秒鐘內從您的[Photon應用程序介面](@WebDashboardBaseUrl)完成。

Photon Cloud: Custom Authentication Creation
Creating a custom authentication provider

如螢幕截圖所示,您可以輸入您的認証URL,並決定在您的認証服務不在線或因其他原因不工作時是否拒絕客戶。 此外,您還可以選擇添加鍵/值對,這些鍵/值對將作為查詢字符串參數在每個請求中被發送到認証服務。

A best practice is to set from the dashboard only "sensitive" and static key/value pairs that should be "invisible" to the client. Examples:
  • API public key to make sure that the request is really coming from one of Photon servers.
  • API version of custom authentication to better handle future changes.

此外,還有一種可能,即允許或拒絕試圖連接到您的應用程序的匿名客戶,而不考慮任何配置的認証供應商。 默認情況下,這一點是啟用的,這意味著最初所有客戶都被授權連接到您的應用程序,無論是否經過認証。 您可以在您的Photon應用程序介面的應用程序詳情頁面的認証部分檢查。 該選項只有在您添加了至少一個認証提供者時才會顯示。 如果沒有配置認証提供者,它將以默認值(啟用)隱藏。

Photon Cloud: Custom Authentication, Allow Anonymous Clients
Allow Anonymous Clients Using Custom Authentication

Back To Top

更新或刪除一個認証提供者

您也可以從應用程序的詳細信息頁面選擇編輯現有的認証提供者。 在編輯表格中,您可以更新所有設置或完全刪除認証提供者。

Photon Cloud: Custom Authentication Editing
Updating or deleting an existing custom authentication provider

Back To Top

執行

如果您在Photon Cloud中使用facebook認証,您可以跳過這一部分。

Back To Top

客戶端

在客戶端,API將處理自定義認証-您只需設置相關參數和目標自定義認証服務一次。 一旦設置完畢,連接並處理最終的錯誤。

Example:

在這個片段中,為了簡化選擇了一個非常基本的密碼的認証憑証。 形成以下的查詢字符串:?user={user}&pass={pass}。 一般來說,這些憑証是一對值,第一個值是唯一的標識符(userId、用戶名、電子郵件等),另一個是 "真實性証明"(散列的密碼、密鑰、秘密、令牌等)。 出於安全原因,不建議發送純文字密碼。

Back To Top

Authenticate操作

Authenticate操作是將認証值實際發送到伺服器的地方。 它通常由我們的API使用,而不是由您的客戶端代碼直接使用。

需要注意的是。連接到一個伺服器總是包括一個認証步驟。 第一次,操作會將實際的認証值作為加密操作發送。 對於後續的伺服器切換,Photon會提供它自己的令牌,該令牌會被加密並自動使用。

Back To Top

伺服器端

一旦Web伺服器收到認証請求,就應該對查詢參數進行檢查和驗証。 例如,可以將憑証與存儲在數據庫中的現有憑証進行比較。

如果收到的參數丟失或無效,返回的結果應該是 { "ResultCode": 3, "Message": "Invalid parameters." }

在完成驗証後,結果應返回如下:

  • 成功: { "ResultCode": 1, "UserId": <userId> }
  • 失敗: { "ResultCode": 2, "Message": "Authentication failed. Wrong credentials." }

Back To Top

進階功能

除了對用戶進行認証外,還可以從認証提供者那裡返回額外的信息。 為了做到這一點,用戶應該在客戶端和扮演 "認証者"角色的網絡服務之間建立某種協議。

Back To Top

向伺服器發送數據

最容易和最簡單的是 "全有或全無"的方式。 選擇是否向客戶端返回靜態的變量數量。 但有些用例需要一種更復雜的方法,即網絡服務根據客戶的要求"照需求"返回數據。 本小節解釋了客戶機如何向Web服務發送數據。 這些數據可以是認証所需的憑証以及任何額外的參數。 額外的參數可以用來請求從伺服器端獲得的數據,並在認証回應中返回。 這是相當有用的,因為它節省了額外的API調用,並簡化了登錄工作流程。

The default HTTP method used in authentication is GET. So, parameters can be sent as key/value pairs in the query string. The final URL will include the "union" of the key/value pairs set from client and those set from the dashboard. In case, the same key is used in both places, only the dashboard value will be sent. A best practice is to set from the dashboard any "sensitive" static values that should be "invisible" to the client; e.g.: API key, API version. Also dashboard key/values can be changed on the fly without the need to update client.

在一些罕見的情況下,認証可能需要大量的數據。 另一方面,大多數網絡伺服器對查詢字符串中使用的字符數有限制,或者對URL的長度有門檻。 這就是為什麼Photon提供了從客戶端將HTTP方法改為POST的可能性,在C# SDKs中,這可以通過明確設置AuthenticationValues.AuthPostData字段為一個值來執行。 後者可以是stringbyte[]Dictionary<string, object>類型。 如果是Dictionary<string, object>,有效載荷將被轉換為JSON字符串,HTTP請求的Content-Type將被設置為 "applicaton/json"。 在C# SDK中,AuthenticationValues類為每個支持的類型提供設置方法。

由於這可能是一個要求或限制,所以POST方法選項也適用於任何選擇以POST方法從Web服務接收認証請求人。

換句話說,為了發送認証參數,您可以自由地使用查詢字符串或POST數據或兩者。 下表給出了可能的組合。

AuthPostData AuthGetParameters HTTP method
null * GET
empty string * GET
string (not null, not empty) * POST
byte[] (not null, can be empty) * POST
Dictionary<string, object> (not null, can be empty) * POST (Content-Type="application/json")

Back To Top

向客戶返回數據

由於Photon伺服器是客戶端和網絡服務之間的代理,您應該注意到可以由Photon伺服器處理的變量。

與Photon伺服器收到的所有HTTP傳入回應一樣,網絡伺服器應該返回一個JSON對象,其中包括一個ResultCode和一個可選的Message。 此外,以下是Photon伺服器在認証過程中可以從網絡服務中期待的內容。

  • UserId: 這可以作為認証本身的一個參數,也可以從客戶端請求。 當Photon伺服器收到這個信息時,總是會轉發給客戶端。 否則,如果AuthenticationValues.UserId最初沒有被設置,一個隨機生成的UserId將被發回給客戶端。 這將覆蓋客戶端的`UserId'值,此後不能更改。
ResultCode Description UserId Data
0 Authentication incomplete, only Data returned.*
1 Authentication successful. (optional) (optional)
2 Authentication failed. Wrong credentials.
3 Invalid parameters.

*: This may be useful for implementing OAuth 2.0 for instance or two-step verification.

Back To Top

從客戶端讀取數據

下面是一個如何從回應中獲取返回值的代碼片段:

Back To Top

Data Types Conversion

In this section, only the type of data exchanged between Photon server and the web service is explained. For more information about data types between clients and Photon servers please refer to serialization in Photon page.

Back To Top

Photon Server -> Web Service

C# / .NET (Photon supported types) 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 (of supported types, count < short.MaxValue, preferably Photon implementation) object
Dictionary (keys and values of supported types, count < short.MaxValue) object
null null

Back To Top

Sample Request Data (types Are Concatenated)

As sent from Photon Server:

As read by Web Service:

Back To Top

Web Service -> Photon Server

Here is a table that matches each JavaScript/JSON type to its equivalent one in C#/.Net :

JavaScript / JSON C# / .Net
object Dictionary
array object[] (array of objects)
number (integral) long
number (floating) double
string string
boolean bool
null (not a type) null
undefined (when sent) null

Back To Top

Sample Response Data (types Are Concatenated)

As sent from Web Service:

As read from Photon Server:

Back To Top

問體排除

當自定義認証失敗時,會觸發以下回調:

void OnCustomAuthenticationFailed(string debugMessage)
{
   // The `debugMessage` could be what the authentication provider returned.
}

如果您在介面中配置的認証URL返回一些HTTP錯誤,Photon伺服器會暫停認証調用一小段時間,以避免過度開銷。 在配置或測試您的URL時,要考慮到"backoff "時間。

Back To Top

最佳實測

  • 從認証提供者返回的結果應該包含一個可讀的Message,特別是在失敗的情況下。 這將為您節省很多除錯的痛苦。
  • 從介面上,設置靜態鍵/值對,這些鍵/值對不應該從客戶端設置。 這將防止在結果查詢字符串中出現重復的鍵。
  • 出於安全考慮,不要發送純文本密碼作為認証參數。
  • 建議從Photon儀表板上設置查詢字符串參數。 這樣您就可以檢查請求的來源。
  • 使用AuthenticationValues方法來設置參數,不要直接影響AuthGetParameters的值。 這將防止不正確架構的查詢字符串。

Back To Top

使用案例示例:阻擋舊的客戶端版本

您可以使用自定義認証來拒絕來自使用舊版本(或意外版本)的客戶端的連接,並返回一個特定的錯誤,以便您可以要求用戶更新。 要做到這一點,您需要在自定義認証請求中發送版本。這取決於您是否想把它作為查詢字符串參數或POST數據參數。 在下面的例子中,我們將使用查詢字符串參數:

string version = chatClient.AppVersion;
AuthenticationValues authValues = new AuthenticationValues();
authValues.AuthType = CustomAuthenticationType.Custom;
chatClient.AuthValues.AddAuthParameter("version", chatAppVersion);
authValues.UserId = userId; // UserId is always required in Photon Chat
chatClient.Connect(chatAppId, chatAppVersion, authValues);

如果您的自定義認証URL是https://example.com,那麼請求將被發送為https://example.com?version={version}。 從您的認証提供者的執行中,您應該獲得並比較收到的版本。 如果版本允許,返回{ "ResultCode": 1 }。 如果不允許,您應該返回一個ResultCode,上面有您選擇的自定義值(不同於1),最好有一條信息。 例如: { "ResultCode": 5, "Message": "Version not allowed." }

To Document Top