User Authentication

Overview

When the client signs in to subscribe Private Channel, Presence Channel and Chat, an authentication callback will be triggered for your server to judge whether the user has the permission so as to ensure non-disclosure of important messages.

These authentication callbacks all use the same process but with different requests and response parameters.

Authentication Process

Take a subscription of Private Channel using JavaScript SDK on Web application for example:

1. Configure authEndpoint and initialize the Engine object.
2. The Engline object automatically initiates a connection to the Realtime Engine.
3. Once the connection is made successfully, a unique socketId will be returned to the client.
4. The client attempts to subscribe the Channel with private- prefix.
5. The client SDK knows this type of Channel needs user authentication, and therefore initiates an authentication callback to the authEndpoint confitured.
6. If authenticated successfully, your application server will return a signature string .
7. The channelName and authenticated signature are sent to the Realtime Engine. If the signature is valid, the authentication process completes.

The purpose of the authentication callback is to let your server judge whether a user has the permission to perform the operation. The specific logic of the judgement is completely decided by the requirement of your application.

Authentication Callback

Address

This is configurable. For more details, please refer to the corresponding SDK docmentation.

Request

It is a HTTP POST request in JSON format, including the following parameters:

• socketId: The unique identification of the connection that is being used on the client.
• channelName: For a subscription of the Channel, the value is the name of the Channel the client is to subscribe or null.
• chatLogin: For a Chat sign-in, the value is true or null.
• authData: Optional, and configurable in the client SDK, which is to provide user credentials.

Authentication Callback Response

If authenticated successfully, please return the result in JSON format.

Private Channel

Use Secret to digest <socketId>:<channelName> using HMAC SHA256 hex hash .

Take PHP for an example:

$secret = 'ae9578feebf46861d5a0bd9a';
$socketId = '0qI6JEP7NODMzvhBANvO';
$channelName = 'private-channel';

$strToSign = $socketId . ':' . $channelName;

// Get：631f7dd2db486eae13fc3272855b7a389743f8026d8d67cb7c14a6f1accba4f4
$signature = hash_hmac('sha256', $strToSign, $secret);

Then return in the following format:

{
    "signature": "631f7dd2db486eae13fc3272855b7a389743f8026d8d67cb7c14a6f1accba4f4"
}

Presence Channel

Apart from returning the signature, the data of the user authenticated needs to be returned as channelData, and the signature is also needed for these content in a form of JSON string: <socketId>:<channelName>:<JSON encoded user data>.

User data needs to be composed of two parts, but the specific content is decided completely by your application requirements. You can access these data through related API in the future.

• userId (String): User’s unique identification.
• userInfo (Object): User information.

Still take PHP for an example:

$secret = 'ae9578feebf46861d5a0bd9a';
$socketId = '0qI6JEP7NODMzvhBANvO';
$channelName = 'presence-channel';

$userData = array(
    'userId' => '1111',
    'userInfo' => array(
        'name' => 'Aaron Wang',
        'gender' => 'male',
        'age' => '25',
        'hoby' => 'coding'
    )
);
$userDataJsonStr = json_encode($userData);

$strToSign = $socketId . ':' . $channelName . ':' . $userDataJsonStr;

// Get：472a4db040887f82d2f458898d0ab46d9589b86518b973a284ae9dc5218ee27d
$signature = hash_hmac('sha256', $strToSign, $secret);

Correspondingly, return the following results:

{
    "signature": "69cda61d96d71bed8aceeaf3a74e3979d95d7efa5761c8e5ea3b562f5052ffed",
    "channelData": "{\"userId\":\"1111\",\"userInfo\":{\"name\":\"Aaron Wang\",\"gender\":\"male\",\"age\":\"25\",\"hoby\":\"coding\"}}"
}

Chat Sign-in

Apart from returning the signature, the data of the user authenticated needs to be returned as userData, and the signature is also needed for these content in a form of JSON string: <socketId>:<JSON encoded user data>.

User data contains the following parts:

• userId (String): User’s unique identification.
• nickname (String): Optional; the nickname of the user, which is used to display offline notification messages on mobile devices. If not provided, userId will be used.
• language (String): Optional; the language with either zh-cn or en-us as its value, which is used to display offline notification messages on mobile devices. If not provided, Chinese language (zh-cn) will be used.

Realtime Engine will use userId as the unique idientification after receiving the user data. The user will be created if not found, and the corresponding properties will be updated if duplicate.

Take PHP for an example:

$secret = 'ae9578feebf46861d5a0bd9a';
$socketId = '0qI6JEP7NODMzvhBANvO';

$userData = array(
    'userId' => '1111',
    'nickname' => 'Aaron Wang'
);
$userDataJsonStr = json_encode($userData);

$strToSign = $socketId . ':' . $userDataJsonStr;

// Get：c62b93b7b1f0dd6aec91ce43c45a663e9069d94874c8b0a762db768c20e46f51
$signature = hash_hmac('sha256', $strToSign, $secret);

Correspondingly, return the following results:

{
    "signature": "69cda61d96d71bed8aceeaf3a74e3979d95d7efa5761c8e5ea3b562f5052ffed",
    "userData": "{\"userId\":\"1111\",\"nickname\":\"Aaron Wang\"}"
}

Web Cross-Domain Problems

When using JavaScript SDK, if the authentication callback address and the current webpage address are cross-domain (For protocols, host names or ports, if any of them are different, it’s cross-domain.) You have two options:

1. IE 8/9 not supported: AddCORS Header for callback response。

2. IE 8/9 supported: Enable JSONP through configuration to resolve cross-domain restriction. For the details on configuration method, see JavaScript Integration Guide.

   • Callback will be sent using the GET method, and the request parameter will be used as the query string, for example:

     https://devapi.tuisongbao.com/v2/engineDemo/authUser?channelName=private-YndpebxJwPApe8Ze&socketId=pBYsZ3cTE3vGDC_VAAAY&callback=wxridtjgxvuyacfrgxnh&timestamp=1425279845633

     Among which there is a special parameter callback, and your server needs to use it to generate a piece of JavaScript code and return it. The content of the code is using the callback parameter to generate a method and then call it.

   • The callback response should have Content-Type set as application/javascript, and return the rulslt in a form of callback(result), for example:

       wxridtjgxvuyacfrgxnh({"signature":"8d33bdc51396a0d130b0c8685cd280dd38b3269bb9f107d39f081e93fa7ef4fe"})
     

     Among which callback is the query string parameter corresponding to the request, and result is the result of various authentication callback described above.