# シークレット API キーを管理するためのベストプラクティス

シークレット API キーを管理し、漏洩または侵害されたキーを処理する方法をご紹介します。

シークレット API キーは、ユーザー名とパスワードのようなアカウント認証情報の一種です。公開可能キーはウェブページやアプリに含めても安全ですが、シークレットキーはサーバー環境内に留める必要があります。権限のない第三者がシークレット API キーを取得すると、不正な支払いを行ったり、顧客データにアクセスしたり、連携を妨害したりする可能性があります。

このガイドでは、サーバー環境でキーを保護する具体的な方法について説明します。Stripe がサポートするさまざまな種類のキーの概要については、[API キー](https://docs.stripe.com/keys.md)をご覧ください。

## シークレット API キーの保護

シークレット API キーは、開発の各段階で安全に処理して保管し、漏洩や侵害から保護する必要があります。

- **シークレット API キーをソースコードに含めないでください**: 不正行為者は公開リポジトリを継続的にスキャンして Stripe API キーを探します。非公開リポジトリでも開発環境を通じて漏洩する可能性があります。
  - プラットフォームのシークレット管理ツール ([シークレット保管庫](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault)など) を使用して、API キーを実装コードに提供してください。プラットフォームでシークレット保管庫を利用できない場合は、代わりに環境変数を使用してください。
  - `sk_live_` および `rk_live_` を検索し、ソースコード、構成ファイル、CI/CD パイプラインで機密キーを定期的に監査します。機密キーが見つかった場合は、そのキーが[漏洩および侵害](https://docs.stripe.com/keys-best-practices.md#handling-compromised-keys)されていると想定します。
  - バージョン管理システムでコミット前フックを使用して、これらのパターンに一致する文字列を含むコミットを拒否します。
  - Stripe のドキュメントのコードスニペットには、説明のためだけにキーが含まれている場合があります。実際のキーをコードに含めないでください。
- **アプリケーションにシークレット API キーを決して埋め込まないでください**: 権限のない第三者がアプリケーションを分解して、埋め込みキーを検索できます。クライアントツール、SDK、モバイルアプリなどのクライアントサイドのユースケースでは、代わりに[公開可能キー](https://docs.stripe.com/keys.md#obtain-api-keys)を埋め込みます。
- **最小権限の原則に従う**: 従業員とシステムは、_職務遂行に必要な権限のみ_を持っている必要があります。
  - シークレット API キーを作成、更新、または読み取る権限を持つチームメンバーに関する明確なポリシーを定義します。アクセスを必要なユーザーに制限し、キーの権限を定期的に監査します。
  - 組織内でのシークレット API キーの扱い方に関する最新のドキュメントを整備します。また、定期的にトレーニングセッションを開催して、ベストプラクティスが守られていることを確認します。
- **シークレット API キーを慎重に扱う**: Stripe ダッシュボードでシークレット API キーを作成すると、表示されるのは 1 回だけです。キーはすぐにプラットフォームの[シークレット保管庫](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault)に保存し、他の場所には保存しないでください。プラットフォームでシークレット保管庫を利用できない場合は、環境変数にキーを保存できます。
  - シークレット API キーは、メール、チャットメッセージ、または顧客サポートメッセージではなく、プラットフォームのシークレット管理ツールを通じて共有してください。**Stripe がシークレット API キーを尋ねることはありません。**
  - 広範な権限を持つシークレット API キーではなく、制限付きの権限を持つ[制限付き API キー](https://docs.stripe.com/keys-best-practices.md#limit-access)を使用。
- **シークレット API キーを定期的にローテーション**: [Stripe API キー](https://docs.stripe.com/keys.md#rolling-keys)をローテーションするプロセスを定義し、練習します。定期的なローテーションにより、各キーが使用されている場所を把握し、チームが急な通知でキーを交換できることを確認します。キーが漏洩または侵害された場合にチームがビジネスへの影響を最小限に抑えて対応できるように、緊急時対応計画を書き留めます。
- **API リクエストログを監査して疑わしいアクティビティを監視**: API [リクエストログ](https://docs.stripe.com/development/dashboard/request-logs.md) を定期的に監査または監視して、不正使用された API キーを積極的に特定することを推奨します。*サンドボックス* (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) キーが適切な場合に開発者が本番キーを使用していないことを確認してください。詳しくは[サンドボックスと本番環境](https://docs.stripe.com/keys.md#test-live-modes)の違いをご覧ください。

## API キーを安全に保管する

制限付き API キーやシークレット API キーは、サーバー上だけにあるコードであっても、コードに含めないでください。悪意のある第三者は、誤って公開された API キーを見つけるために公開コードベースを継続的にスキャンしています。開発者の開発環境にキーを含むコードがあると、開発者が侵害された場合にキーの漏洩につながる可能性があります。

Stripe のコード例には、すぐに実行しやすいようサンドボックスキーが含まれているものがあります。サンプルコードをコピーする場合は、これらのキーを削除して[シークレット保管庫](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault)に保存してください。プラットフォームでシークレット保管庫を利用できない場合は、環境変数にキーを保存できます。

### シークレット保管庫を使用する

シークレット保管庫は、認証情報をコードとは別に保存し、実行時にアプリケーションに提供します。コードはキーを名前または参照でのみ扱うため、キーの値がソースファイル、CI 設定、開発者環境に現れることはありません。キーの値を隠すだけでなく、保管庫はすべてのアクセスの完全な監査ログ、自動キーローテーションに対応する機能、アプリケーションを再デプロイせずにアクセスを即座に取り消す機能も提供します。

ほとんどのクラウドプラットフォームやインフラストラクチャツールには、シークレット保管庫が含まれています。プラットフォームの権限機能を使用して、必要なサービスだけが保管庫にアクセスできるように制限してください:

- **[AWS Secrets Manager](https://aws.amazon.com/secrets-manager/)**: IAM と統合され、自動ローテーションに対応します。
- **[Google Cloud Secret Manager](https://cloud.google.com/secret-manager)**: きめ細かな IAM 権限を備えたバージョン管理されたシークレットを提供します。
- **[Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault/)**: 役割ベースのアクセス制御により、シークレット、キー、証明書を管理します。
- **[HashiCorp Vault](https://developer.hashicorp.com/vault)**: セルフホスト型またはマネージド型で、動的シークレットと監査ログに対応します。

[このブログ記事](https://stripe.dev/blog/securing-stripe-api-keys-aws-automatic-rotation)では、AWS Secrets Manager を使用して Stripe API キーを保存し、自動ローテーションする方法を紹介しています。

### API キーを環境変数として設定する

ホスティングプラットフォームがシークレット保管庫を提供していない場合は、環境変数を通じてアプリケーションにキーを渡します。一部のプラットフォームでは、環境変数を *機密* なものとしてマークでき、設定後は再び表示できなくなります。アプリケーションは引き続きその機密変数を使用できますが、ウェブブラウザから盗まれることはありません。

Stripe のコード例を実行するときは、現在の端末セッション用に一時的な変数を設定します。端末を閉じると、その環境変数はクリアされます。

#### Mac/Linux

```bash
export STRIPE_API_KEY=sk_test_BQokikJOvBiI2HlWgH4olfQ2
```

### コードでの API キーの使用

ハードコードされたキーを埋め込む代わりに、コードは環境変数の名前で API キーを参照します。

#### Ruby

```ruby
client = Stripe::StripeClient.new(ENV["STRIPE_API_KEY"])
```

Stripe の API キーを環境変数に格納する場合は、これらの変数がユーザーに公開されないよう注意してください。たとえば、エラーページに環境変数を表示したり、診断モードを広い範囲のユーザーに公開したりしないでください。

## 制限付き API キーを使用して API アクセスをカスタマイズする

広範なアクセス権を持つシークレット API キーを使用する代わりに、[制限付き API キー](https://docs.stripe.com/keys/restricted-api-keys.md)を作成して、アプリケーションの各コンポーネントに特定の権限を割り当てます。たとえば、請求システムに請求書を管理する権限だけを付与できます。

制限された API キーを使用すると、侵害の潜在的な影響を制限できます。たとえば、不審請求の申請を監視する第三者に Stripe API キーを提供する場合、Stripe アカウントの不審請求の申請関連リソースへの読み取り専用アクセスを許可し、その他をすべてブロックする制限された API キーを作成できます。第三者が侵害された場合、制限された API キーを盗んだ攻撃者は、その API コールのみに限定されます。

## API リクエストを送信できる IP アドレスを制限する

サービスが安定した IP アドレスから API リクエストを送信する場合は、シークレットまたは制限された API キーをそれらのアドレスに制限できます。たとえば、プラットフォームが専用の NAT ゲートウェイや、IP アドレスまたは範囲をリザーブする別の方法を提供している場合は、どこからでもキーを使用して API リクエストをブロックするように Stripe を設定できます。

キーを 1 つ以上の IP アドレスに制限する方法については、[シークレットキーまたは制付きキーを制限する](https://docs.stripe.com/keys.md#limit-api-secret-keys-ip-address)方法を参照してください。

## 侵害された API キーへの対処

制限付きまたはシークレット API キーが漏洩または侵害された場合は、誰かに見られたかどうかが不明でも、直ちにローテーションしてください。漏洩はすべて潜在的な侵害として扱ってください。

- _公開_とは、公開リポジトリ、ログファイル、メールなど、本来表示されるべきでない場所にキーが表示されることを意味します。
- 「侵害」とは、キーの不正使用の反証資料が存在することを意味します。

### キーの漏洩または侵害への対応

制限付きまたはシークレット API キーが漏洩または侵害されたことが判明した場合は、事業への潜在的な被害を最小限に抑えるため、[こちらのサポートページ](https://support.stripe.com/questions/protecting-against-compromised-api-keys)の手順に従ってください。

### Stripe キーをプロアクティブに保護する

Stripe は、漏洩したシークレットまたは制限された付きの API キーを検出すると、お客様に通知し、キーをローテーションするようにリクエストします。場合によっては、Stripe は事前にキーを無効にし、Stripe が実行するアクションについてお客様に通知します。

Stripe は、漏洩または侵害されたすべてのキーの検出を保証するものではありません。これらのベストプラクティスに従うことで、キーの漏洩を防ぎ、Stripe の導入の安全性を維持できます。

## 管理型 API キー

一部のサーバープラットフォームやホスティングプロバイダーは、プロビジョニングやローテーションなどの手順を含め、顧客に代わって [Stripe API キー](https://docs.stripe.com/keys/managed-api-keys.md)を管理できます。管理型 API キーはサーバープラットフォーム上に保持され、サーバー側のコードに渡されます。[Stripe ダッシュボード](https://dashboard.stripe.com/apikeys)には管理型 API キーが一覧表示されますが、完全なキーは公開されません。

管理型 API キーはサーバー環境における機密情報であるため、このガイドのベストプラクティスに従って保護してください。管理型 API キーをサーバー側のコードにハードコードしてはならず、また、アプリケーションから環境変数を直接公開してはなりません。

サーバープラットフォームが、管理型 Stripe API キーを環境変数としてアプリケーションに提供し、特定の環境変数を *機密* としてマークすることで追加の保護をトリガーする機能をサポートしている場合は、すべての Stripe キーを機密としてマークしてください。

管理型 API キーが漏洩または侵害された疑いがある場合は、[Stripe ダッシュボード](https://docs.stripe.com/keys.md#rolling-keys)またはサーバープラットフォームでローテーションしてください。Stripe ダッシュボードで管理型 API キーをローテーションした場合、または Stripe がキーの侵害を検出し、Stripe アカウントを保護するためにキーを失効させた場合は、Stripe が代わりにサーバープラットフォームと自動的に同期するため、2 カ所でキーを変更する必要はありません。

管理型 API キーが変更された場合、サーバープラットフォームが自動的に再デプロイしない限り、通常は対応するサーバー側アプリケーションを再デプロイする必要があります。

## See also

- [API キー](https://docs.stripe.com/keys.md)
- [侵害された API キーからの保護](https://support.stripe.com/questions/protecting-against-compromised-api-keys)