How to integrate remote authentication service instead of the standard

Teach on Mars provides a way to have the user authentication process managed by a remote server. In this article, we're going to see what is required to do that.

Workflow

Quick explanation of each steps:

1. This login screen is the standard Teach on Mars screen. The login process is transparent for the user
2. The application asks for authentication the same way as in a standard configuration
3. The Mission Center sends a request to the remote server (see specifications in the next section)
4. Remote server responds to the Mission Center with a structures response (see specifications in the next section)
5. The Mission Center also fetches the learner account to give the learnerId to the application
6. Application receives the information about either the logged in user, or an error response. 

Remote service specifications

Request specification

In this section we're going to cover what needs to be implemented on the remote server side.

A single route needs to be available. Let's say this route is /auth, here's the format of the request that will be sent to this route by the Mission Center.

POST /auth?login=john.doe&hash=5f4dcc3b5aa765d61d8327deb882cf99

So it is a POST request with parameters actually sent in the query string. But these parameters can be configured so it can adapt to various remote server configurations.

Parameter names

Parameters names like login and hash can be configured to any string.

Ex: email=john.doe@company.com&pass=5f4dcc3b5aa765d61d8327deb882cf99

Password parameter options

The password value can be either:

• put as the user typed it (no encoding)
• encoded with a hash function, which can be either: md5, sha1, crc32

Response specification

And now here's what the remote server should respond to the request made by the Mission Center.

Wrong credentials

In case the credentials are wrong (unknown user or wrong password), the response should be:

401 Unauthorized
Content-Type: application/json

or

200 OK
Content-Type: application/json

{
  "meta": {
    "status": 200,
    "msg": "OK"
  },
  "response": { 
    "auth": false
  }
}

Matching credentials

In case the credentials are recognized, there are two options. Either a simple OK can be sent back, or the server can also respond with information about the user, which will populate the Mission Center.

Example: simple OK

200 OK
Content-Type: application/json

{
  "meta": {
    "status": 200,
    "msg": "OK"
  },
  "response": { 
    "auth": true
  }
}

Example: user information

200 OK
Content-Type: application/json

{
  "meta": {
    "msg": "OK",
    "status": 200
  },
  "response": {
    "auth": {
      "email": "john.doe@company.com",
      "firstname": "John",
      "lastname": "Doe",
      "metadata": {
        "company": "My Company",
        "country": "France"
      }
    }
  }
}

With this method, here are the fields that can be imported in the Mission Center: