# インストールリンクを使用する ユーザーが Stripe App Marketplace の外部でアプリをインストールできるようにします。 インストールリンクを使用すると、Stripe App Marketplace の外部でアプリをインストールできます。特定の導入フローで、アプリケーションから状態を渡し、Stripe アプリのインストールを完了して、アプリケーションまたはサイトにリダイレクトすることができます。 ![アプリの権限を示すインストールリンクのページ](https://b.stripecdn.com/docs-statics-srv/assets/oauth-permissions.9f11ce1ba29fdd77c9d4fa9ee2944222.png) インストールリンクのページ ## 概要 以下の手順では、ユーザーはインストールリンクを使用してアプリをインストールできます。 1. お客様のサイトでは、ユーザーがリンクをクリックすると、Stripe にリダイレクトされ、`app_id` が渡されます。 1. Stripe で、ユーザーは、適切なアカウントを選択して、アプリをインストールする権限を受け取ります。 1. インストールすると、ユーザーは[サイトにリダイレクト](https://docs.stripe.com/stripe-apps/install-links.md#redirect)され、指定されたユーザーの Stripe アカウントも渡されます。 1. これで、アプリは認証済みのアカウントのリクエストを行うことができます。 ## インストールリンクを作成する アプリのマニフェストで `allowed_redirect_uris` を設定します。これは、ユーザーがアプリをインストールした後にリダイレクトされる URL です。すべてのリダイレクト URL をアプリの設定で指定する必要があります。 `allowed_redirect_uris` を設定した後、アプリの[新しいバージョンをアップロード](https://docs.stripe.com/stripe-apps/upload-install-app.md)します。 ```json { "id": "com.invoicing.[YOUR_APP]", "version": "1.2.3", "name": "[YOUR APP] Shipment Invoicing", "icon": "./[YOUR_APP]_icon_32.png", "permissions": [], "app_backend": {}, "ui_extension": {},"allowed_redirect_uris": [ "https://example.com/callback/stripe" ] } ``` ## インストールリンクをテストする 以下の手順で[外部テスト](https://docs.stripe.com/stripe-apps/test-app.md)を実施することで、提出して審査を受ける前にインストールリンクをテストすることができます。 1. アプリのマニフェストで定義されている `allowed_redirect_uris` が指定されたバージョンを使用し、アプリの[外部テストを作成](https://docs.stripe.com/stripe-apps/test-app.md)します。テストがすでに存在する場合は、テスト用のバージョンを必要なバージョンに更新することができます。 1. **外部テスト**タブには、テスト用のインストールリンクが示され、許可されたリダイレクトが表に表示されています。 1. 公開する準備ができたら、テスト用の URI と値を本番環境で使用する予定の値に置き換えて新しいバージョンをアップロードします。 ![インストールリンクを示す外部テストのタブ](https://b.stripecdn.com/docs-statics-srv/assets/external-test.8df1fb2e4ac4df4c934d4acca85ed2de.png) ## インストールリンクを使用する テストが完了したら、以下の手順を使用してすべてのユーザーに提供することができます。 1. `allowed_redirect_uris` を定義するアプリの[新しいバージョンを公開](https://docs.stripe.com/stripe-apps/publish-app.md)します。 1. **設定**タブをクリックします。インストールリンクはここに表示され、コピーすることができます。リンクは次のようになります。`https://marketplace.stripe.com/apps/install/link/{id}?redirect_uri=https://example.com` 1. (Recommended) CSRF 攻撃を防止するには、推奨の `state` パラメーターを追加して、値として一意のトークンを渡すことができます。Stripe は、お客様のサイトにユーザーをリダイレクトするときに、指定された `state` を含めます。サイトでは `state` パラメーターが変更されていないことを確認できます。 1. ユーザーがインストールリンクをクリックすると、Stripe は次のページを開きます。このページでは、アカウントを選択して、アプリの詳細を確認し、インストールを先に進めることができます。 ![アプリをインストールするアカウントを選択する](https://b.stripecdn.com/docs-statics-srv/assets/account-selection.13dde83d3b3b16c9d0faee76b98e584b.png) インストールリンクのアカウントの選択 ## サイトにリダイレクトしています ユーザーは、アプリのインストール後に、アプリのマニフェストに記載された `allowed_redirect_uris` で定義されているリダイレクトと一致する `redirect_uri` URL パラメーターにリダイレクトされます。 ### インストールの成功 インストールが成功すると、URL に以下が含まれます。 - `user_id` の値。インストールを開始した Stripe ユーザーの ID。 - `account_id` 値。貴社のアプリをインストールした Stripe アカウントの ID。 - `state` 値 (指定されている場合) - `install_signature` 値。これは、上記の値のハッシュであり、アプリの[署名シークレット](https://docs.stripe.com/stripe-apps/build-backend.md#expire-and-create-secrets)を使用して生成されます。 - アプリがテスト環境または*サンドボックス* (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)環境にインストールされている場合、リダイレクト URL に `livemode=false` の値が追加されます。 「本番環境のリダイレクトの一例:」 ```url https://example.com/callback/stripe?user_id={USER_ID}&account_id={CONNECTED_ACCOUNT_ID}&state={STATE}&install_signature={INSTALL_SIGNATURE} ``` *テスト環境とサンドボックス環境のリダイレクトの例:* ```url https://example.com/callback/stripe?user_id={USER_ID}&account_id={CONNECTED_ACCOUNT_ID}&state={STATE}&install_signature={INSTALL_SIGNATURE}&livemode=false ``` ### インストールの失敗 ユーザーがインストールをキャンセルした場合でも、お客様のサイトにリダイレクトされますが、URL にはエラーが含まれます。 ```url https://example.com/callback/stripe?error=access_denied&error_description=The%20user%20denied%20your%20request ``` これで、ユーザーがアプリに連結されました。`account_id` をデータベースに保存します (これはユーザーの Stripe アカウント ID です)。この値を使用して、`Stripe-Account` ヘッダーのリクエストに渡すことで、[連結アカウントとして認証](https://docs.stripe.com/connect/authentication.md) します。 ### install_signature を使用してアプリのインストールを確認する (Recommended) アプリのユーザーがリダイレクト URL に入力したアカウントでアプリのインストールを承認されているかを確認することが重要です。`install_signature` が含まれているのはこのためです。このシグネチャーはアプリの[署名シークレット](https://docs.stripe.com/stripe-apps/build-backend.md#expire-and-create-secrets)、およびインストールを実行した `user_id` と `account_id` から生成されます。指定されている場合は渡された `state` もこのシグネチャーに含まれます。署名シークレットにアクセスせずにこのシグネチャーを複製することはできず、実行できるのは、Stripe 内部とアプリのバックエンドのみです。これにより、不正行為者がリダイレクト URL を試したり偽装しようとしても、ハッシュを複製することはできません。アプリのシグネチャーを確認することによって、アカウントがアプリのユーザーに関連付けられていることを確信できます。 シグネチャーを確認するには、以下のステップを使用します。 1. まだ作成していない場合は、[アプリの署名シークレットを作成します](https://docs.stripe.com/stripe-apps/build-backend.md#expire-and-create-secrets)。 1. [アプリのバックエンドを設定して](https://docs.stripe.com/stripe-apps/build-backend.md#send-a-signed-request)、`install_signature` を確認します。 #### インストールを確認するバックエンドのサンプル: ペイロードフィールドの順序と名前は、署名検証を実行する際に重要です。`state` は `user_id` の前にあり、`account_id` に先行します。結果のオブジェクトは `{ state, user_id, account_id }` になります。 #### Ruby ```ruby require 'stripe' require 'sinatra' require 'json' Stripe.api_key = 'API_KEY' get '/' do 'Install Links verification example' end get '/verify' do user_id = params[:user_id] account_id = params[:account_id] state = params[:state] install_signature = params[:install_signature] payload = JSON.dump({ state: state, user_id: user_id, account_id: account_id }) begin Stripe::Webhook::Signature.verify_header( payload, install_signature, 'STRIPE_APP_SECRET' ) rescue Stripe::SignatureVerificationError => e return e.message, 400 end { success: true }.to_json end set :port, 3000 ``` 確認後は、インストールしたアカウントの代理として [API コールを実行](https://docs.stripe.com/stripe-apps/build-backend.md#using-stripe-apis)できます。 ## 認証されたリクエストを行う サーバー側での API コールでは、プラットフォームユーザーの Stripe アカウント ID (プレフィックスは `acct_`) とともに特殊なヘッダー `Stripe-Account` を使用することで、連結アカウントとしてリクエストを作成できます。下記は、プラットフォームの [API シークレットキー](https://docs.stripe.com/keys.md)とユーザーの[アカウント](https://docs.stripe.com/api/accounts.md) ID を使用して [PaymentIntent を作成](https://docs.stripe.com/api/payment_intents/create.md)する方法を示す例です。 ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d amount=1000 \ -d currency=usd \ -d "payment_method_types[]=card" ``` URL に Stripe アカウント ID を含む API リクエストのすべてで、`Stripe-Account` ヘッダーによる方法が必要になります。下記は、URL 内のユーザーの[アカウント](https://docs.stripe.com/api/accounts.md) ID を使用して[アカウントを取得](https://docs.stripe.com/api/accounts/retrieve.md)する方法を示す例です。 ```curl curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}} \ -u "<>:" ``` [こちらで認証されたリクエストを行う方法の例](https://docs.stripe.com/connect/authentication.md)をご覧ください。 ## URL パラメーターを使用してリンクをカスタマイズする インストールリンクに追加の URL パラメーターを含めることで、アプリのインストールの動作を変更できます。 ### サポートされている URL パラメーター | パラメーター | | 説明 | | -------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `redirect_uri` | | ユーザーがアプリをインストールした後にリダイレクトされる URL。指定する場合は、[アプリのマニフェスト](https://docs.stripe.com/stripe-apps/reference/app-manifest.md)に記載されたカンマ区切りの `redirect_uris` 値のいずれかに正確に一致させる必要があります。一部の中間者攻撃から自社を守るためには、本番環境の `redirect_uri` でセキュリティで保護された HTTPS 接続を使用する必要があります。 | | `state` | (推奨) | お客様に返される任意の文字列値。CSRF の対策に推奨されます。 | ### state パラメーターを使用して CSRF 攻撃を防止する クロスサイトリクエストフォージェリ (CSRF) 攻撃を防止するには、`state` パラメーターを使用できます。このパラメーターは任意の文字列値を受け入れ、インストーラーからお客様のアプリケーションまたはプラットフォームにリダイレクトされるときにその文字列を変更せずに返します。このパラメーターを使用するには、インストールリンクを使用してインストールを開始するときに、推測できない一意の値を渡します。その値を保存し、後で確認に使います。 ユーザーがアプリケーションをインストールしてお客様のアプリケーションにリダイレクトされたら、指定された state パラメーターの値が当初のインストールリンク内に存在する値と一致するかどうか確認します。この確認プロセスによって、返された `account_id` がインストールを開始したユーザーのものであることを高い信頼性で確認でき、偽造対策になります。 ## アクセスを取り消す ユーザーがアカウントからアプリの連結を解除すると、`account.application.deauthorized` [イベント](https://docs.stripe.com/api.md#list_events)が発生します。[Webhook](https://docs.stripe.com/connect/webhooks.md) でこのイベントを監視することにより、サーバーで必要なクリーンアップを実行できます。 ## See also - [Stripe Apps の仕組み](https://docs.stripe.com/stripe-apps/how-stripe-apps-work.md) - [API リファレンス完全版](https://docs.stripe.com/api.md)