How to identify a learner in my service

It is possible to create a secondary service that brings new features to the app by using data from the Mission Center webservices. This service must be a web based and online application and could be, for instance, a new profiling quiz, a gift shop, a messaging service, etc.

The key part to implementing this kind of service is identifying the learner. This is where the Identity token comes into play. We are going to go over how it should be used step by step.

Workflow

1. Learner launches the service

From the Add-on tab, a link to the service is available to the learner. This URL contains placeholders to transfer the required information to the service.

https://my-service.com/launch?learnerId=$(LEARNER_ID)&token=$(IDENTITY_TOKEN)

The learner taps on the add-on icon and the service URL is opened in a web view.

2. App requests Identity Token to Mission Center

Because the URL contains $(IDENTITY_TOKEN) the app will send a request to the Mission Center to obtain an identity token for the current logged in learner.

To configure this add-on link, please contact your Teach on Mars Project Manager.

3. Mission Center provides Identity Token

The Mission Center gives the token to the app. The $(IDENTITY_TOKEN) placeholder can now be replaced with the identity token.

4. App opens service with Identity Token and Learner ID

When the learner opens the add-on, the placeholders are replaced. $(LEARNER_ID) is replaced with the current learner's unique identifier. $(IDENTITY_TOKEN) is replaced with the token that was just obtained from the Mission Center.

Therefore, the service receives:

• The ID of the current logged in learner
• An Identity Token linked to this learner

5. Service checks Identity Token with Mission Center

When the service is opened by the learner, it needs to make sure the user is the right one and not someone who just opened the service URL in a random browser.

The service can make sure of that with a request to the MC.

Request (see documentation)

POST /api/identities/v1/learners/verifyIdentityToken

{
  "learnerId": "46e11440-ea40-11e7-a88a-3d64957b0864",
  "token": "oM50g1l1ZctOdjHOTRrK"
}

6. Mission Center validates Identity Token

The Mission Center will either respond with:

• Code 200: which means the token is valid
• Code 401 : which means you are unauthorized, or you forget to send a bearer token with your request
• Code 404: the token was not found and therefore is not valid

NB: The token remains valid for 2 minutes after its generation by the Mission Center (step 3).

7. Service shows interface to the learner

At this point, the service is sure that the learner that is using it is legitimate.

As the service is opened in a web view, it should give a visual feedback or interface to the learner once it has processed everything it needs to process.