# Utiliser des liens d'installation Autorisez les utilisateurs à installer votre application hors du Stripe App Marketplace. Les liens d’installation permettent aux utilisateurs d’installer des applications publiques en dehors du Stripe App Marketplace. Avec un flux intégré, vous pouvez transmettre l’état de votre application, terminer l’installation de l’application Stripe et effectuer une redirection vers votre application ou votre site. ![La page du lien d'installation affichant des autorisations d'accès](https://b.stripecdn.com/docs-statics-srv/assets/oauth-permissions.9f11ce1ba29fdd77c9d4fa9ee2944222.png) La page du lien d’installation ## Présentation En suivant les étapes suivantes, un utilisateur peut installer une application à l’aide d’un lien d’installation : 1. Sur votre site, l’utilisateur clique sur un lien qui le redirige vers Stripe, en transmettant l’`app_id`. 1. Sur Stripe, l’utilisateur sélectionne le compte approprié et accepte les autorisations pour l’installation de votre application. 1. Après l’installation, l’utilisateur [est redirigé vers votre site](https://docs.stripe.com/stripe-apps/install-links.md#redirect), avec le compte Stripe de l’utilisateur indiqué. 1. Votre application peut désormais effectuer des requêtes de comptes authentifiés. ## Créer un lien d'installation Définissez votre `allowed_redirect_uris` dans votre manifeste d’application. Ce sont les URL vers lesquelles les utilisateurs sont redirigés après avoir installé votre application. Vous devez spécifier toutes les URL de redirection dans les paramètres de votre application. Après avoir défini `allowed_redirect_uris`, [chargez une nouvelle version](https://docs.stripe.com/stripe-apps/upload-install-app.md) de votre application. ```json { "id": "com.invoicing.[YOUR_APP]", "version": "1.2.3", "name": "[YOUR APP] Shipment Invoicing", "icon": "./[YOUR_APP]_icon_32.png", "permissions": [], "app_backend": {}, "ui_extension": {},"allowed_redirect_uris": [ "https://example.com/callback/stripe" ] } ``` ## Tester votre lien d'installation Pour vérifier que le lien d’installation fonctionne avant de l’envoyer pour examen, vous pouvez utiliser le [test externe](https://docs.stripe.com/stripe-apps/test-app.md) en appliquant la procédure suivante : 1. [Créez un test externe](https://docs.stripe.com/stripe-apps/test-app.md) pour votre application en utilisant la version avec le `allowed_redirect_uris` définie dans le manifeste de l’application. Si un test existe déjà, vous pouvez mettre à jour la version de test vers celle souhaitée. 1. L’onglet **Test externe** présente un lien d’installation de test et affiche les redirections autorisées dans un tableau. 1. Lorsque vous êtes prêt à publier, assurez-vous de charger une nouvelle version dont les URL et les valeurs de test ont été remplacés par les valeurs que vous comptez utiliser en mode production. ![Onglet Test externe affichant les liens d'installation](https://b.stripecdn.com/docs-statics-srv/assets/external-test.8df1fb2e4ac4df4c934d4acca85ed2de.png) ## Utilisation d'un lien d'installation Lorsque vous avez terminé les tests, vous pouvez le rendre disponible pour tous les utilisateurs en suivant les étapes ci-après : 1. [Publiez une nouvelle version](https://docs.stripe.com/stripe-apps/publish-app.md) de votre application qui définit `allowed_redirect_uris`. 1. Cliquez sur l’onglet **Paramètres**. Vous pouvez copier le lien d’installation affiché. Il prend la forme suivante : `https://marketplace.stripe.com/apps/install/link/{id}?redirect_uri=https://example.com`. 1. (Recommended) Pour prévenir les attaques CSRF, vous pouvez ajouter les `state` et transmettre un token unique comme valeur. Nous inclurons le `state` que vous avez fourni lors de la redirection des utilisateurs vers votre site. Votre site peut confirmer que le paramètre `state` n’a pas été modifié. 1. Une fois qu’un utilisateur a cliqué sur le lien d’installation, Stripe ouvre la page suivante sur laquelle il peut sélectionner un compte, consulter les informations relatives à l’application et procéder à l’installation. ![Sélection d'un compte pour installer l'application sur](https://b.stripecdn.com/docs-statics-srv/assets/account-selection.13dde83d3b3b16c9d0faee76b98e584b.png) Sélection du compte pour le lien d’installation ## Redirection vers votre site Une fois que l’utilisateur a installé votre application, il est redirigé vers l’URL définie dans le paramètre `redirect_uri`, qui correspond à une redirection définie dans `allowed_redirect_uris` dans le manifeste de votre application. ### Installation réussie Pour que les installations fonctionnent, l’URL doit inclure : - La valeur `user_id`. L’ID de l’utilisateur Stripe qui a lancé l’installation. - La valeur `account_id`. L’ID du compte Stripe qui a installé votre application. - La valeur `state`, le cas échéant - La valeur `install_signature`. Il s’agit d’un hachage des valeurs ci-dessus qui est généré à l’aide de la [clé secrète de signature](https://docs.stripe.com/stripe-apps/build-backend.md#expire-and-create-secrets) de votre application. - Si l’application est installée en mode test ou dans un *environnement de test* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes), une valeur `livemode=false` est ajoutée à l’URL de redirection. *Exemple de redirection en mode production :* ```url https://example.com/callback/stripe?user_id={USER_ID}&account_id={CONNECTED_ACCOUNT_ID}&state={STATE}&install_signature={INSTALL_SIGNATURE} ``` *Exemple de redirection vers le mode test et un environnement de test :* ```url https://example.com/callback/stripe?user_id={USER_ID}&account_id={CONNECTED_ACCOUNT_ID}&state={STATE}&install_signature={INSTALL_SIGNATURE}&livemode=false ``` ### Échec de l’installation Si l’utilisateur annule l’installation, il sera quand même redirigé vers votre site, mais cette fois l’URL comprendra une erreur : ```url https://example.com/callback/stripe?error=access_denied&error_description=The%20user%20denied%20your%20request ``` L’utilisateur est maintenant connecté à votre application. Sauvegardez le `account_id` dans votre base de données - il s’agit de l’identifiant du compte Stripe de l’utilisateur. Vous utiliserez cette valeur pour [l’identifier en tant que compte connecté](https://docs.stripe.com/connect/authentication.md) en la transmettant dans les requêtes dans l’en-tête `Stripe-Account`. ### Vérifiez les installations d’application avec install_signature (Recommended) Il est important de vérifier que l’utilisateur de votre application est autorisé à installer l’application pour le compte indiqué dans l’URL de redirection. C’est pour cette raison qu’une `install_signature` est incluse. Cette signature est générée à partir de la [clé secrète de signature](https://docs.stripe.com/stripe-apps/build-backend.md#expire-and-create-secrets) de votre application et des paramètres `user_id` et `account_id` ayant effectué l’installation. La signature inclut également le paramètre `state` transmis, le cas échéant. La signature ne peut pas être répliquée sans accès à la clé secrète de signature, qui est uniquement disponible en interne pour Stripe et pour le back-end de votre application. Les personnes malveillantes ne peuvent donc pas reproduire le hachage s’ils tentent d’usurper l’URL de redirection. Vérifier la signature de l’application permet de garantir que le compte est associé à l’utilisateur de votre application. Pour vérifier la signature, suivez ces étapes : 1. Si vous ne l’avez pas encore fait, [créez la clé secrète de signature de votre application](https://docs.stripe.com/stripe-apps/build-backend.md#expire-and-create-secrets). 1. [Configurez un back-end d’application](https://docs.stripe.com/stripe-apps/build-backend.md#send-a-signed-request) pour vérifier la valeur `install_signature`. #### Exemple de back-end vérifiant l’installation : L’ordre et le nom des champs de la charge utile ont une incidence sur la vérification de la signature… Le `state` précède le `user_id`, qui précède le `account_id`. L’objet résultant doit être `{ state, user_id, account_id }`. #### Ruby ```ruby require 'stripe' require 'sinatra' require 'json' Stripe.api_key = 'API_KEY' get '/' do 'Install Links verification example' end get '/verify' do user_id = params[:user_id] account_id = params[:account_id] state = params[:state] install_signature = params[:install_signature] payload = JSON.dump({ state: state, user_id: user_id, account_id: account_id }) begin Stripe::Webhook::Signature.verify_header( payload, install_signature, 'STRIPE_APP_SECRET' ) rescue Stripe::SignatureVerificationError => e return e.message, 400 end { success: true }.to_json end set :port, 3000 ``` Après vérification, vous pouvez [effectuer des appels à l’API](https://docs.stripe.com/stripe-apps/build-backend.md#using-stripe-apis) au nom du compte installé. ## Effectuer des requêtes authentifiées Pour les appels à l’API côté serveur, vous pouvez effectuer des requêtes en tant que comptes connectés à l’aide de l’en-tête spécial `Stripe-Account` et de l’identifiant de compte Stripe (qui commence par le préfixe `acct_`) de l’utilisateur de votre plateforme. Voici un exemple qui montre comment [créer un PaymentIntent](https://docs.stripe.com/api/payment_intents/create.md) avec la [clé API secrète](https://docs.stripe.com/keys.md) de votre plateforme et l’identifiant du [compte](https://docs.stripe.com/api/accounts.md) de votre utilisateur. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d amount=1000 \ -d currency=usd \ -d "payment_method_types[]=card" ``` L’approche d’en-tête `Stripe-Account` est implicite dans toute requête API qui inclut l’ID du compte Stripe dans l’URL. Voici un exemple qui montre comment [récupérer un compte](https://docs.stripe.com/api/accounts/retrieve.md) avec l’identifiant du [compte](https://docs.stripe.com/api/accounts.md) de votre utilisateur dans l’URL. ```curl curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}} \ -u "<>:" ``` Découvrez plus d’exemples de [requêtes authentifiées ici](https://docs.stripe.com/connect/authentication.md). ## Personnaliser les liens avec des paramètres d’URL Vous pouvez modifier le comportement de l’installation d’applications en incluant des paramètres d’URL supplémentaires dans le lien d’installation. ### Paramètres d’URL pris en charge | Paramètre | | Description | | -------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `redirect_uri` | | L’URL vers laquelle les utilisateurs sont redirigés après avoir installé votre application. Si elle est fournie, elle doit correspondre exactement à l’une des valeurs `redirect_uris` séparées par une virgule de votre [manifeste d’application](https://docs.stripe.com/stripe-apps/reference/app-manifest.md). Pour vous protéger contre certaines attaques d’intercepteurs, la `redirect_uri` du mode production doit utiliser une connexion HTTPS sécurisée. | | `state` | (Recommandé) | Une valeur d’une chaîne arbitraire qui vous sera renvoyée. Elle est recommandée pour la protection contre les attaques CSRF. | ### Prévenir les attaques CSRF à l’aide du paramètre d’état Vous pouvez utiliser le paramètre `state` pour prévenir les attaques de type CSRF (Cross-Site Request Forgery). Celui-ci accepte n’importe quelle valeur de chaîne et la renvoie telle quelle lors de la redirection de l’outil d’installation vers votre application ou votre plateforme. Pour utiliser ce paramètre, transmettez une valeur unique difficile à deviner au lancement d’une installation à partir d’un lien d’installation. Enregistrez cette valeur afin de l’utiliser à des fins de vérification par la suite. Une fois que l’utilisateur a effectué l’installation et a été redirigé vers votre application, vérifiez que la valeur du paramètre d’état fourni correspond à la valeur présente dans le lien d’installation initial. Ce processus de vérification permet de confirmer avec un niveau de confiance élevé que `account_id` renvoyé appartient bien à l’utilisateur qui a lancé l’installation. Vous pouvez ainsi vous prémunir contre d’éventuelles falsifications. ## Révocation de l’accès Un [événement](https://docs.stripe.com/api.md#list_events) `account.application.deauthorized` se produit lorsqu’un utilisateur déconnecte votre application de son compte. Vous pouvez effectuer le nettoyage nécessaire sur vos serveurs en surveillant cet événement via des [webhooks](https://docs.stripe.com/connect/webhooks.md). ## See also - [Fonctionnement de Stripe Apps](https://docs.stripe.com/stripe-apps/how-stripe-apps-work.md) - [Documentation complète relative à l’API](https://docs.stripe.com/api.md)