Microsoft 365 コネクター

English: Microsoft 365 connector

Microsoft 365 コネクターを使うと、Kurahi のエージェントが Outlook のメールと予定表を読み取れます。 設定で有効にすれば、OneDrive と SharePoint のファイルも扱えます。お客様自身のアプリ登録を使って Microsoft Graph に接続し、委任されたアクセス許可で 1 人のユーザーとしてサインインします。 エージェントが見られるのは、そのユーザーが見られる範囲だけです。

項目	内容
プラグイン ID	microsoft-365（同梱、既定は無効）
既定のアクセス	読み取り専用：メールと予定表
追加で有効にできるもの	ファイル、SharePoint サイト、メール送信、下書き、予定の作成、アプリ フォルダーへのアップロード
サインイン	ループバック リダイレクトによる PKCE 付き認可コード、またはデバイス コード
トークンの保存先	Kurahi のシークレット ストア（connector.microsoft-365.token）。設定ファイルには保存しません
状態	提供中

管理者が Microsoft Entra で行う設定

1. Microsoft Entra 管理センターで ID > アプリケーション > アプリの登録 > 新規登録 を開きます。
2. 名前は例えば kurahi。サポートされているアカウントの種類は この組織ディレクトリのみに含まれる アカウント（シングル テナント） を選びます。
3. リダイレクト URI：プラットフォーム パブリック クライアント/ネイティブ (モバイルとデスクトップ)、 値 http://localhost。Kurahi は 127.0.0.1 の空きポートで待ち受けます。localhost であれば Microsoft はポート番号を問いません。
4. 作成後、概要ページの アプリケーション (クライアント) ID と ディレクトリ (テナント) ID を控えます。
5. 認証 で パブリック クライアント フローを許可する を はい にします（デバイス コードでの サインインに必要）。Kurahi はパブリック クライアントとして PKCE を使うため、クライアント シークレットや証明書は不要です。
6. API のアクセス許可 > アクセス許可の追加 > Microsoft Graph > 委任されたアクセス許可 で、 有効にする機能に必要なものだけを追加します（下表）。ユーザー自身による同意を許可していない テナントでは 管理者の同意を与えます を選択します。

機能（設定キー）	委任されたアクセス許可	既定で管理者の同意が必要	アクセス
常に	User.Read、offline_access	いいえ	読み取り
メール（mail、既定で有効）	Mail.Read	いいえ	読み取り
予定表（calendar、既定で有効）	Calendars.Read	いいえ	読み取り
ファイル（files.enabled）	Files.Read.All	いいえ	読み取り
SharePoint（files.sharePoint）	Sites.Read.All	いいえ	読み取り
メール送信（write.mailSend）	Mail.Send	いいえ	書き込み
下書きの作成（write.mailDraft）	Mail.ReadWrite（Mail.Read の代わり）	いいえ	書き込み（下書きの作成のみ、送信はしない）
下書きへの添付（write.mailDraft）	Mail.ReadWrite（下書きと同じ許可）	いいえ	書き込み（下書きのみ）
予定の作成（write.calendarWrite）	Calendars.ReadWrite（Calendars.Read の代わり）	いいえ	書き込み
アプリ フォルダーへのアップロード（write.files）	Files.ReadWrite.AppFolder	いいえ	書き込み（アプリ フォルダーのみ）

Kurahi が要求するのはこれらのスコープだけです。許可されていないスコープが必要なツールは、 要求を送る前に拒否します（scope_missing）。

Kurahi の設定

kurahi plugins enable microsoft-365
kurahi config set plugins.entries.microsoft-365.config '{
  "tenantId": "<ディレクトリ (テナント) ID または確認済みドメイン>",
  "clientId": "<アプリケーション (クライアント) ID>"
}' --json
kurahi m365 status
kurahi m365 login            # このマシンのブラウザーでサインイン
kurahi m365 login --device   # 別の端末でサインイン（サーバー、リモート デスクトップ）
kurahi m365 probe            # 実際の接続確認を 1 回実行

plugins.entries.microsoft-365.config のその他の設定：

キー	既定値	意味
mail	true	メールのツール
calendar	true	予定表のツール
files.enabled	false	ファイルの検索と読み取り
files.sharePoint	false	SharePoint サイトの検索とサイトのライブラリ
files.maxFileBytes	10485760	エージェントがダウンロードできる最大サイズ（上限 20 MB）
write.mailSend	false	m365_mail_send
write.mailDraft	false	m365_mail_create_draft、m365_mail_attach_to_draft
write.calendarWrite	false	m365_calendar_create_event
write.files	false	m365_files_upload
redirectPort	ランダム	ファイアウォールの都合でポートを固定する場合
probeIntervalMinutes	15	接続確認の間隔（分）
ratePerSecond	8	Graph への 1 秒あたりの要求数の上限（クライアント側）
approvalTimeoutSeconds	120	書き込みが承認を待つ時間（秒）
mailWatch.pollSeconds	60	オートパイロットのメールトリガーの差分確認間隔（30〜600 秒）
notifications.publicUrl	なし	Graph の変更通知を受ける https のベース URL（任意）

機能を変えると要求するスコープも変わります。変更後は kurahi m365 login をやり直してください。

ツール

ツール	必要なもの	内容
m365_mail_list	Mail.Read	フォルダー内の最近のメール：ID、日時、差出人、件名、冒頭
m365_mail_search	Mail.Read	メールボックスの検索
m365_mail_read	Mail.Read	1 通をプレーン テキストで読む。添付は ID・名前・サイズ・種類のみ
m365_mail_attachment_fetch	Mail.Read	ファイル添付 1 件（20 MB 以下）を、隔離・ポリシー検査・マルウェアスキャンの後にプロジェクトへ保存（添付ファイルの取り込み）
m365_calendar_list	Calendars.Read	最大 62 日間の予定（UTC）
m365_calendar_read	Calendars.Read	1 件の予定（出席者と説明を含む）
m365_files_search	Files.Read.All / Sites.Read.All	OneDrive または SharePoint サイトのライブラリ内のファイル
m365_files_read	Files.Read.All	PDF、DOCX、XLSX、CSV、TXT、MD のテキスト
m365_sites_search	Sites.Read.All	名前で SharePoint サイトを探す
m365_mail_send（追加）	Mail.Send と承認	プレーン テキストのメールを送信
m365_mail_create_draft（追加）	Mail.ReadWrite	プレーン テキストの下書き・返信の下書きを作成（送信しない）
m365_mail_attach_to_draft（追加）	Mail.ReadWrite	プロジェクトのファイル（最大 3 MB）を下書きに添付（送信しない）
m365_calendar_create_event（追加）	Calendars.ReadWrite と承認	予定を作成し、出席者を招待
m365_files_upload（追加）	Files.ReadWrite.AppFolder	プロジェクトのファイル（最大 4 MB）を OneDrive のアプリ フォルダーにアップロード

エージェントにツールの許可リストを設定している場合は、使わせたいツールを追加してください （例：tools.alsoAllow）。

書き込みには必ず人の承認が必要

書き込みツールは、設定で有効にし、かつサインイン時に書き込みスコープが許可された場合にだけ 登録されます。その場合でも、呼び出しのたびにまず承認依頼（宛先、件名、日時）をコマンド承認と 同じ経路で送り、時間内に人が承認しない限り実行しません。ポリシー ファイルで規則を追加することは できますが、この承認を外すことはできません。例外は次の一つだけです。

継続承認による送信

m365_mail_send が人の承認を省くのは、L3 ルーティンのオートパイロットエンジンからの呼び出し だけです（オートパイロットを参照）。コネクターは送信の時点で、自ら次を確認します。

• 呼び出しがエンジンの実行コンテキストの中で行われていること。これを設定できるのはエンジンだけで、 ツールの引数ではありません。モデルやエージェントのセッションから求めることはできません （approvalId のような引数はツールに存在しません）。
• そのコンテキストが m365_mail_send とルーティン自身のプロジェクト セッションのためのもので、 まだ送信していないこと（エンジンの呼び出し 1 回につき送信 1 回）。
• 指定された継続承認が、オートパイロットの保存領域から検証できること：有効（期限切れでも取り消し 済みでもない）、このルーティンの mail.send 用、ルーティンが有効で L3 かつ mail.send を含む、 to と cc のすべての宛先が範囲内のアドレスまたはドメイン、テンプレートが範囲内、maxPerDay に 残りがある（原子的に 1 回分を使用）。

すべて満たすと、対話的な承認なしで送信します。結果と監査ログには承認 id が残り、使用は autopilot.approval.use として監査されます。それ以外（エージェントのセッション、不一致、期限切れ・ 取り消し済み・範囲外の承認、1 日の上限到達）は、上記のとおり人に承認を求め、誰も承認しなければ 拒否します。

下書きはメールボックスの中にとどまる

write.mailDraft を有効にすると m365_mail_create_draft が追加されます。作成するのは下書きだけで、 内容の確認と送信は人が Outlook から行います。replyToMessageId を指定すると、そのメールに createReply で返信の下書きを作り、本文（プレーン テキスト）、宛先、件名を設定します（引用された 元のメールは置き換わります）。指定しない場合は下書きフォルダーに新しいメールを作成します。本文は 常にプレーン テキスト（最大 64 KiB）で、宛先は m365_mail_send と同じ方法で検査します（to は 1～20 件、cc は 20 件まで）。メールボックスの外に何も出ないため、承認の手順はありません。 このツールが送信を行うことはなく、送信には引き続き write.mailSend（承認つき）が必要です。 監査ログには下書きの ID、返信元メールの ID、宛先の数、本文のサイズだけを記録し、件名、本文、 アドレスは記録しません。

サインイン時には Mail.Read の代わりに Mail.ReadWrite を要求します（読み取りツールはどちらでも 動きます）。Mail.ReadWrite はメールの変更や削除も許可するため、下書きが必要な場合にだけ許可して ください。Kurahi はこれを自分の下書きの作成と編集にのみ使います。

同じ設定で m365_mail_attach_to_draft も追加されます。現在のプロジェクト フォルダーにある ファイルを 1 つ、下書きに添付します。添付の前にメールを読み取り、下書きでなければ拒否するため、 送信済みや受信したメールが変更されることはありません。ファイルは 1 回の要求で送ります（最大 3 MB。 これより大きいファイルは拒否します。このリリースにはアップロード セッションはありません）。 下書きと同じ理由で、承認の手順はありません。

ファイルはアプリ フォルダーにとどまり、共有は人が行う

write.files を有効にすると m365_files_upload が追加されます。現在のプロジェクト フォルダーに あるファイルを 1 つ、サインインしたユーザーの OneDrive の アプリ フォルダー（Graph の special/approot。OneDrive では アプリ > （アプリ登録の名前） と表示）に、最大 4 MB の 1 回の要求でアップロードします。同じ名前のファイルがあっても上書きせず、OneDrive が新しい名前を 付けます。項目 ID と OneDrive のリンク（https のみ）を返します。

アクセス許可は Files.ReadWrite.AppFolder です。Graph で書き込みに使える最小の権限で、届くのは その 1 つのフォルダーだけです。ユーザーの OneDrive のほかの場所、ほかのユーザーのファイル、 SharePoint には届きません。このツールが共有リンクや招待を作ることはありません。ファイルを誰かと 共有するのは、人が OneDrive で行う操作です。

どちらのファイル ツール（添付とアップロード）も、プロジェクトのチャットの中で、現在のプロジェクト フォルダー内のファイルだけを送ります。フォルダーの外に出るパス（../、別の場所を指す絶対パス、 外を指すシンボリック リンク）、_answer-keys などの除外フォルダー、通常のファイルでないものは 拒否します。受け付ける種類はプロジェクトのアップロードと同じ（PDF、DOCX、XLSX、CSV、TXT、MD、 一般的な画像）に PPTX を加えたもので、内容が拡張子と一致している必要があります。監査ログには 項目 ID、バイト数、文書の種類（例：pdf）だけを記録し、ファイル名、パス、内容は記録しません。

オートパイロットのメールトリガー

trigger.event: [{ source: m365.mail, folder: inbox }] を持つルーティン（トリガー）は、新着メールから数秒で実行されます。オンプレミスのゲートウェイは通常 Webhook を受けられないため、既定は Graph の差分クエリ（delta） です。

• サインインごとに一つのウォッチャー。 コネクターはサインインごとに一つのウォッチャーを動かし、購読されたプロジェクトのフォルダーを mailWatch.pollSeconds（既定 60 秒）ごとに GET /me/mailFolders/{folder}/messages/delta?$select=id,receivedDateTime で確認します。他のツールと同じレート制限、再試行、トークン更新を通ります。必要なのは Mail.Read（または Mail.ReadWrite）だけで、メールのツールがすでに要求しています。購読するルーティンがなければ確認しません。
• 伝えるのはシグナルだけ。 ウォッチャーがルーティンに伝えるのは「メールが届いた」こと（件数）だけです。ID、差出人、件名、本文は渡さず保存もしません。メールはルーティン自身の収集が、通常の実行と同じく m365_mail_list / m365_mail_read で読みます。
• 保存するもの。 プロジェクトのフォルダーごとの差分リンク（$deltatoken 付きの Graph の URL）だけを <KOLO_HOME>/projects/<id>/autopilot/triggers/ に保存します（モード 0600）。graph.microsoft.com 以外の URL になっている保存済みリンクは破棄するため、アクセス トークンは Graph にしか送られません。
• 初回の同期。 フォルダーの最初の確認では差分リンクを記録するだけで通知しません。すでにあるメールは新着ではありません。
• 再同期。 Graph が 410 Gone（差分トークンの期限切れ）を返したら、リンクを捨ててフォルダーを最初から同期し、ルーティンに一度だけ通知してフォルダーを確認させます。
• スロットリング。 短い Retry-After はコネクターが待ちます。長い場合や失敗が続く場合は、ウォッチャーが指数的に間隔を空けます（最大 15 分）。その間トリガーは rate_limited 付きの degraded になります。
• サインインの期限切れ。 reauth_required（またはサインインや権限の不足）では autopilot.routines.list のトリガーが degraded になり、保存されたサインインが変わる（kurahi m365 login）まで再試行しません。その間もルーティンの安全網のスケジュールは動きます。

任意の変更通知

ゲートウェイにインターネットから https で到達できる場合は notifications.publicUrl（例：https://kurahi.example.com）を設定します。ウォッチャーはフォルダーごとに Graph のサブスクリプション（changeType: created、通知先 <publicUrl>/plugins/microsoft-365/notifications、メモリにだけ保持するランダムな clientState）も作成し、期限前に更新します。このルートは Graph の検証ハンドシェイクに validationToken を text/plain でそのまま返し、既知のサブスクリプション ID と完全に一致する clientState の通知だけを受け付けます。通知はそのフォルダーの差分クエリをすぐ実行させるだけで、通知の内容は使いません。差分ポーリングは既定かつ予備として常に動き続け、サブスクリプションの作成や更新に失敗しても他には影響しません。値は認証情報やクエリを含まない https の URL でなければならず、そうでなければ変更通知は無効のまま警告を記録します。

データの扱い

• 信頼できない内容として扱う。 メール本文、件名、予定の説明、ファイル名、ファイルのテキストは、 信頼できない外部コンテンツの境界の内側でのみモデルに渡します。内容に含まれる境界マーカーは 無害化します。エージェントには、その中の指示に従わないよう明示しています。
• 監査。 呼び出しごとに、ハッシュ チェーンの監査ログへ 1 行を書きます （connector.microsoft-365.<操作>）。記録するのはエージェント、セッション、項目 ID、件数、 サイズ、送ったファイルの文書の種類、所要時間、エラー コードだけです。件名、本文、アドレス、ファイル名、検索語は記録しません。
• トークン。 アクセス トークンとリフレッシュ トークンは Kurahi のシークレット ストア （OS のキーリングまたは暗号化ファイル）に保存します。ID トークンは保存しません。期限前に更新し、 同時に呼び出しがあっても更新はコネクターごとに 1 回です。
• 制限。 クライアント側で要求数を制限し、スロットリングや障害時はバックオフ付きで再試行し、 Retry-After に従います（60 秒を超える待機を求められた場合は待たずに rate_limited で失敗します）。 ダウンロードは files.maxFileBytes で制限し、ダウンロード開始前に確認します。
• 通信先は Microsoft だけ。 接続するのは login.microsoftonline.com と graph.microsoft.com のみです。

デスクトップのカタログでの状態

ゲートウェイは起動時と probeIntervalMinutes ごとに接続確認（GET /me）を行います。コネクター カタログが 稼働中 と表示するのは、設定済みでサインイン済み、かつ 25 時間以内の接続確認が成功した 場合だけです。それ以外は 未検証 です。connectors.status も同じ情報（設定の有無、サインインの 有無、最後の確認結果と時刻、スコープ名、エラー コード）を返し、トークン、アカウント名、 プロバイダーのメッセージは含みません。

アクセスの取り消し

kurahi m365 logout は保存したトークンを削除します。委任サインインのリフレッシュ トークンを アプリ単位で取り消す Graph の API はないため、すぐに止めるには管理者が Microsoft Entra でも 取り消してください：エンタープライズ アプリケーション > Kurahi > アクセス許可（同意の削除）、 または ユーザー > 対象ユーザー > セッションの取り消し。

このリリースの制限

• グローバルの Microsoft クラウド（login.microsoftonline.com、graph.microsoft.com）のみ。
• ゲートウェイごとにサインインするユーザーは 1 人。アプリケーションのアクセス許可（デーモン）には未対応。
• 添付ファイルは有無を表示するだけで、ダウンロードはしません。
• アップロード セッションには未対応。添付は 3 MB まで、アップロードは 4 MB までです。