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. Die Umleitungs-URL gilt ausschließlich für Ihre App und enthält die id Ihrer App im Pfad. Beispiel: Wenn das Feld id im Manifest Ihrer App "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
`reponse_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 gültige Autorisierungsversuche der Werte code, verifier und gegebenenfalls der benutzerdefinierten Werte state lesen. Ein Autorisierungsversuch ist gültig, wenn durch den OAuth-Anbieter eine Weiterleitung zu redirect_uri erfolgt und die entsprechenden Parameter der Abfragezeichenfolge des Autorisierungslinks den Wert state umfassen. Der Wert state muss identisch mit dem von der Funktion createOAuthState zurückgegebenen Wert state 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: '2024-12-18.acacia',
});

// 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: '2024-12-18.acacia',
});

// 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.