プラグインを OAuth 2.0 アプリに移行する

Stripe Apps を使用してプラグインを OAuth 認証に移行する方法をご紹介します。

このガイドを使用して、認証に OAuth 2.0 を使用する Stripe App (OAuth 2.0 アプリとも呼ばれる) にプラグインを移行します。

以前は、Stripe ではプラグインによってユーザーの標準の API キーをリクエストして、商品に連携させることができました。2024 年 9 月 30 日以降、Stripe はユーザーを不正利用から保護するために、すべてのプラグイン開発者に対して安全な認証方法 (制限付きの API キー、OAuth 2.0、または Stripe Connect) の採用を義務付けています。既存および新規のプラグイン開発者はすべて、これらの安全な認証方法のいずれかを使用する必要があります。プラグインを OAuth 2.0 アプリに移行すると、この要件が満たされます。

OAuth 2.0 の詳細については、Stripe Apps のOAuth 2.0 をご覧ください。

はじめに

Stripe Apps または Stripe Connect にプラグインを移行するを確認します。
Stripe Connect を使用していて、Stripe Apps を通じて既存のプラグインを移行する場合は、新しい Stripe アカウントを作成する必要があります。現在、Connect が有効になっている Stripe アカウントではアプリを公開することはできません。
アカウントごとに作成できる公開アプリは 1 つのみです。アカウントにすでに公開アプリがある場合は、新しい Stripe アカウントを作成してください。同じアカウント上でも、プライベートアプリの場合は、公開アプリと並行して複数作成することができます。

Stripe CLI プラグインをインストールする

Stripe ダッシュボードにログインします。
まだインストールしていない場合は、Stripe CLI をインストールし、同じアカウントを使用してログインします。
Command Line
homebrew
# Install Homebrew to run this command: https://brew.sh/ brew install stripe/stripe-cli/stripe # Connect the CLI to your dashboard stripe login
その他のインストールオプションについては、Stripe CLI を使ってみるをご覧ください。
CLI バージョン 1.12.4 以降を使用していることを確認します。これは以下を実行することで確認できます。
Command Line
```
stripe version
```
Stripe の CLI バージョンが 1.12.4 より前のバージョンの場合は、最新のStripe CLIバージョンに更新してください。
ノードがインストールされており、最新であることを確認します。
Command Line
```
node -v
```
アプリの依存関係は、NPM または Yarn を使用して管理できます。最新の安定バージョンを使用してください。アプリを App Marketplace に公開する予定の場合は、さらに次の制限が適用されます。
- 本番環境のアカウントが必要です。
- Connect が有効になった Stripe アカウントでアプリを公開することはできません。

アプリを開発する

Stripe Apps CLI プラグインをインストールする: Stripe App の構築を開始するために、Stripe Apps CLI プラグインをインストールします。
Command Line
```
stripe plugin install apps
```
apps プラグインがすでにインストールされている場合は、バージョンが 1.5.12 以降であることを確認してください。
Command Line
```
stripe apps -v
# apps version 1.5.12
```
apps プラグインをアップグレードする必要がある場合は、以下のコマンドを実行します。
Command Line
```
stripe plugin upgrade apps
```
CLI で stripe apps create <app-name> を実行して、Stripe アプリを作成します。
- アプリに名前を付ける際に、Stripe では、Authenticator、RAK、Generator、RAK Auth、App、Generator App、Stripe という単語の使用を禁止しています。
- 受け入れ可能な名前の例には、「Analytics Pro by DataWiz」、「Invoice Manager by PayFlow」などがあります。
- サードパーティーサービス用のアプリを開発する場合は、[アプリの機能] by [開発者の名前] という命名規則を使用します。たとえば、「Hubspot Sync by Boomi」のようにします。
アプリのマニフェストで次のフィールドを編集します。
- stripe_api_access_type を oauth に設定します。
- distribution_type を public に設定します。
- allowed_redirect_uris を設定します。これは、OAuth を使用してアプリをインストールした後にユーザーをリダイレクトする URL です。リストの最初の URL がデフォルトのリダイレクト先です。
例:
Command Line
```
{
  "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
  ]
}
```
stripe apps grant permission "PERMISSION_NAME" "EXPLANATION" コマンドを使用して、アプリで必要なすべての権限を追加します。
(オプション) アプリに UI 拡張機能を追加します。ユーザーが設定を変更したり、アプリのドキュメントへのリンクを追加したりできるように、設定ビューを追加することをお勧めします。アプリの目的が認証のみである場合は、不要な UI/UX コードを必ず削除してください。これにより、アプリを主要機能に集中させることができます。
stripe apps upload コマンドを使用して Stripe にアプリをアップロードします。OAuth 2.0 アプリをアップロードした後、API 認証方法を変更することはできません。
アプリと OAuth プロバイダーが連携するように、OAuth 2.0 を構成します。
- ユーザーの OAuth フローを開始する際には、必ず正しい OAuth インストールリンクを使用してください。
- OAuth 認証コードを受け取ることができるコールバック URL をアプリのマニフェストに指定する必要があります。
- ユーザーのアカウントに適用される OAuth アクセストークンと更新トークンの認証コードを交換するには、シークレットキーを使用する必要があります。
- アクセストークンが期限切れになるたびにユーザーが認証を求められないように、定期的に更新トークンを使用して新しいアクセストークンを取得する必要があります。

アプリをテストする

OAuth アプリは、自身のアカウントまたは他のアカウントでテストできます。

開発者ダッシュボード > アプリから、外部テストを行うアプリを選択します。
アプリの詳細ページで、外部テストタブをクリックし、始めるをクリックします。
- 外部テストタブが表示されない場合は、リリースを作成するから一般公開を選択していることを確認します。
次のフィールドに入力して、外部テストを設定します (いつでも編集可能です)。
- リンクアクセス: リンクを使用して誰でもアプリをインストールできるようにするか、招待されたユーザーのみに制限するかを選択します。
- バージョン: ユーザーがインストールするバージョンを選択します。バージョンを変更すると、現在のすべてのユーザーが新しいバージョンに更新されます。
Test OAuth セクションで承認用リンクをコピーします。ユーザーにこのリンクを送信し、ユーザーのアカウントにアプリをインストールできるようにします。これらのユーザーがアプリをインストールするには、管理者権限が必要です。ユーザーがテストバージョンのアプリをインストールすると、アカウントのすべてのメンバーがアプリを使用できるようになります。

外部テストの詳細については、アプリの外部テストを参照してください。

アプリを公開して配布する

Stripe App Marketplace にアプリを公開するには、次のようにします。

アプリを審査に提出します。
Stripe がアプリを承認したら、アプリを Stripe App Marketplace に公開します。

アプリを配布するには、次のようにします。

インストール済みアプリを表示して、配信するアプリをクリックします。アプリの詳細ページで、設定タブをクリックします。
アプリ開発時の OAuth インストールリンクを特定します。このリンクは環境固有のものです。ユースケースに応じて、本番環境またはテスト環境を指定する必要があります。アプリマニフェストを設定して、サンドボックス環境へのインストールを有効にすることもできます。
商品およびユーザーとの通信全体で、同じ OAuth インストールリンクを一貫して使用します。検討すべき例を以下に示します。
- ドキュメントを更新して、Stripe OAuth 2.0 アプリをインストールするようにユーザーに指示し、API キーのコピーおよびペーストに関する手順を削除します。
- プラグインアカウント登録に OAuth インストールリンクを追加して、ユーザーがアプリをインストールできるようにします。
- ユーザーとのメール通信に OAuth インストールリンクを使用して、ユーザーが既存のインストール済み環境を更新できるようにします。

既存のユーザーを移行する

プラグインを Stripe App に移行した後、既存のユーザーを移行する必要があります。手順は通常のユーザーとのやり取りの方法によって異なりますが、すべてのプラグインに共通する一般的な重要なステップを以下に示します。

OAuth インストールリンクを使用して Stripe への接続を更新するように既存のユーザーに通知します。これは、メール、プラグインの UI、製品内の通知、リリースノート、またはその他さまざまな方法を利用して行えます。
ユーザーがアプリをインストールして OAuth フローを完了したら、以前のシークレット API キーを削除します。
ユーザーの移行の進捗を追跡します。可能な場合は、ユーザーの移行の進捗を追跡します。移行をまだ行っていないユーザーをフォローアップし、時間の経過に伴ってスムーズに移行できるようにします。

オプションアプリの健全性を監視して改善する

アプリの健全性を事前に改善するために、以下のアクションを検討して実行することができます。

アプリを宣伝する際は、アプリトラックの一環として Stripe Partner Ecosystem への参加をご検討ください。すべてのアプリ開発者がパートナープログラムに参加できます。アプリの成長度が特定のマイルストーンに達すると、その成長度に応じて追加のパートナー特典が付与されます。
Stripe ダッシュボードを拡張して、ユーザー向けにカスタマイズされた機能を提供するには、UI 拡張機能を作成します。
ユーザーのインストール指標など、App Marketplace のリスト掲載の実績に関するインサイトを取得するには、App 分析を追跡します。

オプション支払いを設定する

ユーザーの決済処理を支援するアプリを構築する際は、これらのガイドラインを確認してください。

支払い情報を安全に収集する

Stripe ユーザーは、クレジットカードデータを安全に保存、処理、送信する方法を指定した PCI への準拠を求められます。ビジネスは、コンプライアンス違反や潜在的な不履行が発生したときに罰則の対象となります。

Stripe ユーザーに代わって API コールを行うため、クライアント側のトークン化を使用してクレジットカードデータを安全に送信する必要があります。顧客は、Web ブラウザまたはモバイルアプリを介して直接 Stripe に個人情報を提供し、それと引き換えに Stripe が単純なトークンを送信します。これにより、機密データがサーバーを介することなく、ユーザーはカードの詳細情報を安全に収集できます。

プラグインにブラウザのクライアント側の支払いフォームが含まれている場合は、次のいずれかを使用することをお勧めします。

Stripe Elements: Web 決済フローを構築するための事前構築された UI コンポーネントのセットです。支払いフローを構築するための Stripe の基本的な JavaScript ライブラリーである、Stripe.js の機能として提供されています。
Stripe Checkout: カスタマイズ可能な支払いフォームをローコードで作成し提供する決済プロダクトです。ウェブサイトに直接埋め込むことも、Stripe がオンラインで提供している決済ページに顧客をリダイレクトすることもできます。

上記のオプションは両方とも、クライアント側のトークン化を提供します。

プラグインがバックエンド環境でのみ動作する場合は、Elements または Checkout を使用して支払いの詳細をトークン化するようにユーザーに求める注意書きをドキュメントに追加してください。トークン化により、Stripe ユーザーは Stripe のプラットフォーム上で可能な限り安全に処理を行うことができます。

Express Checkout Element を追加する

Express Checkout Element では、Apple Pay、Google Pay、Link、PayPal など、ワンクリック支払いボタンを使用して支払いを受け付けるための単一統合が提供されています。この統合により、複数のボタンを同時に表示することができます。顧客のデバイスとブラウザーの組み合わせに応じて、異なる支払いボタンが表示されます。

複数の支払い方法を有効にする

Stripeは、クレジットカード以外にも複数の支払い方法をサポートしています。決済手段の詳細については、決済手段をご覧ください。

Payment Methods API を使用すると、ユーザーは追加の支払い方法 (Alipay、iDEAL、Sofort など) で支払いを回収できます。これらの支払い方法は、1 つの導入パスを使用して追加できます。

HTTPS が有効になっていることを確認する

プラグインで決済フォームがウェブブラウザーに表示される場合は、フォームが HTTPS を介して表示されることを確認する必要があります。Stripe では HTTPS を有効することをユーザーに求めています。ユーザーが適切に保護されていない場合は、ユーザーにわかりやすくエラーを表示する必要があります。

次の例は、ユーザーが HTTPS を有効化しているかどうかを確認する方法を示しています。

Command Line
// 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);

プラグインにフロントエンドコンポーネントがある場合は、ブラウザから HTTPS が使用されているかどうかを確認します。たとえば、JavaScript を使用する場合は、以下のとおりです。

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