附註
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
本文說明如何使用 Azure App 服務(又稱「Easy Auth」)內建的驗證功能,設定與 Azure Function 應用程式的索引器連線。Azure Function 應用程式是託管自訂 Web API 的絕佳解決方案,例如 Foundry IQ(Azure AI 搜尋服務)服務可用於豐富索引器執行期間匯入的內容,或者如果您使用自訂嵌入模型進行整合向量化,則可將搜尋查詢內容向量化。
您可以使用 Foundry IQ 服務的系統指派或使用者指派的管理身份,對 Azure Function 應用程式進行驗證。 此方法需要設定 Microsoft Entra ID 應用程式註冊,作為 Azure Function 應用程式的認證提供者,本文將詳細說明。
先決條件
- 您的 Foundry IQ 服務的 受控識別。
將 Microsoft Entra ID 應用程式設定為認證提供者
若要使用 Microsoft Entra ID 作為 Azure 函式應用程式的驗證提供者,則必須建立應用程式註冊。 有兩個選項:透過 Azure Function 應用程式自動建立,或使用現有應用程式。 想了解更多這些步驟,請參閱 App Service 文件。
無論採用哪種選項,請確保應用程式註冊依照下列步驟設定,以確保與 Foundry IQ 相容。
確定應用程式註冊已設定應用程式識別碼 URI
應用程式註冊應設定應用程式 ID URI,該 URI 可作為 Azure Function 應用程式與 Foundry IQ 的權杖受眾。 以格式 api://<applicationId> 進行設定。 這可以透過瀏覽至應用程式註冊的 [概觀] 區段並設定 [應用程式識別碼 URI] 欄位來完成。
設定受支援的帳戶類型以進行驗證
到應用程式註冊的 認證 區塊,設定 支援的帳號類型 ,讓只有與應用程式註冊相同組織目錄中的帳號才能使用該帳號進行驗證。
(選用) 定用戶端祕密
App Service 建議在認證提供者應用程式中使用客戶端秘密。 只要設定了委派權限,驗證仍可在沒有用戶端祕密的情況下運作。 若要設定用戶端祕密,請瀏覽至應用程式註冊的 [憑證和祕密] 區段,並依本文中的說明新增一個新的用戶端祕密。
新增範圍以委派權限
瀏覽至 [公開 API] 區段,並設定應用程式註冊,使其具有將系統管理員和使用者權限委派給它的範圍,以確保它與索引器的驗證流程相容。
設定委派的權限範圍之後,您應該會在應用程式註冊的 [API 權限] 區段中看到 Microsoft.Graph 上的 User.Read API 已設定。
在 Azure Function 應用程式中配置 Microsoft Entra ID 認證提供者
客戶端應用程式依先前規範註冊後,可以透過 App Service 文件設定 Azure Function 應用程式的 Microsoft Entra ID 認證。 瀏覽至 Azure 函式應用程式的 [驗證] 區段,以設定驗證詳細資料。
請確保已設定以下設定,以確保 Foundry IQ 能成功驗證至 Azure Function 應用程式。
設定驗證設定值
- 確保應用程式服務驗證為已啟用
- 將 Azure 函式應用程式的存取限制為需要驗證
- 針對未經驗證的要求,建議選擇 HTTP 401: 未授權
下列螢幕擷取畫面會醒目提示了範例 Azure 函式應用程式的這些特定設定。
新增 Microsoft Entra ID 驗證提供者
- 新增 Microsoft Entra ID 作為 Azure 函式應用程式的驗證提供者。
- 建立新的應用程式註冊,或選擇先前設定的應用程式註冊。 確保它依照本文件前一節的指引進行設定。
- 確定在 [允許的權杖對象] 區段中,已指定應用程式註冊的應用程式識別碼 URI。 它應該採用
api://<applicationId>格式,並且符合使用先前建立的應用程式註冊所設定的格式。 - 如果你願意,也可以設定其他檢查,專門限制索引器的存取權限。
設定其他檢查
- 請確保特定 Foundry IQ 服務身份的 物件(主體)ID 被指定為身份 要求,方法是勾選 「允許來自特定身份的請求 」選項,並在身份區段輸入 物件(主體)ID 。
- 在 用戶端應用程式需求中,選擇 「允許特定用戶端應用程式的請求」。 你需要查詢 Foundry IQ 服務身份的用戶端 ID。 若要這樣做,請複製上一個步驟中的物件 (主體) 識別碼,並在您的 Microsoft Entra ID 租用戶中查閱。 應該有一個相符的企業應用程式,其概觀頁面會列出應用程式識別碼,這是需要被指定為用戶端應用程式需求的 GUID。
附註
此步驟是 Azure 函式應用程式上最重要的設定,若執行錯誤可能導致索引器被禁止存取 Azure 函式應用程式。 確定您正確執行身分識別企業應用程式詳細資料的查閱,並在正確的位置指定應用程式識別碼和物件 (主體) 識別碼。
- 對於租用戶需求,請選擇與您的安全性態勢相符的任何選項。 欲了解更多資訊,請參閱 App Service 文件。
建立與 Azure Function app 的連接
根據是否需要在自訂 Web API 技能或自訂 Web API 向量化工具中建立與 Azure 函式應用程式的連線,JSON 定義略有不同。 在這兩種情況下,請確定您為 Azure 函式應用程式指定正確的 URI,並將 authResourceId 設定為與針對驗證提供者所設定的 [允許的權杖對象] 相同的值。
根據你選擇使用系統指定的身份還是使用者指定的身份連接,所需的屬性會略有不同。
使用系統指派的身分識別
以下是一個呼叫以範例 Azure Function 應用程式命名test的函式範例,其中允許系統指派的 Foundry IQ 服務身份透過「Easy Auth」進行驗證。
"uri": "https://contoso-function-app.azurewebsites.net/api/test?",
"authResourceId": "api://00000000-0000-0000-0000-000000000000"
使用使用者指派的身分識別
這裡有一個範例,可以呼叫同一個函式,允許特定使用者指派的身份透過「Easy Authorization」進行認證。 你需要在組態的 identity 屬性中,指定要使用的特定使用者指派身分識別之資源識別碼。
"uri": "https://contoso-function-app.azurewebsites.net/api/test?",
"authResourceId": "api://00000000-0000-0000-0000-000000000000",
"identity" : {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]"
}
附註
在自訂 Web API 技能或向量器定義中指定使用者指派身份之前,請先將該身份指派給 Foundry IQ 服務。
執行索引器/向量化工具來驗證權限
對於自訂 Web API 技能,權限會在索引器執行階段期間進行驗證。 對於向量化器來說,當使用自訂網頁 API 向量化器發出向量查詢時,這些向量會被驗證。 若要排除驗證的任何特定問題,您可以在 Azure 函式應用程式上停用驗證提供者,並確保來自索引器/向量化工具的呼叫成功,藉此進行測試。
- 如果驗證問題持續存在,請確保在 Azure Function 應用程式的驗證提供者中指定正確的身份資訊——也就是應用程式 ID、Foundry IQ 服務身份的物件(主體)ID。