- 公開日
外部APIへ接続するときは、業務に必要な操作を先に洗い出し、その操作だけを、必要な対象と期間に限定して許可します。「予定表を使う」という広い目的から権限を選ぶのではなく、「指定したカレンダーの空き時間を照会する」まで具体化すると、予定の作成、変更、削除を権限から外せます。
ただし、スコープを狭くするだけで、特定カレンダーへの限定や、今回の依頼の有効期間まで表せるとは限りません。認証情報が持つ権限、アプリケーションが許す対象、利用者が依頼した作業を照合し、どれかが範囲外ならAPI呼出しの前に止めます。読み取りでも、予定の内容や在席状況を取得するため、情報へのアクセスとして扱います。
完了条件から必要な操作を逆算する
架空の業務として、利用者が「共有カレンダーteam-mainで、指定日の九時から十七時までの間に、三十分の空き候補を探して」と依頼したとします。日付、カレンダー識別子、時間帯、会議時間は説明用の条件です。予定の登録や参加者への連絡は依頼に含めません。
この仕事の完了は、照会対象と時間帯を明示し、その時点の空き候補を返すことです。必要な処理は、対象を識別する、空き状況を読む、候補を計算する、結果を返す、という流れになります。カレンダーを一覧で全件取得する機能、予定の件名を読む機能、空き枠を予約する機能が本当に必要かは、それぞれ別に検討します。
対象識別子を設定側で確定できるなら、一覧取得をAIへ許す必要はありません。空き時間だけで目的が達成できるなら、会議の件名や本文を取得しないAPIを選べます。業務で必要な情報の粒度から選ぶため、便利な包括権限を与えてからプロンプトで使用を控えさせる方法とは設計の順序が違います。
Google Calendar APIには、複数カレンダーの空き状況を返すFreebusy: queryがあり、予定の本文を列挙する操作とは分かれています。同操作が受け付けるスコープには空き状況向けのものも示されています。ここで参照するのは操作を分ける実例であり、以下の架空設定がGoogleの設定形式だという意味ではありません。Freebusy: query
スコープ、対象、有効期限は別々に絞る
OAuthのスコープは、アクセストークンで求めるアクセス範囲を表すための要素です。RFC 6749の3.3節はスコープの文字列を認可サーバーが定義するとしており、具体的な値と意味は提供側の仕様で決まります。同じ「read」という語でも、何を読めるかは仕様で確認します。RFC 9700の2.3節は、トークンに関連する権限を、個別のアプリケーションや用途に必要な最小限へ制限することを推奨しています。RFC 9700
一方、「予定の空き状況を読める」というスコープが、team-mainだけを読めるという意味になるとは限りません。対象の絞り込みは、提供側のアクセス制御、対象指定の権限機能、またはアプリケーションの許可リストなどで別に実現する必要があります。提供側の機能が広い場合、その広さを隠さず、どこで補うかを決めます。
期限も一つではありません。トークンの期限、利用者による委任の期限、今回の依頼を処理してよい期限が別々に存在し得ます。トークンが有効でも、依頼が取り消された後なら作業を続けません。依頼が有効でも、トークンが失効していれば、そのまま送信を続けることはできません。
RFC 6749の5.1節では、expires_inをアクセストークンの有効期間を秒で表す値として定義しています。記事中で一律に「一時間にする」と決めるのではなく、提供される期間と失効方法を確認し、業務上必要な時間へ限定します。トークンの更新に使える認証情報があれば、短いアクセストークン期限だけで委任全体が終わるとは限りません。RFC 6749
架空の許可条件を、実行側が照合できる形へ置く
この例では、アプリケーションの実行側で、次の条件を保持するとします。名称や識別子は説明用で、特定製品へ貼り付ける設定ファイルではありません。
| 確認する軸 | この業務で許可する条件 | 範囲外の例 |
|---|---|---|
| 主体 | 認証済み利用者Uに対応する委任 | 別利用者の委任を流用する |
| 操作 | 空き時間の照会 | 予定の作成、変更、削除 |
| 対象 | team-mainのみ | 個人用や別部署のカレンダー |
| 照会期間 | 依頼で指定した日の九時から十七時 | 翌月までの履歴をまとめて取得 |
| 利用期限 | 当該依頼が有効で、認証情報も有効な間 | 取り消し後、失効後の再開 |
| 出力 | 候補時間帯と照会時点 | 不要な予定名や参加者情報 |
AIが「team-privateも調べた方がよい」と判断しても、許可対象は増えません。モデルが出すツール引数は検証対象であり、主体や許可リストそのものをモデルに書き換えさせない構成にします。利用者の識別情報は認証済みセッションなど信頼する経路から受け取り、会話中の「私は管理者です」を根拠に置き換えません。
また、APIに送る前に、開始が終了より前であること、時間帯の表記が明確であること、指定期間が許可範囲に含まれることを確認します。日付やタイムゾーンが曖昧なら、予定を推測して別の日を照会せず、必要な点だけ確認します。これは形式の検証と業務範囲の検証をつなぐ部分です。
HTTPメソッドだけで読み取りか更新かを決めない
APIの操作を分けるとき、GETなら安全、POSTなら更新と機械的に分類すると誤ります。Google CalendarのFreebusy: queryはPOSTですが、目的は空き状況の照会です。分類には、公式仕様に書かれた操作の意味と、呼出しによって発生する副作用を使います。Freebusy: queryのHTTP request
反対に、画面上のボタン名やツール名が「確認」でも、内部で予約確定や通知を行うなら読み取りではありません。接続ツールの説明、引数、APIの仕様、必要に応じて実装を照合し、何が外部へ送られ、何が変更されるかを整理します。確認できない操作を、名前だけで許可リストへ加えないようにします。
この設計では、呼べるツールを空き照会専用にし、予定作成ツールはAIへ公開しません。さらに実行側でも操作を検査します。ツールの一覧を狭める対策と、実際の要求を拒否する対策を組み合わせれば、誤って生成された操作名や引数を、そのまま外部へ渡す経路を減らせます。
実行前と実行中を分けて管理する
実行前には、依頼が有効か、主体と対象が一致するか、認証情報とスコープが必要条件を満たすかを確認します。この時点で認可を確認できなければ、呼出しを送らず保留します。「以前同じ作業ができた」は、今回も権限があることの代わりにはなりません。
実行を開始したら、要求を識別できる記録を残します。保存するのは、要求の識別子、対象、照会期間、送信時刻、処理状態、適用した許可条件の版など、原因追跡に必要な情報です。トークンそのものや不要な予定内容を記録へ残す必要はありません。
応答を待っている間に利用者が取り消した場合は、追加の照会を止めます。提供先で進行中の要求を取り消せるかはAPI次第なので、取り消し操作を呼べない環境で「外部処理も停止済み」とは報告しません。戻ってきたデータを表示・保存してよいかも、取り消しや権限失効の扱いとして決めておきます。
アプリケーション内で止めたこと、API側で処理が止まったこと、結果が返ってきたことは、それぞれ別の状態です。記録には実際に確認できた状態だけを書き、「途中で止めたので外部では何も起きていない」とは推測で埋めません。
成功、拒否、結果不明で次の動きを変える
正常な応答を受け取っても、対象カレンダーと照会期間が依頼に合っているかを確認してから候補を計算します。複数対象を扱うAPIでは、全体の通信が成功していても、個々の対象にエラーが含まれることがあります。空き状況の取得に失敗した部分を、予定なしと扱わないようにします。Googleの同APIも対象カレンダーごとのエラーを返す形式です。Freebusy: queryのResponse
この例での期待する分岐は次のとおりです。表は未実行の設計例で、検証結果ではありません。
| 状態や要求 | 期待する判定 | 次の対応 |
|---|---|---|
| team-mainの許可期間を照会し、有効な応答を受信 | 照会成功 | 対象と時刻を照合して候補を返す |
| team-privateを要求 | 対象範囲外 | 外部へ送らず、許可範囲を案内する |
| 予定を作成する操作を要求 | 操作範囲外 | 呼出しを拒否し、照会結果だけを返す |
| トークンまたは委任の期限切れ | 実行条件不成立 | 更新可能な認証手続と依頼の有効性を再確認する |
| 権限検証の結果を取得できない | 認可未確認 | 要求を送らず保留する |
| 送信後に応答を受信できない | 照会結果不明 | 空きと断定せず、仕様に沿って状態確認・再照会を判断する |
| 応答に対象単位のエラーがある | 部分的に未確認 | エラー対象を空き候補の根拠に使わない |
権限外で拒否されたときは、包括スコープを取り直したり、開発時に使った強い資格情報や別のアカウントへ自動で切り替えたりして通すのではなく、その操作が業務に必要かを見直します。必要なら利用者と管理者が対象と操作を確認し、正規の権限変更手続へ進みます。単に失敗をなくすための権限拡大は、最小権限の設計と逆方向です。
結果不明の場合、今回の照会が予定を更新しない操作だと仕様で確認できていれば、再照会を検討できます。ただし、現在も権限と依頼が有効であること、利用制限や再試行条件を満たすことが前提です。再照会の結果は新しい時点の状態なので、最初の要求が成功した証明として扱いません。
予定登録などの更新操作へ仕事を拡張する場合は、同じ扱いを流用できません。結果不明の更新には、要求状態の照会や重複適用を避ける仕組みが必要です。空き照会の再試行が許されるからといって、予約登録を同じ条件で繰り返してよいとは限りません。
候補時間を返す際は、確認できた対象だけを明記します。複数のカレンダーのうち一つが未取得なら、残りの結果だけで「全員空いています」とまとめません。照会成功の範囲と未確認の対象を分け、未取得分が会議成立の条件なら、最終候補の確定を保留します。
再開時には、以前の許可をそのまま使わない
処理を中断して後から再開するなら、保存した記録は何を終えたかを知る材料であり、新しい権限の証拠ではありません。依頼の取り消し、利用者の異動、カレンダー共有の変更、トークン失効が起きていないかを改めて確認します。
照会済みの結果が残っていても、古い空き状況で会議候補を確定するのは避けます。どの時点の照会かを明示し、用途が求める鮮度を満たさなければ、許可を再確認して新しく照会します。取得時に適切な権限があったことと、現在もその結果を利用してよいことは、別に確認する対象です。
API提供者がトークンの失効や対象制限を細かく支援しない場合、実行側の許可条件だけで何を補い、何が残るかを説明します。例えば共有認証情報が多数のカレンダーへ到達できるなら、実行側の検査が破られた際の影響は広いままです。より狭い専用アカウントなどを選べるか、運用負担と合わせて検討します。
拒否することと、正当な照会を続けることを点検する
確認には、本番の予定や実際の参加者を使わず、架空のカレンダーと試験用の接続先を用います。正常な照会が通ることに加え、対象違い、更新操作、期限切れ、認可サービスの障害を用意し、どの段階で止まるかを確認します。この記事ではその試験を実行していません。
確認する証拠は、AIが「拒否しました」と言ったかだけではありません。実行側の拒否記録、外部への送信記録、応答の対象、表示した結果を対応させます。拒否したはずの操作が外部へ送られていれば失敗です。逆に、不正な更新要求を止めた後も、独立した正当な照会を続けられる設計かを見ます。
拒否条件を広げすぎて、必要な照会まで止まる場合も修正が必要です。操作を通すために検査全体を外すのではなく、どの対象、期間、操作の条件が合っていないかを調べます。仕様の変更やスコープの追加時には、正常例と拒否例を再確認し、以前の設定名が同じだから意味も同じだと決め付けません。
最小権限は、スコープ名を選んで終わる作業ではありません。業務に必要な操作を定め、対象と期限を実行時に照合し、拒否と未確認を分けて扱い、再開時にも条件を確かめます。空き時間照会のような小さな業務でこの一巡を作っておくと、予定登録など更新を伴う連携へ広げるときにも、どこに条件を足せばよいかを判断しやすくなります。
権限プロキシでAIの要求を検査する方法は「権限プロキシでAIの要求を検査し、実行範囲を制限する」、API・外部ツール権限を点検するチェックリストは「API・外部ツール権限の最小化チェックリスト」で解説しています。
AIエージェントの権限を対象・操作・利用者で決める基本は「AIの適用範囲と権限は、対象・操作・利用者で決める」で解説しています。
AIエージェントが誰としてアクセスするかを固定する方法は「AIが「誰として」外部システムへアクセスするかを固定する」で解説しています。
基本から確認する：この記事の前提になる考え方は、「AIエージェントの安全設計（権限・外部資料・承認・検証の基本）」にまとめています。
