啟用第三方 AI agent 存取你的應用程式

本指南將帶你整合 Logto 與你的服務，並啟用 AI agent 存取該服務。

你將學會：

• 將 Logto 設定為你的服務的授權 (Authorization) 伺服器。
• 取得 AI agent 存取你服務所需的存取權杖 (Access token)。
• 使用 AI agent 測試整個流程。

第三方 AI agent 與你自己的 AI agent（或應用程式）的差異

讓我們來看一個例子。假設你是一位開發者，經營一個提供天氣資料的服務。

官方天氣應用程式（你自己的 AI agent / 應用程式）

• 你提供一個官方天氣應用程式，讓使用者查詢天氣。
• 運作方式：官方天氣應用程式透過 Logto 連接你的服務並驗證 (Authentication) 使用者。當 Alice 登入時，她會自動取得天氣資料的存取權，不需要額外的授權頁面，因為這是你信任的應用程式。

第三方 AI agent

• 你希望圍繞你的服務建立生態系，因此另一位開發者建立了「WeatherBot」（一個能提供天氣更新與預報的 AI 助理），並將其作為第三方 AI agent 整合進來。
• 運作方式：WeatherBot（第三方 AI agent）希望透過你的服務存取使用者的天氣資料。當 Alice 使用她的帳號登入 WeatherBot 時：
  • 她會看到一個使用者授權頁面 (Consent screen)，詢問是否允許 WeatherBot 存取她的天氣資料。
  • Alice 可以允許或拒絕這個存取。
  • 只有她同意分享的資料會提供給 WeatherBot，WeatherBot 無法在未經明確同意的情況下存取其他資料。

這種存取（權限）控制確保了使用者資料的安全，即使你的服務管理所有資料，像 WeatherBot 這樣的第三方 AI agent 也只能存取使用者明確允許的內容。他們無法繞過這個流程，因為這是由你在服務中實作的存取控制所強制執行的。

總結

用戶端類型	範例	需要授權頁面？	誰控制？
官方天氣應用程式	你自己的天氣應用程式	否	你（開發者）
第三方 AI agent	WeatherBot 助理	是	其他開發者

備註:

如果你想將服務整合到你自己的 AI agent 或應用程式，請參考我們的 快速入門指南 以獲得更多資訊。

先決條件

• 一個 Logto Cloud（或自架）租戶
• 一個對 AI agent 開放 API 端點的服務

流程說明

• 服務 (Service)：你希望讓 AI agent 存取的服務。
• AI agent：將要存取你服務的 AI agent。
• Logto：作為 OpenID Connect 提供者（授權 (Authorization) 伺服器），管理使用者身分。

以下是一個非標準的時序圖，說明整體流程：

設定第三方 AI agent

要讓第三方 AI agent 存取你的服務，請依照下列步驟操作：

1. 在 Logto 註冊 AI agent：在 Logto 中建立一個應用程式來代表該 AI agent。
2. 設定 AI agent：確保 AI agent 能向你的服務發送請求，並正確處理 401 Unauthorized 回應。
3. 實作授權 (Authorization) 流程：AI agent 應能處理 OAuth 2.0 授權流程，從 Logto 取得存取權杖 (Access token)。
4. 測試整合：使用 AI agent 存取你的服務，確認其能成功驗證 (Authentication) 並授權 (Authorization) 請求。

在 Logto 設定第三方 AI agent

若要讓第三方 AI agent 存取你的 服務，你需要在 Logto 中建立一個第三方應用程式（third-party app）。這個應用程式將代表 AI agent 並取得驗證 (Authentication) 與授權 (Authorization) 所需的憑證。

什麼是第三方應用程式？:

第三方應用程式（third-party app） 是由外部開發者（非資源擁有者）建立的應用程式，需經使用者同意才能存取受保護資源。與第一方應用程式（你自己的應用程式）不同，第三方應用程式會顯示使用者授權頁面（consent screen），要求使用者核准特定權限後才能存取其資料。這確保使用者能掌控與外部服務分享哪些資料。

想了解更多，請參閱 第三方應用程式。

允許開發者在 Logto 建立第三方應用程式

如果你正在打造市集或希望開發者能在 Logto 建立第三方應用程式，可以利用 Logto Management API 以程式化方式建立第三方應用程式。這讓開發者能註冊他們的應用程式並取得驗證所需的憑證。

你需要自行架設服務來處理 client 註冊流程。該服務會與 Logto Management API 互動，代表開發者建立第三方應用程式。

你也可以在 Logto Console 手動建立第三方應用程式，以熟悉整個流程。

在 Logto 手動建立第三方應用程式

你可以在 Logto Console 手動建立第三方應用程式，用於測試或臨時整合。這在你想快速測試整合而不需實作完整 client 註冊流程時特別有用。

1. 登入你的 Logto Console。

2. 前往 應用程式 (Applications) → 建立應用程式 (Create application) → 第三方應用程式 (Third-party app) -> OIDC。

3. 填寫應用程式名稱及其他必要欄位，然後點擊 建立應用程式 (Create application)。

4. 點擊 權限 (Permissions) 分頁，在 使用者 (User) 區塊點擊「新增 (Add)」。

5. 在開啟的對話框中 -> 使用者資料 (User data) -> 選擇 profile、email 權限，然後點擊 儲存 (Save)。

6. 在第三方應用程式中，設定 scopes 以請求 openid profile email 權限（scopes）。

   注意：openid 為 OIDC 必填，profile 與 email 則是你在前一步新增的權限。

7. 根據需求設定你的第三方應用程式的 redirect URI，並記得在 Logto 中同步更新 redirect URI。

---

在底層，第三方應用程式是一個標準的 OAuth 2.0 / OIDC 用戶端。這表示你（或第三方開發者）可以使用任何 OAuth 2.0 / OIDC 函式庫或框架來整合 Logto。

幾點注意事項：

1. 建立第三方應用程式時，請根據應用架構選擇合適的應用程式類型：
   • 傳統網頁 (Traditional web)：使用 client secret 進行驗證。
   • 單頁應用程式 / 原生應用程式 (Single page app / Native)：使用 PKCE 進行安全授權，無需 client secret。
2. 我們的大多數快速入門指南是針對第一方應用程式撰寫，但你仍可將其作為第三方應用程式整合的參考。
3. 主要差異在於第三方應用程式會顯示使用者授權頁面 (Consent screen)，請求使用者明確授權存取其資料。

完整整合指南請參閱 第三方應用程式 (Third-party applications)。

在你的服務中設定授權 (Authorization)

要在你的服務中啟用存取控制，請實作下列內容：

1. 在 Logto 定義 API 資源：在 Logto 中建立代表 AI agent 將要存取之端點的 API 資源。
2. 實作存取控制邏輯：在你的服務中，實作邏輯以驗證從 AI agent 收到的存取權杖 (Access token)，並檢查使用者是否有權存取所請求的資源。
3. 回應 AI agent：如果存取權杖有效且使用者有權限，則回傳所請求的資源；否則回傳 401 Unauthorized 回應。

想進一步瞭解如何在服務中實作存取控制，請參考我們的 授權 (Authorization) 指南。

測試整合

1. 啟動你的服務。
2. 啟動 AI agent。
3. 在 AI agent 中呼叫 API 端點以存取你的服務。
4. AI agent 應能處理 401 Unauthorized 回應並將使用者導向 Logto 進行驗證 (Authentication)。
5. 驗證成功後，AI agent 應收到存取權杖 (Access token)，並用它向你的服務發送請求。
6. AI agent 應能使用存取權杖從你的服務取得資源。