# Installationslinks verwenden Gestatten Sie Nutzern/Nutzerinnen, Ihre App außerhalb des Stripe App Marketplace zu installieren. Über Installationslinks können Nutzer/innen öffentliche Apps außerhalb des Stripe App Marketplace installieren. Mit einem integrierten Ablauf können Sie den Status von Ihrer Anwendung aus übergeben, die Installation der Stripe-App abschließen und die Weiterleitung zu Ihrer Anwendung oder Website durchführen. ![Die Installationslink-Seite mit App-Berechtigungen](https://b.stripecdn.com/docs-statics-srv/assets/oauth-permissions.9f11ce1ba29fdd77c9d4fa9ee2944222.png) Die Installationslink-Seite ## Übersicht Mit den folgenden Schritten können Nutzer/innen eine App über einen Installationslink installieren: 1. Auf Ihrer Website klickt der/die Nutzer/in auf einen Link und wird zu Stripe weitergeleitet und die `app_id` wird übergeben. 2. Auf Stripe wählt der Nutzer/die Nutzerin das entsprechende Konto aus und akzeptiert die Berechtigungen für die Installation der App. 3. Nach der Installation werden Nutzer/innen zusammen mit dem Stripe-Konto für den/die jeweilige Nutzer/in [zu Ihrer Website weitergeleitet](https://docs.stripe.com/stripe-apps/install-links.md#redirect). 4. Ihre App kann jetzt authentifizierte Kontoanfragen durchführen. ## Installationslink erstellen Legen Sie Ihre `allowed_redirect_uris` in Ihrem App-Manifest fest. Dies sind die URLs, an die Nutzer/innen nach der Installation Ihrer App weitergeleitet werden. Sie müssen alle Weiterleitungs-URLs in Ihren App-Einstellungen angeben. Nachdem Sie `allowed_redirect_uris` eingestellt haben, [laden Sie eine neue Version](https://docs.stripe.com/stripe-apps/upload-install-app.md) Ihrer App hoch. ```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" ] } ``` ## Installationslink testen Sie können [externe Tests](https://docs.stripe.com/stripe-apps/test-app.md) mit den folgenden Schritten durchführen, um den Installationslink zu testen, bevor Sie ihn zur Überprüfung übermitteln: 1. [Erstellen Sie einen externen Test](https://docs.stripe.com/stripe-apps/test-app.md) für Ihre App unter Verwendung der im App-Manifest definierten Version mit `allowed_redirect_uris`. Sie können die Testversion auf die gewünschte Version aktualisieren, wenn bereits ein Test existiert. 2. Die Registerkarte **Externer Test** enthält einen Test-Installationslink, und die zulässigen Weiterleitungen werden in einer Tabelle angezeigt. 3. Wenn Sie zur Veröffentlichung bereit sind, müssen Sie unbedingt eine neue Version hochladen, in der alle Test-URIs und -Werte durch die Werte ersetzt sind, die Sie in der Produktion verwenden möchten. ![Die Registerkarte „Externer Test“ mit Installationslinks](https://b.stripecdn.com/docs-statics-srv/assets/external-test.8df1fb2e4ac4df4c934d4acca85ed2de.png) ## Installationslink verwenden Wenn Sie die Tests abgeschlossen haben, können Sie sie mit den folgenden Schritten für alle Nutzer/innen verfügbar machen: 1. [Veröffentlichen Sie eine neue Version](https://docs.stripe.com/stripe-apps/publish-app.md) Ihrer App, die `allowed_redirect_uris` definiert. 2. Klicken Sie auf die Registerkarte **Einstellungen**. Hier wird der Installationslink angezeigt. Diesen können sie kopieren. Der Link sieht wie folgt aus: `https://marketplace.stripe.com/apps/install/link/{id}?redirect_uri=https://example.com`. 3. (Recommended) Um CSRF-Angriffe zu verhindern, können Sie den empfohlenen Parameter `state` hinzufügen und ein eindeutiges Token als Wert übergeben. Wir fügen den von Ihnen angegebenen `state` hinzu, wenn Nutzer/innen auf Ihre Website weitergeleitet werden. Ihre Website kann bestätigen, dass der Parameter `state` nicht geändert wurde. 4. Nach dem Klick auf den Installationslink öffnet Stripe die folgende Seite. Auf dieser wählen die Nutzer/innen ein Konto aus, überprüfen die App-Details und können mit der Installation fortfahren. ![Auswahl eines Kontos, in dem die App installiert werden soll](https://b.stripecdn.com/docs-statics-srv/assets/account-selection.13dde83d3b3b16c9d0faee76b98e584b.png) Auswahl des Installationslinks für das Konto ## Weiterleitung an Ihre Website Nachdem die Nutzer/innen Ihre App installiert haben, werden sie an den URL-Parameter `redirect_uri` weitergeleitet, der einer in `allowed_redirect_uris` definierten Weiterleitung in Ihrem App-Manifest entspricht. ### Erfolgreiche Installation Bei erfolgreichen Installationen enthält die URL Folgendes: - Der Wert `user_id`. Die ID des Stripe Nutzers/der Stripe-Nutzerin, der/die die Installation initiiert hat. - Der Wert `account_id`. Die ID des Stripe-Konto , das Ihre App installiert hat. - Der Wert `state`, falls angegeben - Der Wert `install_signature`. Dies ist ein Hash der obigen Werte, der mit dem [Signaturgeheimnis](https://docs.stripe.com/stripe-apps/build-backend.md#expire-and-create-secrets) Ihrer App generiert wurde. - Wenn die App im Test-Modus oder in einer *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)-Umgebung installiert ist, wird der Wert `livemode=false` an die Weiterleitungs-URL angehängt. *Ein Beispiel für eine Weiterleitung im Live-Modus:* ```url https://example.com/callback/stripe?user_id={USER_ID}&account_id={CONNECTED_ACCOUNT_ID}&state={STATE}&install_signature={INSTALL_SIGNATURE} ``` *Ein Beispiel für eine Weiterleitung in den Test-Modus und eine Sandbox-Umgebung:* ```url https://example.com/callback/stripe?user_id={USER_ID}&account_id={CONNECTED_ACCOUNT_ID}&state={STATE}&install_signature={INSTALL_SIGNATURE}&livemode=false ``` ### Installationsfehler Wenn ein Nutzer/eine Nutzerin die Installation abbricht, wird er/sie trotzdem zu Ihrer Website weitergeleitet, aber die URL enthält stattdessen einen Fehler: ```url https://example.com/callback/stripe?error=access_denied&error_description=The%20user%20denied%20your%20request ``` Jetzt ist die Nutzerin/der Nutzer mit Ihrer App verbunden. Speichern Sie die `account_id` in Ihrer Datenbank – dies ist die Stripe-Konto-ID der Nutzerin/des Nutzers. Verwenden Sie diesen Wert, um sich [als verbundenes Konto zu authentifizieren](https://docs.stripe.com/connect/authentication.md), indem Sie ihn in den `Stripe-Account`-Header Ihrer Anfragen einfügen. ### Überprüfen Sie die App-Installationen mit install_signature (Recommended) Es ist wichtig zu überprüfen, ob der/die Nutzer/in Ihrer App autorisiert wurde, die App für das in der Umleitungs-URL angegebene Konto zu installieren. Aus diesem Grund ist eine `install_signature` enthalten. Diese Signatur wird aus dem [Signaturgeheimnis](https://docs.stripe.com/stripe-apps/build-backend.md#expire-and-create-secrets) Ihrer App und der `user_id` und `account_id` generiert, mit denen die Installation abgeschlossen wurde. Die Signatur enthält auch den übergebenen `state`, falls angegeben. Die Signatur kann nicht ohne Zugriff auf das Signaturgeheimnis repliziert werden, das nur intern für Stripe und das Backend Ihrer App verfügbar ist. Aus diesem Grund können böswillige Akteure den Hash nicht replizieren, wenn sie versuchen würden, die Umleitungs-URL zu fälschen. Durch Verifizieren der App-Signatur können Sie sicher sein, dass das Konto mit Ihrem/Ihrer App-Nutzer/in verbunden ist. Um die Signatur zu verifizieren, befolgen Sie diese Schritte: 1. [Erstellen Sie das Signaturgeheimnis Ihrer App](https://docs.stripe.com/stripe-apps/build-backend.md#expire-and-create-secrets), falls noch nicht geschehen. 2. [Richten Sie ein App-Backend ein](https://docs.stripe.com/stripe-apps/build-backend.md#send-a-signed-request), um die `install_signature` zu verifizieren. #### Beispiel für ein Backend zur Bestätigung der Installation: Die Reihenfolge und Benennung der Nutzlastfelder ist bei der Signaturüberprüfung wichtig. Der `state` geht der `user_id` voraus und diese wiederum der `account_id`. Das resultierende Objekt sollte `{ state, user_id, account_id }` lauten. #### Ruby ```ruby require 'stripe' require 'sinatra' require 'json' client = Stripe::StripeClient.new('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 ``` Nach der Verifizierung können Sie für das installierte Konto [API-Aufrufe](https://docs.stripe.com/stripe-apps/build-backend.md#using-stripe-apis) durchführen. ## Authentifizierte Anfragen durchführen Für serverseitige API-Aufrufe können Sie Anfragen als verbundene Konten stellen, indem Sie den speziellen Header `Stripe-Account` mit der Stripe-Kontokennung (sie beginnt mit dem Präfix `acct_`) Ihres Plattformnutzers/Ihrer Plattformnutzrin verwenden. Das folgende Beispiel zeigt, wie Sie mit dem [geheimen API-Schlüssel](https://docs.stripe.com/keys.md) Ihrer Plattform und der [Konto-ID](https://docs.stripe.com/api/accounts.md) Ihres Nutzers/Ihrer Nutzerin einen [PaymentIntent erstellen](https://docs.stripe.com/api/payment_intents/create.md). ```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" ``` Das `Stripe-Account`-Header-Verfahren wird in jeder API-Anfrage impliziert, die die Stripe-Konto-ID in der URL enthält. Das folgende Beispiel zeigt, wie Sie mit der [Konto](https://docs.stripe.com/api/accounts.md)-ID Ihres/Ihrer Nutzers/in in der URL ein [Konto abrufen](https://docs.stripe.com/api/accounts/retrieve.md). ```curl curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}} \ -u "<>:" ``` [Hier](https://docs.stripe.com/connect/authentication.md) finden Sie weitere Beispiele dafür, wie Sie eine authentifizierte Anfrage durchführen. ## Links mit URL-Parametern anpassen Sie können das Verhalten der App-Installation ändern, indem Sie weitere URL-Parameter in den Installationslink aufnehmen. ### Unterstützte URL-Parameter | Parameter | | Beschreibung | | -------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `redirect_uri` | | Die URL, an die Nutzer/innen nach der Installation Ihrer App weitergeleitet werden. Falls angegeben, muss sie genau mit einem der durch Kommas getrennten `redirect_uris`-Werte in Ihrem [App-Manifest](https://docs.stripe.com/stripe-apps/reference/app-manifest.md) übereinstimmen. Um sich vor bestimmten Man-in-the-Middle-Angriffen zu schützen, muss der `redirect_uri` im Live-Modus eine sichere HTTPS-Verbindung verwenden. | | `state` | (Empfohlen) | Ein willkürlicher Zeichenfolgenwert, den wir an Sie zurückgeben. Dieser wird für den CSRF-Schutz empfohlen. | ### CSRF-Angriffe mit dem Status-Parameter verhindern Um CSRF-Angriffe (Cross-Site Request Forgery) zu verhindern, können Sie den Parameter `state` verwenden. Dieser Parameter akzeptiert jede Zeichenfolge und gibt diese unverändert zurück, wenn das Installationsprogramm zurück zu Ihrer Anwendung oder Plattform geleitet wird. Um diesen Parameter zu verwenden, übergeben Sie einen eindeutigen und nicht zu erratenden Wert, wenn Sie eine Installation über einen Installationslink initiieren. Speichern Sie den Wert ab, um ihn später zur Verifizierung zu verwenden. Nach Abschluss der Installation wird die Nutzerin/der Nutzer zu Ihrer Anwendung zurückgeleitet. Prüfen Sie an dieser Stelle, ob der Wert des angegebenen Statusparameters mit dem Wert im ursprünglichen Installationslink übereinstimmt. Dieser Verifizierungsschritt bietet ein hohes Maß an Sicherheit, um zu bestätigen, dass die zurückgegebene `account_id` zu der Nutzerin/dem Nutzer gehört, die/der die Installation initiiert hat und schützt vor potenziellem Betrug. ## Widerrufen des Zugriffs Ein [Ereignis](https://docs.stripe.com/api.md#list_events) `account.application.deauthorized` tritt ein, wenn ein Nutzer/eine Nutzerin die Verbindung Ihrer Anwendung zu seinem/ihrem Konto trennt. Sie können alle notwendigen Bereinigungen auf Ihren Servern durchführen, indem Sie mit [Webhooks](https://docs.stripe.com/connect/webhooks.md) nach diesem Ereignis suchen. ## See also - [Funktionsweise von Stripe Apps](https://docs.stripe.com/stripe-apps/how-stripe-apps-work.md) - [Vollständige API-Dokumentation](https://docs.stripe.com/api.md)