Authentification

Vous devez authentifier vos requêtes pour accéder aux points de terminaison de l’API Protocol. Ce guide explique le fonctionnement de l’authentification. Les requêtes utilisant l’authentification MeSomb Signature doivent être signées conformément au standard MeSomb.

Note: Toutes les requêtes doivent être envoyées via le https protocole de transport.

Sécurité des signatures et migration SHA256

HMAC-SHA256 est pris en charge avec HMAC-SHA1 pour les clients existants. Pour SHA256, remplacez SHA1 dans l’empreinte du corps, l’empreinte de la requête canonique et le HMAC final, puis utilisez HMAC-SHA256 dans Authorization. Le format canonique ne change pas. Les signatures SHA256 comportent 64 caractères hexadécimaux minuscules. Les exemples SHA1 ci-dessous restent applicables aux SDK existants ; vérifiez la compatibilité du SDK avant de changer d’algorithme.

Les requêtes API signées doivent inclure host et x-mesomb-date dans SignedHeaders et fournir chaque en-tête signé. Les requêtes POST exigent également un x-mesomb-nonce signé. Le nonce est facultatif pour les autres méthodes, notamment GET /api/v1.1/payment/transactions/check/. Pour GET, un nonce absent ou vide est aussi accepté lorsqu’il figure dans SignedHeaders : sa valeur canonique reste vide et la signature est tout de même vérifiée. Un nonce non vide doit être signé et fait l’objet d’un contrôle contre le rejeu. Le timestamp doit comporter exactement 10 chiffres (secondes) ou 13 chiffres (millisecondes). Pour 13 chiffres, les 10 premiers servent aux contrôles de date et d’expiration ; signez la valeur complète originale de l’en-tête. Par défaut, le timestamp ne doit pas dater de plus de 5 minutes ni être en avance de plus de 60 secondes. La date du Credential doit correspondre à ce timestamp en UTC. Les formats YYYYMMDD et JavaScript historique (année + mois indexé à partir de zéro + jour, sans remplissage) sont acceptés : le 16 janvier 2023 s’écrit 20230116 ou 2023016. Signez la portée Credential originale exactement telle qu’elle est envoyée. Synchronisez l’horloge de votre serveur.

Lorsque vous envoyez un nonce, utilisez une nouvelle valeur pour chaque requête : de 1 à 200 caractères ASCII imprimables sans espaces. La réutilisation d’un nonce accepté avec la même clé API est refusée pendant la fenêtre d’acceptation du timestamp. Lors d’une nouvelle tentative, générez un nouveau timestamp, un nouveau nonce et une nouvelle signature, mais conservez la clé d’idempotence pour la même opération métier. Les nonces empêchent le rejeu des requêtes signées ; les clés d’idempotence empêchent la duplication des opérations métier.

Ces contrôles s’appliquent à l’authentification MeSomb Signature de l’API v1.1. L’ancienne API v1.0 utilise un mécanisme d’authentification distinct.

Pourquoi les requêtes sont-elles signées ?

Le processus de signature contribue à sécuriser les requêtes de la manière suivante :

  • Vérifiez l’identité du demandeur La signature garantit que la requête a été envoyée par quelqu’un disposant d’une clé d’accès valide.
  • Protégez les données en transit Pour empêcher toute falsification d’une requête pendant son acheminement, certains éléments de la requête sont utilisés pour calculer un hachage (digest) de la requête, et la valeur de hachage obtenue est incluse dans la requête. Lorsqu’un service MeSomb reçoit la requête, il utilise les mêmes informations pour calculer un hachage et le compare à la valeur de hachage de votre requête. Si les valeurs ne correspondent pas, MeSomb refuse la requête.
  • Protégez-vous contre les attaques par rejeu potentielles Dans la plupart des cas, une requête doit parvenir à MeSomb dans les cinq minutes suivant l’horodatage indiqué dans la requête. Dans le cas contraire, MeSomb refuse la requête.

Comment fonctionne la signature MeSomb

MeSomb Signature (MeSombSig) est le processus consistant à ajouter des informations d’authentification aux requêtes API MeSomb envoyées via HTTPS. Pour des raisons de sécurité, la plupart des requêtes adressées à MeSomb doivent être signées avec une clé d’accès. La clé d’accès se compose d’un identifiant de clé d’accès et d’une clé d’accès secrète, généralement appelés vos identifiants de sécurité.

Comment fonctionne la version 4 de Signature

  1. Créer une requête canonique.
  2. Utilisez la requête canonique et les métadonnées supplémentaires pour créer une chaîne à signer.
  3. Dérivez une clé de signature à partir de votre clé d’accès secrète MeSomb. Utilisez ensuite la clé de signature et la chaîne de l’étape précédente pour créer une signature.
  4. Ajoutez la signature résultante à la requête HTTP dans un en-tête.

Lorsqu’un service MeSomb reçoit la requête, il effectue les mêmes étapes que celles que vous avez suivies pour calculer la signature envoyée dans votre requête. MeSomb compare ensuite la signature qu’il a calculée à celle que vous avez envoyée avec la requête. Si les signatures correspondent, la requête est traitée. Si elles ne correspondent pas, la requête est refusée.

Éléments d’une requête de signature MeSomb

Chaque requête HTTP/HTTPS qui utilise la signature MeSomb doit contenir ces éléments.

  • Méthode HTTP
  • Chemin complet de l’URL
  • Paramètres obligatoires et facultatifs
  • Date
  • Paramètres d’authentification

Méthode HTTP

Voici la méthode HTTP de votre requête : GET, POST, PATCH, PUT, HEAD, DELETE. Cette méthode doit être en majuscules.

Chemin d’URL complet

Voici l’URL complète de l’action à effectuer sur MeSomb : https:///. Vous trouverez ci-dessous le point de terminaison de chaque action à effectuer.

Paramètres obligatoires et facultatifs

Cet élément spécifie les paramètres de l’action de requête. Chaque action d’un service web dispose d’un ensemble de paramètres obligatoires et facultatifs qui définissent un appel d’API. La version de l’API est généralement un paramètre obligatoire. Consultez la documentation du service pour obtenir le détail des paramètres obligatoires et facultatifs.

Date

Il s’agit de la date et de l’heure auxquelles vous effectuez la requête. L’inclusion de la date dans la requête permet d’éviter que des tiers interceptent votre requête et la renvoient ultérieurement. La date est indiquée à l’aide du format d’horodatage via l’en-tête x-mesomb-date.

Paramètres d’authentification

Chaque requête que vous envoyez doit inclure l’ensemble des paramètres suivants que MeSomb utilise pour garantir la validité et l’authenticité de la requête.

  • Algorithme. L'algorithme de hachage que vous utilisez dans le cadre du processus de signature. Par exemple, si vous utilisez SHA1 pour créer des hachages, utilisez la valeur HMAC-SHA1 (HMAC-SHA256 est également pris en charge).
  • Portée des identifiants. Cette chaîne séparée par des barres obliques (« / ») associe l’identifiant de votre clé d’accès au service demandé. Par exemple, la chaîne suivante représente le paramètre Credential pour un service de paiement : AKIAIOSFODNN7EXAMPLE/payment
  • SignedHeaders Une liste délimitée par des points-virgules (« ; ») des en-têtes HTTP/HTTPS à inclure dans la signature.
  • Signature Une chaîne encodée en hexadécimal qui représente le résultat de l’opération de signature décrite dans la Tâche 3 : calculer la signature pour MeSomb Signature. Vous devez calculer la signature en utilisant l’algorithme que vous avez spécifié dans le paramètre Algorithm.

Signature des requêtes avec MeSomb Signature

Pour créer une requête signée, procédez comme suit :

Le tableau suivant décrit les fonctions présentées dans le diagramme. Vous devez implémenter le code pour ces fonctions.

FonctionDescription
Lowercase()Convertissez la chaîne en minuscules.
Hex()Encodage hexadécimal en minuscules.
SHA1Hash()Fonction de hachage cryptographique Secure Hash Algorithm (SHA).
HMAC-SHA1()Calcule le HMAC en utilisant l’algorithme SHA1 avec la clé de signature fournie. Il s’agit de la signature finale.
Trim()Supprimez tout espace blanc en début ou en fin.
UriEncode()Encodez chaque octet en URI.

Tâche 1 : Créer une requête canonique pour la signature MeSomb

Cette section fournit un aperçu de la création d’une requête canonique.

Voici le format de requête canonique que MeSomb utilise pour calculer une signature. Pour que les signatures correspondent, vous devez créer une requête canonique dans ce format :

{HTTPMethod}\n
{CanonicalURI}\n
{CanonicalQueryString}\n
{CanonicalHeaders}\n
{SignedHeaders}\n
{HashedPayload}

Où :

  • HTTPMethod: est l’une des méthodes HTTP, par exemple, GET, PUT, HEAD et DELETE.

  • CanonicalURI: correspond à la version encodée du chemin absolu de l’URI, du « / » suivant le nom de domaine jusqu’à la fin de la chaîne ou au caractère « ? » précédant les paramètres de requête. Dans l’exemple suivant, /example/payment est le chemin absolu ; ses barres obliques ne doivent pas être encodées : http://mesomb.hachther.com/example/payment

  • CanonicalQueryString: définit les paramètres de requête encodés pour l’URI. Encodez séparément les noms et les valeurs, puis triez les paramètres par nom de clé dans l’ordre alphabétique. Le tri intervient après l’encodage. Voici la chaîne de requête de l’URI donnée en exemple : param=value&service=payment&value=20

<span><span style="color: undefined">http://mesomb.hachther.com/service?param=value&amp;service=payment&amp;value=20</span></span>
<span><span style="color: undefined"></span></span>

La chaîne de requête canonique est la suivante (des sauts de ligne sont ajoutés à cet exemple pour des raisons de lisibilité) :

UriEncode("marker")+"="+UriEncode("someMarker")+"&"+
UriEncode("max-keys")+"="+UriEncode("20") + "&" +
UriEncode("prefix")+"="+UriEncode("somePrefix")
  • CanonicalHeaders: est une liste d’en-têtes de requête avec leurs valeurs. Les paires individuelles nom de l’en-tête et valeur sont séparées par le caractère de nouvelle ligne ("\n"). Les noms des en-têtes doivent être en minuscules. Vous devez trier les noms des en-têtes par ordre alphabétique pour construire la chaîne, comme illustré dans l’exemple suivant
Lowercase(<HeaderName1>)+":"+Trim(<value>)+"\n"
Lowercase(<HeaderName2>)+":"+Trim(<value>)+"\n"
Lowercase(<HeaderNameN>)+":"+Trim(<value>)+"\n"

Les fonctions Lowercase() et Trim() utilisées dans cet exemple sont décrites dans la section précédente.

Le CanonicalHeaders doit inclure les éléments suivants :

  • En-tête HTTP Host.
  • Si l'en-tête Content-Type est présent dans la requête, vous devez l'ajouter à la liste CanonicalHeaders.
  • Ajoutez également tous les en-têtes x-mesomb-* présents dans votre requête. Certains sont obligatoires :
  • x-mesomb-date: correspond à la date de la requête au format timestamp
  • x-mesomb-nonce: est la chaîne unique générée aléatoirement pour chaque requête

Voici un exemple de chaîne CanonicalHeaders. Les noms des en-têtes sont en minuscules et triés.

host:mesomb.hachther.com
x-mesomb-date:1666091223
x-mesomb-nonce:8fd90ffs903if0394ls
  • SignedHeaders: est une liste de noms d’en-têtes de requête en minuscules, triés par ordre alphabétique et séparés par des points-virgules. Les en-têtes de requête figurant dans la liste sont les mêmes que ceux que vous avez inclus dans la chaîne CanonicalHeaders. Par exemple, pour l’exemple précédent, la valeur de SignedHeaders serait la suivante :
host;x-mesomb-date;x-mesomb-nonce
  • HashedPayload est la valeur hexadécimale du hachage SHA1 du corps de la requête. Le corps est la représentation JSON la plus compacte de l’objet, sans espaces superflus.
Hex(SHA1Hash(<payload>)

S’il n’y a aucune charge utile dans la requête, vous calculez un hachage de l’objet JSON de chaîne vide comme suit :

Hex(SHA1Hash("{}"))

Tâche 2 : Créer une chaîne à signer pour la signature MeSomb

Cette section fournit un aperçu de la création d’une chaîne à signer.

La chaîne à signer est une concaténation des chaînes suivantes :

"HMAC-SHA1" + "\n" +
timeStamp + "\n" +
<Scope> + "\n" +
Hex(SHA1Hash(<CanonicalRequest>))

La chaîne constante HMAC-SHA1 spécifie l’algorithme de hachage que vous utilisez, HMAC-SHA1. Le timeStamp est l’horodatage actuel.

Scope lie la signature résultante à une date et à un service spécifiques (paiement, portefeuille, ...). Ainsi, votre signature résultante ne fonctionnera que pour le service spécifique. La signature est valide pendant sept jours après la date spécifiée.

date.Format(<YYYYMMDD>) + "/" <service> + "/mesomb_request"

La portée suivante limite la signature résultante au service de paiement.

20220101/payment/mesomb_request

Tâche 3 : Calculer la signature pour MeSomb Signature

La signature finale est le hachage HMAC-SHA1 de la chaîne à signer, en utilisant la clé secrète.

HMAC-SHA1(SecretKey, StringToSign)

Tâche 4 : Ajouter la signature à la requête HTTP

Vous incluez les informations de signature en les ajoutant à un en-tête HTTP nommé Authorization. Le contenu de cet en-tête est créé après le calcul de la signature, comme décrit dans les étapes précédentes, de sorte que l’en-tête Authorization n’est pas inclus dans la liste des en-têtes signés. Bien que l’en-tête soit nommé Authorization, les informations de signature sont utilisées à des fins d’authentification.

Le pseudocode suivant montre la construction de l’en-tête Authorization.

Authorization: algorithm Credential=access key ID/credential scope, SignedHeaders=SignedHeaders, Signature=signature

À l’aide d’un SDK

Si vous utilisez un SDK officiel, ces opérations sont prises en charge automatiquement. Récupérez votre jeton d’accès dans le MeSomb dashboard dans les paramètres Développeur ; la bibliothèque cliente s’occupe du reste. Toutes nos bibliothèques clientes utilisent MeSomb Signature en interne.

Diagnostiquer une erreur de signature

Les réponses conservent les champs existants detail, code, supportet le statut HTTP. Le champ diagnostic_code est ajouté pour les intégrateurs ; request_id (également renvoyé dans X-MeSomb-Request-ID) permet au support de retrouver le refus dans les journaux serveur. Le journal ne contient que cet identifiant et la catégorie du refus.

Code historique conservédiagnostic_codeQue vérifier
no-signaturesignature_missing_authorizationEn-tête Authorization absent
invalid-signature-formatsignature_invalid_formatSyntaxe, doublons ou longueur de la signature
unsupported-signature-algorithmsignature_unsupported_algorithmAlgorithme et autorisation SHA1 côté serveur
missing-signed-headersignature_missing_headerNom exact de l’en-tête dans detail ; en-tête présent et signé
invalid-signature-datesignature_invalid_timestampTimestamp Unix de 10 ou 13 chiffres et date UTC du Credential
expired-signaturesignature_expired_timestampHorloge du serveur et fenêtre d’acceptation
invalid-noncesignature_invalid_nonceFormat du nonce
bad-signaturesignature_mismatchRequête canonique, JSON et clé utilisée
replayed-requestsignature_nonce_reusedNouveau nonce pour chaque appel ; même clé d’idempotence pour une reprise métier

Les autres refus liés à la clé, à l’utilisateur ou à la portée utilisent signature_credentials_rejected et conservent leur message et leur code historiques. La voie historique v1.0 reste inchangée.

Comparer la signature avec un SDK en sandbox

Pour obtenir les détails de comparaison, utilisez une clé API sandbox et ajoutez cet en-tête à la requête :

<span><span style="color: undefined">X-MeSomb-Signature-Diagnostics: 1</span></span>
<span><span style="color: undefined"></span></span>

L’environnement est déterminé automatiquement à partir de la clé API. Utilisez des données fictives pour ces essais. Les clés inconnues ou inactives ne permettent pas d’obtenir les empreintes.

Pour un signature_mismatch, diagnostics contient la méthode, le chemin canonique, l’algorithme, les noms et l’ordre des en-têtes signés, le schéma du host, la longueur et l’empreinte SHA256 du JSON signé, l’empreinte SHA256 de la query canonique, ainsi que canonical_request_sha256 et canonical_request_digest (SHA1 ou SHA256 selon le protocole). raw_body_bytes et raw_body_sha256 décrivent le corps HTTP lorsque ses octets sont disponibles. Aucune valeur d’en-tête, query, corps, clé, signature attendue ou chaîne à signer n’est retournée.

  1. Comparez la méthode, le chemin (slash final, encodage et éventuel préfixe de langue) et la query.
  2. Comparez l’ordre des en-têtes. Le host signé contient le schéma, par exemple https://api.example.
  3. Comparez payload_sha256 avec le SHA256 du JSON compact réellement signé par le SDK. Le serveur conserve la règle historique : json.dumps(request.data, separators=(',', ':')), suivi de ensure_ascii=True et d’un encodage UTF-8. Il ne signe pas directement les octets bruts du corps HTTP. Les espaces, l’ordre des propriétés, Unicode et la représentation des nombres peuvent donc provoquer un écart.
  4. Comparez canonical_request_digest avec l’empreinte incluse dans la chaîne à signer du SDK.
  5. Si les empreintes correspondent, vérifiez localement l’algorithme, le timestamp, la portée Credential et la clé secrète. N’envoyez jamais la clé secrète au support.

Une signature différente ne permet pas au serveur d’identifier avec certitude le composant erroné. Les empreintes servent à comparer chaque étape sans contourner la vérification ni réserver un nonce pour une requête dont la signature est incorrecte.