Security and Authentication – Learnosity Product & Developer Help

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

Note: we provide helper SDKs in several languages which already handle security and authentication and we strongly recommend their use. The SDK is available in Node.js, PHP, Python ASP.Net, Java, and Ruby. You can add one of these to your codebase and get going quickly by following the readme tutorial and examples in each SDK.

If you absolutely have to write your own code for security and authentication, for example if your programming language is not supported by an SDK, then please contact Learnosity Support. We are happy to help with your use case, and can provide essential guidance in getting this done.

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.

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 68 character long string, resulting from applying the HMAC message authentication code with the SHA256 hashing algorithm using the following parameters:

consumer_key
The consumer_key is a unique identifier supplied by Learnosity to be used when an API consumer is accessing Learnosity APIs.
domain
The domain is the current domain for the site loading Items API. The Learnosity server will check if the requests come from one of the authorized domains for the API consumer.
timestamp
The timestamp is the current time recorded by your script.
user_id
The user_id is an anonymized identifier that represents the current learner attempting an assessment.
consumer_secret
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.

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

<html>
    <head>
    </head>

    <body>

    <?php

    $security = array(
        "consumer_key"    => "INSERT_CONSUMER_KEY_HERE",
        "domain"          => "my.domain.com",
        "timestamp"       => gmdate('Ymd-Hi'),
        "user_id"         => <ANONYMIZED_USER_ID>
    ); /* The user_id should be replaced with a UUID from your user database. */

Code example 1: HTML structure and the signature array

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; Node.js, PHP, Python, ASP.Net, Java, and 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, json_encode($request));
    $preHashString = implode("_", $signatureArray);

    /*
    example output:
    yis0TYCu7U9V4o7M_demos.learnosity.com_20131212-1157_81b44c76-da57-47ce-8433-aa46b6d62a4d_{"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"}}
    */

Code example 2: creating the pre-hash string

Generating the Hash

The SHA256 algorithm is then applied to the concatenated string creating the signature. The generated signature must be prepended with $02$ which denotes the current default signature version in use.

The consumer_secret must be used as the secret key value when calling the hash_hmac function. The consumer secret should not be included in the pre hash string.

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

    $security['signature'] = '$02$' . hash_hmac('sha256', $preHashString, $consumer_secret);

    /*
    example output (using string above)
    $signature = "$02$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>

Code example 3: generating the hash

Signature Components

Creating the Pre-Hash String

Generating the Hash

Related articles