アダプター設定ガイド

このページでは、Ankole に含まれるエンタープライズ Identity と chat アダプターをまとめます。まず、そのプラットフォームが Identity Provider（IdP） を提供するのか、Channel Provider を提供するのか、それとも両方かを決め、該当する詳細ガイドを開いてください。

初回セットアップ時、/setup は選択した IdP のログイン callback URL とガイドリンクを表示します。セットアップ後は、Identity 設定を Console → Identity Providers で管理します。chat アプリケーションの Agent へのバインドは、Console → Signal Routing で行います。

Identity Providers

IdP は Console へのサインインを提供します。プラットフォームが対応している場合、従業員、部門、グループの同期もできます。組み込みのローカルパスワード provider には外部アプリケーションが不要です。常に /setup と Console に表示され、メールアドレスと Ankole が保存するパスワードでサインインします。最初の管理者、ディレクトリを持たない小さなチーム、またはコンシューマー向け IM のユーザーをマッピングする先のアカウントに使用してください。下の credential 名は Ankole のフォームと一致します。正確な権限、provider console の操作手順、検証手順は、リンク先のガイドを参照してください。

プラットフォーム	外部アプリケーション	主な設定	詳細ガイド
Slack	スクラッチから作成する Slack アプリ	Client ID と Client Secret。ディレクトリ同期には Bot Token と App Token も必要	Slack IdP ガイド
Microsoft Entra ID	シングルテナントのアプリ登録	Tenant ID、Client ID、Client Secret、Microsoft Graph の権限	Entra ID ガイド
Google Workspace	OAuth web client とドメイン全体委任を持つ service account	OAuth client、許可ドメイン、service account の JSON、委任された管理者メール	Google Workspace ガイド
Feishu / Lark	エンタープライズの自社ビルドアプリまたは Custom App	App ID、App Secret、サービスリージョン、アプリの利用範囲	Feishu / Lark IdP ガイド
DingTalk	社内エンタープライズアプリ	Client ID、Client Secret、Corp ID、ディレクトリの権限	DingTalk IdP ガイド
WeCom	連絡先同期が任意の自社ビルドアプリ	CorpID、AgentId、アプリの Secret、連絡先同期の Secret、信頼済み IP アドレス	WeCom IdP ガイド

provider を設定したら、callback URL を /setup が表示する通りに正確に登録します。手入力しないでください。ブラウザがアクセスする HTTPS origin を社内のコンテナアドレスに置き換えないでください。サインインに成功したら、ディレクトリのフル同期を 1 回実行し、Principals and permission groups でユーザー、部門、グループを確認します。

Channel Providers

chat アダプターはメッセージを受信し、Agent の返信を送信します。本番環境では、1 つのプラットフォームが両方を提供する場合でも、Identity 用と chat 用に別々のアプリケーションを作成してください。この分離により、サインイン権限、bot 権限、リリース範囲、credential のローテーションが独立して保たれます。

プラットフォーム	外部アプリケーション	接続と主な設定	詳細ガイド
Slack	Bot User を持つ Slack アプリ	Socket Mode。Bot Token、App Token、events、Bot scopes	Slack channel ガイド
Microsoft Teams	対応する Entra アプリケーションを伴う Azure Bot	Bot Framework。App ID、Client Secret、tenant、messaging endpoint	Teams channel ガイド
Feishu / Lark	別個のエンタープライズ自社ビルドアプリまたは Custom App	常時接続。App ID、App Secret、events、bot 権限	Feishu / Lark channel ガイド
DingTalk	bot を持つ社内エンタープライズアプリ	Stream モード。Client ID と Client Secret、AI カードは任意	DingTalk channel ガイド
WeCom	スーパー管理者が作成する API モードの AI bot	常時接続。Bot ID と bot の Secret	WeCom channel ガイド
Telegram	@BotFather で作成する bot	ロングポーリング。Bot token、グループのプライバシーモードはオフ	Telegram channel ガイド
Discord	Developer Portal で作成する bot を持つアプリケーション	Gateway WebSocket。Bot token、メッセージ内容の intent、bot 権限	Discord channel ガイド
LINE	Official Account の Messaging API channel	Webhook。Channel ID、Channel secret、channel access token、webhook URL	LINE channel ガイド
WhatsApp	WhatsApp product を追加した Meta App と Business の電話番号	Cloud API webhook。App ID、App secret、verify token、Phone number ID、System User token	WhatsApp channel ガイド
Email	IMAP と SMTP を持つ専用のメールボックス	IMAP と SMTP のホストとポート、ログイン名、パスワード、送信者認証	Email channel ガイド

Telegram、Discord、LINE、WhatsApp はコンシューマー向け IM です。そのユーザーには従業員レコードがないため、Agent が応答する前に、新しい送信者を アイデンティティ → 保留中のマッピング でアカウントにマッピングします。WhatsApp では、既知のアカウントがすでにその電話番号を所有している場合、送信者は自動的にマッピングされます。メールの送信者は、明示的なメールの identity 紐付けによってのみ既知になります。この紐付けは、社員についてはディレクトリ同期が作成し、それ以外の人については管理者が作成します。Signal routing ルールを参照してください。

外部アプリケーションを準備したら、Console → Signal Routing → New routing rule を開きます。Agent とアダプターを選択し、credential を入力します。IdP と chat アプリケーションの両方が同じエンタープライズ組織に属する場合にだけ、両者で同じ platformSubjectNamespace を使います。組織をまたいで namespace を共有しないでください。

保存済み credential を更新する

Identity Provider または signal routing ルールを編集するとき、Console は暗号化された credential が保存されていることだけを表示します。token や secret をブラウザーに返したり、ページに埋め込んだりしません。保存済みの値を維持する場合は credential フィールドを空のままにします。値を置き換える場合だけ、新しい値を入力して保存します。古い credential のローテーションまたは失効は外部 provider で実行します。現在の値を Console で表示することはできません。

検証の順序

IdP のサインインを検証し、最初の管理者が Console を開けることを確認します。
ディレクトリのフル同期を実行し、Principals と permission groups を確認します。
chat のルーティングルールを作成し、まず direct message または明示的なメンションでテストします。
Agent がメッセージを受信して返信を送ることを確認してから、グループ監視、リアルタイムのディレクトリ同期、カードなどの高度な機能を有効にします。

provider の scopes、アプリケーションの権限、リリース範囲を変更した場合は、provider が要求するときにアプリケーションを再インストールまたは再公開してください。ローテーションした credential のたびに Ankole を更新します。