# Ein Plugin zu einer OAuth 2.0-App migrieren

So migrieren Sie Ihr Plugin über Stripe Apps zur OAuth-Authentifizierung.

Verwenden Sie dieses Handbuch, um Ihr Plugin zu einer Stripe-App zu migrieren, die OAuth 2.0 für die Authentifizierung verwendet, auch bekannt als OAuth 2.0-App.

Zuvor hat es Stripe Plugins gestattet, die Standard-API-Schlüssel eines Nutzers/einer Nutzerin anzufordern, um sich mit deren Produkten zu vernetzen. Ab dem 30. September 2024 verlangt Stripe von allen Plugin-Entwicklern/Entwicklerinnen, dass sie sichere Authentifizierungsmethoden (eingeschränkte API-Schlüssel, OAuth 2.0 oder Stripe Connect) verwenden, um die Nutzer/innen vor Betrug zu schützen. Alle vorhandenen und neuen Plugin-Entwickler/innen müssen eine dieser sicheren Autorisierungsmethoden verwenden. Die Migration Ihres Plugins auf eine OAuth 2.0-App erfüllt diese Anforderung.

Weitere Informationen zu OAuth 2.0 finden Sie unter [OAuth 2.0 für Stripe Apps](https://docs.stripe.com/stripe-apps/api-authentication/oauth.md).

## Before you begin

- Lesen Sie den Abschnitt [Ein Plugin zu Stripe Apps oder Stripe Connect migrieren](https://docs.stripe.com/stripe-apps/plugins/decide-migration.md).
- Wenn Sie Stripe Connect verwenden und ein vorhandenes Plugin über Stripe Apps migrieren möchten, müssen Sie ein neues Stripe-Konto erstellen. Derzeit kann ein Stripe-Konto mit aktiviertem Connect keine App veröffentlichen.
- Sie können pro Konto nur eine öffentliche App erstellen. Wenn Ihr Konto bereits über eine öffentliche App verfügt und Sie eine weitere veröffentlichen möchten, müssen Sie ein neues Stripe-Konto erstellen. Sie können weiterhin mehrere private Apps gleichzeitig mit der öffentlichen App auf demselben Konto erstellen.

## Stripe-CLI-Plugin installieren

1. Melden Sie sich beim [Stripe-Dashboard](https://dashboard.stripe.com) an.
2. Sofern noch nicht geschehen, installieren Sie die Stripe-CLI und melden Sie sich mit demselben Konto an.
   Installieren Sie die Stripe-CLI mit [npm](https://www.npmjs.com/):

   ```bash
   npm install --global @stripe/cli
   ```

   > Weitere Installationsoptionen für Windows, macOS, Linux und Docker finden Sie in der [Stripe-CLI-Readme](https://github.com/stripe/stripe-cli#installation) auf GitHub.

   Nach der Installation verbinden Sie die CLI mit Ihrem Stripe-Konto, indem Sie sich anmelden:

   ```bash
   stripe login
   ```

   Die CLI zeigt einen Kopplungscode an und öffnet das Stripe-Dashboard, in dem Sie den Zugriff auf Konten, Sandboxes und den Live-Modus genehmigen. Die CLI speichert Ihre Anmeldedaten im sicheren Anmeldedatenspeicher Ihres Betriebssystems (sofern verfügbar) und aktualisiert die Sitzung automatisch. Um sich stattdessen mit einem API-Schlüssel zu authentifizieren, führen Sie `stripe login --interactive` aus, verwenden Sie `stripe config`, übergeben Sie `--api-key` oder legen Sie die Umgebungsvariable `STRIPE_API_KEY` fest.

3. Stellen Sie sicher, dass Sie CLI Version `1.12.4` oder neuer verwenden. Sie können dies überprüfen, indem Sie Folgendes ausführen:
   ```bash
   stripe version
   ```
Wenn Ihre Stripe CLI-Version älter als `1.12.4` ist, [aktualisieren Sie sie auf die neueste Stripe-CLI-Version](https://docs.stripe.com/cli/upgrade).
4. Überprüfen Sie, ob [Node.js](https://nodejs.org/) installiert ist, indem Sie Folgendes ausführen:
   ```bash
   node -v
   ```
Stripe Apps erfordert mindestens die Node.js-Version `14`. Wir empfehlen die Verwendung einer [Active LTS-Version](https://nodejs.org/en/about/previous-releases) (18 oder höher). Wenn Sie Node.js nicht installiert haben, [laden Sie es herunter und installieren](https://nodejs.org/en/download/) Sie es. Sie können die Abhängigkeiten Ihrer App mit NPM oder Yarn verwalten. Wenn Sie planen, [Ihre App auf dem App-Marktplatz zu veröffentlichen](https://docs.stripe.com/stripe-apps/publish-app.md), gelten zusätzliche Einschränkungen:
   - Sie müssen ein [aktiviertes Konto](https://docs.stripe.com/get-started/account/set-up.md) haben.
   - Sie können eine App nicht in einem Connect-fähigen Stripe-Konto veröffentlichen.

## Ihre App entwickeln

1. Installieren Sie das CLI-Plugin für Stripe-Apps: Um mit der Erstellung einer Stripe-App zu beginnen, installieren Sie das CLI-Plugin für Stripe-Apps:

   ```bash
   stripe plugin install apps
   ```

   Wenn Sie das `apps`-Plugin bereits installiert haben, überprüfen Sie, ob Sie Version `1.5.12` oder höher verwenden.

   ```bash
   stripe apps -v
   # apps version 1.5.12
   ```

   Wenn Sie das `apps`-Plugin aktualisieren müssen, führen Sie folgenden Befehl aus:

   ```bash
   stripe plugin upgrade apps
   ```

2. [Erstellen Sie Ihre Stripe-App](https://docs.stripe.com/stripe-apps/create-app.md#create-app), indem Sie `stripe apps create <app-name> in der CLI ausführen:

   - Bei der Benennung Ihrer App verbietet Stripe die folgenden Begriffe: Authenticator, RAK, Generator, RAK Auth, App, Generator-App, Stripe.
   - Im Folgenden finden Sie einige Beispiele für akzeptable Namen: Analytics Pro von DataWiz, Invoice Manager von PayFlow.
   - Wenn Sie eine App für einen Drittanbieter entwickeln, verwenden Sie die folgende Namenskonvention: [App-Funktionalität] von [Entwicklername]. Zum Beispiel: Hubspot Sync von Boomi.

3. Bearbeiten Sie die folgenden Felder im App-Manifest:

   - Legen Sie `stripe_api_access_type` auf `oauth` fest.
   - Legen Sie `distribution_type` auf `public` fest.
   - Legen Sie Ihre `allowed_redirect_uris`. Dies sind die URLs, an die Sie Ihre Nutzer/innen weiterleiten, nachdem Sie Ihre App über OAuth installiert haben. Die erste in der Liste ist die Standardweiterleitung.

   Beispiel:

   ```bash
   {
     "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
     ]
   }
   ```

4. Fügen Sie mit dem Befehl `stripe apps grant permission "PERMISSION_NAME" "EXPLANATION"` alle Berechtigungen hinzu, die Ihre App benötigt.

5. (Optional) Fügen Sie [Erweiterungen der Nutzeroberfläche](https://docs.stripe.com/stripe-apps/build-ui.md) zu Ihrer App hinzu. Wir empfehlen, eine Einstellungsansicht hinzuzufügen, damit Ihre Nutzer/innen Einstellungen konfigurieren oder einen Link zur Dokumentation Ihrer App erstellen können. Wenn der einzige Zweck Ihrer App die Authentifizierung ist, entfernen Sie jeglichen unnötigen Code zu Nutzeroberfläche und Nutzererlebnis. Dies trägt dazu bei, dass sich Ihre App auf ihre Hauptfunktion konzentriert.

6. [Laden Sie Ihre App](https://docs.stripe.com/stripe-apps/upload-install-app.md) mithilfe des Befehls `stripe apps upload` in Stripe hoch. Nachdem Sie Ihre OAuth&nbsp;2.0-App hochgeladen haben, können Sie die [API-Authentifizierungsmethode](https://docs.stripe.com/stripe-apps/api-authentication.md) nicht mehr ändern.

7. [Konfigurieren Sie OAuth 2.0](https://docs.stripe.com/stripe-apps/api-authentication/oauth.md) für die Arbeit mit Ihrer App und Ihrem OAuth-Anbieter.

   - Stellen Sie sicher, dass Sie den richtigen [OAuth-Installationslink verwenden](https://docs.stripe.com/stripe-apps/api-authentication/oauth.md#create-install-link), um den OAuth-Ablauf für Ihre Nutzer/innen zu starten.
   - Sie müssen eine Callback-URL in Ihrem App-Manifest angeben, die den OAuth-Autorisierungscode empfangen kann.
   - Sie müssen Ihren geheimen Schlüssel verwenden, um [den Autorisierungscode für den OAuth-Zugriff auszutauschen und die Token zu aktualisieren](https://docs.stripe.com/stripe-apps/api-authentication/oauth.md#obtain-access-token), die für das Konto des Nutzers/der Nutzerin gelten.
   - Sie müssen das [Aktualisierungs-Token regelmäßig verwenden, um ein neues Zugriffs-Token zu erhalten](https://docs.stripe.com/stripe-apps/api-authentication/oauth.md#refresh-access-token), damit Ihre Nutzer/innen sich nicht jedes Mal authentifizieren müssen, wenn ihr Zugriffs-Token abläuft.

## Ihre App testen

Sie können Ihre OAuth-App in Ihrem eigenen Konto oder mit anderen Konten testen:

1. Wählen Sie im [Dashboard für Entwickler/innen](https://dashboard.stripe.com/developers) > [Apps](https://dashboard.stripe.com/apps) die App aus, die Sie extern testen möchten.
2. Klicken Sie auf der Detailseite der App auf die Registerkarte **Externer Test** und dann auf **Jetzt starten**.
   - Wenn die Registerkarte **Externer Test** nicht angezeigt wird, überprüfen Sie, ob Sie unter **Veröffentlichung erstellen** die öffentliche Verteilung ausgewählt haben.
3. Füllen Sie die folgenden Felder aus, um externe Tests zu konfigurieren (die Sie jederzeit bearbeiten können):
   - **Link Zugriff**: Wählen Sie aus, ob jemand die App über den Link installieren kann oder ob diese Möglichkeit auf eingeladene Nutzer/innen beschränkt sein soll.
   - **Version**: Wählen Sie aus, welche Version die Nutzer/innen installieren können. Wenn Sie die Version ändern, wird für alle aktuellen Nutzer/innen eine Aktualisierung auf die neue Version vorgenommen.
4. Kopieren Sie den Autorisierungslink im Abschnitt **OAuth testen**. Senden Sie diesen Link an Nutzer/innen, um die App in ihrem Konto zu installieren. Diese Nutzer/innen müssen über Administratorrechte verfügen, um die App installieren zu können. Nachdem ein/e Nutzer/in die Testversion Ihrer App installiert hat, können alle Mitglieder des Kontos diese verwenden.

Weitere Informationen zu externen Tests finden Sie unter [App extern testen](https://docs.stripe.com/stripe-apps/test-app.md).

## Veröffentlichen und verbreiten Sie Ihre App

So veröffentlichen Sie Ihre App im Stripe App Marketplace:

1. [App zur Prüfung vorlegen](https://docs.stripe.com/stripe-apps/publish-app.md#submit-app-for-review).
2. Nachdem wir sie genehmigt haben, [veröffentlichen Sie Ihre App](https://docs.stripe.com/stripe-apps/publish-app.md) auf dem Stripe App Marktplatz.

So verteilen Sie Ihre App:

1. Sehen Sie sich Ihre [installierten Apps](https://dashboard.stripe.com/settings/apps) an und klicken Sie auf die App, die Sie verteilen möchten. Klicken Sie auf der Detailseite der App auf die Registerkarte **Einstellungen**.
2. Ermitteln Sie den [OAuth-Installationslink](https://docs.stripe.com/stripe-apps/api-authentication/oauth.md#create-install-link) aus der Zeit, als Sie [Ihre App entwickelt haben](https://docs.stripe.com/stripe-apps/plugins/oauth.md#develop-app). Dieser Link ist modusspezifisch. Je nach Use case müssen Sie den Live- oder den Test-Modus angeben. Sie können auch das [App-Manifest konfigurieren](https://docs.stripe.com/stripe-apps/review-requirements.md#sandbox-support), um die Installation in *Sandbox* (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)-Umgebungen zu ermöglichen.
3. Verwenden Sie konsequent denselben OAuth-Installationslink für Ihr Produkt und in den Nutzermitteilungen. Einige zu berücksichtigende Beispiele sind:
   - Aktualisieren Sie Ihre Dokumentation, um Nutzer/innen anzuweisen, die Stripe OAuth 2.0-App zu installieren und alle Schritte zu entfernen, die sich auf das Kopieren und Einfügen von API-Schlüsseln beziehen.
   - Fügen Sie den OAuth-Installationslink zu Ihrem Plugin-Onboarding hinzu, um Nutzer/innen bei der Installation der App zu unterstützen.
   - Verwenden Sie den OAuth-Installationslink in der E-Mail-Kommunikation mit den Nutzern/Nutzerinnen, um sie bei der Aktualisierung ihrer bestehenden Installationen zu unterstützen.

## Ihre bestehenden Nutzer/innen migrieren

Nachdem Sie Ihr Plugin zu einer Stripe-App migriert haben, müssen Sie Ihre bestehenden Nutzer/innen migrieren. Je nachdem, wie Sie normalerweise mit Ihren Nutzern/Nutzerinnen interagieren, kann die Vorgehensweise unterschiedlich sein. Hier sind einige allgemeine wichtige Schritte, die jedoch für die meisten Plugins gelten:

1. Bitten Sie Ihre bestehenden Nutzer/innen, ihre Verbindung zu Stripe mithilfe Ihres OAuth-Installationslinks zu aktualisieren. Dies kann per E-Mail, über die Nutzeroberfläche Ihres Plugins, über Benachrichtigungen innerhalb des Produkts, in Ihren Versionshinweisen oder auf viele andere Arten erfolgen.
2. Nachdem ein/e Nutzer/in Ihre App installiert und den OAuth-Ablauf abgeschlossen hat, löschen Sie den vorherigen geheimen API-Schlüssel.
3. Verfolgen Sie den Fortschritt der Nutzermigration. Verfolgen Sie nach Möglichkeit den Fortschritt der Nutzermigrationen. Setzen Sie sich mit Nutzern/Nutzerinnen in Verbindung, die noch nicht migriert sind, um einen reibungslosen Übergang zu gewährleisten.

## Optional: Den Systemzustand Ihrer App überwachen und verbessern

Sie können die folgenden Maßnahmen erkunden und umsetzen, um den Zustand Ihrer App proaktiv zu verbessern:

- Um Ihre App zu bewerben, können Sie dem [Stripe Partner Ecosystem](https://docs.stripe.com/partners.md) als Teil des [Apps Track](https://docs.stripe.com/partners/apps.md) beitreten. Alle App-Entwickler/innen sind berechtigt, dem Partnerprogramm beizutreten, und Apps, die bestimmte Meilensteine erreichen, können zusätzliche Partnervorteile freischalten, wenn sie sich weiterentwickeln.
- Um das Stripe-Dashboard zu erweitern und nutzerdefinierte Funktionen für Ihre Nutzer/innen bereitzustellen, [erstellen Sie eine Erweiterung der Nutzeroberfläche](https://docs.stripe.com/stripe-apps/how-ui-extensions-work.md).
- Verfolgen Sie Ihre [App-Analyse](https://docs.stripe.com/stripe-apps/analytics.md), um Einblicke in die Leistung Ihres Eintrags im App-Marktplatz zu erhalten, beispielsweise Nutzerinstallationskennzahlen.

## Optional: Zahlungen konfigurieren

Wenn Sie eine App entwickeln, mit der Nutzer/innen Zahlungen abwickeln können, lesen Sie diese Richtlinien:

### Zahlungsdaten sicher erfassen

Nutzer/innen von Stripe müssen für [PCI-Konformität](https://stripe.com/guides/pci-compliance) sorgen, die festlegt, wie Kreditkartendaten sicher zu speichern, zu verarbeiten und zu übertragen sind. Bei Nichteinhaltung oder möglichen Verstößen drohen Unternehmen Strafen.

Da Sie API-Aufrufe für Nutzer/innen von Stripe tätigen, müssen Sie Kreditkartendaten sicher mithilfe der clientseitigen Tokenisierung übermitteln. Kunden/Kundinnen übermitteln ihre persönliche Daten über einen Webbrowser oder eine mobile App direkt an Stripe. Im Gegenzug sendet Stripe ein einfaches Token an Sie. So können Ihre Nutzer/innen Kartendaten sicher erfassen, ohne dass sensible Daten auf den Server gelangen.

Wenn Ihr Plugin ein clientseitiges Zahlungsformular im Browser umfasst, empfehlen wir die Verwendung von:

- [Stripe Elements](https://docs.stripe.com/payments/elements.md): Eine Reihe vorgefertigter Komponenten der Nutzeroberfläche zur Einrichtung Ihres Web-Bezahlvorgangs. Es ist als Feature von [Stripe.js](https://docs.stripe.com/js.md) verfügbar, unserer grundlegenden JavaScript-Bibliothek für die Erstellung von Zahlungsabläufen.
- [Stripe Checkout](https://docs.stripe.com/payments/checkout.md): Eine Low-Code-Zahlungsintegration, die ein anpassbares Formular für den Zahlungseinzug erstellt. Sie können Checkout direkt in Ihre Website integrieren oder Kundinnen/Kunden auf eine von Stripe gehostete Zahlungsseite weiterleiten.

Beide Optionen bieten die clientseitige Tokenisierung.

Wenn Ihr Plugin nur in einer Backend-Umgebung betrieben wird, sollten Sie die Nutzer/innen in Ihrer Dokumentation dazu auffordern, die Zahlungsangaben mit Elements oder Checkout zu tokenisieren. Durch die Tokenisierung können Nutzer/innen von Stripe Zahlungen so sicher wie möglich auf unserer Plattform abwickeln.

### Express Checkout Element hinzufügen

Das [Express Checkout Element](https://docs.stripe.com/elements/express-checkout-element.md) bietet eine einzelne Integration für das Akzeptieren von Zahlungen über One-Click-Zahlungsschaltflächen, einschließlich Apple Pay, Google Pay, Link oder PayPal. Diese Integration ermöglicht es Ihnen, mehrere Schaltflächen gleichzeitig anzuzeigen. Die Kundinnen und Kunden sehen unterschiedliche Zahlungsschaltflächen, je nachdem, was ihre Geräte- und Browser-Kombination unterstützt.

### Mehrere Zahlungsmethoden ermöglichen

Stripe unterstützt neben Kreditkarten noch mehrere andere Zahlungsmethoden. Weitere Informationen zu Zahlungsmethoden finden Sie unter [Zahlungsmethoden](https://docs.stripe.com/payments/payment-methods/overview.md).

Mit der [Payment Methods API](https://docs.stripe.com/payments/payment-methods.md) können Ihre Nutzer/innen Zahlungen mit weiteren Zahlungsmethoden erfassen (beispielsweise Alipay, iDEAL, Sofort). Sie können diese [Zahlungsmethoden](https://docs.stripe.com/payments/payment-methods.md#supported-payment-methods) über einen Integrationspfad hinzufügen.

### Prüfen, ob HTTPS aktiviert ist

Wenn Ihr Plugin ein Zahlungsformular in einem Webbrowser anzeigt, muss es prüfen, ob das Formular über HTTPS bereitgestellt wird. Wir verlangen von unseren Nutzer/innen, dass sie HTTPS aktivieren: Zeigen Sie Ihren Nutzer/innen eine eindeutige Fehlermeldung an, wenn sie nicht ausreichend geschützt sind.

Das folgende Beispiel zeigt, wie Sie überprüfen können, ob Ihre Nutzer/innen HTTPS aktiviert haben:

```javascript
// 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);
```

Wenn Ihr Plugin eine Frontend-Komponente hat, prüfen Sie, ob HTTPS vom Browser verwendet wird. Mit JavaScript sähe das z. B. so aus:

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

## See also

- [Migrieren Sie ein Plugin zu Stripe Apps oder Stripe Connect](https://docs.stripe.com/stripe-apps/plugins/decide-migration.md).
- [Ein Plugin zu einer RAK-App migrieren](https://docs.stripe.com/stripe-apps/plugins/rak.md)