Vérifier l’identité de l’expéditeur pour effectuer des envois eIDAS via l’API

Afin d’effectuer un envoi de LRE eIDAS il est nécessaire d’identifier l’expéditeur du courrier.
Cette identification passe par des OTP pour l’expéditeur, lorsqu’il souhaite faire un envoi via l’API.
Pour ce faire nous devons lui transmettre, par voie postale en recommandé papier, la clé OTP qui lui permettra de générer ses OTP.

1. Vérifier l’identité de l’expéditeur via l’API

Avant de débuter cette procédure, assurez-vous que votre client ne possède pas déjà une clé OTP qu’il aurait commandé par lui-même directement via le site d’AR24.
Il est possible de vérifier si un compte possède une identité vérifiée en récupérant les informations de l’utilisateur via la route /user. Dans le retour de l’API, cherchez l’attribut is_identity_verified : sa présence indiquera que l’utilisateur possède une identité vérifiée.

Vous avez la possibilité d’effectuer la demande d’envoi des identifiants pour votre destinataire via la route /user/identity. Avant d’appeler cette route, assurez-vous que l’adresse postale du compte soit correctement renseignée.

Les paramètres attendus sont les suivants :

• token : votre token
• id_user : l’identifiant du compte expéditeur à qui envoyer la clé OTP (si le compte expéditeur fait parti d’une équipe, l’administrateur de l’équipe payera cette identification)

Vous obtenez un retour de notre API avec le statut SUCCESS. (Dans le cas d’une erreur, vous retrouverez dans le retour une explication et un slug. Vous retrouverez dans notre documentation la liste des erreurs dans l’onglet « Error » de la route en question).

En environnement de production, l’appel à cette route enverra un recommandé papier à l’adresse postale de l’expéditeur (enregistrée sur son compte). Il contient un QRCode, la clé OTP et les explications nécessaires pour l’utiliser et générer ses OTP. Voir les tarifs. (En savoir plus sur le document transmis).

L’acheminement de la clé OTP par voie postale peut être suivi grâce au numéro de tracking envoyé par mail au compte AR24. Ce numéro de tracking peut également être retrouvé dans les informations de l’utilisateur via la route /user. Dans le retour de l’API, cherchez l’attribut is_identity_verified_otp_tracking_number : sa présence indiquera que le courrier a été remis aux services postaux et pourra être utilisé sur https://www.laposte.fr/outils/suivre-vos-envois.
En fonction des délais de traitement du prestataire d’impression et de la mise à jour des statuts du suivi, le numéro de tracking ainsi que son suivi peuvent être en décalage avec la réalité.

2. Utilisation de la clé OTP

Une fois le document en sa possession, l’expéditeur peut générer des TOTP afin de s’identifier lors de l’envoi d’une LRE eIDAS via la route /mail/ (dans le champ otp). Voir comment l’utilisateur peut générer lui-même ses TOTP

Si l’expéditeur est amené à effectuer plusieurs envois il peut également s’identifier pendant une heure sur l’API pour faire des envois qualifiés en n’entrant qu’un seul OTP via la route /user/auth_otp

Les paramètres attendus sont les suivants :

• token : votre token
• id_user : l’identifiant du compte expéditeur que vous souhaitez identifier grâce à un de ses codes OTP
• otp : code OTP en cours lié à l’identifiant du compte expéditeur

Vous obtenez alors un retour de notre API avec le statut SUCCESS et également la date de fin de l’identification de l’expéditeur dans le paramètre expiration_date. (Dans le cas d’une erreur, vous retrouverez dans le retour une explication et un slug. Vous retrouverez dans notre documentation la liste des erreurs dans l’onglet « Error » de la route en question).

Un paramètre hash est retourné lors de la requête, celui-ci doit être transmis lors de l’envoi d’un courrier dans le champ auth_otp_hash.

La génération des OTP se base sur la norme https://tools.ietf.org/html/rfc6238. Vous pouvez très simplement générer les OTP de vos expéditeurs directement dans votre logiciel en y incluant un générateur de TOTP basé sur la clé OTP du client. A titre d’exemple, nous avons un outil en ligne à l’adresse suivante afin de montrer la faisabilité d’un tel processus : https://otp-client.ar24.fr/

Vous pouvez retrouver d’autres exemples de code :

• https://github.com/arcanericky/ga-cmd en ligne de commande
• http://www.nongnu.org/oath-toolkit/oathtool.1.html en ligne de commande
• https://github.com/gbraad/gauth avec un exemple utilisable en ligne : https://gauth.apps.gbraad.nl/
• https://github.com/qoomon/otp-authenticator-webapp avec un exemple utilisable en ligne : https://qoomon.github.io/otp-authenticator-webapp/
• https://github.com/jiangts/JS-OTP avec un exemple utilisable en ligne : https://jiangts.github.io/JS-OTP/
• et d’autres exemples en fonction de votre langage de programmation : https://github.com/search?q=totp+generator

Stockage de votre clé OTP

L’identifiant d’AR24 est un document vous permettant de confirmer votre identité pour accuser réception ou expédier des LRE. Il s’agit d’un moyen d’authentification à part entière et qui doit donc être stocké de manière complètement sécurisée. Ce document contient la clé OTP vous permettant de générer automatiquement des codes à usages uniques (Protocole TOTP).

Cette clé OTP est une donnée sensible, c’est pourquoi vous devez obligatoirement :

• Permettre à l’utilisateur de révoquer la clé OTP en cas de perte ou de vol /user/identity_revoke/
• Stocker de manière sécurisé la clé, seul l’utilisateur associé à la clef doit pouvoir accéder et utiliser cette donnée
• Stocker cette clé localement sur un dispositif sous contrôle exclusif de l’utilisateur
• Stocker la clé de manière chiffrée en utilisant des algorithmes sécurisés tels que l’AES256

3. Modification des informations du profil de l’expéditeur

Une fois l’identité de l’expéditeur vérifiée, il n’est plus possible d’éditer le nom, le prénom ainsi que la société du compte en question : ces informations étant fortement liées à la vérification d’identité effectuée. Pour modifier ces informations vous devrez :

• Révoquer la vérification d’identité du compte en question via la route /user/identity_revoke. Cette action désactivera la clé OTP actuelle du compte et ne sera plus utilisable.
• Modifier les informations du compte via la route /user
• Effectuer une nouvelle vérification d’identité en reprenant la procédure expliquée dans la partie 1. Vérifier l’identité de l’expéditeur via l’API. Cette action générera une nouvelle clé OTP pour le compte en question.