來自 Foundry Agent Service 的安全 OpenAPI 工具呼叫

Foundry Agent Service 可以匿名或使用管理身份呼叫 App Service 的 OpenAPI 端點。 當 App Service 認證保護端點時，請使用管理身份。

此情境包含兩個獨立的管理身份指令：

• 當 App Service 呼叫 Foundry 時，呼叫者是 App Service 系統指派的管理身份。 對 Foundry 資源或專案設定的 Azure 角色型存取控制 (RBAC) 會授權該呼叫。
• 當 Foundry 呼叫 App Service OpenAPI 端點時，呼叫者是父 Foundry 資源系統指派的管理身份。 App Service 驗證權杖驗證與允許清單會授權該呼叫。

App Service 認證的 Microsoft Entra 應用程式是受保護的 API 資源。 它不會取代兩者中任何一方的呼叫端受控身分識別。

下表總結了此情境中的身份與應用。

先決條件

• 具有 OpenAPI 端點的 App Service 應用程式。 如果您需要將 OpenAPI 功能新增至應用程式，請參閱下列其中一個教學課程：

  • 在 Foundry Agent Service （.NET） 中新增一個 App Service 應用程式作為工具
  • 在 Foundry Agent Service（Java）中新增一個 App Service 應用程式作為工具
  • 在 Foundry Agent Service（Python）中新增一個 App Service 應用程式作為工具
  • 在 Foundry Agent Service （Node.js） 中新增 App Service 應用程式作為工具

• 這是一個 Microsoft Foundry 專案，你可以將應用程式加入為 OpenAPI 工具。

找出父層 Foundry 資源的受控識別碼

Foundry 代理服務在呼叫 OpenAPI 工具時，會使用 父 Foundry 資源系統 指派的管理身份。 它並未使用 Foundry 專案的管理身份來執行此請求。

你需要兩個識別碼來表示父資源身份：

• 應用程式識別碼（用戶端識別碼）： 會出現在存取權杖的 azp 聲明中，並用於 App Service 認證允許的客戶端應用程式檢查。
• 物件 (主體) 識別碼：顯示於權杖的 oid 宣告中，並在 App Service 驗證限制對特定身分識別的存取時使用。

1. 在 Foundry 入口網站中，開啟您的專案，然後在頂端功能表中選取 管理。

2. 在 Project 詳細資料中選擇父資源，然後選擇「在 Azure 開啟入口網站」。

3. 在 Foundry 資源左側選單中，選擇 資源管理>身份。

4. 在 [系統指派] 底下，複製 [物件 （主體） 識別碼] 的值以供稍後使用。

5. 在 Azure 入口網站中，搜尋並選取 Microsoft Entra ID。

6. 在搜尋方塊中，搜尋您複製的物件 ID，然後在搜尋結果中選取它。

7. 在 [ 概觀 ] 頁面上，複製 [應用程式識別碼] 的值。

   物件 ID 與系統指派受控識別中顯示的物件 ID 相同。 將應用程式 ID 和物件 ID 同時儲存，以便設定 App Service 認證。

設定應用程式的 Microsoft Entra 驗證

1. 在 Azure 入口網站中，流覽至您的 App Service 應用程式。

2. 在應用程式的左側功能表上，選取 [設定]>[驗證]，然後選取 [新增識別提供者]。

3. 在 [ 新增身分識別提供者 ] 頁面上，選取 [Microsoft ] 作為 身分識別提供者 ，以建立新的應用程式註冊。

4. 針對 [限制存取]，請選取 [需要驗證]。

5. 在 [其他檢查] 底下，針對 [用戶端應用程式需求]，選取 [允許來自特定用戶端應用程式的要求]。

6. 選擇鉛筆圖示並設定允許的用戶端應用程式：

   • 新增您在尋找父系 Foundry 資源的受控身分識別識別碼中複製的應用程式識別碼。 此識別碼允許父系 Foundry 資源身分識別要求的權杖。
   • 如果應用程式支援互動式瀏覽器登入，也請將 Microsoft Entra 應用程式本身的應用程式（用戶端）ID 加入 App Service 認證。 此識別碼允許使用者登入時向 Web 應用程式核發權杖。 如果你要建立新的應用程式註冊，請在建立身份提供者後再加入這個 ID。

7. 設定 身份要求：

   • 對於僅由 Foundry 呼叫的端點中最窄的政策，請選擇 「允許來自特定身份的請求」。 選擇鉛筆圖示，並新增父 Foundry 資源識別碼的 物件 ID。
   • 如果應用程式也支援互動式瀏覽器登入，請選擇 允許任何身份的請求 ，這樣租戶用戶就不會被封鎖。 此設定不允許匿名存取。 要求仍必須包含來自允許用戶端應用程式及已設定租用戶的有效權杖。

8. 在 租用戶需求 中，選取 僅允許來自簽發者租用戶的要求。 父系 Foundry 資源身分識別及任何登入的使用者都必須位於此租用戶中。

9. 設定 未認證請求：

   • 若應用程式僅支援 API 用戶端，請選擇 HTTP 401 未授權：推薦 API 使用。
   • 如果應用程式支援互動式瀏覽器登入，請選擇 HTTP 302 Found 重定向，然後選擇 Microsoft 作為重定向提供者。

10. 選取 [ 新增 ] 以建立身分識別提供者。

    下圖顯示 Foundry 專用的最精簡組態。

    

11. 如果應用程式支援互動式瀏覽器登入，請編輯提供者並確保 Token 儲存 已被啟用。 如果你建立了新的應用程式註冊，請將它的應用程式 ID 加入允許的客戶端應用程式。

當應用程式支援互動式瀏覽器登入時，你需要同時擁有兩個應用程式 ID。 僅限 Foundry 的 API 只需提供父系 Foundry 資源身分識別的應用程式識別碼。

更新應用程式註冊應用程式識別碼 URI

Application ID URI 將受保護的 API 識別為 OAuth 資源。 對於受控識別 OpenAPI 工具，其受眾必須與註冊於 App Service 驗證所使用的 Microsoft Entra 應用程式上的 Application ID URI 完全相符。 Foundry 在要求具有父系 Foundry 資源身分識別的存取權杖時，會使用該值做為對象。

應用程式 ID 與應用程式 ID URI 是不同的屬性：

• 應用程式 ID，也稱為用戶端 ID，是產生的 GUID。
• 應用程式識別碼 URI 是一種用來識別應用程式所擁有的 API 或資源的 URI。 它不一定要包含應用程式的客戶端 ID。

選擇一個穩定的應用程式 ID URI，並將其視為 API 合約的一部分：

該 URI 必須有效、在租戶內唯一，且被租戶的 Application ID URI 政策接受。 像 這樣的 some-random-string 純字串不是有效的應用程式 ID URI。

本指南使用完整的 HTTPS App Service 網址：

https://<app-name>.azurewebsites.net

1. Microsoft 提供者設定完成後，請在 [身分識別提供者] 資料行中選取它，以開啟應用程式註冊頁面。

2. 在左側功能表中，選取 [管理公開>API]。

3. 在 [應用程式識別碼 URI] 旁邊，選取 [編輯]。

4. 將值改為你 App Service 應用程式的完整 HTTPS URL，例如 https://<app-name>.azurewebsites.net。

   您可以在預設網域的「概觀」頁面中找到應用程式的主機名稱。

5. 新應用程式註冊時，請確保 存取權杖版本 設為 2。

6. 選取 [儲存]。

之後若要更改應用程式 ID URI，則需要更新 Foundry 工具的受眾以及所有其他請求 API 權杖的客戶端。

對應的 OpenAPI 工具認證設定如下：

{
  "type": "managed_identity",
  "security_scheme": {
    "audience": "https://<app-name>.azurewebsites.net"
  }
}

你不需要在 允許的代幣受眾下列出工具受眾。 App Service 認證會辨識您在 Microsoft Entra 應用程式中登錄的資源識別碼。 相反地，僅對允許的代幣受眾加值，則不會註冊 OAuth 資源，也無法讓 Microsoft Entra 為該資源發行代幣。

除非你也將該確切值設定為 Application ID URI，否則請勿使用 Foundry 專案端點或 App Service 用戶端 ID 作為受眾。 其他有效的應用程式識別碼URI格式，包括 api:// URI，只要註冊值與受眾完全匹配即可運作。 相關邊緣案例請參見 常見問題。

請以宣告式方式配置受保護的 API

使用 Bicep 來設定受保護的 API 和 App Service 認證政策。 以下模式假設：

• webApp 是 App Service 資源。
• entraApp 是一個可建立供 App Service 驗證使用的 Microsoft Entra 應用程式的模組。
• foundryAccountClientId 是父 Foundry 資源識別碼的應用程式 ID。
• appServiceAuthCredentialSettingName 是包含現有 App Service 認證客戶端秘密的應用程式設定名稱。

在 Microsoft Graph Bicep 應用程式模組中，將 App Service URL 設定為識別碼 URI，並要求第 2 版存取權杖：

extension microsoftGraphV1

param environmentName string
param appServiceUrl string

resource app 'Microsoft.Graph/applications@v1.0' = {
  uniqueName: 'my-app-${environmentName}'
  displayName: 'My app (${environmentName})'
  signInAudience: 'AzureADMyOrg'
  identifierUris: [
    appServiceUrl
  ]
  api: {
    requestedAccessTokenVersion: 2
  }
  web: {
    homePageUrl: appServiceUrl
    redirectUris: [
      '${appServiceUrl}/.auth/login/aad/callback'
    ]
  }
}

output clientId string = app.appId
output webAppUrl string = appServiceUrl

以下 authsettingsV2 範例允許互動式瀏覽器登入及 Foundry OpenAPI 呼叫：

@description('Parent Foundry resource identity application ID')
param foundryAccountClientId string = ''

resource webAppAuthSettings 'Microsoft.Web/sites/config@2024-11-01' = {
  name: '${webApp.name}/authsettingsV2'
  properties: {
    platform: {
      enabled: true
    }
    globalValidation: {
      requireAuthentication: true
      unauthenticatedClientAction: 'RedirectToLoginPage'
      redirectToProvider: 'azureActiveDirectory'
    }
    identityProviders: {
      azureActiveDirectory: {
        enabled: true
        registration: {
          clientId: entraApp.outputs.clientId
          clientSecretSettingName: appServiceAuthCredentialSettingName
          openIdIssuer: 'https://login.microsoftonline.com/${tenant().tenantId}/v2.0'
        }
        validation: {
          allowedAudiences: [
            'api://${entraApp.outputs.clientId}'
          ]
          defaultAuthorizationPolicy: {
            allowedApplications: concat(
              [
                entraApp.outputs.clientId
              ],
              empty(foundryAccountClientId) ? [] : [foundryAccountClientId]
            )
            allowedPrincipals: {}
          }
        }
      }
    }
    login: {
      tokenStore: {
        enabled: true
      }
    }
    httpSettings: {
      requireHttps: true
    }
  }
}

透過 Azure Developer CLI（AZD）傳遞 Foundry 資源身分識別應用程式 ID：

{
  "foundryAccountClientId": {
    "value": "${AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID=}"
  }
}

接著設定環境並重新部署：

azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
azd provision

在 Microsoft Foundry 中配置 OpenAPI 工具

1. 回到 Foundry 入口，選擇你的代理人。

2. 找到 OpenAPI 工具並選擇 ...>編輯。

3. 確認 OpenAPI 3.0+ 的結構 框是否包含你的 App Service 應用程式的架構。 如果沒有，就貼上你的 OpenAPI 架構。 欲了解更多資訊，請參閱 《如何與 Foundry Agent Service 使用 OpenAPI》。

4. 對於 認證方法，請選擇 管理身份。

5. 對於 Audience，請輸入你先前設定的 應用程式 ID URI 。 本指南中的設定，請使用您的 App Service 應用程式的完整 HTTPS URL，例如 https://<app-name>.azurewebsites.net。 數值必須完全一致。

6. 選擇 更新工具。

測試代理程式

1. 在 Foundry 入口中，選擇你的代理並選擇Try in playground。

2. 與代理程式聊天以測試您的 OpenAPI 端點。 例如：

   • 顯示所有任務。
   • 建立名為「購買雜貨」的工作。
   • 將該任務更新為“購買雜貨並做飯”。

如果你正確設定認證，代理程式會透過 OpenAPI 工具呼叫你應用程式的 API。

常見問題

為什麼我可以在設定 App Service 授權前先儲存 OpenAPI 工具？

當你儲存 OpenAPI 工具時，Foundry 會驗證其結構、受眾格式和定義。 它不會呼叫 App Service 端點。 因此，您可以先儲存該工具，再將父層 Foundry 資源識別新增至 App Service 的允許清單。

在測試區或執行階段叫用工具之前，請先設定允許清單。 在那之前，App Service 會拒絕工具呼叫。

為什麼預設 api://<client-id> 對象有時會失效？

App Service 入口網站通常會建立一個 Microsoft Entra 應用程式，並將 api://<application-client-id> 設為其 Application ID URI。 在這種情況下，Foundry 可以採用與其受眾相同的價值觀。

自訂或宣告式佈建可能會使 Microsoft Entra 應用程式的 identifierUris 集合保持空白，即使 App Service 驗證在 [允許的權杖對象] 底下顯示 api://<client-id> 亦然。 在這種情況下，Foundry 無法取得該值的管理身份令牌，因為它不是註冊的資源識別碼。

要解決這個問題，請使用以下選項之一：

• 將 api://<client-id> 註冊為 Application ID URI，並將其作為 Foundry 的受眾。
• 將 App Service 的 HTTPS URL 註冊為應用程式 ID URI，並以此 URL 作為 Foundry 受眾。

不要透過在 allowedAudiences 中加入任意字串來修正不一致。

App Service 認證可以在沒有 Application ID URI 的情況下運作嗎？

互動式瀏覽器登入可以在沒有應用程式 ID URI 的情況下運作，因為瀏覽器流程使用 ID 標記來設定網頁應用程式的客戶端 ID。

Foundry 的受控識別 OpenAPI 流程需要已註冊 API 資源的存取權杖。 在此流程中，設定一個應用程式 ID URI，並使用與工具受眾相同的值。

疑難排解驗證與授權

OpenAPI 工具接收 HTTP 401

HTTP 401 回應表示 App Service 認證無法驗證請求。 可能原因包括：

• 你沒有為 OpenAPI 工具選擇受管理身份。
• 受眾與 Microsoft Entra Application ID 的 URI 並不完全相符。
• 憑證發行者或租戶與 App Service 認證不符。
• 你沒有在 Microsoft Entra 應用程式上設定 Application ID URI。

確認 OpenAPI 受眾是否與已註冊的應用程式 ID URI 完全吻合。 本指南中的設定值是完整的 App Service HTTPS URL。

OpenAPI 工具接收 HTTP 403

HTTP 403 回應表示認證成功，但授權檢查拒絕呼叫者。 可能原因包括：

• 你把 Foundry 專案 的識別碼加入允許清單，而不是父 Foundry 資源 識別碼。
• 你輸入了物件 ID，而 App Service 認證需要應用程式 ID。
• 你尚未將父資源應用程式 ID 新增至 allowedApplications。
• 你未將父資源物件識別碼加入僅限 Foundry 的組態所允許的身分清單中。

檢查存取權杖宣告：

• azp 應等於父 Foundry 資源識別碼的應用程式 ID。
• oid 應等於父 Foundry 資源識別碼的物件 ID。

瀏覽器使用者登入後會收到 HTTP 403

對於支援互動式瀏覽器登入的應用程式，請檢查以下設定：

• 網頁應用程式自身的用戶端 ID 仍保留在 allowedApplications。
• 身分識別要求允許一般租用戶使用者。
• 未認證的瀏覽器請求使用 HTTP 302 而非 HTTP 401。

該工具可匿名運作，但啟用驗證後會失敗

將工具從 匿名 更新為 受控識別，將受眾設為已註冊的應用程式 ID URI，並允許父層 Foundry 資源的受控識別。

清理資源

當你刪除或替換此情境中的資源時：

• 刪除或替換 Foundry 資源時，請從 App Service 認證中移除父 Foundry 資源識別碼。
• 當您永久刪除 App Service 應用程式時，請刪除用於 App Service 驗證的 Microsoft Entra 應用程式。 此步驟同時避免了先前所述的孤兒應用程式識別碼 URI 風險。
• 如果你使用使用者指派的身份和聯邦身份憑證來進行無秘密的 App Service 認證，請刪除該應用程式中的該身份和聯邦憑證。

相關內容

• 設定您的 App Service 或 Azure Functions 應用程式以使用 Microsoft Entra 登入
• 將 AI 整合到 Azure App 服務 應用程式中
• 什麼是 Foundry Agent Service？ (部分內容可能是機器或 AI 翻譯)