# OAuth 2.0

業界標準の OAuth 2.0 を使用し、ユーザーに代わって Stripe API へのリクエストを認証します。

OAuth を使用したユーザー認証は次の手順で行います。

1. お客様のサイトで、ユーザーがリンクをクリックすると、Stripe にリダイレクトされます。
1. Stripe で、ユーザーは、適切なアカウントを選択して、アプリをインストールする権限を受け取ります。
1. アプリがインストールされると、認証が完了し、ユーザーは定義された URI にリダイレクトされます。
![OAuth を使用してアプリをインストールする](https://b.stripecdn.com/docs-statics-srv/assets/oauth-user-journey.0fd6041638a1cbb305dc88690354a462.png)

## アプリを開発する

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

1. [アプリのマニフェスト](https://docs.stripe.com/stripe-apps/reference/app-manifest.md)で次のフィールドを編集します。

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

   アプリのマニフェストは以下のようになります。

   ```json
   {
     "id": "com.example.my-app",
     "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. アプリに必要な[権限](https://docs.stripe.com/stripe-apps/reference/permissions.md)をすべて追加します。

1. 「(オプション)」[UI Extensions](https://docs.stripe.com/stripe-apps/build-ui.md) をアプリに追加します。ユーザーが設定を行ったり、アプリのドキュメントへのリンクを追加したりできるように、[設定ビュー](https://docs.stripe.com/stripe-apps/app-settings.md)を追加することをお勧めします。

1. アプリを Stripe に[アップロード](https://docs.stripe.com/stripe-apps/upload-install-app.md)します。

   ```bash
   stripe apps upload
   ```

## アプリをテストする

1. アプリの詳細ページに移動します。
1. **外部テスト**タブを開き、**始める**をクリックして[外部テスト](https://docs.stripe.com/stripe-apps/test-app.md)を設定します。
1. **OAuth をテスト**セクションにある認証リンクにアクセスします。このリンクを使用すると、異なるアカウントでテストすることができます。

## OAuth インストールリンクを作成する

ウェブページから、次のパラメーターを指定して OAuth インストールリンクにリダイレクトします: `https://marketplace.stripe.com/oauth/v2/authorize?client_id=${clientId}&redirect_uri=${redirectUrl}&state=${state}`。

Stripe は、本番環境とテスト環境の両方に対応するリンクを生成します。リンクは**外部テスト**タブにあります。
![Stripe ダッシュボード内のテスト OAuth リンクの場所](https://b.stripecdn.com/docs-statics-srv/assets/test-oauth-links.a5b8e31857cfe1a8d6b356f89738ff5d.png)

> CSRF 攻撃を防止するには、推奨される `state` パラメーターを追加し、一意のトークンを値として渡します。Stripe は、お客様のサイトにユーザーをリダイレクトするときに、指定された `state` を含めます。サイトでは、`state` パラメーターが変更されていないことを確認できます。詳細については、[URL パラメーター](https://docs.stripe.com/stripe-apps/api-authentication/oauth.md#url-parameters)をご覧ください。

## アプリを公開

アプリを Stripe App Marketplace に公開する準備ができたら、[レビューに送信](https://docs.stripe.com/stripe-apps/publish-app.md#submit-app-for-review)してください

OAuth アプリを審査のために提出する際は、マーケットプレイスのインストール URL を指定する必要があります。この URL は、前のステップの OAuth インストールリンクを使用して、明確な手順が記載された、アカウント登録とインストールプロセスを開始できるページにリンクしている必要があります。

App Review に入力するインストール URL には必ず、**設定** タブの公開 OAuth リンクを使用してください。このリンクは、**外部テスト** タブのリンクとは異なります。
![Stripe ダッシュボード内の公開 OAuth リンクの場所](https://b.stripecdn.com/docs-statics-srv/assets/public-oauth-links.510f38d240869e2ebf88ad5ee3b97625.png)

> 公開 OAuth インストールリンクは、アプリが公開されるまで機能しません。ただし、Stripe のアプリ審査チームは、このリンクからアプリをインストールしてテストすることができます。

## アプリをインストールして認証する

1. ブラウザーで、OAuth インストールリンクを開きます。クエリパラメーターを調整して、リダイレクト URL をアプリが対応している URL に変更できます。
1. アプリをインストールするための権限を表示して受け入れます。[URL パラメーター](https://docs.stripe.com/stripe-apps/api-authentication/oauth.md#url-parameters)を指定していない場合、インストールが完了すると、ユーザーはお客様がアプリのマニフェストで定義した最初のコールバック URL にリダイレクトされます。

## アクセストークンの認証コードを交換する

コールバック URL が OAuth [認証コード](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1)パラメーターを受信します。バックエンドはその OAuth 認証コードを API アクセストークンおよびリフレッシュトークンと交換する必要があります。この認証コードを使用するのは 1 回限りで、5 分間だけ有効であるため、その間にバックエンドは認証コードをアクセストークンと交換しなくてはなりません。バックエンドコードに OAuth [クライアントライブラリ](https://oauth.net/code/)を使用して実装する必要があるコマンドを以下に示します。

```bash
curl -X POST https://api.stripe.com/v1/oauth/token \
  -u sk_live_***: \
  -d code=ac_*** \
  -d grant_type=authorization_code
```

[インストール ステップ](https://docs.stripe.com/stripe-apps/api-authentication/oauth.md#install-app)で使用する該当の Link タイプに対して、アプリ開発者用 API キーを使用する必要があります。

| Link          | API キー                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------- |
| 本番環境の Link    | アプリ開発者用 本番環境 API キー                                                                               |
| テスト環境の Link   | アプリ開発者用 テスト環境 API キー                                                                              |
| サンドボックスの Link | [管理サンドボックス](https://docs.stripe.com/stripe-apps/enable-sandbox-support.md#managed-sandbox) API キー |

これを有効にするには、`state` パラメータ内で該当の Link タイプを渡します。

上記の `curl` コマンドのレスポンス例を以下に示します。

```json
{
  "access_token": "{{ ACCESS_TOKEN }}",
  "livemode": true,
  "refresh_token": "{{ REFRESH_TOKEN }}",
  "scope": "stripe_apps",
  "stripe_publishable_key": "pk_live_***",
  "stripe_user_id": "acct_***",
  "token_type": "bearer"
}
```

## アクセストークンを更新する

アクセストークンの有効期限は 1 時間、リフレッシュトークンの有効期限は 1 年間です。リフレッシュトークンは交換のたびに更新されるため、新しいリフレッシュトークンの有効期限は常に、そのトークンが生成された時点または更新された時点から 1 年後の日付になります。1 年以内にリフレッシュトークンをアクセストークンに交換すると、リフレッシュトークンが有効期限日を迎えることはありません。

以下は、シークレットキーを使用してアクセストークンをリフレッシュトークンに交換する同等の `curl` コマンドです。

```bash
curl -X POST https://api.stripe.com/v1/oauth/token \
  -u sk_live_***: \
  -d refresh_token={{ REFRESH_TOKEN }} \
  -d grant_type=refresh_token
```

レスポンス例を以下に示します。

```json
{
  "access_token": "{{ ACCESS_TOKEN }}",
  "livemode": true,
  "refresh_token": "{{ REFRESH_TOKEN }}",
  "scope": "stripe_apps",
  "stripe_publishable_key": "pk_live_***",
  "account_id": "acct_***",
  "token_type": "bearer"
}
```

新しいリフレッシュトークンを取得し、以前のリフレッシュトークンを有効期限切れにします。リフレッシュトークンはバックエンドに安全に保管し、Stripe ユーザーに代わって Stripe API にアクセスするときにいつでもそのリフレッシュトークンを使用して、新しいアクセストークンを取得する必要があります。

> アクセストークンを更新すると、必要な権限がないことを示すエラーが表示される場合があります。このエラーが表示された場合は、API コールの承認にアカウントのシークレットキーを使用していること、および誤ってリフレッシュトークン、アクセストークン、または制限付きキーを使用していないことを確認してください。

次の例のように Stripe API にリクエストして、アクセストークンを検証します。

```curl
curl https://api.stripe.com/v1/customers \
  -u "{{ ACCESS_TOKEN }}"
```

## Optional: 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 フィールドに機密情報に関わるパラメーターを含めないでください。