Documentation
Documentation
Application Web BETA

1Idée générale des Web Apps

Avec une Web App, un système externe peut demander l’accès à des Spaces spécifiques via l’API du service web. L’utilisateur peut accorder l’accès à d’autres systèmes de manière automatisée. Le flux OAuth 2.0 décrit ce concept en détail.

De manière générale, la spécification OAuth laisse une certaine marge pour adapter ce cas d’usage concret.

2Flux OAuth 2.0

L’intégration suit globalement la spécification OAuth. Le flux implique les acteurs suivants :

  • Utilisateur : L’utilisateur peut accorder à la Web App l’accès à un Space. L’utilisateur est généralement le marchand qui accorde l’accès à votre application.

  • Client : Le client appelle l’API du service web pour accéder aux données au sein du Space. Il s’agit de votre application. Votre application peut également s’exécuter sur un serveur web.

  • Server : Nous utilisons dans cette documentation le terme server pour notre système. Comme dans le modèle client-serveur, notre système représente le serveur.

Pour garder cette documentation simple, nous réutilisons la terminologie de la spécification OAuth.

OAuth Flow
Figure 1. Le flux OAuth 2.0 avec les différents acteurs.

La figure ci-dessus montre les étapes suivantes :

  1. L’utilisateur demande l’installation de la Web App.

  2. La Web App (client) renvoie l’URL d’autorisation via laquelle l’utilisateur accorde l’accès à la Web App. L’URL d’autorisation requiert la présence d’une redirect_uri.

  3. Lorsque l’utilisateur appelle l’URL d’autorisation, le serveur demande à son tour à l’utilisateur de confirmer l’autorisation demandée sur le Space. En conséquence, le serveur renvoie la redirect_uri au navigateur.

  4. Le navigateur appelle la redirect_uri qui pointe vers une URL contrôlée par la Web App. La redirect_uri contient un paramètre code grâce auquel la Web App peut demander l’installation de l’application.

Les sections suivantes couvrent les étapes ci-dessus plus en détail.

2.1Créer la configuration de la Web App

Dans un premier temps, vous devez configurer une Web App et récupérer le client_id et le client_secret.

2.2Déclencher l’installation

Il existe deux façons pour l’utilisateur de démarrer l’installation. Dans les deux cas, la Web App doit rediriger l’utilisateur vers l'`authorization URL`. Voir Demander l’autorisation pour savoir comment procéder.

  • Option 1 : L’utilisateur déclenche l’installation depuis notre application. Dans ce cas, nous redirigeons l’utilisateur vers l'`Installation Redirect URL` telle que définie dans la configuration de la Web App. Dans ce cas, l’utilisateur appellera l'`Installation Redirect URL` sous forme de requête HTTP GET. Nous veillons à ce que la requête contienne les paramètres suivants :

    • space_id : L’application est installée dans le Space résolu par l’ID du Space.

    • action : L’action est définie sur install. L’action permet de comprendre quelle opération doit être effectuée.

    • timestamp : L’horodatage en secondes depuis 1970. Cela permet de vérifier les attaques par rejeu. Il est recommandé de refuser les requêtes datant de plus de quelques heures.

    • hmac : Un HMAC est calculé à partir des paramètres de requête space_id, action et timestamp. Cela permet la vérification qu’une requête provient réellement de nous. Voir Calcul du HMAC.

  • Option 2 : L’utilisateur déclenche l’installation depuis la Web App. Dans ce cas, la Web App doit demander l’ID du Space ou utiliser une autre approche pour le récupérer.

2.3Demander l’autorisation

Pour demander l’autorisation à l’utilisateur, l’utilisateur doit être redirigé vers : https://app-wallee.com/oauth/authorize

La requête doit contenir les paramètres de requête suivants :

  • space_id : L’application est installée dans le Space résolu par l’ID du Space.

  • redirect_uri : L’URI vers laquelle l’utilisateur est redirigé après avoir autorisé l’accès. La configuration de la Web App doit contenir cette URL en tant que redirection endpoint, sinon elle sera rejetée.

  • scope : Le paramètre scope contient une liste, séparée par des espaces, des ID d’autorisation demandés. La liste des autorisations fournit la liste complète de toutes les autorisations pouvant être demandées.

  • state : Une valeur générée aléatoirement, fournie par votre application (client), qui est unique pour chaque requête d’autorisation. Lorsque l’utilisateur revient à la redirect_uri, nous incluons à nouveau cette valeur. Il est important que vous vérifiiez cette valeur, car la sécurité peut être compromise. Nous recommandons de vous assurer que le state ne puisse pas être utilisé pour des attaques par rejeu (par exemple inclure un horodatage et refuser les requêtes trop anciennes).

  • client_id : L’ID client qui identifie votre application. Le client ID peut être récupéré dans la configuration de la Web App.

Si vous demandez dans le paramètre scope des autorisations qui nécessitent des fonctionnalités spécifiques non disponibles pour le Space, nous essayons soit d’activer ces fonctionnalités, soit de renvoyer un ensemble réduit d’autorisations lors de la confirmation de l’installation. Nous supprimons donc les autorisations que nous ne pouvons pas accorder.

Exemple de requête :

https://app-wallee.com/oauth/v2/authorize?space_id=15023&client_id=14141&redirect_uri=https%3A%2F%2Fexample.com%2Fconfirm%2Finstall&state=1609445756&scope=1432736711150%201432736711152
Note
 Si vous souhaitez modifier les autorisations de la Web App à un moment donné, vous pouvez exécuter les mêmes étapes que si vous installiez l’application à partir de zéro. Vous pouvez rediriger l’utilisateur vers l'`\https://app-wallee.com/oauth/v2/authorize` avec le paramètre scope adapté. Toutes les étapes suivantes restent identiques.

2.4Confirmer l’installation de l’application

Lorsque l’utilisateur revient à la redirect_uri, la Web App doit confirmer l’installation et récupérer l'`access_token` conformément à la spécification OAuth.

Avec la redirect_uri, les paramètres suivants seront envoyés :

  • state : Le paramètre state contient la valeur transmise à l’URL d’autorisation. Vérifiez que cette valeur est identique à celle que vous avez transmise.

  • space_id : L’ID du Space auquel l’utilisateur a accordé l’accès.

  • timestamp : L’heure à laquelle l’utilisateur a accordé l’accès. L’heure est en secondes depuis 1970 (horodatage Unix). Vérifiez que l’octroi n’est pas trop ancien. Une valeur raisonnable ici est d’environ 10 minutes. Cela empêche les attaques par rejeu.

  • code : Le code identifie l’octroi créé à l’étape précédente. Vous avez besoin de ce code pour confirmer l’installation. Voir ci-dessous comment procéder.

  • return_url : L’URL vers laquelle l’utilisateur peut être redirigé une fois l’installation terminée. Le paramètre optionnel message peut être ajouté à l’URL pour afficher un message personnalisé. Le paramètre d’URL type définit si un message success ou un message failure est affiché.

  • hmac : Le HMAC permet de vérifier que la requête n’a pas été altérée. Voir Calcul du HMAC pour savoir comment procéder.

Exemple de requête :

https://example.com/confirm/install?state=1609445756&space_id=14141&timestamp=1609449756&code=AdF7812311414312312387483&hmac=8jAYtV4R7FFTjl3UqWpkmBy78PVQdDygJ1NbM7v_-1AcAMWMhv45PPJA-nYkNT4gCNZ2XECYF3-N5W29ZXGJ6Q

Pour confirmer l’installation, vous devez envoyer un appel API. Vous devez envoyer un message POST à l' URL https://app-wallee.com/api/v2.0/web-apps/confirm/{code}. Voir aussi la documentation du service web.

Comme il s’agit d’un point de terminaison de service web classique, vous devez fournir les identifiants d’authentification dans l’en-tête de la requête HTTP. À cette fin, utilisez le client_id comme identifiant d’utilisateur et pour le client_secret le secret.

La réponse ressemble à l’exemple suivant :

{
    "access_token": "dummy-value",
    "scope": "1432736711150 1432736711152",
    "space": 14141,
    "state": "1609445756",
    "token_type": "web-service-hmac",
}

À cette étape, vous devriez vérifier si la liste scope renvoyée correspond à ce que vous avez demandé et si l’ensemble renvoyé répond à vos exigences. Comme indiqué précédemment, toutes les autorisations demandées ne peuvent pas être accordées dans toutes les situations.

L’étape suivante explique comment appeler réellement l’API du service web.

2.5Accéder à l’API du service web

Une fois l’application installée avec succès dans le Space, le client_id et le client_secret peuvent être utilisés pour accéder à l’API du service web pour le Space donné. Sur l’API du service web, vous devez utiliser le client_id comme identifiant d’utilisateur et le client_secret comme secret. L’appel de l’API se fait de la même manière que si vous créiez un utilisateur d’application et utilisiez ses identifiants pour appeler l’API.

2.6Configurer la Web App

L’URL de redirection de configuration permet de définir une page sur laquelle la Web App peut être configurée par l’utilisateur. Cela signifie que la liste des Web Apps contiendra un bouton Configure qui redirige l’utilisateur vers l’URL définie dans la configuration de la Web App.

L’URL de redirection contient les paramètres suivants :

  • space_id : L’ID du Space identifie le Space pour lequel la configuration doit être ajustée.

  • timestamp : L’horodatage en secondes depuis 1970. Cela permet de vérifier les attaques par rejeu. Il est recommandé de refuser les requêtes datant de plus de quelques heures.

  • action : L’action est définie sur configure. L’action vous permet de comprendre l’action déclenchée par l’utilisateur.

  • return_url : L’URL vers laquelle l’utilisateur peut être redirigé une fois la configuration terminée. Le paramètre optionnel message peut être ajouté à l’URL. Ce message sera affiché à l’utilisateur. Le paramètre type définit si un message success ou un message failure est affiché.

  • hmac : Un HMAC est calculé à partir des paramètres de requête space_id, action, return_url et timestamp. Cela permet la vérification qu’une requête provient réellement de nous. Voir Calcul du HMAC.

Note
 Vous devriez toujours vérifier le hmac pour éviter qu’un attaquant puisse modifier la configuration d’une application. Le hmac garantit que l’utilisateur est autorisé à effectuer l’opération de configuration.

3Notifications

Pour maintenir votre Web App synchronisée avec l’état d’installation au sein des différents Spaces, nous recommandons de configurer une URL de notification. Tout changement de l’installation de la Web App au sein d’un Space sera signalé sur cette URL.

Nous envoyons un message HTTP POST avec le corps suivant :

{
	"space_id": 15023,
	"client_id": "14141",
}

Le message ne précise pas si l’application a été installée ou désinstallée. Utilisez l’API du service web pour découvrir quel a été le déclencheur de l’envoi de ce message.

Le comportement ci-dessus est intentionnel. Il résout les problèmes suivants :

  • Il peut arriver qu’une notification soit envoyée avec un retard parce que nous avons eu des difficultés à joindre votre système. Dans ce cas, vous lisez tout de même l’état d’installation depuis une source unique qui détient l’état correct.

  • Il n’y a aucun risque de sécurité, car aucune information critique n’est incluse dans la requête HTTP. Le message n’est qu’un déclencheur pour que vous récupériez les informations correctes via l’API du service web.

  • Dans certains cas, la Web App et notre système peuvent se désynchroniser en raison de pannes temporaires. Avec l’approche ci-dessus, vous pouvez décider de récupérer l’état d’installation actuel à tout moment.

Note
 Sachez qu’une panne de votre système peut nous empêcher d’envoyer des notifications à votre système. Dans ce cas, nous envoyons un e-mail si cela est spécifié dans la configuration de votre Web App.

4Calcul du HMAC

Pour vérifier que les requêtes proviennent de notre système, nous ajoutons un HMAC avec SHA-512. Il garantit que les paramètres ne sont pas modifiés pendant la transmission. C’est similaire à un hachage normal, mais de manière sécurisée. La plupart des langages de programmation fournissent une implémentation pour le calcul du HMAC.

De manière générale, nous devons d’abord construire une chaîne et la sécuriser ensuite avec le client_secret. Pour ce faire, nous prenons tous les paramètres, les ordonnons alphabétiquement et les concaténons avec un | (barre verticale).

Voir l’exemple PHP suivant avec les paramètres : space_id, timestamp, client_id et scope

<?php

$client_secret = "OWOMg2gnaSx1nukAM6SN2vxedfY1yLPONvcTKbhDv7I=";

$requestParameters = array();
$requestParameters['client_id'] = "14141";
$requestParameters['state'] = "87ggfr456zghjui876tgvbji";
$requestParameters['space_id'] = 15023;
$requestParameters['scope'] = "1432736711150 1432736711152";

// We sort the array elements by the element's key
ksort($requestParameters);


$parametersToSecure = array();

foreach ($requestParameters as $key => $value) {
	$parametersToSecure[] = $key . "=" . $value;
}

$toSecure = implode('|', $parametersToSecure);

$decodedSecret = base64_decode($client_secret);
$hmacValue = base64_encode(hash_hmac("sha512", $toSecure, $decodedSecret, true));

// Replacing "+" with "-" and "/" with "_"
$cleanedMac = $url = strtr($hmacValue, '+/', '-_');

// Remove padding
$cleanedMac = rtrim($cleanedMac, '=');

echo $cleanedMac;

Remarques :

  • Nous n’encodons pas les paramètres en URL lorsque nous calculons le HMAC. Lorsque votre infrastructure (par exemple le serveur) ne décode pas automatiquement le paramètre d’URL, vous devrez peut-être le faire avant de calculer le HMAC.

  • Le client_secret fourni sur la page de configuration de la Web App est encodé en tant que chaîne Base64. Nous devons d’abord le convertir en binaire.

  • Les paramètres à sécuriser dépendent du cas d’usage. Nous utilisons le HMAC dans plusieurs situations, veuillez donc adapter les paramètres en conséquence. Nous incluons uniquement les paramètres explicitement listés. Nous n’incluons jamais tous les paramètres. Ainsi, si la requête contient d’autres paramètres, ignorez-les.

  • Le HMAC inclus dans la requête est toujours encodé en Base64. Lorsque vous comparez le HMAC calculé avec le HMAC transmis, veuillez les comparer au format binaire ou assurez-vous d’unifier d’abord les différents formats Base64. Étant donné le fait que nous transmettons le HMAC en tant que paramètre d’URL, nous devons utiliser une implémentation compatible avec les URL sans remplissage. Voir RFC 4648

  • Les valeurs des paramètres peuvent provenir d’un objet JSON. Dans ce cas, les valeurs doivent être converties en chaînes avant de les concaténer. Les nombres à virgule flottante sont représentés avec un point et avec le même nombre de chiffres que dans le JSON, et les éventuels zéros à la fin seront également ajoutés. Les booléens doivent être représentés comme true ou false.

5Appel distant

Dans certains cas, les points de terminaison de votre application seront appelés par une requête HTTP envoyée via nos serveurs vers vos serveurs. La requête a donc lieu sans l' utilisateur (navigateur). Cette section couvre des informations importantes sur ces appels.

5.1Objectif des appels distants

Dans certains cas, nous devons vous informer de certaines activités que votre application doit effectuer. Dans ces cas, nous utilisons des appels distants. Ces appels envoient à une URL définie par vous une requête HTTP avec certaines données. Les données que nous envoyons dépendent du cas d’usage concret. Nous couvrons ici uniquement les éléments qui s’appliquent à tous les types d’appels.

Veuillez donc utiliser les documentations correspondantes pour les cas d’usage concrets afin de comprendre ce que contiendra le corps réel de la requête.

5.2Sécurité

Chaque requête contient un en-tête x-mac-value. Cet en-tête contient un HMAC qui vous permet de vérifier que la requête provient réellement de nos systèmes. De plus, la requête contient également l’en-tête x-timestamp qui indique l’heure à laquelle la requête a été créée. L’horodatage contient l’heure en secondes depuis le premier janvier 1970. Il s’agit donc d’un horodatage Unix.

Pour vérifier le HMAC, vous devez concaténer la valeur de x-timestamp avec une barre verticale (|) et le corps de la requête. La chaîne résultante doit être transmise au HMAC avec l’algorithme SHA-512. Comme secret, vous pouvez utiliser le secret généré pour l’application. Donc le même secret que celui que vous utilisez aussi pour appeler notre API de service web.

Voir ci-dessous également un exemple en PHP :

<?php

$client_secret = "OWOMg2gnaSx1nukAM6SN2vxedfY1yLPONvcTKbhDv7I=";

$hmac = $_SERVER['HTTP_X_MAC_VALUE']; // PHP requires to transform the header name.
$timestamp = $_SERVER['HTTP_X_TIMESTAMP']; // PHP requires to transform the header name.

$body = file_get_contents('php://input'); // That might be different depending on how you run PHP

$toSecure = $timestamp . '|' . $body;

$decodedSecret = base64_decode($client_secret);
$calculatedHmac = base64_encode(hash_hmac("sha512", $toSecure, $decodedSecret, true));

if (strtolower($calculatedHmac) !== strtolower($hmac)) {
	die('The calculated HMAC does not match with the supplied one.');
}

$allowedOffset = 15 * 60; // 15 minutes
if ($timestamp < time() - $allowedOffset) {
	die('The request has expired. This seems like a reply attack.');
}

5.3Fiabilité

Si votre serveur est hors ligne, nous répétons les requêtes plusieurs fois. Nous considérons la requête comme livrée avec succès lorsque nous recevons une réponse HTTP avec un code de statut HTTP 2XX. Toute autre réponse sera considérée comme un échec. Cela inclut les redirections via le code de statut HTTP 302 ou 301.

De même, lorsque le serveur n’est pas joignable, nous répétons l’appel. Il y a aussi un délai d’expiration de 30 secondes. Votre serveur doit répondre dans les 30 secondes, sinon nous répétons l’appel. Lorsque nous répétons l’appel, nous incluons des en-têtes mis à jour (x-mac-value et x-timestamp) et le corps peut aussi éventuellement contenir des données mises à jour.

Il vous appartient de gérer les appels multiples. Selon le cas d’usage, il existe différentes alternatives. Veuillez consulter la documentation correspondante pour voir quelles possibilités vous avez d’empêcher l’exécution de l’opération correspondante plus d’une fois.