Speichern Sie geheime Anmeldedaten und Token

Speichern Sie vertrauliche Daten für die Authentifizierung mit der Secret Store API.

Die Secret Store API ist eine Möglichkeit, dauerhafte Geheimschlüssel, die in Stripe Apps verwendet werden, sicher festzulegen, zu finden, aufzulisten und zu löschen. Diese Anmeldedaten, auch als Geheimschlüssel bezeichnet, sind nur für Ihre App und die Nutzer/innen zugänglich, denen sie gehören.

Übersicht

Mit der Secret Store API kann Ihre App:

Authentifizierungs-Zugangsdaten sicher speichern und abrufen
Ermöglichen Sie Endnutzer/innen, bei Drittanbieterdiensten authentifiziert zu bleiben, auch wenn sie sich bei stripe.com abmelden und wieder anmelden.
Sichere Übergabe von Geheimschlüsseln zwischen Ihrer Nutzeroberflächen-Erweiterung und dem Backend

Vorsicht

Stripe untersagt das Speichern von sensiblen personenbezogenen Daten und persönlichen Kontonummern wie Kreditkartennummern und anderen Daten im Rahmen der PCI-Konformität mit der Secret Store API.

Bereiche

Die Geheimschlüssel einer hochgeladenen App sind nur für andere Apps zugänglich, die Sie hochgeladen haben. Sie können nur eine App in einem Konto veröffentlichen, daher können veröffentlichte Apps niemals Geheimschlüssel teilen. Anfragen von Drittanbieter-Apps können niemals auf die Geheimschlüssel Ihrer Apps zugreifen.

Verwenden Sie Geltungsbereiche, um die Zugänglichkeit eines bestimmten Geheimschlüssels festzulegen. Ein Geltungsbereich ist eine Sammlung von Geheimschlüsseln, die durch ihre Zugänglichkeit gekennzeichnet sind.

Die Secret Store API unterstützt die folgenden Bereichstypen:

Bereichstyp	Bereichsgrenzen	Speichert bis zu	Verwenden für	Zugänglich für
Kontobereich	Es gibt einen `account`-Bereich pro App. Beispiel: API-Schlüssel eines Drittanbieters	Höchstens 10 Geheimschlüssel	Geheimnisse, die für alle Nutzer/innen eines Stripe Kontos gelten, das Ihre App installiert	Alle Dashboard-Nutzer/innen eines Stripe-Kontos und das Backend der App, auf Pro-App-Basis
Nutzerbereich	Jede/r Nutzer/in hat einen `user`-Bereich pro App. Beispiel: OAuth-Zugriffstoken	Höchstens 10 Geheimschlüssel	Geheimnisse, die nur für eine/n bestimmte/n Nutzer/in eines Stripe-Kontos gelten	Ein/e bestimmte/r Dashboard-Nutzer/in eines Stripe-Kontos und das Backend der App, auf Pro-App-Basis

Das folgende Diagramm zeigt die Geheimnisbereiche zwischen den folgenden Elementen:

Das Stripe-Konto: „Das Cactus Übungs-Stripe-Konto”
Zwei Nutzer/innen, die sich dasselbe Stripe-Konto teilen: „Nutzer/in 1“, „Nutzer/in 2“
Zwei verschiedene Apps, die vom Stripe-Konto installiert werden: „Installierte App A”, „Installierte App B”
account-bezogene Geheimschlüssel: „Foo API-Schlüssel“-Geheimnis für App A, „Bar API-Schlüssel“ für App B
user-bezogene Geheimschlüssel: „OAuth Zugriffs-Token”, „OAuth Aktualisierungs-Token”

Beziehung zum Geheimschlüssel des Kontos

Die bereichsbezogenen Geheimschlüssel von zwei verschiedenen Apps, die vom Cactus Übungs-Stripe-Konto installiert wurden.

Ablaufdatum

Wenn ein Geheimschlüssel irgendwann in der Zukunft ungültig wird, können Sie einen Ablaufzeitpunkt angeben, indem Sie den optionalen Parameter expires_at festlegen, wenn Sie einen Geheimschlüssel festlegen. Dieser Parameter enthält einen Unix-Zeitstempel (die Anzahl der Sekunden, die seit der letzten Unix-Epoche vergangen sind).

Nachdem das Datum unter expires_at verstrichen ist, wird der Geheimschlüssel automatisch aus der Secret Store API gelöscht.

Die Ablaufzeit kann nicht in der Vergangenheit liegen und darf nicht mehr als 100 Jahre in der Zukunft liegen.

Geheimnis einrichten

Fügen Sie die Berechtigung secret_write zu Ihrer App hinzu:

Command Line
stripe apps grant permission "secret_write" "Allows storing secrets between page reloads"

Richten Sie ein Geheimnis nach Name und Umfang in der Secret Store API ein. Sie können den folgenden Beispielcode in der Nutzeroberflächen-Erweiterung oder im Backend Ihrer App verwenden:

App.tsx
Nutzeroberflächen-Erweiterung
import { createHttpClient, STRIPE_API_KEY } from '@stripe/ui-extension-sdk/http_client';
import Stripe from 'stripe';
import type { ExtensionContextValue } from '@stripe/ui-extension-sdk/context';
import { useEffect } from 'react';

// Create an instance of a Stripe object to access customer information.
// You don't need an API Key here, because the app uses the
// dashboard credentials to make requests.
const stripe: Stripe = new Stripe(STRIPE_API_KEY, {
  httpClient: createHttpClient() as Stripe.HttpClient,
  apiVersion: '2024-11-20.acacia',
});

const App = ({userContext}: ExtensionContextValue) => {
  useEffect(() => {
    stripe.apps.secrets.create({
      scope: { type: 'user', user: userContext.id },
      name: 'secret_name',
      payload: 'secret value',
      expires_at: 1956528000  // optional
    }).then(resp => console.log(resp));
  }, []);

  return null;
};

export default App;

Weitere Informationen finden Sie in der API-Dokumentation zum Einrichten von Geheimschlüsseln.

Geheimnis finden

Sie können den Geheimschlüssel nach Name und Umfang in der Secret Store API suchen. Verwenden Sie den folgenden Beispielcode in der Nutzeroberflächen-Erweiterung oder im Backend Ihrer App:

App.tsx
Nutzeroberflächen-Erweiterung
import Stripe from 'stripe';
import { createHttpClient, STRIPE_API_KEY } from '@stripe/ui-extension-sdk/http_client';
import type { ExtensionContextValue } from '@stripe/ui-extension-sdk/context';
import { useEffect } from 'react';

// Create an instance of a Stripe object to access customer information.
// You don't need to use an API key, because the app uses the
// dashboard credentials to make requests.
const stripe: Stripe = new Stripe(STRIPE_API_KEY, {
  httpClient: createHttpClient() as Stripe.HttpClient,
  apiVersion: '2024-11-20.acacia',
});

const App = ({userContext}: ExtensionContextValue) => {
  useEffect(() => {
    stripe.apps.secrets.find({
      scope: { type: 'user', user: userContext.id },
      name: 'secret_name',
      expand: ['payload'],
    }).then(resp => console.log(resp.payload));
  }, []);

  return null;
};

export default App;

Weitere Informationen finden Sie unter Geheimschlüssel finden.

Geheimnis löschen

Um ein Geheimnis nach Name und Umfang in der Secret Store API zu löschen, können Sie den folgenden Beispielcode in der Nutzeroberflächen-Erweiterung oder im Backend Ihrer App verwenden:

App.tsx
Nutzeroberflächen-Erweiterung
import Stripe from 'stripe';
import { createHttpClient, STRIPE_API_KEY } from '@stripe/ui-extension-sdk/http_client';
import type { ExtensionContextValue } from '@stripe/ui-extension-sdk/context';
import { useEffect } from 'react';

// Create an instance of a Stripe object to access customer information.
// Note that you don't need to use an API key, because the app uses the
// dashboard credentials to make requests.
const stripe: Stripe = new Stripe(STRIPE_API_KEY, {
  httpClient: createHttpClient() as Stripe.HttpClient,
  apiVersion: '2024-11-20.acacia',
});

const App = ({userContext}: ExtensionContextValue) => {
  useEffect(() => {
    stripe.apps.secrets.deleteWhere({
      scope: { type: 'user', user: userContext.id },
      name: 'secret_name',
    }).then(resp => console.log(resp));
  }, []);

  return null;
};

export default App;

Weitere Informationen finden Sie unter Geheimschlüssel löschen.

Geheimnisse auflisten

Wenn Sie die Höchstzahl an Geheimschlüsseln in einem account- oder user-Bereich gespeichert haben und einen weiteren Geheimschlüssel hinzufügen möchten, müssen Sie mindestens einen der 10 Geheimschlüssel löschen. Um zu bestimmen, welche Geheimschlüssel gelöscht werden sollen, können Sie alle Geheimschlüssel für einen bestimmten Bereich auflisten.

Um die Geheimnisse eines account- oder user-Umfangs aufzulisten, können Sie den folgenden Beispielcode in der Nutzeroberflächen-Erweiterung oder im Backend Ihrer App verwenden:

App.tsx
Nutzeroberflächen-Erweiterung
import Stripe from 'stripe';
import { createHttpClient, STRIPE_API_KEY } from '@stripe/ui-extension-sdk/http_client';
import type { ExtensionContextValue } from '@stripe/ui-extension-sdk/context';
import { useEffect } from 'react';

// Create an instance of a Stripe object to access customer information.
// Note that you don't need to use an API key, because the app uses the
// dashboard credentials to make requests.
const stripe: Stripe = new Stripe(STRIPE_API_KEY, {
  httpClient: createHttpClient() as Stripe.HttpClient,
  apiVersion: '2024-11-20.acacia',
});

const App = ({userContext}: ExtensionContextValue) => {
  useEffect(() => {
    stripe.apps.secrets.list({
      scope: { type: 'user', user: userContext.id },
    }).then(resp => console.log(resp.data));
  }, []);

  return null;
};

export default App;

Weitere Informationen finden Sie unter Geheimschlüssel auflisten.

Beispiel-Apps

Die folgenden Beispiel-Apps zeigen, wie die Secret Store API verwendet wird: