๐Ÿ‘ฎโ€โ™€๏ธ Authentication

Authentication

To ensure security and confidentiality of our services, it is required to verify the user's identity for each request.

These pieces of information are stored in an access token. This token is delivered by our authentication service.

Below are detailed the API endpoints used for this service.

How to obtain a token

In order to obtain a token, the client must be authenticate by the service. This authentication is performed using a challenge (i.e. a unique string forged using the information contained in our database):

  1. First the client requests a challenge from the server.

  2. Using the user credentials (i.e. the password) the client tries to solve the challenge.

  3. The client posts its response to the server.

  4. The server effectively solves the challenge with the credentials stored in its database and compares the two responses.

  5. If the responses match, the server returns a token.

This approach ensures a certain level of security because the password is not sent during the authentication process.

Each of the authentication steps is defined in the sections below.

Requesting the challenge

Description

In order to obtain a token, the client is responsible for requesting a challenge. This challenge can be requested using the following API endpoint:

[GET] https://kligo.medeo.io/auth?email=<your@mail.com>

This endpoint expects an email address to be passed.

Response

Depending on the email provided, different responses can be expected:

Here are some example response:

//  For a 200 - OK response, the body should look like:

    {
        "userId": "<yourUserId>",
        "challenge":"<yourChallenge>"
    }
//  For a 200 - OK response, the body should look like:

    {
        "userId": "<yourUserId>",
        "challenge":"<yourChallenge>"
    }

Here is a comprehensive example for requesting a challenge:

fetch(`https://kligo.medeo.io/api/auth?email=${email}`, {
    method: 'GET',
    headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json; charset=utf-8'
    }
}).then(response => {
    /* ... */
});

Solving the challenge

description

Once fetched, the challenge must be solved using the user credentials. The expected solution is computed as follows:

  • First, concatenate the challenge string with the user password.

  • Then hash the concatenated string using a SHA256 hashing method.

  • Send back the hashed string along with the userId

response

The authentication service will responds depending on the solution passed. There are three cases:

  • The userId is incorrect

  • The solution is incorrect

  • Everything is correct

Once you receive the token, its TTL attribute is set to 1 day. Passed this date, the token will no longer authenticate your requests and our services will automatically respond with a401 UnauthorizedHTTP response.

In other words, it will be required to start again an authentication process to continue to use our services.

Here are some example responses:

//  For a 200 - OK response, the body should look like:

{
    "token": "aaa.bbb.ccc"
}
//    For a 400 - Bad Request response:   

{
  "message": "Bad Request"
}
//    For a 404 - Not Found response:   

{
    "message": "Not Found"
}

Here is the first method required for getting the token:

// performs a simple concatenation of the challenge and the password
let concatenatedString = [challenge, password].join('');
//simply hash the result
let solution = SHA256(concatenatedString);

Eventually, here is an example of posting the solution to the authentication service :

fetch('https://kligo.medeo.io/api/auth', {
    method: 'POST',
    body: JSON.stringify({userId: userId, challenge: solution}),
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json; charset=utf-8'
    } ,
    credentials: 'same-origin',
});

Last updated