Insufficient Scopeが出る原因と確認ポイント

OAuthの権限不足エラーを、Token・Scope・再認可・接続先のアクセス制御に分けて解決するガイド

まず結論

insufficient_scope** は、現在使っているAccess Tokenの権限では、要求したリソースや操作にアクセスするには不十分であることを表すOAuthのエラーです。** たとえば、外部の文書サービスで読み取り専用の権限を承認しているのに、AIから文書の更新を依頼すると、必要な書き込み権限がなく拒否される場合があります。 ただし、エラーを見ただけで「すべてのScopeを追加する」と判断するのは適切ではありません。まずエラーの種類、要求された操作、実際に許可されたScope、サービス側のアクセス制御を順番に確認します。 OAuth Scope自体を理解したい場合は、先に「OAuth Scopeとは？AIに許可する範囲をどう決めるか」を参照してください。

症状

次のような状態なら、Scope不足の可能性があります。

• 外部サービスの検索や閲覧はできるのに、更新すると拒否される。

• アプリの接続は成功しているのに、特定の操作だけ失敗する。

• APIレスポンスやエラーログに insufficient_scope と表示される。

• アプリへ新しい操作を追加した後、以前の接続ではその操作だけ使えない。 接続できることと、その操作が認可されていることは別です。一方、単なるHTTP 403だけではScope不足と断定できません。

まず確認すること

読者が最初に行うべき確認は、次の5つです。

1. エラーの正確な種類を確認する。 insufficient_scope なのか、invalid_token なのか、サービス独自の権限エラーなのかを区別します。
2. 失敗した操作を特定する。 閲覧なのか、作成・更新なのか、削除なのかを整理します。
3. 接続先が要求するScopeを確認する。 APIの公式ドキュメントやエラーレスポンスの案内を参照します。
4. 現在の接続で許可されたScopeを確認する。 アプリが要求したScopeではなく、実際に認可された範囲が重要です。
5. 必要な場合だけ再認可する。 不足している権限が確定したら、接続先の正規の認可手順で追加の許可を取得します。 接続を解除したり、すべての権限を付与したりする前に、上記を確認するのが基本です。

主な原因

原因1：読み取りScopeでは書き込み操作ができない

架空の文書サービスに、説明用のScopeとして documents.read と documents.write があるとします。 AIに「議事録を検索して」と依頼した場合は読み取り権限で対応できても、「議事録を更新して」には書き込み権限が必要になる場合があります。

対処： 操作に必要なScopeを公式資料で確認します。不要な削除・管理者権限までまとめて要求しないでください。

原因2：アプリが要求したScopeと、実際に許可されたScopeが異なる

OAuthでは、Clientが希望したScopeが必ず全部許可されるわけではありません。 RFC 6749では、要求したScopeと発行されたAccess TokenのScopeが異なる場合、実際に許可されたScopeを返してClientへ知らせることとされています。

対処： アプリの設定値だけでなく、認可結果や接続管理画面で実際の許可範囲を確認します。

原因3：新しい権限が必要になったが、以前のTokenを使っている

アプリに新しい機能を追加したり、利用者が以前より広い操作を依頼したりすると、従来の接続で発行されたTokenでは不足することがあります。

対処： 不足するScopeが判明している場合は、接続先がサポートする認可手順で追加の権限を承認します。単に同じ条件で再ログインしただけではScopeが増えない場合があります。

原因4：Scopeではなく、接続先の個別権限が不足している

読み取りScopeがあっても、利用者自身にアクセス権がない文書を読めるわけではありません。組織の設定、共有状態、対象フォルダの権限などで拒否される場合があります。

対処： サービス側のファイル共有や利用者権限を確認します。Scopeだけを広げても解決しないことがあります。

原因5：別のサービス向けのToken、または無効なTokenを使っている

Tokenが有効でも、意図したAPIではない別のサービス向けに発行されている場合は利用できないことがあります。また期限切れや失効による invalid_token は、Scope不足とは別の問題です。

対処： 開発者はTokenの対象サービス、有効期限、検証結果を確認します。Tokenそのものを公開の問い合わせやログへ貼り付けないでください。

切り分け手順

開発者・管理者は以下の順序で診断します。

ステップ1：エラーコードとHTTPステータスを確認する。

OAuth Bearer TokenのRFC 6750では、insufficient_scope に対してHTTP 403が推奨され、必要なScopeを WWW-Authenticate ヘッダーの scope 属性で知らせることがあります。一方、invalid_token ではHTTP 401が推奨されます。 ただし、APIごとに独自のエラー設計があり得るため、ステータスコードだけで原因を確定しません。

ステップ2：どのAPI操作に失敗したか確認する。

同じサービスでも、検索APIと更新APIでは必要な権限が異なる場合があります。まずメソッドと機能を確認し、利用者が何を依頼したかと照合します。

ステップ3：必要なScopeを仕様から特定する。

エラーの案内や接続先の公式ドキュメントで必要なScopeを確認します。Scope名はサービス固有で、世界共通の documents.write が存在するわけではありません。

ステップ4：要求Scopeと許可Scopeを照合する。

Client設定上の scope と、実際に許可された権限が一致しているかを確認します。アプリ設定を変更しても、既存のTokenへ自動的に反映されるとは限りません。

ステップ5：最小限の追加許可が必要か判断する。

不足分だけの権限を取得できる場合は、正規の再認可フローを利用します。再認可が不要なケースでは、サービス側の共有設定や権限を確認します。

ステップ6：同じ操作を再試行して結果を確認する。

再認可したことだけを成功とせず、失敗した操作を再実行して結果まで確認します。

解決方法

症状別の一覧

症状	考えられる原因	確認・対応
読めるが更新できない	書き込みScope不足、または対象の更新権限不足	必要なScopeとファイルの権限をそれぞれ確認
APIが insufficient_scope を返す	Tokenに必要な権限がない	要求Scopeと許可Scopeを比較
以前の接続で新機能が動かない	新しいScopeが未承認	必要に応じて再認可
HTTP 403だけが返る	個別ACLやサービス独自の拒否もあり得る	エラー詳細とサービス仕様を確認
HTTP 401・invalid_token	期限切れや失効など	Scope追加ではなくTokenの有効性を確認
再ログインしても改善しない	同じScopeで認可し直した、または別原因	許可Scopeと対象リソース権限を再確認

エラーレスポンスの例

RFC 6750に沿うBearer Token APIでは、次のような応答があり得ます。

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
                  scope="documents.write"

※ documents.write は架空の例です。実際の応答やScope名は接続先サービスによって異なります。また、必要なScopeの通知は必須ではありません。

ChatGPT・MCP連携ではどう考える？

ChatGPTなどのAIアプリケーションがMCP経由で外部サービスを利用する場合、Toolが見えていることと、必要なScopeが許可されていることは別です。 たとえば、文書更新Toolの呼び出し自体ができても、接続先APIが現在のTokenを読み取り専用と判断すれば更新は拒否されます。 逆に、Tool自体がChatGPTに出てこない場合は、アプリ公開、Tool discovery、接続先Serverなど、Scope以外の原因も考えられます。 「MCPツールがChatGPTに表示されないときの確認ポイント」も参照してください。

OGINAUの実装・検証から分かったこと

OGINAUでは、OGINAU RemoteとOGINAU Browserの開発で、外部サービスへの接続と操作権限を分けて確認してきました。 実装経験から一般化できるのは、接続が成立した、Toolを認識した、実際の操作が認可された、という3つは別の検証項目だということです。 権限不足の原因調査では、いきなりすべての許可を広げるのではなく、操作の種類・認可状態・接続先の権限を分けて確認することが重要でした。 ただし、ここで紹介するのは技術的に一般化可能な考え方です。OGINAU固有のScope体系、認証設定、権限判定ロジックや実際の内部ログは公開していません。

根拠・一次情報

• RFC 6750 Section 3.1：Bearer Tokenのエラーコード：insufficient_scope と invalid_token の違い、HTTPステータスの推奨。

• RFC 6749 Section 3.3：Access Token Scope：要求Scopeと許可Scopeの扱い。

• RFC 9700：OAuth 2.0 Security Best Current Practice：対象サービスと操作を制限するToken設計の考え方。

• OGINAU Remote・OGINAU Browserの開発検証記録：接続・Tool認識・権限確認を分離して調べる知見。

再発防止

アプリへ新しい機能を追加する場合は、必要なScopeを実装前に整理し、認可画面で要求する権限、実際に許可されたTokenの権限、接続先APIのアクセスチェックを確認しましょう。 運用時には、利用者が権限不足エラーとToken無効エラーを区別できるようにし、必要以上に広い権限を要求しないことが重要です。 insufficient_scope** が出たら、エラーを確認し、対象操作に必要なScopeと現在の許可Scopeを照合する。その後、必要な場合だけ再認可して動作を検証する。** この順序が安全で効率的な対処法です。