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:
- This login screen is the standard Teach on Mars screen. The login process is transparent for the user
- The application asks for authentication the same way as in a standard configuration
- The Mission Center sends a request to the remote server (see specifications in the next section)
- Remote server responds to the Mission Center with a structures response (see specifications in the next section)
- The Mission Center also fetches the learner account to give the learnerId to the application
- 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:
Field | Description |
firstname | The first name of the user |
lastname | The last name of the user |
The email address of the user | |
metadata | An object that contains values for custom fields configured in the Mission Center |
Comments
0 comments
Please sign in to leave a comment.