Authentication

Authentication API overview

The authentication does not require any communication between your application server side and our infrastructure. Instead, on the server side, application should prepare all the required data, sign them using a “shared secret” (“API Key”) and pass it to the JavaScript which uses them to prepare the connection descriptor.

To authenticate given connection request, AddLive SDK expects following data to be provided:

• application id
  It explicitly identifies an application using the cloudeo service. We use it to know who to charge for the traffic generated by the user and also to get the app-specific API key to verify the signature.
• user id
  Application unique identifier for the particular user. Having this property in set of authentication fields, allows the developer to explicitly control who can join media scope with given id. Also this property will be used with all the AddLive events dispatched to the AddLiveServiceListener and corresponding to remote user’s actions (connect, disconnect, publish, unpublish, sendMessage).
• scope id
  Identifies id of a scope to which connection attempt is being made. This property is a second component required to control who can join which scope.
• salt
  Random string used when calculating the authentication signature. It increases the signature randomness.
• expires timestamp
  UTC Timestamp, defining how long the authentication signature should be valid. It prevents malicious users from hijacking already calculated signature and reusing them outside application control.
• signature
  Authentication signature which guarantees that the connection request is being made on behalf of our client. It is a SHA-256 hash, calculated from a string generated by concatenation of all the above attributes and the API key. The signature must be represented as a hex-string, uppercased.

AddLive-Powered Applications

When designing the new Authentication API, we wanted to make it flexible for our customers. And so we decided that the smallest entity that can use our SDK is an application. You may create multiple applications, each of them having it’s own id, API key and presumably additional settings (e.g. restricted set of streamer IPs that given application shall use, customized installers).

Traffic from all applications owned by a customer will be billed under a single account.

Setting an Application ID

Since the application id is something application specific, we assumed that it does not make sense to include it in every connection request and allow developers to define it during the platform initialization. To define the application id, the applicationId property of init options should be used:

function initADL(appId) {
  var initListener = createADLInitListener(),
      options = {applicationId:appId}
  ADL.initPlatform(initListener, options);
}

Preparing Authenticated Connection Request

To provide the authentication details, new attribute called “authDetails” was added to the ConnectionDescriptor. The complete sample covering auth details generation and setting can be found in the following snipped:

function genAuthDetails(userId, scopeId) {

  // Some constants
  var sharedSecret = 'Some shared secret';
  var applicationId = 1;

  // Calculate the expiry timestamp
  var dateNow = new Date();
  var now = Math.floor((dateNow.getTime() / 1000) -
                       dateNow.getTimezoneOffset() * 60);

  // Define the main authentication details object
  var authDetails = {
  // Signature valid 5 mins
  expires: now + (5 * 60),
  userId: userId,
  salt: 'Some random string, at least 20 characters long'
  };

  // Prepare the string that will be used to calculate the signature
  // by simply concatenating the auth details attributes in following order
  var signatureBody =
        applicationId +
        scopeId +
        userId +
        authDetails.salt +
        authDetails.expires +
        sharedSecret;

  // Calculate the signature - SHA256 hash, as a hex string, uppercased
  authDetails.signature =
  CryptoJS.SHA256(signatureBody).toString(CryptoJS.enc.Hex).toUpperCase();
  return authDetails;
};

Having the authDetails prepared, connection establishment is pretty simple:

function connect() {

// Prepare the connection descriptor by cloning the configuration and
// updating the URL and the token.
  var userId = 123;
  var connDescriptor = {};
  connDescriptor.scopeId = 'some_scope_id';
  connDescriptor.authDetails = genAuthDetails(userId, connDescriptor.scopeId);

//  3. Define the result handler
  var onSucc = function () {
  };

//  4. Define the error handler
  var onErr = function (errCode, errMessage) {
  };

//  5. Request the SDK to establish the connection
  ADL.getService().connect(ADL.r(onSucc, onErr), connDescriptor);
};

Obtaining API Credentials

To obtain the API credentials, please request an invitation.