AI エージェントをサードパーティ API に接続する

ヒント:

Logto の AI ソリューションをご覧ください：MCP サーバー、AI エージェント、およびアプリ向けの認証 (Authentication) と認可 (Authorization)。

このガイドでは、AI エージェントがユーザーの代理としてサードパーティ API（例： Google Calendar、GitHub など）へアクセスできるようにする方法を説明します。Logto のソーシャルコネクターと Secret Vault を活用することで、アクセストークン (Access token) を安全に保存・管理し、ユーザーに再認証を繰り返し求めることなく、エージェントが自動タスクを実行できるようになります。

このガイドで学べること：

サードパーティトークン保存付きのソーシャルコネクターの設定方法
初回サインイン時に最小限の権限 (Permission) をリクエストする方法
必要に応じて追加の権限 (Permission) を段階的にリクエストする方法
保存されたトークンを取得し、サードパーティ API へアクセスする方法

なぜ AI エージェントにサードパーティ API アクセスが必要なのか

AI エージェントは、外部サービスと連携してタスクを自動化する用途が増えています。例えば：

📅 カレンダー管理：AI エージェントが Google Calendar で自動的に会議をスケジューリングしたり、イベントを追加・調整できます。
📧 メール自動化：Gmail API を使ってフォローアップメールを送信したり、受信箱を整理したり、返信を下書きできます。
💻 コード管理：GitHub の issue 作成、プルリクエストのレビュー、リポジトリ管理などが可能です。
📁 ファイル管理：Google Drive や Dropbox でファイルのアップロード、整理、共有ができます。

これらのタスクを実行するには、AI エージェントがユーザーの許可を得たサードパーティ API へ安全にアクセスする必要があり、OAuth トークンを正しく安全に扱うことが求められます。

仕組みの概要

フローの概要は以下の通りです：

ユーザーがタスクを依頼：ユーザーが AI エージェントにサードパーティ API アクセスが必要なタスク（例：カレンダーイベント追加）を依頼します。
認可 (Authorization) の促し：エージェントがサードパーティアクセスの必要性を検知し、ユーザーに認可 (Authorization) を促します。
トークン保存：ユーザーが認可 (Authorization) すると、Logto がアクセストークン (Access token) とリフレッシュトークン (Refresh token) を Secret Vault に安全に保存します。
タスク実行：エージェントが保存されたトークンを取得し、サードパーティ API を呼び出してタスクを完了します。

一度認可 (Authorization) されれば、ユーザーは再認可なしで複数のタスクを実行できます。Logto はトークンを安全に保存し、必要に応じて自動でリフレッシュするため、AI エージェントとのやり取りがシームレスになります。

前提条件

始める前に、以下を用意してください：

Logto Cloud（または自己ホスト型 Logto v1.31 以上）のテナント
API アクセス権を持つサードパーティプロバイダーアカウント（例： Google Cloud Console）
Logto SDK と連携済みの AI エージェントアプリケーション（ユーザーが AI エージェントにサインインできること）

AI エージェントがサードパーティ API へアクセスできるようにするには、トークン保存を有効にしたソーシャルコネクターを設定する必要があります。これにより、ユーザーが AI エージェントとのやり取りの中でサードパーティサービスを認可 (Authorization) した際に、Logto がアクセストークン (Access token) を保存・管理できるようになります。

ここでは Google を例に説明します：

コンソール > コネクター > ソーシャルコネクターへ移動します。
ソーシャルコネクターを追加 をクリックし、Google を選択します。
Google コネクター設定ガイドに従って OAuth クライアント認証情報を設定します。
コネクター設定で以下を行います：
- 永続的な API アクセスのためにトークンを保存 を有効にし、トークンを Secret Vault に保存します。
- プロンプト に consent を含め、ユーザーに権限 (Permission) リクエスト画面を必ず表示します。
- オフラインアクセス を有効にし、長期間有効な API アクセス用のリフレッシュトークン (Refresh token) を受け取ります。
変更を保存します。

備考:

このコネクターをサインイン体験に追加する必要はありません。コネクターは、AI エージェントがサードパーティ API へアクセスする際のオンデマンド認可 (Authorization) 用に使用され、ユーザーのサインインには使いません。

認可 (Authorization) をリクエストしサードパーティ API へアクセスする

AI エージェントがサードパーティ API（例：Google Calendar）へアクセスする必要がある場合、まずユーザーがすでに認可 (Authorization) しているか確認します。未認可の場合は、ユーザーに認可 (Authorization) を促します。

アカウント API を有効化:

進める前に、コンソール > サインイン & アカウント > アカウントセンターで Account API を有効にしてください。 Account API の有効化方法もご参照ください。

ステップ 1: 既存の認可 (Authorization) を確認

まず、保存済みのアクセストークン (Access token) を取得し、ユーザーがすでに認可 (Authorization) しているか確認します：

async function getGoogleAccessToken(userAccessToken: string) {
  const response = await fetch(
    'https://[tenant-id].logto.app/my-account/identities/google/access-token',
    {
      headers: {
        Authorization: `Bearer ${userAccessToken}`,
      },
    }
  );

  return response.json();
}

ステップ 2: 必要に応じて認可 (Authorization) をリクエスト

トークンが存在しない場合や期限切れの場合、またはアクセストークン (Access token) のスコープを拡張したい場合は、Logto の Social Verification API を使って認可 (Authorization) フローを開始します：

async function requestGoogleAuthorization(userAccessToken: string, scopes: string) {
  // CSRF 対策のためランダムな state を生成
  const state = crypto.randomUUID();
  sessionStorage.setItem('oauth_state', state);

  // ソーシャル認証 (Authentication) を開始
  const response = await fetch('https://[tenant-id].logto.app/api/verification/social', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${userAccessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      connectorId: '<google_connector_id>',
      state,
      redirectUri: 'https://your-ai-agent.com/callback',
      scope: scopes,
    }),
  });

  const { verificationRecordId, authorizationUri } = await response.json();

  // verificationRecordId を後で使うため保存
  sessionStorage.setItem('verificationRecordId', verificationRecordId);

  // ユーザーを Google へリダイレクトし認可 (Authorization) を促す
  window.location.href = authorizationUri;
}

ステップ 3: 認可 (Authorization) コールバックの処理

ユーザーが権限 (Permission) を付与すると、Google からアプリへリダイレクトされます。認証 (Authentication) を完了し、トークンを保存します：

async function handleAuthorizationCallback(
  userAccessToken: string,
  callbackParams: URLSearchParams
) {
  const verificationRecordId = sessionStorage.getItem('verificationRecordId');
  const storedState = sessionStorage.getItem('oauth_state');
  const code = callbackParams.get('code');
  const state = callbackParams.get('state');

  // state を検証し CSRF 攻撃を防止
  if (state !== storedState) {
    throw new Error('Invalid state parameter');
  }

  // 認可 (Authorization) を検証
  await fetch('https://[tenant-id].logto.app/api/verification/social/verify', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${userAccessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      verificationRecordId,
      connectorData: {
        code,
        state,
        redirectUri: 'https://your-ai-agent.com/callback',
      },
    }),
  });

  // トークンを Logto の Secret Vault に保存
  await fetch('https://[tenant-id].logto.app/my-account/identities/google/access-token', {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${userAccessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      verificationRecordId,
    }),
  });

  // 後処理
  sessionStorage.removeItem('verificationRecordId');
  sessionStorage.removeItem('oauth_state');
}

ステップ 4: サードパーティ API を呼び出す

これで AI エージェントはトークンを取得し、API を呼び出せます：

async function addCalendarEvent(userAccessToken: string, eventDetails: EventDetails) {
  // 保存済みの Google アクセス トークン (Access token) を取得
  const tokenData = await getGoogleAccessToken(userAccessToken);

  if (!tokenData) {
    // ユーザーが未認可の場合、calendar スコープで認可 (Authorization) をリクエスト
    await requestGoogleAuthorization(
      userAccessToken,
      'https://www.googleapis.com/auth/calendar.events'
    );
    return; // リダイレクト後に続行
  }

  // Google Calendar API を呼び出す
  const response = await fetch('https://www.googleapis.com/calendar/v3/calendars/primary/events', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${tokenData.accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(eventDetails),
  });

  return response.json();
}

Logto はトークンの自動リフレッシュに対応しています。アクセストークン (Access token) が期限切れでもリフレッシュトークン (Refresh token) が存在すれば、取得エンドポイント呼び出し時に新しいアクセストークン (Access token) を自動で取得します。

追加の権限 (Permission) をリクエストする

AI エージェントがより多くのタスクを担う場合、追加の権限 (Permission) をリクエストする必要が出てきます。例えば、ユーザーが最初はカレンダーの読み取りのみを許可していたが、イベント作成も希望する場合は書き込み権限 (Permission) が必要です。

なぜ段階的な認可 (Authorization) が重要なのか

より良いユーザー体験：ユーザーは必要な理由が明確な場合、権限 (Permission) を承認しやすくなります。
高いコンバージョン率：最初に求める権限 (Permission) を最小限にすることで摩擦が減ります。
信頼構築：必要な権限 (Permission) のみを求めるアプリは信頼されやすいです。

例：読み取りから書き込み権限 (Permission) へのアップグレード

async function createCalendarEvent(userAccessToken: string, eventDetails: EventDetails) {
  const tokenData = await getGoogleAccessToken(userAccessToken);

  if (!tokenData) {
    // まだ認可 (Authorization) されていない場合、カレンダー書き込み権限 (Permission) を直接リクエスト
    await requestGoogleAuthorization(userAccessToken, 'https://www.googleapis.com/auth/calendar');
    return;
  }

  // イベント作成を試みる
  const response = await fetch('https://www.googleapis.com/calendar/v3/calendars/primary/events', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${tokenData.accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(eventDetails),
  });

  if (response.status === 403) {
    // 権限 (Permission) 不足の場合、追加スコープをリクエスト
    await requestGoogleAuthorization(
      userAccessToken,
      'https://www.googleapis.com/auth/calendar' // カレンダー全体アクセス
    );
    return;
  }

  return response.json();
}

ヒント:

追加スコープをリクエストする際、ユーザーには新たに必要な権限 (Permission) のみが同意画面 (Consent screen) に表示されます。既存の権限 (Permission) は保持されます。

トークンの状態を管理する

Logto コンソールでは、ユーザーごとのトークン状態を確認できます：

コンソール > ユーザー管理へ移動します。
ユーザーをクリックして詳細を表示します。
接続セクションまでスクロールし、連携済みソーシャルアカウントを確認します。
各接続のトークン状態は以下の通りです：
- アクティブ：アクセストークン (Access token) が有効で利用可能
- 期限切れ：アクセストークン (Access token) が期限切れ。リフレッシュトークン (Refresh token) があれば次回自動更新
- 非アクティブ：この接続に保存されたトークンなし

セキュリティのベストプラクティス

AI エージェントがサードパーティ API へアクセスする際は、以下のセキュリティ対策を心がけてください：

最小限のスコープ (Scope) をリクエスト：本当に必要な権限 (Permission) のみをリクエストしましょう。
段階的な認可 (Authorization) を活用：一度にすべての権限 (Permission) を求めず、必要なタイミングで追加リクエストしましょう。
トークンの期限切れを適切に処理：トークンが期限切れや無効化されるケースを常に考慮しましょう。
ユーザーのアクセストークン (Access token) を安全に管理：Logto のユーザーアクセストークン (Access token) はサードパーティトークン取得の鍵です。厳重に保護しましょう。
API アクセスの監査：AI エージェントがサードパーティ API へアクセスした際はログを残し、トラブルシューティングやコンプライアンスに備えましょう。

サードパーティトークン保存ソーシャルコネクターソーシャルサインイン Account API

なぜ AI エージェントにサードパーティ API アクセスが必要なのか​

仕組みの概要​

前提条件​

トークン保存付きソーシャルコネクターの設定​

認可 (Authorization) をリクエストしサードパーティ API へアクセスする​

ステップ 1: 既存の認可 (Authorization) を確認​

ステップ 2: 必要に応じて認可 (Authorization) をリクエスト​

ステップ 3: 認可 (Authorization) コールバックの処理​

ステップ 4: サードパーティ API を呼び出す​

追加の権限 (Permission) をリクエストする​

なぜ段階的な認可 (Authorization) が重要なのか​

例：読み取りから書き込み権限 (Permission) へのアップグレード​

トークンの状態を管理する​

セキュリティのベストプラクティス​

関連リソース​