{{warning}}

Player Token

When you launch the player, you pass a Player Token.

The Player Token is used to provide authorization to the browser to load the player, and allows you to control some access settings of the player securely.

The token is a JSON object, encrypted using your Client Secret. You can encrypt the token in your own server code, or use the REST API method provided by the CoreSpring Platform.

Token Object Properties

  {
    // required. Unix Timestamp date when the token expires. Set to 0 to never expire
    "expires": "1411738012",
    // optional, defaults to false. Whether player should run in secure mode. See below.
    "secure" : "true|false"
  }

You can also provide values for the player options within the player token object. (See the Player Options section.)

Any options set in the player token will override those provided in the options object passed to the player on creation. This makes the options in the javascript tamper-proof.

For example, if you wanted to load the player for a specific Item Session Id, and only allow the Player to show the session in gather mode you might put these options in the player token:

    {
      "mode": "gather",
      "sessionId": "abcde",
      "expires": "0"
    }

If you pass options this way, they will be read from your encrypted token, and settings passed in the Javascript options will be ignored. In the above example, the player will only load the item for the sessionId "12345abc" even if sessionId is passed in the options parameter when constructing the player:

    var options = {};

    options.itemId = "abcde";  // ignored by player because was set in token
    options.mode = "view";     // ignored by player because was set in token

    var player = new org.corespring.players.ItemPlayer('#player', options);

Secure Mode

When creating a Player Token you can set the property secure to indicate special behavior the player should enforce.

When this property is set to true:

  • mode cannot be changed to evaluate with setMode() if the server-side item session is not marked as complete
  • mode cannot be changed to gather with setMode() if the server-side item session is marked as complete
  • getScore() will not work unless the server-side item session is not marked as complete

See the Options page for some more details.

Creating a Token With the CoreSpring API

To create the player token you can call the CoreSpring REST API. As shown in this CURL example:

    $~ curl \
      -H "Content-Type: application/json" \
      -d '{
        "expires" : "0",
        "mode":"gather",
        "sessionId": "51fc0b9de4b044e577788537"
      }' \
      https://platform.corespring.org/api/v2/player-token?access_token=${your_token}

Note: This request should be performed from your server code, not in the user's browser.

You can also create an options token in your own code If you create tokens frequently, it may be better to encrypt them in your own code rather than calling the API to create tokens.

Encrypting a Player Token in Your Code

Instead of using our REST API to create player tokens, you can encrypt them in your own (server-side) code. Corespring uses AES 128 bit encryption with Cipher Block Chaining (CBC) as the mode of operation and PKCS5 padding. In order for Corespring to be able to read and decrypt your encryption you should:

  • generate a 128 bit initialization vector(IV) and output the result in hexadecimal
  • hash your secret using MD5 Message Digest
  • encrypt your options with the hashed key and output the result in hexademical
  • encode both the cipher text and iv in utf-8 and combine the two into one string using the delimeter '--' e.g. [encrypted]--[iv]

The CoreSpring Ruby Library can be used to generate a token, or as a reference example.

The following is an example in NodeJs:

    // Options is the options you are encrypting and secret is your client secret.
    // This code assumes both are defined elsewhere
    var crypto = require('crypto'); //nodejs crypto module. see nodejs api documentation
    var uuid = require('node-uuid'); //generate uuid to represent initialization vector

    var iv = new Array(16);
    var digest = new Array(16);

    uuid.v4(null, iv, 0);

    var hash = crypto.createHash('md5');
    hash.update(secret,'utf8');
    var digest = hash.digest('hex');
    //digest is now the hashed secret to be used to encrypt options

    var cipher = crypto.createCipheriv('aes-128-cbc',
                                      new Buffer(digest,'hex'),
                                      new Buffer(iv));
    var encrypted = cipher.update(JSON.stringify(options), "utf8", "hex");
    encrypted += cipher.final("hex"); //the final encrypted message
    //the final output in the form of [encrypted]--[iv]
    //callback with the encrypted options
    callback(null,encrypted+"--"+new Buffer(iv).toString('hex'));