Mise en œuvre de l'authentification multifactorielle (MFA) avec TOTP

Découvrez comment intégrer l'authentification double facteur (2FA), pour une organisation. Apprenez à créer une connexion TOTP pour une Organisation et à générer un challenge pour l'utilisateur.

• Démarrage rapide
• 15 min

Un TOTP (Time-based One-Time Password) est un mot de passe à usage unique basé sur le temps, utilisé dans le cadre de l'authentification à plusieurs facteurs (MFA) pour renforcer la sécurité des accès aux applications web. Après avoir saisi ses identifiants habituels, l'utilisateur reçoit un code unique via une application authenticator 2FA (Two-Factor Authentication) comme Google Authenticator, Microsoft Authenticator, 2FAS, FreeOTP... ou par SMS. Ce mot de passe à usage unique, ou 'one-time passcode', doit être entré dans l'application pour finaliser l'accès au service. Cette méthode, appelée double authentication (dual authentication), rend l'authentification traditionnelle plus robuste et moins vulnérable aux attaques.

Pour assurer une sécurité maximale, il est essentiel de mettre en place des mesures de sécurité et de s'assurer que le code est utilisable uniquement sur une courte période. L'utilisation de one-time passwords via des applications d'authentification est devenue incontournable pour protéger les comptes et les données des utilisateurs contre les cybermenaces.

Avant de commencer

Créez votre compte Cryptr gratuitement maintenant, vous aurez ainsi les deux éléments requis pour suivre ce guide :

• Clé d’API : Vous obtiendrez un client_id et un client_secret, Vous pouvez lire notre guide d'authentification de l'API pour apprendre comment vous authentifier avec ces éléments et utiliser l’API Cryptr
• Organization: Vous créerez votre première organisation, qui représente par exemple votre client et qui peut être vous même pour un 1er test. En savoir plus sur l'API Organisation.

1. Activer l'authentification multifactorielle pour une organisation

Afin d'activer le MFA Cryptr, vous devez activer votre connexion MFA pour l'organisation que vous avez précédemment créée dans votre tableau de bord.

Pour ce faire, accédez à la page dédiée à l'organisation pour laquelle vous souhaitez activer la connexion TOTP. Vous pouvez sélectionner l’organisation via la barre de navigation latérale du répertoire des utilisateurs à gauche de votre écran.

Une fois activé, vous pourrez effectuer des challenges TOTP pour l'organisation sélectionnée.

2 Enrôler vos utilisateurs à l'authentification multifactorielle

Enrôlement MFA

Avant que les utilisateurs puissent utiliser une méthode MFA comme le TOTP, ils doivent être enrôlés. Nous allons voir comment procéder :

Enrôler vos utilisateurs

cURL

curl -X POST ${cryptr_service_url}/api/v2/org/${org_domain}/totp-enrollment/${user_id} \
    -d force_enroll='false'

JavaScript

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");
myHeaders.append("Authorization", "Bearer ***");

const urlencoded = new URLSearchParams();
urlencoded.append("force_enroll", "false");

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: urlencoded,
  redirect: "follow"
};

fetch("{cryptr_service_url}/api/v2/org/{org_domain}/totp-enrollment/{user_id}", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Ruby

require "uri"
require "net/http"

url = URI("{cryptr_service_url}/api/v2/org/{org_domain}/totp-enrollment/{user_id}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer ***"

response = https.request(request)
puts response.read_body

info

Le paramètre force_enroll est utilisé pour enrôler de nouveau un utilisateur qui a utilisé tous ses codes de récupération. Un code de récupération permet de s'enregistrer de nouveau si l'utilisateur a perdu son téléphone (et donc son application Authenticator) par exemple, avec son code Par défaut, un utilisateur ne peut pas se réinscrire plus de 5 fois sans vérification humaine.

Cet option peut également être utilisé pour générer cinq nouveaux recovery_codes pour remplacer les anciens.

Forcer l'enrôlement d'un utilisateur

cURL

curl -X POST ${cryptr_service_url}/api/v2/org/${org_domain}/totp-enrollment/${user_id} \
    -d force_enroll='true'

JavaScript

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");
myHeaders.append("Authorization", "Bearer ***");

const urlencoded = new URLSearchParams();
urlencoded.append("force_enroll", "true");

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: urlencoded,
  redirect: "follow"
};

fetch("{cryptr_service_url}/api/v2/org/{org_domain}/totp-enrollment/{user_id}", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Ruby

require "uri"
require "net/http"

url = URI("{cryptr_service_url}/api/v2/org/{org_domain}/totp-enrollment/{user_id}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/x-www-form-urlencoded"
request["Authorization"] = "Bearer ***"
request.body = "force_enroll=true"

response = https.request(request)
puts response.read_body

Cet appel API vous donnera un code QR que vous devez afficher à votre utilisateur, vous pouvez également utiliser l'URI OTP. Si vous souhaitez inscrire vos utilisateurs pour les SMS, ceci n'est pas nécessaire.

Valider l'enrôlement d'un utilisateur

Après leur enrôlement, vos utilisateurs doivent confirmer l'activation de leur méthode 2FA, soit via une application TOTP (Time-based One-Time Password), soit par SMS .

• Méthode par SMS : Une fois l'inscription complétée, vous devez envoyer à l'utilisateur un code par SMS, obtenu lors de l'inscription. L'utilisateur devra ensuite saisir ce code reçu par SMS dans votre application.
• Méthode par application TOTP : L'utilisateur devra configurer une application d'authentification (comme Google Authenticator) pour générer des codes temporaires. Une fois configurée, l'utilisateur devra entrer le code généré par l'application TOTP dans votre application.

Dans les deux cas, vous pouvez utiliser notre endpoint de validation pour vérifier le code saisi par l'utilisateur.

cURL

curl -X PUT ${cryptr_service_url}/api/v2/org/${org_domain}/totp-enrollment/validation/${user_id} \
    -d code='145632'

JavaScript

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");
myHeaders.append("Authorization", "Bearer ***");

const urlencoded = new URLSearchParams();
urlencoded.append("code", "145632");

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: urlencoded,
  redirect: "follow"
};

fetch("{cryptr_service_url}/api/v2/org/{org_domain}/totp-enrollment/validation/{user_id}", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Ruby

require "uri"
require "net/http"

url = URI("{cryptr_service_url}/api/v2/org/{org_domain}/totp-enrollment/validation/{user_id}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/x-www-form-urlencoded"
request["Authorization"] = "Bearer ***"
request.body = "force_enroll=145632"

response = https.request(request)
puts response.read_body

Code de récupération TOTP

Après l'inscription d'un utilisateur, vous recevrez un payload contenant cinq codes de récupération. Ceux-ci seront fournis sous forme d'un seul String, chaque code étant séparé par un saut de ligne (\n), prêt à être utilisé dans un champ textarea pour faciliter le copier-coller ou l'impression papier par l'utilisateur.

Ces codes doivent être affichés afin que l'utilisateur puisse les sauvegarder et les utiliser en cas de perte d'accès à son application TOTP, à son téléphone ou à son numéro de téléphone.

info

Ces codes de récupération doivent être conservés avec autant de soin qu'un mot de passe (ils ne doivent pas être divulgués ou conservés sur le même appareil que l'application TOTP ...). Chaque fois qu'un code de récupération est utilisé, l'utilisateur doit s'enrôler à nouveau.

En outre, ils sont à usage unique, de sorte qu'un utilisateur ne peut utiliser les codes de récupération que 5 fois. Une fois ce nombre dépassé, vous devrez forcer un nouvel enrôlement pour que l'utilisateur puisse en récupérer de nouveaux (voir ci-dessus le paramètre force_enroll). Enfin, les codes ne peuvent être utilisés qu'une seule fois par période de 24 heures.

3 Intégrer l'authentification multifactorielle TOTP à votre application

Recevoir un code TOTP (uniquement pour la méthode SMS)

L'appel ci-dessous n'est utile qu'avec la méthode SMS. Pour la méthode de l'application mobile OTP, le code est généré par l'application OTP de l'utilisateur, mais dans le cas de la méthode SMS, vous devez générer le code pour l'envoyer à vos utilisateurs.

TOTP Challenge

cURL

curl -X POST ${cryptr_service_url}/api/v2/org/${org_domain}/totp-challenge/${user_id}

JavaScript

const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer ***");

const urlencoded = new URLSearchParams();

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: urlencoded,
  redirect: "follow"
};

fetch("{cryptr_service_url}/api/v2/org/{org_domain}/totp-challenge/{user_id}", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Ruby

require "uri"
require "net/http"

url = URI("{cryptr_service_url}/api/v2/org/{org_domain}/totp-challenge/{user_id}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer ***"

response = https.request(request)
puts response.read_body

Cet appel API prend un user_id pour créer un totp hallenge, qui créera un code TOTP à envoyer à vos utilisateurs.

Validation du TOTP

Valider un code TOTP

cURL

curl -X POST ${cryptr_service_url}/api/v2/org/${org_domain}/totp-challenge/validation/${user_id} \
  -d code='124578'

JavaScript

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");
myHeaders.append("Authorization", "Bearer ***");

const urlencoded = new URLSearchParams();
urlencoded.append("code", "145632");

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: urlencoded,
  redirect: "follow"
};

fetch("{cryptr_service_url}/api/v2/org/{org_domain}/totp-challenge/validation/{user_id}", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Ruby

require "uri"
require "net/http"

url = URI("{cryptr_service_url}/api/v2/org/{org_domain}/totp-challenge/validation/{user_id}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/x-www-form-urlencoded"
request["Authorization"] = "Bearer ***"
request.body = "force_enroll=145632"

response = https.request(request)
puts response.read_body

Cet appel API prend un identifiant utilisateur et un code pour valider un challenge TOTP. Si le challenge est validé, l'authentification est réussie.

info

Au lieu d'utiliser un code TOTP, les utilisateurs peuvent utiliser leur code de récupération. Si un code de récupération est utilisé, vous devrez enrôler à nouveau votre utilisateur. Lorsqu'un utilisateur utilisera son code la clé recovery_code_usedaura pour valeur true.

Réponse lorsqu'un utilisateur a utilisé son code de récupération.

cURL

  {

    "__type__": "TotpChallenge",
    "challenged_at": "2023-08-22T15:00:55.816432",
    "code": "008029",
    "recovery_code_used": true, # This key will be set to true
    "request_id": "totp-challenge_2ULQbzNww3R4ANIZyroXwYsS8Wg",
    "sent_at": null,
    "success": true
}

Si les cinq codes de récupération sont utilisés, vous pouvez enrôler votre utilisateur une dernière fois. Après cela, si l'utilisateur perd à nouveau son accès, vous devrez forcer l'enrôlement de votre utilisateur. Cela donnera à votre utilisateur 5 nouveaux codes de récupération.

Procédure de challenge complète

1. Après avoir généré un challenge TOTP (méthode SMS uniquement), vous devriez obtenir un code à envoyer à votre utilisateur.
2. Vous devez alors demander à l'utilisateur de saisir le code reçu par SMS ou par l'intermédiaire d'une application TOTP.
3. Ensuite, nous vérifions si la validation du challenge a réussi (propriété « success ») ou non. Si c'est le cas, l'authentification TOTP est valide.
4. Si l'utilisateur a utilisé un code de récupération, vous devrez l'enrôler à nouveau immédiatement.

What’s next

Vous pouvez également vous référer à notre références API pour effectuer ces actions via l'API REST.