Security and Authentication – Learnosity Product & Developer Help

This document explains how to handle security and authentication in Learnosity API calls.

Most Learnosity services require hashing of certain attributes to prevent tampering with the intended context. This article details this approach so you can replicate it in your code. However for ease of use we provide helper SDKs in several languages and strongly recommend their use.

The SDK is available in ASP.Net, Java, Node.js, PHP, Python and Ruby. You can add one of these to your codebase and get going quickly by following the readme and examples in each SDK.

<html>

    <head>
    </head>

    <body>


    <?php

Signature Components

A valid signature is required to authenticate each Items API request, and is one of the required parameters of the Items JSON Object.

The signature is a 64 character long string, resulting from applying the SHA256 hashing algorithm to the concatenation of the following parameters in order, separated by underscores ('_'):

consumer_key
domain *
timestamp
user_id ^†
consumer_secret ^‡

* The domain is the name of the host of the API's client. The server will check the requests come from one of the authorized domains for the client. This will need to match location.hostname of the client system.

^† The user_id is an anonymized identifier used in some Learnosity APIs' init options to represent a unique user within the client application.

The user_id field in Learnosity APIs’ init options:

Must not contain any personally identifiable information (PII)
Must be an anonymized string representing a unique user (we recommend using a UUID)
Must not exceed 50 characters

^‡ The consumer_secret is a secret key supplied by Learnosity, known only by the client and Learnosity. The consumer_secret must not be exposed either by sending it to the browser or across the network.

    $security = array(
        "consumer_key"    => "INSERT_CONSUMER_KEY_HERE",
        "domain"          => "my.domain.com",
        "timestamp"       => gmdate('Ymd-Hi'),
        "user_id"         => "$ANONYMIZED_USER_ID"
    );

    $consumer_secret = 'INSERT_CONSUMER_SECRET_HERE';

Creating the Pre-Hash String

To create the string, a simple concatenation needs to performed, in the order specified above, along with the JSON representation of the request object.

Note this is available in the following SDKs; ASP.Net, Java, Node.js, PHP, Python or Ruby.

    $request = array(
        rendering_type => "assess",
        user_id => "$ANONYMIZED_USER_ID",
        session_id => "b0280bcb-223c-4c33-a978-88a94d79d900",
        items => array(
            "ccore_video_260_classification",
            "ccore_parcc_tecr_grade3"
        ),
        type => "submit_practice",
        activity_id => "itemsassessdemo",
        name => "Items API demo - assess activity",
        config => array(
            ui_style => "main",
        )
    );


    $signatureArray = array_merge(array(), $security);

    array_push($signatureArray, $consumer_secret);
    array_push($signatureArray, json_encode($request));

    $preHashString = implode("_", $signatureArray);


    /*
    example output:
    yis0TYCu7U9V4o7M_demos.learnosity.com_20131212-1157_81b44c76-da57-47ce-8433-aa46b6d62a4d_74c5fd430cf1242a527f6223aebd42d30464be22_{"rendering_type":"assess","user_id":"81b44c76-da57-47ce-8433-aa46b6d62a4d","session_id":"b0280bcb-223c-4c33-a978-88a94d79d900","items":["ccore_video_260_classification","ccore_parcc_tecr_grade3"],"type":"submit_practice","activity_id":"itemsassessdemo","name":"Items API demo - assess activity","config":{"ui_style":"main"}}
    */

Generating the Hash

The SHA256 algorithm is then applied to the concatenated string creating the signature.

Further examples, as well as examples in other languages, can be found in the source code for our Demos page.

    $security['signature'] = hash('sha256', $preHashString);

    /*
    example output (using string above)
    $signature = "7f28d7bbca370f1900883817348a5e2c40b1add2d8e8c7796f57816473d588e1";
    */


    $initOptions = array(
        "security" => $security,
        "request" => $request
    );


    ?>

    <div id="learnosity_assess"></div>
    <script src="https://items.learnosity.com?[VERSION]"></script>
    <script>

        var initOptions = <?php echo(json_encode($initOptions));?>

        var itemsApp = LearnosityItems.init(initOptions);

    </script>
    </body>
</html>

Signature Components

Creating the Pre-Hash String

Generating the Hash

Related articles