SaaS APIの認証設計｜APIキー管理とスコープベース権限制御の実装パターン

なぜSaaS APIの認証設計が重要なのか

SaaSプロダクトにおいて、APIは外部システムとの連携やデータのやり取りを支える基幹インフラです。ここでの認証設計の判断は、セキュリティ・利便性・運用コストのすべてに直結します。

FUNBREWでは自社SaaSプロダクト「FUNBREW PDF」の開発を通じて、APIキー管理・スコープ制御・レート制限といった認証基盤を実装してきました。本記事では、その経験をもとに実践的な設計パターンを解説します。

認証設計で考慮すべきポイントは大きく3つあります。

• APIキーの安全な管理：発行・保存・検証の仕組み
• スコープベースの権限制御：誰がどのリソースにアクセスできるか
• レート制限とアクセス制御：サービスの安定性を守る仕組み

これらはSaaSの開発工程全体のなかでも、初期段階で設計を固めておくべき領域です。後からの変更はAPIの破壊的変更につながりやすく、利用者への影響が大きいためです。

認証方式の選定：APIキー vs OAuth 2.0

SaaS APIの認証方式として代表的なのは、APIキー認証とOAuth 2.0の2つです。どちらを選ぶかは、APIの利用シーンによって決まります。

APIキー認証が適するケース

• サーバー間のB2B連携（バッチ処理、Webhook送信）
• 管理画面や内部ツールからのAPI利用
• シンプルな認可で十分なユースケース

OAuth 2.0が適するケース

• エンドユーザーが直接操作するアプリケーション
• サードパーティアプリへの認可委譲が必要な場合
• ユーザーごとの細かいアクセス制御が必要な場合

多くのSaaSプロダクトでは、両方を併用するハイブリッド方式を採用しています。外部公開APIにはAPIキー認証、エンドユーザー向けにはOAuth 2.0という使い分けです。

本記事では、SaaSのバックエンドAPIで広く採用されているAPIキー認証を中心に解説します。

APIキー管理の設計パターン

APIキーの管理は「発行・保存・検証・失効」の4つのライフサイクルで考えます。それぞれに設計上の判断ポイントがあります。

1. APIキーの発行

APIキーの生成には、暗号学的に安全な乱数生成器を使用します。キーの長さは最低32文字が推奨されます。

設計のポイントは以下の通りです。

プレフィックスの工夫は運用面で大きな効果があります。たとえば、fb_live_（本番用）とfb_test_（テスト用）を使い分けることで、誤って本番APIキーをテスト環境で使ってしまう事故を防げます。

2. APIキーのハッシュ化保存

APIキーは平文で保存してはいけません。パスワードと同様に、ハッシュ化して保存します。

ここでの設計判断のポイントは、どのハッシュアルゴリズムを使うかです。

パスワードにはbcryptやArgon2が推奨されますが、APIキーの場合は事情が異なります。パスワードは人間が決めるため短く推測されやすいですが、APIキーは暗号学的に安全な乱数で生成された十分な長さを持っています。そのため、レインボーテーブル攻撃やブルートフォース攻撃のリスクが極めて低く、SHA-256で十分な安全性を確保できます。

APIリクエストの検証は毎回行われるため、ハッシュ計算の速度はレスポンスタイムに直結します。ここでbcryptを使うと、数十〜100ms程度のオーバーヘッドが全リクエストに加算されてしまいます。

3. APIキーの検証フロー

リクエスト受信からレスポンス返却までの認証フローは、以下のステップで構成します。

1. リクエストヘッダーからAPIキーを抽出（X-API-KeyヘッダーまたはAuthorization: Bearer）
2. 受け取ったキーをSHA-256でハッシュ化
3. ハッシュ値でデータベースを検索
4. 該当するキーが見つかったら、有効期限・ステータスを確認
5. スコープ（権限）の検証へ進む

この設計により、プレーンテキストのAPIキーがデータベースに存在しない状態を実現できます。たとえデータベースが流出しても、ハッシュ値から元のキーを復元することは計算上不可能です。

4. APIキーの失効とローテーション

APIキーには必ず失効の仕組みを設けます。設計上考慮すべき点は以下の通りです。

• 有効期限：発行時に有効期限を設定可能にする
• 手動無効化：管理画面から即時無効化できる
• ローテーション支援：新旧キーの並行運用期間を設けて、移行中のダウンタイムをゼロにする
• 最終使用日時の記録：使われていないキーの特定と削除に活用

ローテーション時に一瞬でもAPIが使えなくなると、利用者のシステムに影響が出ます。新しいキーを発行→利用者が切り替え→古いキーを無効化、という段階的な移行フローを提供することが重要です。

スコープベースの権限制御

APIキーで「誰か」を認証した後は、「何ができるか」を制御する認可の設計です。ここでは、スコープベースの権限制御パターンを解説します。

スコープの設計原則

スコープは「リソース:操作」の形式で設計するのが一般的です。

この設計には「最小権限の原則（Principle of Least Privilege）」を徹底します。たとえば、データ分析用の連携ではanalytics:readだけを付与し、データの書き換え権限は与えません。

スコープの粒度の考え方

スコープの粒度は、細かすぎても粗すぎても問題です。

• 細かすぎる例：blog:create、blog:update、blog:delete、blog:publish、blog:unpublish …
• 粗すぎる例：all:full_access
• 適切な例：blog:read、blog:write、admin:manage

最初から細かく分けすぎると、APIキーの発行時にユーザーが選択肢に混乱します。readとwriteの2軸からスタートし、実際のユースケースに応じて細分化していくアプローチが現実的です。

スコープの検証フロー

各APIエンドポイントに必要なスコープを定義し、リクエスト処理の前に検証を行います。一般的なフローは以下の通りです。

1. APIキー認証を通過（前述のフロー）
2. 認証済みキーに紐づくスコープ一覧を取得
3. リクエスト先のエンドポイントが要求するスコープと照合
4. 必要なスコープがすべて含まれていれば許可、なければ403 Forbiddenを返却

重要なのは、スコープ不足時のエラーレスポンスで「どのスコープが不足しているか」を明示することです。これにより、API利用者は自力で問題を解決できます。

スコープとプランの連動

SaaSの料金プラン設計と連動させることで、プランごとに使えるAPIの範囲を制御できます。

この設計により、アップセルの導線をAPIレベルで自然に組み込めます。

レート制限の設計

レート制限は、APIの安定性を守りつつ、利用者に公平なアクセスを提供するための仕組みです。マルチテナントSaaSでは特に重要になります。

レート制限の基本設計

レート制限は「単位時間あたりのリクエスト数上限」で定義します。一般的には、以下のように設計します。

レスポンスヘッダーによる残量通知

業界標準のレート制限ヘッダー（X-RateLimit-Limit等、GitHub・Stripeなど主要APIが採用）をレスポンスに含めることで、API利用者は残りのリクエスト数を把握できます。

これらのヘッダーを提供することで、利用者側でリクエスト頻度を自動調整する仕組み（バックオフ処理）を実装しやすくなります。

429 Too Many Requestsの設計

レート制限を超過した場合は、HTTPステータス429を返却します。レスポンスボディには以下を含めます。

• エラーメッセージ（人間が読める説明）
• 現在の制限値
• リセットまでの待機時間
• プランアップグレードの案内（オプション）

重要なのは、429レスポンスで既存のリクエスト処理を中断しないことです。処理中のリクエストはそのまま完了させ、新規リクエストのみを制限する設計にします。

IP制限の追加レイヤー

APIキー認証とスコープ制御に加えて、IPアドレスによるアクセス制限を追加のセキュリティレイヤーとして提供できます。

CIDR表記によるサブネット指定

単一IPだけでなく、CIDRサブネット（例：192.168.1.0/24）での指定に対応することで、企業のネットワーク環境に柔軟に対応できます。

IP制限の設計ポイントは以下の通りです。

• 許可IPリストはAPIキーごとに設定可能にする
• CIDR表記（/8 〜 /32）をサポート
• IPv4とIPv6の両方に対応
• IP制限が未設定の場合はすべてのIPを許可（オプトイン方式）

この設計により、セキュリティ要件の厳しいエンタープライズ顧客のニーズに対応しつつ、小規模利用者には手軽さを維持できます。

セキュリティ上の考慮事項

認証基盤の設計では、以下のセキュリティ対策も合わせて実装します。SaaSのセキュリティ対策の詳細も参考にしてください。

通信のセキュリティ

• HTTPS必須：APIキーが平文で流れるHTTPは絶対に許可しない
• HSTS設定：HTTPからHTTPSへの強制リダイレクト

ログと監査

• APIキーの発行・無効化・スコープ変更をすべて監査ログに記録
• 認証失敗のログを記録し、異常なパターン（短時間に大量の認証失敗）を検知
• 最終使用日時・使用元IPを記録し、不正使用の早期発見に活用

エラーレスポンスの設計

• 認証失敗時に「APIキーが無効」と「APIキーが存在しない」を区別しない（情報漏洩防止）
• 一律で401 Unauthorizedを返却し、詳細な原因は内部ログにのみ記録
• 認可失敗（スコープ不足）は403 Forbiddenで返却し、不足スコープを明示

まとめ：堅牢なAPI認証基盤の設計指針

SaaS APIの認証設計は、以下の3つの柱で構成されます。

1. APIキー管理：SHA-256ハッシュ化保存、プレフィックス設計、ローテーション支援
2. スコープベース権限制御：リソース:操作の粒度設計、最小権限の原則、プラン連動
3. レート制限：プラン別上限、業界標準ヘッダー、429応答設計

これらを組み合わせることで、セキュリティと利便性のバランスが取れた認証基盤を構築できます。

FUNBREWでは、自社SaaSプロダクト「FUNBREW PDF」の開発で培った知見をもとに、システム開発のご支援を行っています。API設計や認証基盤の構築でお悩みの方は、ぜひお気軽にご相談ください。