Autorisierungsabläufe hinzufügen

Implementieren Sie PKCE OAuth-Workflows in Ihrer Stripe-App.

Sie können OAuth mit Ihrer Nutzeroberflächen-Erweiterung im Dashboard implementieren, um Zugriffs-Token von einem OAuth-Anbieter abzurufen, statt ein OAuth-Backend zu erstellen. Wenn der/die Nutzer/in Ihrer Stripe-App Zugriff auf einen OAuth-Anbieter gewährt, kann er/sie direkt über Ihre Stripe-App im Dashboard mit den Diensten des OAuth-Anbieters interagieren.

OAuth-Ablauf mit einer Stripe-App

Bevor Sie loslegen

Stellen Sie sicher, dass OAuth den Proof Key for Code Exchange (PKCE)-Ablauf unterstützt.
Falls nicht bereits geschehen, erstellen Sie eine App mit Ihrem OAuth-Anbieter, die Sie mit Ihrer Stripe-App verbinden und verwenden können.
Erstellen Sie eine Stripe-App und eine Nutzeroberfläche. Die UI-Erweiterung ruft den Zugriffs-Token des OAuth-Anbieters per PKCE-Ablauf ab.

Autorisierungs-Link erstellen

Endnutzer/innen klicken auf einen Autorisierungslink Ihrer App, um den OAuth-Ablauf zu starten und Ihrer App Zugriff auf den Dienst des OAuth-Anbieters zu gewähren.

Erstellen Sie die Test- und Live-OAuth-Umleitungs-URLs. Dieses Verfahren gilt auch in einer Sandbox-Umgebung. Die Umleitungs-URL gilt ausschließlich für Ihre App und enthält Ihre App-id im Pfad. Beispiel: Wenn das Feld id in Ihrem App-Manifest "id": "com.example.oauth-example" lautet:
- Die Test-Modus-URL lautet:
```
https://dashboard.stripe.com/test/apps-oauth/com.example.oauth-example
```
- Die Live-Modus-URL lautet:
```
https://dashboard.stripe.com/apps-oauth/com.example.oauth-example
```
Registrieren Sie die Test- und Live-OAuth-Umleitungs-URLs bei Ihrem OAuth-Anbieter.

Erstellen Sie in der Nutzeroberflächen-Erweiterung Ihrer App einen Pfad, der Nutzer/innen von Ihrer Stripe-App weiterleitet, um den OAuth-Anbieter zu autorisieren. Übergeben Sie hierfür die folgenden Parameter in den OAuth-Umleitungs-URLs:

Parameter	Wert
`response_type`	Dies lautet immer `code`. Der PKCE-Ablauf verwendet `code` als Wert, um einen Autorisierungscode vom OAuth-Anbieter anzufordern.
`client_id`	Die von Ihrem OAuth-Anbieter zugewiesene ID Ihrer OAuth-App.
`redirect_uri`	Die OAuth-Umleitungs-URL der Stripe-App. Dies ist die URL, die der OAuth-Anbieter verwendet, um eine/n Nutzer/in zu Ihrer App umzuleiten.
`state`	Der `state`-Rückgabewert der Funktion createOAuthState.
`code_challenge`	Der `challenge`-Rückgabewert der Funktion createOAuthState.
`code_challenge_method`	Dies ist immer `S256`.

Für die Nutzerweiterleitung aus Ihrer Stripe-App können Sie das folgende Codebeispiel verwenden, um eine Drittanbieter-App mithilfe der OAuth-Umleitungs-URLs und der Nutzeroberflächenkomponente „Schaltfläche” zu autorisieren:

import {
  ContextView,
  Button,
} from '@stripe/ui-extension-sdk/ui';
import * as React from 'react';
import {createOAuthState} from '@stripe/ui-extension-sdk/oauth';
import type {ExtensionContextValue} from '@stripe/ui-extension-sdk/context';

const {useState, useEffect} = React;

const clientID = 'your_client_id';
const getRedirectURL = (mode: 'live' | 'test') => `https://dashboard.stripe.com/${
  mode === 'test' ? 'test/' : ''
}apps-oauth/com.example.oauth-example`;
const getAuthURL = (state: string, challenge: string, mode: 'live' | 'test') =>
  `https://www.example.com/oauth2/authorize?response_type=code&client_id=${clientID}&redirect_uri=${getRedirectURL(mode)}&state=${state}&code_challenge=${challenge}&code_challenge_method=S256`;

const ExampleApp = ({environment}: ExtensionContextValue) => {
  const {mode} = environment;
  const [authURL, setAuthURL] = useState('');
  useEffect(() => {
    createOAuthState().then(({state, challenge}) => {
      setAuthURL(getAuthURL(state, challenge, mode));
    });
  }, [mode]);

  return (
    <ContextView title="Example">
      <Button type="primary" href={authURL} target="_blank">Authorize ExampleApp</Button>
    </ContextView>
  );
};
export default ExampleApp;

Zugriffs-Token vom OAuth-Anbieter abrufen

Ihre App kann nur Anfragen im Auftrag aktueller Nutzer/innen stellen. Nachdem Ihre App autorisiert wurde, übergibt das Dashboard die OAuth-Daten an Ihre App durch die code- und verifier-Werte der Kontexteigenschaft oauthContext.

Ihre App kann nur bei gültigen Autorisierungsversuche die Werte code, verifier und gegebenenfalls den benutzerdefinierten Wert state lesen. Ein Autorisierungsversuch ist gültig, wenn durch den OAuth-Anbieter eine Weiterleitung zu redirect_uri`` erfolgt und der entsprechende Parameter der Abfragezeichenfolge des Autorisierungslinks den Wert stateumfasst. Der Wertstatemuss identisch mit dem von der FunktioncreateOAuthStatezurückgegebenen Wertstate` sein (der bei der Erstellung des Autorisierungslinks vorlag).

Rufen Sie über die Nutzeroberflächen-Erweiterung Ihrer App den Zugriffs-Token vom OAuth-Anbieter mit den folgenden Parametern ab:

Parameter	Wert
`code`	Der Wert des React-Props `oauthContext.code`.
`grant_type`	Dies ist immer `authorization_code`.
`code_verifier`	Der Wert des React-Props `oauthContext.verifier`.
`client_id`	Ihre Client-ID vom OAuth-Anbieter
`redirect_uri`	Die OAuth-Umleitungs-URL der Stripe-App.

Sie können das folgende Codebeispiel verwenden, um einen Zugriffs-Token von einem OAuth-Anbieter abzurufen:

import {ContextView} from '@stripe/ui-extension-sdk/ui';
import * as React from 'react';
import type {ExtensionContextValue} from '@stripe/ui-extension-sdk/context';

const {useState, useEffect} = React;

// Store the authorization token data.
interface TokenData {
  account_id: string;
  access_token: string;
  expires_in: number;
}

const clientID = 'your_client_id';
const getRedirectURL = (mode: 'live' | 'test') => `https://dashboard.stripe.com/${
  mode === 'test' ? 'test/' : ''
}apps-oauth/com.example.oauth-example`;

// Fetch the authorization token from an example authorization server.
const getTokenFromAuthServer = async ({code, verifier, mode}: {code: string, verifier: string, mode: 'live' | 'test'}): Promise<null | TokenData> => {
  try {
    const response = await fetch(`https://api.example.com/oauth2/token?code=${code}&grant_type=authorization_code&code_verifier=${verifier}&client_id=${clientID}&redirect_uri=${getRedirectURL(mode)}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    });
    if (response.ok) {
      return await response.json();
    }
    throw new Error(await response.text());
  } catch (e) {
    console.error('Unable to retrieve token from authorization server:', (e as Error).message);
    return null;
  }
};

const ExampleApp = ({environment, oauthContext}: ExtensionContextValue) => {
  const [tokenData, setTokenData] = useState<TokenData | null>(null);
  const code = oauthContext?.code || '';
  const verifier = oauthContext?.verifier || '';
  const {mode} = environment;

  useEffect(() => {
    if (code && verifier && !tokenData) {
      getTokenFromAuthServer({code, verifier, mode}).then(setTokenData);
    }
  }, [code, verifier, mode, tokenData]);

  return (
    <ContextView title="Example" />
  )
};
export default ExampleApp;

Einen Zugriffs-Token finden und einrichten

Richten Sie den Zugriffs-Token ein und suchen Sie ihn in der Secret Store API, damit Ihre App ihn in späteren Sitzungen verwenden und speichern kann.

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 in der Nutzeroberflächen-Erweiterung Ihrer App den Zugriffs-Token in der Secret Store API ein:

import {ContextView} from '@stripe/ui-extension-sdk/ui';
import * as React from 'react';
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';

const {useState, useEffect} = React;

interface TokenData {
  account_id: string;
  access_token: string;
  expires_in: number;
}

const clientID = 'your_client_id';
const getRedirectURL = (mode: 'live' | 'test') => `https://dashboard.stripe.com/${
  mode === 'test' ? 'test/' : ''
}apps-oauth/com.example.oauth-example`;

// Fetch the authorization token from an example authorization server.
const getTokenFromAuthServer = async ({code, verifier, mode}: {code: string, verifier: string, mode: 'live' | 'test'}): Promise<null | TokenData> => {
  try {
    const response = await fetch(`https://api.example.com/oauth2/token?code=${code}&grant_type=authorization_code&code_verifier=${verifier}&client_id=${clientID}&redirect_uri=${getRedirectURL(mode)}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    });
    if (response.ok) {
      return await response.json();
    }
    throw new Error(await response.text());
  } catch (e) {
    console.error('Unable to retrieve token from authorization server:', (e as Error).message);
    return null;
  }
};

const stripe = new Stripe(STRIPE_API_KEY, {
  httpClient: createHttpClient(),
  apiVersion: '2025-12-15.clover',
});

// Save the token to Secret Store API
const saveTokenData = async ({userID, tokenData}: {userID: string, tokenData: TokenData}) => {
  try {
    await stripe.apps.secrets.create({
      scope: { type: 'user', user: userID },
      name: 'oauth_token',
      payload: JSON.stringify(tokenData),
    });
  } catch (e) {
    console.error('Unable to save token to Secret Store API:', (e as Error).message);
  }
}

const ExampleApp = ({userContext, environment, oauthContext}: ExtensionContextValue) => {
  const [tokenData, setTokenData] = useState<TokenData | null>(null);
  const code = oauthContext?.code || '';
  const verifier = oauthContext?.verifier || '';
  const {mode} = environment;
  const {id: userID} = userContext;

  useEffect(() => {
    if (code && verifier && !tokenData) {
      getTokenFromAuthServer({code, verifier, mode}).then(tokenData => {
        if (tokenData) {
          setTokenData(tokenData);
          saveTokenData({userID, tokenData});
        }
      });
    }
  }, [code, verifier, mode, userID, tokenData]);

  return (
    <ContextView title="Example" />
  )
};

export default ExampleApp;

Weitere Informationen finden Sie unter Geheimschlüssel einrichten.

Suchen Sie in der UI-Erweiterung Ihrer App den Zugriffs-Token in der Secret Store API:

import {ContextView} from '@stripe/ui-extension-sdk/ui';
import * as React from 'react';
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';

const {useState, useEffect} = React;

interface TokenData {
  account_id: string;
  access_token: string;
  expires_in: number;
}

const stripe = new Stripe(STRIPE_API_KEY, {
  httpClient: createHttpClient(),
  apiVersion: '2025-12-15.clover',
});

// Read the token from Secret Store API
const getTokenFromSecretStore = async (userID: string): Promise<TokenData | null> => {
  try {
    const response = await stripe.apps.secrets.find({
      scope: { type: 'user', user: userID },
      name: 'oauth_token',
      expand: ['payload'],
    });
    const secretValue: string = response.payload!;
    return JSON.parse(secretValue) as TokenData;
  } catch (e) {
    console.error('Unable to retrieve token from Secret Store API:', (e as Error).message);
    return null;
  }
};

const ExampleApp = ({userContext}: ExtensionContextValue) => {
  const [tokenData, setTokenData] = useState<TokenData | null>(null);
  const {id: userID} = userContext;

  useEffect(() => {
    if (!tokenData) {
      getTokenFromSecretStore(userID).then(setTokenData);
    }
  }, [userID, tokenData]);

  return (
    <ContextView title="Example" />
  )
};

export default ExampleApp;

Weitere Informationen finden Sie unter Geheimschlüssel finden.