rt0044432

Grades Journey Authorisation (C# code example)

Blog Post created by rt0044432 on Oct 19, 2018

At the University of South Wales we are currently implementing Grades Journey, for anyone going through the same process you will be concentrating on two key areas of work, provisioning and extraction.

 

The first task for us was provisioning and successfully connecting to the Grade Journey API is the first stepping stone.

 

Documentation

The details on how to use the REST API are available here:

https://help.blackboard.com/Learn/Administrator/SaaS/Integrations/Student_Information_System/SIS_Integration_Types/Grades_Journey/RESTful_Web_Services_Implementation/REST_Interface_Specifications#authorization_OTP-3

 

Details

We are interested in generating a MAC code which is passed along with API calls, the documentation tells us how to achieve this:

 

To properly authenticate users, the trusted system must be able to generate a valid MAC (message authentication code) to send with the SSO request. This MAC is used to determine the integrity of an SSO request. The steps required to generate a secure MAC are as follows:

 

  1. Sort the parameters API Key, Timestamp alphabetically by parameter name.
  2. Concatenate the parameter values by the sorted parameter names into a single string.
  3. Append the Shared Secret to the string obtained from Step 2.
  4. Encrypt the string into a 16-byte string using the MD5 algorithm.
  5. Convert the 16-byte string into a 32-byte alphanumeric (hexadecimal) string to make it URL-friendly.

Access the Grades Journey Building Block settings / REST API Security Settings (Incoming Data Security) and set the following values:

code.png

C Sharp code

A simple example of taking the API Key, Shared Secret and UNIX timestamp in milliseconds and generating a MAC code. In alphabetical order the parameters are:

  • api key
  • timestamp

if you name these differently in the settings then adapt to match accordingly.

 

* This code has no tests, error checking and sits in the body of the main method but is only for reference

 

Edit / run this code sample here: Repl.it - AdorableSlushyIrc

 

using System;

 

using System.Security.Cryptography;

using System.Text;

using System.IO;

 

class MainClass {

 

  public static void Main (string[] args) {

   // Grades Journey Authorization

   // Example of generating a MAC key 

   // API key and secret are set within the Building Block

   string APIKey = "this_is_your_api_key";

   string secret = "no_one_knows_this";

   int validTimeMS = 10000;


   // Current timestamp in Milliseconds

   string currentTimestamp = DateTimeOffset.Now.ToUnixTimeMilliseconds().ToString();

   string timestampExpiry = (DateTime.Now).AddMilliseconds(validTimeMS).ToString();

   string concactString = string.Concat(APIKey, currentTimestamp, secret);


   // Encrypt

  MD5 md5 = new MD5CryptoServiceProvider();

  UTF8Encoding encoder = new UTF8Encoding();

  Byte[] encodedBytes = md5.ComputeHash(encoder.GetBytes(concactString));

  string MAC = BitConverter.ToString(encodedBytes).Replace("-", "").ToLower();

 

  Console.WriteLine("******************************");

  Console.WriteLine("MAC: " + MAC);

  Console.WriteLine ("Valid until: " + timestampExpiry);

  Console.WriteLine("******************************");

  }


}

The outcome is a MAC code that was created at 13:07:05 which is valid for 10 seconds:

 

******************************

MAC: 4ee273df794692bc6e890f4184271878

Valid until: 10/19/2018 13:07:15

******************************

 

You would then use this MAC when calling the gradable items API endpoint to provision grade columns. If the API returns any authentication errors it is possible to access the system logs and view details on the API call and debug the issue. If anyone is interested I can post details on calling the API in another post.

 

Outcomes