Migrer un plugin vers une application OAuth 2.0

Comment migrer votre plugin vers l'authentification AAuth via Stripe Apps.

Utilisez ce guide pour migrer votre plugin vers une application Stripe qui utilise OAuth 2.0 pour l’authentification, également connue sous le nom d’application OAuth 2.0.

Auparavant, Stripe autorisait les plugins à demander les clés API standard d’un utilisateur pour s’intégrer à leurs produits. À partir du 30 septembre 2024, Stripe exige que tous les développeurs de plugins adoptent des méthodes d’authentification sécurisées (clé API limitée, OAuth 2.0 ou Stripe Connect) afin de protéger les utilisateurs contre la fraude. Tous les développeurs de plugins existants et nouveaux doivent utiliser l’une de ces méthodes d’autorisation sécurisées. La migration de votre plugin vers une application Oauth 2.0 répond à cette exigence.

Pour plus d’informations sur OAuth 2.0, consultez OAuth 2.0 pour Stripe Apps.

Avant de commencer

Consultez la rubrique Migrer un plugin vers Stripe Apps ou Stripe Connect.
Si vous utilisez Stripe Connect et que vous souhaitez migrer un plugin existant via Stripe Apps, vous devez créer un nouveau compte Stripe. Actuellement, les comptes Stripe ayant activé Connect ne peuvent pas publier d’application.
Vous ne pouvez créer qu’une seule application publique par compte. Si votre compte dispose déjà d’une application publique et que vous souhaitez en publier une autre, veuillez créer un nouveau compte Stripe. Vous pouvez toujours créer plusieurs applications privées sur le même compte que celui utilisé pour l’application publique.

Installez le plugin CLI Stripe

Connectez-vous au Dashboard Stripe.
Si vous ne l’avez pas encore fait, installez la CLI Stripe et connectez-vous avec le même compte.
Command Line
homebrew
# Install Homebrew to run this command: https://brew.sh/ brew install stripe/stripe-cli/stripe # Connect the CLI to your dashboard stripe login
Pour davantage d’options d’installation, consultez la page consacrée à l’interface de ligne de commande Stripe.
Vérifiez que vous utilisez la version 1.12.4 de la CLI ou une version plus récente. Pour ce faire, exécutez la commande suivante :
Command Line
```
stripe version
```
Si la version de votre CLI Stripe est antérieure à la 1.12.4, mettez votre système à jour avec la dernière version CLI Stripe.
Vérifiez que le node est installé et à jour.
Command Line
```
node -v
```
Vous pouvez gérer les dépendances de votre application avec NPM ou Yarn. Veillez à utiliser la dernière version stable. Si vous prévoyez de publier votre application sur App Marketplace, il existe des restrictions supplémentaires :
- Vous devez avoir un compte activé.
- Vous ne pouvez pas publier une application sur un compte Stripe avec Connect activé.

Développez votre application

Installez le plugin CLI Stripe Apps : pour créer une application Stripe, vous devez en premier lieu installer le plugin CLI Stripe Apps :
Command Line
```
stripe plugin install apps
```
Si vous avez déjà installé le plugin apps, vérifiez que vous utilisez bien la version 1.5.12 ou une version ultérieure.
Command Line
```
stripe apps -v
# apps version 1.5.12
```
Si vous devez mettre à niveau le plugin apps, vous pouvez exécuter :
Command Line
```
stripe plugin upgrade apps
```
Créez votre application Stripe en exécutant stripe apps create<app-name> dans l’interface de ligne de commande :
- Lorsque vous nommez votre application, Stripe interdit l’usage des termes suivants : Authenticator, RAK, Generator, RAK Auth, App, Generator App, Stripe.
- Voici quelques exemples de noms acceptés : Analytics Pro by DataWiz, Invoice Manager by PayFlow.
- Si vous développez une application pour un service tiers, utilisez la convention de dénomination suivante : [Fonctionnalités de l’application] par [Nom du développeur]. Par exemple, Hubspot Sync par Boomi.
Modifiez les champs suivants dans le manifeste de l’application :
- Définissez stripe_api_access_type sur oauth.
- Définissez distribution_type sur public.
- Définissez votre allowed_redirect_uris . Il s’agit des URL vers lesquelles vous redirigez les utilisateurs après l’installation de votre application à l’aide d’OAuth. La première dans la liste est l’URL de redirection par défaut.
Par exemple :
Command Line
```
{
  "id": "<YOUR_APP_ID>",
  "version": "0.0.1",
  "name": "Your Stripe App",
  "icon": "./[YOUR_APP]_icon_32.png",
  "permissions": [
    // Your app permissions here
  ],
  "stripe_api_access_type": "oauth",
  "distribution_type": "public",
  "allowed_redirect_uris": [
    // Your redirect URIs here
  ]
}
```
Ajoutez toutes les permissions dont votre application a besoin à l’aide de la commande stripe apps grant permission "PERMISSION_NAME" "EXPLANATION".
(Facultatif) Ajoutez des extensions d’interface utilisateur à votre application. Nous vous recommandons d’ajouter une vue des paramètres pour permettre à vos utilisateurs de configurer les paramètres ou de créer un lien vers la documentation de votre application. Si votre application ne sert qu’à l’authentification, assurez-vous de supprimer tout code d’interface utilisateur inutile. Cela permet à votre application de se concentrer sur sa fonction principale.
Chargez votre application sur Stripe en utilisant la commande stripe apps upload. Après avoir chargé votre application OAuth 2.0, vous ne pouvez pas modifier la méthode d’authentification de l’API.
Configurez OAuth 2.0 pour qu’elle fonctionne avec votre application et votre fournisseur OAuth.
- Assurez-vous d’utiliser le bon lien d’installation OAuth pour commencer le flux OAuth pour vos utilisateurs.
- Vous devez fournir une URL de rappel dans le manifeste de votre application qui peut recevoir le code d’autorisation OAuth.
- Vous devez utiliser votre clé secrète pour échanger le code d’autorisation pour des tokens d’accès et d’actualisation OAuth applicables avec le compte de l’utilisateur.
- Vous devez périodiquement utiliser le token d’actualisation pour obtenir un nouveau token d’accès pour éviter de demander à vos utilisateurs de s’authentifier à chaque fois que leur token d’accès expire.

Tester votre application

Vous pouvez tester votre application OAuth sur votre propre compte ou avec d’autres comptes :

Dans le Dashboard des développeurs > Applications, sélectionnez l’application que vous souhaitez tester en externe.
Sur la page d’informations de l’application, cliquez sur l’onglet Test externe, plus cliquez sur Démarrer.
- Si vous ne voyez pas l’onglet Test externe, vérifiez si vous avez sélectionné la distribution publique dans Créer une version.
Renseignez les champs suivants pour configurer les tests externes (vous pourrez les modifier à tout moment) :
- Accès par lien : décidez si tout le monde peut installer l’application à l’aide du lien ou si vous souhaitez autoriser uniquement les utilisateurs invités à installer l’application.
- Version : sélectionnez la version que les utilisateurs devront installer. En cas de changement, la nouvelle version est actualisée pour tous les utilisateurs actuels.
Copiez le lien d’autorisation dans la section Tester OAuth. Envoyez ce lien aux utilisateurs pour qu’ils installent l’application sur leur compte. Ces utilisateurs doivent disposer de droits d’administrateur pour installer l’application. Après qu’un utilisateur a installé la version de test de votre application, tous les membres du compte peuvent l’utiliser.

Pour plus d’informations sur les tests externes, consultez la rubrique Tester votre application en externe.

Publier et distribuer votre application

Pour publier votre application sur le Stripe App Marketplace :

Soumettez votre application pour vérification.
Une fois approuvée par Stripe, publiez votre application sur Stripe App Marketplace.

Pour distribuer votre application :

Affichez vos applications installées et cliquez sur l’application que vous souhaitez distribuer. Sur la page de détails de l’application, cliquez sur l’onglet Paramètres.
Identifiez le lien d’installation OAuth obtenu lorsque vous avez développé votre application. Ce lien est spécifique à un mode. Vous devez préciser le mode production ou le mode test en fonction de votre cas d’usage.
Utilisez systématiquement le même lien d’installation OAuth pour l’ensemble de vos produits et dans les communications destinées aux utilisateurs. Voici quelques exemples à prendre en considération :
- Mettez à jour votre documentation pour indiquer aux utilisateurs d’installer l’application Stripe OAuth 2.0, et supprimez toutes les étapes qui font référence au copier-coller des clés API.
- Ajoutez le lien d’installation OAuth à l’inscription de votre plugin pour aider les utilisateurs à installer l’application.
- Utilisez le lien d’installation OAuth dans les e-mails envoyés aux utilisateurs pour les aider à mettre à jour leurs installations existantes.

Migrer les utilisateurs existants

Après avoir migré votre plugin vers une application Stripe, vous devez migrer vos utilisateurs existants. L’approche peut varier en fonction de la façon dont vous communiquez habituellement avec vos utilisateurs. Voici quelques étapes essentielles générales qui s’appliquent à tous les plugins :

Notifiez vos utilisateurs existants pour qu’ils mettent à jour leur connexion à Stripe à l’aide de votre lien d’installation OAuth. Vous pouvez le faire par e-mail, dans l’interface utilisateur de votre plugin, par des notifications dans le produit, dans vos notes de version, ou de bien d’autres façons.
Après qu’un utilisateur a installé votre application et terminé le flux OAuth, supprimez la clé API secrète précédente.
Suivre la progression de la migration des utilisateurs. Si possible, suivez la progression des migrations d’utilisateurs. Assurez un suivi auprès des utilisateurs qui n’ont pas migré afin de garantir une transition fluide au fil du temps.

FacultatifSurveiller et améliorer le fonctionnement de votre application

Vous pouvez explorer et mettre en œuvre les actions suivantes pour améliorer de manière proactive le bon fonctionnement de votre application :

Pour promouvoir votre application, envisagez de rejoindre le Partner Ecosystem de Stripe dans le cadre de l’Apps Track. Tous les développeurs d’applications sont admissibles pour rejoindre le programme de partenariat, et les applications qui atteignent certaines étapes peuvent débloquer des avantages supplémentaires pour les partenaires au fur et à mesure qu’elles se développent.
Pour développer le Dashboard Stripe et fournir des fonctionnalités personnalisées à vos utilisateurs, créez une extension d’interface utilisateur.
Suivez votre App Analytics pour obtenir des informations sur les performances de votre référencement sur App Marketplace, telles que les mesures d’installation des utilisateurs.

FacultatifConfigurer les paiements

Si vous créez une application qui aide les utilisateurs à traiter les paiements, suivez ces instructions :

Recueillir les informations de paiement en toute sécurité

Les utilisateurs Stripe sont soumis à la conformité PCI, qui précise les modalités de stockage, de traitement et de transmission des données de carte de crédit de manière sécurisée. Les entreprises s’exposent à des sanctions en cas de non-conformité ou de violation potentielle.

Parce que vous effectuez des appels à l’API au nom d’un utilisateur Stripe, vous devez transmettre les données de carte bancaire en toute sécurité à l’aide de la tokenisation côté client. Les clients soumettent leurs informations personnelles via leur navigateur Web ou leur application mobile directement à Stripe, et en retour, Stripe vous envoie un simple token. Vos utilisateurs peuvent ainsi collecter en toute sécurité les informations de carte sans qu’aucune donnée sensible ne soit stockée sur leur serveur.

Si votre plugin comprend un formulaire de paiement côté client dans le navigateur, nous vous recommandons d’utiliser l’une des deux options suivantes :

Stripe Elements : un ensemble de composants d’interface utilisateur préconfigurés qui permet de créer votre tunnel de paiement Web. Il s’agit d’une fonctionnalité de Stripe.js, notre bibliothèque JavaScript fondamentale pour créer des tunnels de paiement.
Stripe Checkout : une intégration de paiement nécessitant peu de code qui permet de créer un formulaire personnalisable pour l’encaissement des paiements. Vous pouvez intégrer Checkout directement à votre site Web ou rediriger les clients vers une page de paiement hébergée par Stripe.

Ces deux options fournissent une tokenisation côté client.

Si votre plugin fonctionne uniquement dans un environnement back-end, incluez une note dans la documentation demandant aux utilisateurs de tokeniser les informations de paiement en utilisant Elements ou Stripe Checkout. La tokenisation aide les utilisateurs Stripe à effectuer les traitements de manière aussi sécurisée que possible sur notre plateforme.

Ajouter le composant Express Checkout Element

L’Express Checkout Element offre une intégration unique pour accepter des paiements via des boutons de paiement en un clic, notamment Apple Pay, Google Pay, Link ou PayPal. Cette intégration vous permet d’afficher plusieurs boutons en même temps. Les clients ont accès à des boutons de paiement différents selon les services pris en charge par leur appareil et leur navigateur.

Activer plusieurs moyens de paiement

Stripe prend en charge plusieurs moyens de paiement, en plus des cartes bancaires. Pour en savoir plus sur les moyens de paiement, consultez la rubrique Moyens de paiement.

L’API Payment Methods permet à vos utilisateurs d’encaisser les paiements en utilisant d’autres moyens de paiement (par exemple Alipay, iDEAL, Sofort). Vous pouvez ajouter ces moyens de paiement en utilisant un seul chemin d’intégration.

Vérifier que HTTPS est activé

Si votre plugin présente un formulaire de paiement dans un navigateur Web, il doit vérifier que le formulaire est proposé via HTTPS. Nous demandons à nos utilisateurs d’activer le protocole HTTPS. S’il n’est pas correctement sécurisé, indiquez clairement à l’utilisateur la présence d’une erreur.

L’exemple suivant montre comment vérifier si vos utilisateurs ont activé le protocole HTTPS :

Command Line
// This example uses Express
const express = require('express');
const app = express();

app.get('/', function(request, response) {
 if (!request.secure) {
   // Present an error to the user
 }
});


app.listen(3000);

Si votre plugin comporte un composant front-end, vérifiez que le protocole HTTPS est utilisé à partir du navigateur. Par exemple, en utilisant JavaScript :

Command Line
// This example checks for HTTPS from the browser
if (window.location.protocol !== "https:") {
 // Present an error to the user
}