アプリポータルの権限設計のベストプラクティス（APIキー）
このドキュメントでは、APIキーを利用する際のアプリポータル権限を安全に運用するための推奨設定について説明します。
アプリポータルの概要については、アプリポータルの概要（APIキー）を参照してください。
前提：APIキーの認証モデル
APIキーによる認証には、以下の特性があります。
- APIキーは発行したユーザーの権限でAPIを実行する
- 発行されたAPIキーは、指定したサービスの範囲内でデータにアクセスできる
- アプリポータルのユーザーを適切に管理することが重要
つまり、APIキーを発行できるユーザーは、そのAPIキーを使用してマネーフォワード クラウドのAPIにアクセスできます。このため、誰がAPIキーを発行できるかを適切に管理することが重要です。
各権限のセキュリティ上の意味
アプリポータルには3つの権限があります。APIキーを利用する場合、それぞれの機能とセキュリティ上の意味（APIキー利用時）を理解してください。
| 権限 | できること | セキュリティ上の意味（APIキー利用時） |
|---|---|---|
| システム管理者（情報システム部門など） | ユーザーの招待・削除、全権限の設定 | アプリポータル全体の統制を担う。付与は最小限にする |
| アプリ開発 | アプリの登録・編集・削除（Client ID／Client Secretの取得） | APIキーには直接関係しない。OAuth認可に使用される |
| アプリ連携 | アプリとマネーフォワード クラウドのサービスの連携を認可 | APIキーには直接関係しない。OAuth認可に使用される |
| 権限なし | APIキーの発行・無効化 | アプリポータルにユーザーとして追加されていればAPIキーを発行できる |
APIキー発行に関する注意
アプリポータルのユーザーは、APIキーを発行し、そのAPIキーを使用してマネーフォワード クラウドのAPIにアクセスできます。アプリポータルのユーザーを慎重に管理し、不要なユーザーは速やかに削除してください。
権限の設定方法は「権限」の設定方法を参照してください。
APIキー発行に関するユーザー管理
なぜ適切な管理が必要か
アプリポータルにユーザーとして追加されたユーザーは、以下のことができます。
- 指定したサービスへのアクセス権限を持つAPIキーを発行する
- 発行したAPIキーを使用してマネーフォワード クラウドのAPIにアクセスする
不適切なユーザー追加や管理は、以下のリスクにつながります。
- 管理者の認識なしに、意図しないAPIキーが発行される
- 従業員が個人的に発行したAPIキーが、管理者の知らないうちに使用される
これらにより、たとえば次のような事態が発生する可能性があります。
- 会計データや従業員情報など機密性の高いデータが、承認されていないシステムや外部サービスからAPI経由で取得・操作される
- 発行済みAPIキーの把握が困難になり、漏洩時の影響範囲の特定や無効化対応が遅れる
推奨される運用
- 必要最小限の追加: APIキーの発行を担当するユーザーのみをアプリポータルにユーザーとして追加する
- 定期的な棚卸し: 発行済みAPIキーの一覧を定期的に確認し、不要なAPIキーは速やかに無効化する
- ローテーション: セキュリティ強化のため、APIキーは定期的に新しいものに更新する
ユースケース別の推奨権限構成
お使いのSaaSとマネーフォワード クラウドを連携する場合
お使いのSaaSが、マネーフォワード クラウドとの連携でAPIキー認証に対応している場合の例です。APIキーによる連携では、利用者がアプリポータルで行う主な操作はユーザーの追加とAPIキーの発行です。画面や手順の詳細はお使いのSaaSによって異なるため、連携するSaaSが公開している手順やドキュメントをご確認ください。
- APIキー発行：アプリポータルのユーザーとして、APIキーを発行する。発行したAPIキーを、お使いのSaaSの設定画面などに入力する
- 連携の利用：お使いのSaaSがAPIキーで認証し、取得されたJWTを用いて、マネーフォワード クラウドのAPIにアクセスする
次の表は、この場合の権限構成の一例です。APIキーの発行そのものに特定の権限の付与は不要です。上記の各権限のセキュリティ上の意味も参照してください。
| 役割 | アプリ開発 | アプリ連携 | 理由 |
|---|---|---|---|
| SaaS連携設定の実行者 部門担当者や情報システム部門などが担うことが多い。お使いのSaaSの案内に沿ってAPIキーを発行し、発行したキーをSaaSの設定画面などに入力する担当。アプリポータルではAPIキー発行のためユーザーを利用する。 | 付与しない | 付与しない | APIキー発行のためアプリポータルにユーザーを追加する必要があるが、アプリ開発・アプリ連携はいずれも付与しない。 |
| システム管理者 情報システム部門などが担うことが多い。ユーザーの招待や発行済みAPIキーの棚卸しなど、運用の統制を担う担当。日常的なAPIキー発行は担当者が行い、システム管理者が必ずしも発行するわけではない。 | 付与しない | 付与しない | ユーザー招待や他ユーザーの権限設定を担ってもよいが、自身にはアプリ開発・アプリ連携をいずれも付与しない。 |
社内システムとマネーフォワード クラウドを連携する場合
アプリ開発者がAPIキーを発行・利用し、自社システムとマネーフォワード クラウドを連携するケースです。
次の表は、この場合における権限構成の一例です。
| 役割 | アプリ開発 | アプリ連携 | 理由 |
|---|---|---|---|
| アプリ開発者 APIキーを発行し、自社システム側のAPI連携の開発・設定を担う担当。APIキー発行のためにアプリポータルを利用する。 | 付与しない | 付与しない | APIキー発行のためアプリポータルにユーザーを追加する必要があるが、アプリ開発・アプリ連携はいずれも付与しない。 |
| システム管理者 情報システム部門などが担うことが多い。必要に応じてアプリポータルへユーザーを招待・追加し、運用の統制を担う担当。開発者に代わってAPIキーを発行する場合もある。 | 付与しない | 付与しない | ユーザー招待やAPIキー代行発行を担ってもよいが、自身にはアプリ開発・アプリ連携をいずれも付与しない。 |
開発環境と本番環境
開発環境と本番環境で異なるAPIキーを発行することを推奨します。本番用のAPIキーは、本番環境へのデプロイ権限を持つ担当者のみが発行・管理するようにしてください。
JWTのライフサイクル
APIキーで取得するJWTには有効期限があります。
| トークン | 有効期間 |
|---|---|
| JWT | 1時間 |
JWTが期限切れになった場合は、/auth/exchangeエンドポイントを再度呼び出して新しいJWTを取得してください。APIキー自体に有効期限はありませんが、セキュリティのため定期的なローテーションを推奨します。
APIキーの定期的な棚卸し
不要なAPIキーが残り続けるリスクを防ぐため、以下の運用を推奨します。
- 定期的な確認: 発行済みAPIキーの一覧を定期的に確認し、不要なAPIキーがないか棚卸しする
- 速やかな無効化: 不要になったAPIキーは、アプリポータルから速やかに無効化する
- 担当者変更時の引き継ぎ: APIキーの管理担当者が変わる際は、既存のAPIキー状況を引き継ぐ