OAuth 2.0による認可
このドキュメントでは、マネーフォワード クラウドのAPIにOAuth 2.0の認可フロー（主に認可コードフロー）を用いてアクセスする方式について説明します。
OAuth 2.0による認可とは
OAuth 2.0による認可は、ユーザーが連携を承認したうえで、アプリケーションがマネーフォワード クラウドのAPIにアクセスするための方式です。Web・モバイル・デスクトップなど、ユーザー操作を介してログインや同意画面を表示できるクライアント向けに適しています。
ユーザーはマネーフォワード クラウドにサインインし、連携先アプリに必要な権限（スコープ）を同意します。同意後に発行されるアクセストークンを、APIリクエストの認証に用います。ユーザーのIDやパスワードをアプリに直接渡す代わりに、トークンを通じて安全にアクセスできます。
事前にアプリポータルでアプリ（OAuth 2.0におけるクライアント）を登録し、Client ID、Client Secret、リダイレクトURIなどを取得する必要があります。
トークンと権限の概念
| 要素 | 役割 |
|---|---|
| アクセストークン | APIを呼び出す際にAuthorizationヘッダーにBearerスキームで付与する、短期間有効な利用許可証。 |
| スコープ | アクセストークンに付与される権限（どのサービスに対し、どのような操作が可能か）。呼び出すAPIに対応したスコープがトークンに含まれている必要があります。 |
| リフレッシュトークン | アクセストークンの再発行に用いるトークン。有効期限はアクセストークンより長く設定されます。 |
APIエンドポイントの対応状況
各APIエンドポイントがサポートする認証方式（OAuth、APIキー、または両方）は異なります。使用予定のAPIエンドポイントがどの認証方式をサポートしているか、APIリファレンスで確認してください。
APIキーによる認証との違い
マネーフォワード クラウドのAPIへのアクセスには、APIキーとOAuth 2.0認可フローの2つの認証方式があります。どちらの方式を使用するかは、アプリケーションの種類や利用シーンによって異なります。
| 項目 | APIキー | OAuth 2.0認可フロー |
|---|---|---|
| 認証の対象 | ユーザーの権限で実行 | 事業者全体のデータにアクセス |
| トークンの有効期限 | APIキー自体に期限なし（JWTは1時間） | アクセストークンは1時間、リフレッシュトークンで更新可能 |
| 権限の範囲 | APIキー発行時にサービス単位で設定 | ユーザーの同意に基づいてスコープを指定 |
どちらの認証方式を選ぶべきか
OAuth 2.0認可フローは、事業者に登録されたデータに対して、ユーザー同意とスコープに沿ってアクセスする必要がある場合に使用します。 APIキーは、サーバー間通信や自動化など、プログラムからユーザーの操作なしにAPIを実行する場合に使用します。
APIキーによる認証の詳細は、APIキーによる認証を参照してください。
認可の仕組み
OAuth 2.0の認可コードフローでマネーフォワード クラウドのAPIにアクセスする流れは、おおむね次のステップで構成されます。
STEP 1: アプリの登録
アプリポータルでアプリを登録し、Client ID、Client Secretを取得、リダイレクトURIを設定します。
STEP 2: 認可コードの取得
ユーザーに認可画面を表示し、同意後に認可コードを受け取ります。パラメーターは認可エンドポイントのドキュメントを参照してください。
STEP 3: アクセストークンの取得
認可コードをトークンエンドポイントに送信し、アクセストークンおよびリフレッシュトークン（該当する場合）を取得します。
STEP 4: APIの呼び出し
取得したアクセストークンをAuthorization: Bearerで付与して、マネーフォワード クラウドの各APIを呼び出します。
GET https://api.biz.moneyforward.com/{service}/api/v1/...
Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...
STEP 5: トークンの更新
アクセストークンの有効期限が切れた場合は、リフレッシュトークンを用いてトークンエンドポイントから再取得します。 アクセストークンの有効期限は1時間です、リフレッシュトークンの有効期限は540日です。
セキュリティ上の注意事項
OAuth 2.0による認可を利用するにあたっては、次の点に注意してください。
1. Client Secretを安全に保管する
- コードに直接記述しない: ソースコードにClient Secretをハードコードしないでください
- バージョン管理システムにコミットしない: 設定ファイルは
.gitignoreに追加してください - 環境変数やシークレット管理サービスを使用する: AWS Secrets Manager、HashiCorp Vaultなどを利用してください
2. リダイレクトURIを適切に設定する
認可後にリダイレクトされるURIは、事前にアプリポータルで登録したものと一致させる必要があります。意図しないURIへの認可コードの漏洩を防ぐため、本番環境と開発環境で別のURIを登録するなど、運用に合わせて管理してください。
3. 通信の暗号化
認可・トークン取得・API呼び出しは、必ずHTTPSを使用してください。HTTPSを使用することで、通信内容が暗号化され、中間者攻撃を防ぐことができます。
4. アクセストークン・リフレッシュトークンの管理
取得したトークンは機密情報です。ログに出力したり、クライアントに不必要に送信したりしないでください。 トークンが漏洩した可能性がある場合は、速やかにトークンを失効させ、必要に応じてClient Secretのローテーションなどの対応を検討してください。
トークンやClient Secretが漏洩した場合、弊社は一切の保証を提供できません。厳重に管理し、漏洩を防ぐようお願いいたします。
漏洩に関するご相談やサポートが必要な場合は、アプリポータルサポートまでお問い合わせください。
次のステップ
OAuth 2.0による認可の概要を理解したら、目的に応じて次のドキュメントを参照してください。
| 目的 | 次のステップ |
|---|---|
| アプリポータルにおけるOAuth連携の役割と主な機能を知りたい | アプリポータルの概要（OAuth） |
| アプリポータル権限を安全に運用したい | アプリポータルの権限設計のベストプラクティス（OAuth） |
| OAuth 2.0の認可コードフローを体験したい | チュートリアル: APIを手動で呼び出してみる |
| クライアント実装のポイントを学びたい | クライアントアプリを作って実装ポイントを学ぶ |
| 認可エンドポイント・トークンエンドポイントの技術仕様を確認したい | 認可サーバーAPI |
| サーバー間通信や自動化向けの認証方式（APIキー）を知りたい | APIキーによる認証 |