SSO using API

In short, API-based SSO is based on a process of exchanging an authentication token between the external application and Teach on Mars application, enabling a single authentication and simplified access for the learner.

Additional developments are required from the source application.

Overall process

First, you need to check if the learner is already existing on Teach on Mars side.

If the learner doesn't exist, you need to create it first to get his technical identifier, which will be required to obtain the authentication token. Please check the section below dedicated to the creation of the learner.

If the learner already exists, you need to obtain an authentication token from the Mission Center and pass it to the application. This will lead to the learner being authenticated in the app. Here's how it works : Obtain an authentication token. You may need to update the learner during the authentication process, if so, please check the dedicated section below.

Use the web services

How to call the Mission Center web services

The Mission Center web services require a specific authentication technique that is described in the article How to use the Mission Center Web services. Please refer to it when you need to implement your WS authentication methods.

How to create a new learner in the Mission Center

To create a learner in the Mission Center, the following request should be sent (see documentation):

POST /api/identities/v1/learners
{
 "login" : "john.doe",
 "firstname" : "John",
 "lastname" : "Doe",
 "email" : "john.doe@company.com",
 "password" : "ACu$tomPassword!",
 "segment": {
   "country": ["FRANCE"]
 },
 "lang": "en-GB"
}

Response:
{
 "identifier": "46e11440-ea40-11e7-a88a-3d64957b0864",
 "email": "john.doe@company.com",
 "login": "john.doe,
 "metadata": {
   "country": ["FRANCE"]
 },
 "status": "Active",
 ...
}

Some details about this payload:

• The only required field is login. The login must be unique for all learners.
• The segment relates to the custom fields in the Mission Center

Question to consider before implementing : Will the learner also be able to connect directly to the Teach on Mars app ?

• If yes, the email must be defined, thus the learner will reset his password on first login. Otherwise, the password must be defined and communicated to the learner.
• If no, the email and the password can be omitted if the learner will never be able to connect directly to Teach on Mars app

How to update the learner in the Mission Center

To update a learner in the Mission Center, the following request should be sent (see documentation)

PUT /api/identities/v1/learners/{learnerId}
{
 "login" : "john.doe",
 "firstname" : "John",
 "lastname" : "Doe",
 "email" : "john.doe@company.com",
 "segment": {
   "country": ["FRANCE"]
 },
 "lang": "en-GB"
}

Response:
{
 "identifier": "46e11440-ea40-11e7-a88a-3d64957b0864",
 "email": "john.doe@company.com",
 "login": "john.doe,
 "metadata": {
   "country": ["FRANCE"]
 },
 "status": "Active",
 ...
}

Some details about this payload:

• Fields not included into the payload will not be updated
• The segment relates to the custom fields in the Mission Center.

How to check the learner's presence

If you have not saved the learner's technical identifier on your side, you need to search for the learner based on his information.

This endpoint allows you to search among all learners thanks to the parameter search. As the login is unique on Teach on Mars side, it will help you identify the learner easily.

Project sheet

Things to consider when planing this kind of integration: