# プラグインを 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](https://docs.stripe.com/stripe-apps/api-authentication/oauth.md) をご覧ください。

## Before you begin

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

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

1. [Stripe ダッシュボード](https://dashboard.stripe.com)にログインします。
1. まだインストールしていない場合は、Stripe CLI をインストールし、同じアカウントを使用してログインします。その他のインストールオプションについては、[Stripe CLI を使ってみる](https://docs.stripe.com/stripe-cli.md)をご覧ください。
1. CLI バージョン `1.12.4` 以降を使用していることを確認します。これは以下を実行することで確認できます。
   ```bash
   stripe version
   ```
Stripe の CLI バージョンが `1.12.4` より前のバージョンの場合は、[最新のStripe CLIバージョンに更新](https://docs.stripe.com/stripe-cli/upgrade.md)してください。
1. 次のコマンドを実行して、[Node.js](https://nodejs.org/) がインストールされていることを確認します:
   ```bash
   node -v
   ```
Stripe Apps には Node.js バージョン `>14 が` 必要です。[アクティブな LTS バージョン](https://nodejs.org/en/about/previous-releases) (18 以降) を使用することをお勧めします。Node.js をインストールしていない場合は、[ダウンロードして](https://nodejs.org/en/download/) インストールします。アプリの依存関係は、NPM または Yarn で管理できます。[アプリを App マーケットプレイスに公開する](https://docs.stripe.com/stripe-apps/publish-app.md) 予定の場合は、さらに次の制限があります:
   - [本番環境のアカウント](https://docs.stripe.com/get-started/account/activate.md)が必要です。
   - Connect が有効になった Stripe アカウントでアプリを公開することはできません。

## アプリを開発する

1. Stripe Apps CLI プラグインをインストールする: Stripe App の構築を開始するために、Stripe Apps CLI プラグインをインストールします。

   ```bash
   stripe plugin install apps
   ```

   `apps` プラグインがすでにインストールされている場合は、バージョンが `1.5.12` 以降であることを確認してください。

   ```bash
   stripe apps -v
   # apps version 1.5.12
   ```

   `apps` プラグインをアップグレードする必要がある場合は、以下のコマンドを実行します。

   ```bash
   stripe plugin upgrade apps
   ```

1. CLI で `stripe apps create <app-name>` を実行して、[Stripe アプリを作成](https://docs.stripe.com/stripe-apps/create-app.md#create-app)します。

   - アプリに名前を付ける際に、Stripe では、Authenticator、RAK、Generator、RAK Auth、App、Generator App、Stripe という単語の使用を禁止しています。
   - 受け入れ可能な名前の例には、「Analytics Pro by DataWiz」、「Invoice Manager by PayFlow」などがあります。
   - サードパーティーサービス用のアプリを開発する場合は、[アプリの機能] by [開発者の名前] という命名規則を使用します。たとえば、「Hubspot Sync by Boomi」のようにします。

1. アプリのマニフェストで次のフィールドを編集します。

   - `stripe_api_access_type` を `oauth` に設定します。
   - `distribution_type` を `public` に設定します。
   - `allowed_redirect_uris` を設定します。これは、OAuth を使用してアプリをインストールした後にユーザーをリダイレクトする URL です。リストの最初の URL がデフォルトのリダイレクト先です。

   例:

   ```bash
   {
     "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
     ]
   }
   ```

1. `stripe apps grant permission "PERMISSION_NAME" "EXPLANATION"` コマンドを使用して、アプリで必要なすべての権限を追加します。

1. (オプション) アプリに [UI 拡張機能を追加](https://docs.stripe.com/stripe-apps/build-ui.md)します。ユーザーが設定を変更したり、アプリのドキュメントへのリンクを追加したりできるように、設定ビューを追加することをお勧めします。アプリの目的が認証のみである場合は、不要な UI/UX コードを必ず削除してください。これにより、アプリを主要機能に集中させることができます。

1. `stripe apps upload` コマンドを使用して Stripe に[アプリをアップロード](https://docs.stripe.com/stripe-apps/upload-install-app.md)します。OAuth 2.0 アプリをアップロードした後、[API 認証方法](https://docs.stripe.com/stripe-apps/api-authentication.md)を変更することはできません。

1. アプリと OAuth プロバイダーが連携するように、[OAuth 2.0 を構成](https://docs.stripe.com/stripe-apps/api-authentication/oauth.md)します。

   - ユーザーの OAuth フローを開始する際には、必ず正しい [OAuth インストールリンク](https://docs.stripe.com/stripe-apps/api-authentication/oauth.md#create-install-link)を使用してください。
   - OAuth 認証コードを受け取ることができるコールバック URL をアプリのマニフェストに指定する必要があります。
   - ユーザーのアカウントに適用される [OAuth アクセストークンと更新トークンの認証コードを交換する](https://docs.stripe.com/stripe-apps/api-authentication/oauth.md#obtain-access-token) には、シークレットキーを使用する必要があります。
   - アクセストークンが期限切れになるたびにユーザーが認証を求められないように、定期的に[更新トークンを使用して新しいアクセストークンを取得](https://docs.stripe.com/stripe-apps/api-authentication/oauth.md#refresh-access-token)する必要があります。

## アプリをテストする

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

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

外部テストの詳細については、[アプリの外部テスト](https://docs.stripe.com/stripe-apps/test-app.md)を参照してください。

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

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

1. [アプリを審査に提出](https://docs.stripe.com/stripe-apps/publish-app.md#submit-app-for-review)します。
1. 承認された後、Stripe App Marketplace へ [アプリを公開する](https://docs.stripe.com/stripe-apps/publish-app.md) ことができます。

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

1. [インストール済みアプリ](https://dashboard.stripe.com/settings/apps)を表示して、配信するアプリをクリックします。アプリの詳細ページで、**設定**タブをクリックします。
1. [アプリ開発](https://docs.stripe.com/stripe-apps/plugins/oauth.md#develop-app)時の [OAuth インストールリンク](https://docs.stripe.com/stripe-apps/api-authentication/oauth.md#create-install-link)を特定します。このリンクは環境固有のものです。ユースケースに応じて、本番環境またはテスト環境を指定する必要があります。[アプリマニフェストを設定](https://docs.stripe.com/stripe-apps/review-requirements.md#sandbox-support)して、*サンドボックス* (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)環境へのインストールを有効にすることもできます。
1. 商品およびユーザーとの通信全体で、同じ OAuth インストールリンクを一貫して使用します。検討すべき例を以下に示します。
   - ドキュメントを更新して、Stripe OAuth 2.0 アプリをインストールするようにユーザーに指示し、API キーのコピーおよびペーストに関する手順を削除します。
   - プラグインアカウント登録に OAuth インストールリンクを追加して、ユーザーがアプリをインストールできるようにします。
   - ユーザーとのメール通信に OAuth インストールリンクを使用して、ユーザーが既存のインストール済み環境を更新できるようにします。

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

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

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

## Optional: アプリの健全性を監視して改善する

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

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

## Optional: 支払いを設定する

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

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

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

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

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

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

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

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

### Express Checkout Element を追加する

[Express Checkout Element](https://docs.stripe.com/elements/express-checkout-element.md) では、Apple Pay、Google Pay、Link、PayPal など、ワンクリック決済ボタンを使用して決済を受け付けるための単一導入が提供されています。この導入により、複数のボタンを同時に表示できます。顧客のデバイスとブラウザの組み合わせに応じて、表示される決済ボタンが異なります。

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

Stripeは、クレジットカード以外にも複数の支払い方法をサポートしています。決済手段の詳細については、[決済手段](https://docs.stripe.com/payments/payment-methods/overview.md) をご覧ください。

[Payment Methods API](https://docs.stripe.com/payments/payment-methods.md) を使用すると、ユーザーは追加の支払い方法 (Alipay、iDEAL、Sofort など) で支払いを回収できます。これらの[支払い方法](https://docs.stripe.com/payments/payment-methods.md#supported-payment-methods)は、1 つの導入パスを使用して追加できます。

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

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

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

```bash
// 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 を使用する場合は、以下のとおりです。

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

## See also

- [Stripe Apps または Stripe Connect にプラグインを移行](https://docs.stripe.com/stripe-apps/plugins/decide-migration.md)します。
- [RAK アプリにプラグインを移行する](https://docs.stripe.com/stripe-apps/plugins/rak.md)