Mettere in sicurezza le chiamate agli strumenti OpenAPI dal servizio Agente Foundry

Foundry Agent Service può chiamare un endpoint OpenAPI di App Service in modo anonimo o con identità gestita. Usa l'identità gestita quando l'autenticazione App Service protegge l'endpoint.

Questo scenario contiene due direzioni indipendenti di identità gestita:

• Quando App Service chiama Foundry, il chiamante è l'identità gestita assegnata al sistema App Service. Il controllo di accesso basato sul ruolo (RBAC) di Azure sulla risorsa o progetto Foundry autorizza la chiamata.
• Quando Foundry chiama l'endpoint App Service OpenAPI, il chiamante è l'identità gestita assegnata dal sistema di risorse Foundry madre. La convalida dei token di autenticazione di App Service e le liste di elementi consentiti autorizzano la chiamata.

L'applicazione Microsoft Entra per autenticazione App Service è la risorsa API protetta. Non sostituisce nessuna delle due, incluso l'uso dell'identità gestita.

La tabella seguente riassume le identità e le applicazioni in questo scenario.

Prerequisiti

• Un'app di App Service con endpoint OpenAPI. Se è necessario aggiungere funzionalità OpenAPI all'app, vedere una delle esercitazioni seguenti:

  • Aggiungere un'app del Servizio app di Azure come strumento nel Servizio Agente Fonderia (.NET)
  • Aggiungere un'app di App Service come uno strumento in Foundry Agent Service (Java)
  • Aggiungere un'app di App Service come strumento in Foundry Agent Service (Python)
  • Aggiungere un'app del Servizio app di Azure come strumento nel Servizio Agente Fonderia (Node.js)

• Un progetto Microsoft Foundry in cui aggiungi la tua app come strumento OpenAPI.

Trova gli ID di identità gestiti della risorsa Foundry madre

Foundry Agent Service utilizza l'identità gestita assegnata dal sistema della risorsa madre quando chiama uno strumento OpenAPI. Non utilizza l'identità gestita del progetto Foundry per questa richiesta.

Servono due identificatori per l'identità della risorsa genitore:

• ID applicazione (ID client): Compare nel claim azp del token di accesso e viene utilizzato per la verifica delle applicazioni client consentite per l'autenticazione di App Service.
• ID oggetto (principale): Appare nella rivendicazione del oid token ed è utilizzato quando l'autenticazione tramite App Service limita l'accesso a identità specifiche.

1. Nel portale Foundry, apri il tuo progetto e poi seleziona Gestisci nel menu in alto.

2. Seleziona la risorsa principale nei dettagli di Project, poi seleziona Apri in Azure portal.

3. Nel menu a sinistra della risorsa Foundry, selezionare Gestione delle Risorse>Identità.

4. In Sistema assegnato, copiare il valore di ID (entità di sicurezza) oggetto per utilizzarlo in seguito.

5. Nel portale di Azure cercare e selezionare Microsoft Entra ID.

6. Nella casella di ricerca cercare l'ID oggetto copiato e selezionarlo nei risultati della ricerca.

7. Nella pagina Panoramica copiare il valore di ID applicazione.

   L'ID dell'oggetto è lo stesso indicato per l'identità gestita assegnata al sistema. Salva sia l'ID dell'applicazione che l'ID dell'oggetto per configurare l'autenticazione degli App Service.

Configurare l'autenticazione di Microsoft Entra per l'app

1. Nel portale di Azure, vai alla tua app di App Service.

2. Nel menu a sinistra dell'app, selezionare Impostazioni>Autenticazione, quindi selezionare Aggiungi provider di identità.

3. Nella pagina Aggiungi provider di identità selezionare Microsoft come provider di identità per creare una nuova registrazione dell'app.

4. Per Limita l'accesso selezionare Richiedi autenticazione.

5. In Controlli aggiuntivi, per Requisito dell'applicazione client, selezionare Consenti richieste da applicazioni client specifiche.

6. Seleziona l'icona a matita e configura le applicazioni client consentite:

   • Aggiungi l'ID dell'applicazione che hai copiato negli ID di identità gestite della risorsa Foundry di Trova la risorsa madre. Questo ID consente i token richiesti dall'identità della risorsa Foundry principale.
   • Se l'app supporta l'accesso interattivo tramite browser, aggiungi anche l'ID applicazione (client) dell'applicazione Microsoft Entra di autenticazione di App Service. Questo ID consente di emettere token all'applicazione web durante l'accesso dell'utente. Se stai creando una nuova registrazione dell'app, aggiungi questo ID dopo aver creato il provider di identità.

7. Configura il requisito di identità:

   • Per la policy più ristretta su un endpoint chiamato solo da Foundry, seleziona Consenti richieste da identità specifiche. Seleziona l'icona a matita e aggiungi l'ID dell'oggetto dell'identità della risorsa Foundry principale.
   • Se l'app supporta anche l'accesso interattivo del browser, seleziona Consenti richieste da qualsiasi identità così che gli utenti tenant non vengano bloccati. Questa impostazione non consente l'accesso anonimo. Le richieste devono ancora contenere un token valido da un'applicazione client consentita e dal tenant configurato.

8. Per Requisito tenant, selezionare Consenti richieste solo dal tenant emittente. L'identità della risorsa Foundry principale e tutti gli utenti che effettuano l'accesso devono trovarsi in questo tenant.

9. Configura le richieste non autenticate:

   • Se l'app serve solo client API, seleziona HTTP 401 Non autorizzato: raccomandato per le API.
   • Se l'app supporta l'accesso interattivo al browser, seleziona HTTP 302 Found redirect, e poi seleziona Microsoft come fornitore di reindirizzamento.

10. Selezionare Aggiungi per creare il fornitore di identità.

    L'immagine seguente mostra la configurazione esclusiva di Foundry più limitata.

    

11. Se l'app supporta l'accesso interattivo del browser, modifica il provider e assicurati che il Token Store sia abilitato. Se hai creato una nuova registrazione di un'app, aggiungi il suo ID applicazione alle applicazioni client consentite.

Servono entrambi gli ID dell'applicazione quando l'app supporta l'accesso interattivo del browser. Un'API esclusiva di Foundry richiede solo l'ID dell'applicazione dell'identità della risorsa Foundry padre.

Aggiornare l'URI dell'ID applicazione di registrazione dell'app

Un URI di ID applicazione identifica l'API protetta come una risorsa OAuth. Per uno strumento OpenAPI con identità gestita, l'audience deve corrispondere esattamente a un URI ID applicazione registrato nell'applicazione Microsoft Entra usata per l'autenticazione di App Service. Foundry usa tale valore come destinatario quando richiede un token di accesso con l'identità della risorsa Foundry padre.

L'ID applicazione e l'URI dell'ID applicazione sono proprietà diverse:

• L'ID dell'applicazione, chiamato anche ID client, è un GUID generato.
• Un URI ID applicazione è un URI che identifica un'API o una risorsa di proprietà dell'applicazione. Non deve per forza contenere l'ID client dell'applicazione.

Scegli un URI applicativo stabile e trattalo come parte del contratto API:

L'URI deve essere valido, univoco nel tenant e conforme ai criteri dell'Application ID URI del tenant. Una stringa semplice come some-random-string non è un URI valido dell'ID applicazione.

Questa guida utilizza l'URL completo del servizio HTTPS:

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

1. Al termine della configurazione del provider Microsoft, selezionarlo nella colonna Provider di identità per aprire la pagina di registrazione dell'app.

2. Nel menu a sinistra selezionare Gestisci>Esporre un'API.

3. Accanto a URI ID applicazione selezionare Modifica.

4. Modifica il valore impostandolo sull'URL HTTPS completo della tua app di App Service, ad esempio https://<app-name>.azurewebsites.net.

   È possibile trovare il nome host dell'app nella pagina Panoramica in Dominio predefinito.

5. Per una nuova registrazione dell'app, assicurati che la versione del token Access sia impostata su 2.

6. Seleziona Salva.

Modificare successivamente l'URI dell'ID dell'applicazione richiede di aggiornare il pubblico dello strumento Foundry e tutti gli altri client che richiedono token per l'API.

La corrispondente configurazione di autenticazione dello strumento OpenAPI è:

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

Non è necessario elencare i destinatari dello strumento in Destinatari token consentiti. L'autenticazione tramite App Service riconosce gli identificatori di risorse che registri nella sua applicazione Microsoft Entra. Al contrario, aggiungere un valore solo in Destinatari dei token consentiti non registra una risorsa OAuth né consente a Microsoft Entra di emettere un token per essa.

Non usare l'endpoint del progetto Foundry o l'ID client di App Service come destinatario, a meno che tu non configuri anche quel valore esatto come URI ID applicazione. Altri formati URI validi per l'ID applicazione, inclusi gli URI api://, funzionano quando il valore registrato e il destinatario corrispondono esattamente. Per casi limite correlati, vedi Domande frequenti.

Configura l'API protetta in modo dichiarativo

Usa Bicep per configurare l'API protetta e la policy di autenticazione dei servizi applicativi. Il seguente schema presume:

• webApp è la risorsa del Servizio App.
• entraAppè un modulo che crea l'applicazione di autenticazione App Service Microsoft Entra.
• foundryAccountClientId è l'ID applicazione dell'identità della risorsa Foundry principale.
• appServiceAuthCredentialSettingName è il nome dell'impostazione dell'app che contiene il client secret di autenticazione dell'App Service esistente.

Nel modulo applicativo Microsoft Graph Bicep, configura l'URL del servizio App come URI identificativo e richiedi token di accesso versione 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

Il seguente authsettingsV2 esempio consente sia l'accesso interattivo del browser sia le chiamate 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
    }
  }
}

Passa l'ID dell'applicazione dell'identità della risorsa Foundry tramite Azure Developer CLI (AZD):

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

Poi configura l'ambiente e ridistribuisci:

azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
azd provision

Configurare lo strumento OpenAPI in Microsoft Foundry

1. Torna al portale Foundry e seleziona l'agente.

2. Trovare lo strumento OpenAPI e selezionare ...>Modifica.

3. Verifica che la casella dello schema OpenAPI 3.0+ contenga lo schema della tua app App Service. Se non lo fa, incolla il tuo schema OpenAPI. Per altre informazioni, vedere Come usare OpenAPI con il servizio agente Foundry.

4. Per Metodo di autenticazione selezionare Identità gestita.

5. Per Audience, inserisci l'URI dell'ID applicazione che hai configurato in precedenza. Per la configurazione in questa guida, usa l'URL HTTPS completo della tua app App Service, come https://<app-name>.azurewebsites.net. I valori devono corrispondere esattamente.

6. Selezionare Strumento di aggiornamento.

Testare l'agente

1. Nel portale di Foundry selezionare l'agente e selezionare Prova nel playground.

2. Chattare con l'agente per testare gli endpoint OpenAPI. Per esempio:

   • Mostra tutte le attività.
   • Creare un'attività denominata "Acquista generi alimentari".
   • Aggiorna l'attività a "Acquistare generi alimentari e cucinare la cena".

Se configuri correttamente l'autenticazione, l'agente chiama le API della tua app tramite lo strumento OpenAPI.

Domande frequenti

Perché posso salvare lo strumento OpenAPI prima di configurare l'autorizzazione dei servizi App?

Quando salvi uno strumento OpenAPI, Foundry ne valida lo schema, il formato del pubblico e la definizione. Non chiama l'endpoint di App Service. Puoi quindi salvare lo strumento prima di aggiungere l'identità della risorsa Foundry madre alla lista dei permessi del servizio App.

Configura la lista dei permessi prima di invocare lo strumento nel playground o in runtime. Fino ad allora, App Service rifiuta le chiamate agli strumenti.

Perché a volte il pubblico predefinito api://<client-id> fallisce?

Il portale App Service crea comunemente un'applicazione Microsoft Entra con api://<application-client-id> come URI dell'ID applicazione. In tal caso, Foundry può utilizzare lo stesso valore del suo pubblico.

Il provisioning personalizzato o dichiarativo può lasciare vuota la raccolta identifierUris dell'applicazione Microsoft Entra anche quando l'autenticazione di App Service mostra api://<client-id> in Destinatari di token consentiti. In quello stato, Foundry non può ottenere un token di identità gestita per il valore perché non è un identificatore di risorsa registrato.

Per risolvere il problema, usa una di queste opzioni:

• Registra api://<client-id> come URI ID applicazione e usalo come audience di Foundry.
• Registrare l'URL HTTPS di App Service come URI ID applicazione e usare tale URL come audience di Foundry.

Non correggere la discrepanza aggiungendo stringhe arbitrarie a allowedAudiences.

L'autenticazione App Service può funzionare senza un URI dell'ID applicazione?

L'accesso interattivo del browser può funzionare senza un URI dell'ID dell'applicazione perché il flusso del browser utilizza un token ID per l'ID client dell'applicazione web.

Il flusso OpenAPI dell'identità gestita da Foundry necessita di un token di accesso per una risorsa API registrata. Per questo flusso, configura un URI dell'ID applicazione e usa lo stesso valore del pubblico dello strumento.

Risoluzione di problemi nell'autenticazione e autorizzazione

Lo strumento OpenAPI riceve HTTP 401

Una risposta HTTP 401 significa che l'autenticazione tramite App Service non ha potuto autenticare la richiesta. Le cause probabili includono:

• Non hai selezionato l'identità gestita per lo strumento OpenAPI.
• Il destinatario non corrisponde esattamente all'URI dell'ID applicazione di Microsoft Entra.
• L'emittente o il tenant del token non corrisponde all'autenticazione di App Service.
• Non hai configurato l'URI dell'ID applicazione sull'applicazione Microsoft Entra.

Verifica che il destinatario OpenAPI corrisponda esattamente a un URI ID dell'applicazione registrato. Per la configurazione in questa guida, il valore è l'URL HTTPS completo del servizio App.

Lo strumento OpenAPI riceve HTTP 403

Una risposta HTTP 403 significa che l'autenticazione è andata a buon fine, ma i controlli di autorizzazione hanno rifiutato il chiamante. Le cause probabili includono:

• Hai aggiunto l'identità del progetto Foundry all'elenco degli elementi consentiti invece che l'identità della risorsa Foundry padre.
• Hai inserito l'ID oggetto dove l'autenticazione tramite App Service richiede un ID applicazione.
• Non hai aggiunto l'ID dell'applicazione della risorsa genitore a allowedApplications.
• Non hai aggiunto l'ID dell'oggetto risorsa padre all'elenco delle identità consentite per una configurazione esclusiva di Foundry.

Ispeziona le richieste del token di accesso:

• azp dovrebbe essere uguale all'ID dell'applicazione dell'identità della risorsa Foundry principale.
• oid dovrebbe essere uguale all'ID dell'oggetto dell'identità della risorsa Foundry principale.

Gli utenti del browser ricevono HTTP 403 dopo l'accesso

Per un'app che supporta l'accesso interattivo al browser, verifica queste impostazioni:

• L'ID client dell'app web rimane in allowedApplications.
• Il requisito di identità consente utenti normali del tenant.
• Le richieste del browser non autenticate utilizzano HTTP 302 invece di HTTP 401.

Lo strumento funziona in modo anonimo ma fallisce dopo l'attivazione dell'autenticazione

Aggiorna lo strumento da Anonimo a Identità gestita, imposta il destinatario su un URI dell’ID applicazione registrato e consenti l’identità della risorsa Foundry padre.

Pulire le risorse

Quando elimini o sostituisci risorse da questo scenario:

• Rimuovi l'identità della risorsa Foundry madre dall'autenticazione dei servizi App quando elimini o sostituisci la risorsa Foundry.
• Elimina l'applicazione di Microsoft Entra usata per l'autenticazione di App Service quando elimini definitivamente l'app di App Service. Questo passaggio previene anche il rischio di Application ID URI orfano descritto in precedenza.
• Se si usa un'identità assegnata dall'utente e una credenziale di identità federata per l'autenticazione di App Service senza segreti, eliminare tale identità e la credenziale federata insieme all'app.

Contenuti correlati

• Configura il servizio app o l'app Funzioni di Azure per accedere con Microsoft Entra
• Integrare l'intelligenza artificiale nelle applicazioni del servizio app di Azure
• Che cos'è il Servizio Agente Fonderia?