Autorizzazione dell'endpoint dell'agente in Microsoft Foundry

L'autorizzazione dell'endpoint agente determina se un chiamante può interagire con un agente in fase di esecuzione nel servizio agente Foundry. L'accesso alla gestione controlla invece chi può creare, configurare, aggiornare o eliminare agenti e altre risorse nel progetto Foundry. Un principal può essere autorizzato a chiamare un singolo agente senza ricevere l'autorizzazione per gestire tale agente o il relativo progetto. Per l'accesso alla gestione di Foundry, vedere Autenticazione e autorizzazione in Microsoft Foundry e il controllo degli accessi in base al ruolo in Foundry.

Usare questo articolo per scegliere il modo in cui i chiamanti eseguono l'autenticazione e ottengono l'accesso a un endpoint agente. Per applicare queste impostazioni, vedere Configurare l'autorizzazione dell'endpoint dell'agente. Per comprendere in che modo l'accesso agli endpoint è correlato alle identità usate da un agente per strumenti e risorse, vedere Identità e accesso in Agent Service.

Limite di accesso agli endpoint

Un endpoint agente è l'URL stabile usato da client e canali per chiamare un agente. L'endpoint può esporre più protocolli, ma la configurazione di autorizzazione si applica al confine tra chiamante e agente.

L'autorizzazione a questo confine risponde a due domande:

  • Quale identità o canale attendibile rappresenta la richiesta?
  • Quale autorizzazione consente a tale identità o canale di chiamare l'agente?

Confrontare gli schemi di autorizzazione degli endpoint

Uno schema di autorizzazione dell'endpoint definisce il modo in cui Foundry convalida una richiesta in ingresso e decide se il chiamante può interagire con l'agente. È possibile configurare più configurazioni su un endpoint. Ad esempio, un endpoint può accettare sia client diretti Azure autorizzati dal controllo degli accessi in base al ruolo sia client diretti autorizzati dal blueprint dell'agente, insieme a uno schema di servizio Bot per Microsoft Teams o Microsoft 365.

Scheme Come viene deciso l'accesso Uso tipico
AzureRbac o il relativo Entra alias1 Il chiamante presenta un token per la risorsa Foundry e il controllo degli accessi in base al ruolo di Azure (RBAC) determina se l'entità rappresentata può accedere all'agente. Applicazioni, SDK, client REST, strumenti di sviluppo e client workload che utilizzano l'accesso a Foundry.
AgentBlueprint (anteprima) Il chiamante presenta un token per il blueprint dell'agente dell'agente e l'endpoint applica le regole di convalida dei token dello schema. Applicazioni che richiedono l'accesso a singoli agenti senza concedere al chiamante le autorizzazioni RBAC di Foundry.
BotServiceRbac 2 Azure servizio Bot valida la richiesta del canale e Azure RBAC determina se l'utente connesso ha accesso. Microsoft Teams e canali Microsoft 365 in cui ogni utente necessita dell'autorizzazione Azure applicabile.
BotServiceTenant 2 Azure servizio Bot convalida la richiesta del canale e limita l'accesso agli utenti connessi nel tenant configurato. Canali di Microsoft Teams e Microsoft 365 destinati all'accesso a livello di tenant.
BotService 2 Azure servizio Bot convalida la richiesta di canale senza una regola di autorizzazione utente aggiuntiva. Solo per compatibilità legacy. Per i nuovi agenti, usare BotServiceRbac o BotServiceTenant.

1AzureRbac è il nome corrente per lo schema di autorizzazione esistente Entra . Il nuovo nome distingue il comportamento di autorizzazione del controllo degli accessi in base al ruolo Azure da altri schemi che usano anche l'autenticazione Microsoft Entra. Le configurazioni esistenti che usano Entra rimangono supportate, ma non configurare entrambi gli alias nello stesso endpoint.

2 È possibile configurare solo uno di BotService, BotServiceRbace BotServiceTenant alla volta.

Le chiavi API non sono supportate per gli endpoint dell'agente. Configurare gli schemi di autorizzazione nell'endpoint dell'agente e assegnare i ruoli di Azure necessari nell'ambito del progetto o dell'agente.

accesso all'endpoint Microsoft Entra

Sia AzureRbac che AgentBlueprint usano Microsoft Entra per autenticare il chiamante. Differiscono in base alla risorsa di destinazione del token e al modo in cui l'endpoint autorizza l'accesso dopo l'autenticazione. Un token di accesso Microsoft Entra contiene un'attestazione 'audience' (aud) che identifica la risorsa per cui è stato rilasciato il token. Ogni schema accetta un'audience del token diversa e applica una regola di autorizzazione diversa:

  • AzureRbac accetta i token rilasciati per la risorsa Foundry (https://ai.azure.com) e applica Azure RBAC.
  • AgentBlueprint accetta i token rilasciati per il blueprint dell'agente del singolo agente e applica le regole di convalida dei token configurate in tale schema.

È possibile configurare entrambe le configurazioni nello stesso punto finale. L'audience del token di richiesta determina quale schema configurato può autorizzare la richiesta.

schema RBAC di Azure

Il protocollo AzureRbac è l'impostazione predefinita per un endpoint dell'agente. Il client richiede un token per la risorsa Foundry, identificata da https://ai.azure.com. Il chiamante deve inoltre disporre dell'autorizzazione Microsoft.CognitiveServices/accounts/AIServices/endpoints/interact/action a livello di progetto Foundry o di singolo agente. Foundry Agent Consumer è il ruolo predefinito con privilegi minimi consigliati per questa autorizzazione. Foundry User comprende anche l'autorizzazione, ma concede privilegi aggiuntivi per creare e gestire gli agenti nel progetto.

Importante

I ruoli RBAC di Foundry sono stati recentemente rinominati. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager erano precedentemente denominati Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. È possibile che i nomi precedenti vengano visualizzati in alcune posizioni durante l'esecuzione della ridenominazione. Gli ID ruolo e le autorizzazioni di base sono invariati dalla ridenominazione.

Usare un'assegnazione con ambito agente quando un principal deve chiamare un agente senza ricevere un accesso più ampio al progetto. Le assegnazioni di ruolo con ambito agente vengono valutate per l'accesso agli endpoint agente e non concedono autorizzazioni del piano di controllo o di gestione più ampie.

Il nome dello schema precedente Entra ha lo stesso comportamento di runtime di AzureRbac. Usare AzureRbac per le nuove configurazioni e conservare Entra solo quando è necessaria la compatibilità con una configurazione o una libreria client esistente.

Schema dell'agente (anteprima)

La AgentBlueprint configurazione accetta un token rilasciato per il blueprint dell'agente del singolo agente anziché per la risorsa Foundry condivisa. Autorizza l'accesso diretto al runtime senza richiedere all'entità di utilizzo di avere un ruolo Foundry.

Un client delegato autentica l'utente e richiede un'autorizzazione esposta dalla registrazione dell'applicazione blueprint dell'agente. Per impostazione predefinita, l'ambito delegato completo è:

api://<agent-blueprint-client-id>/access_agent

L'access_agentURI della risorsa e api://<agent-blueprint-client-id>nome dell'autorizzazione sono predefiniti, non valori fissi. Se si personalizza uno dei due valori nella registrazione dell'applicazione del blueprint dell'agente, il client richiede lo scope completo configurato.

Il token risultante rappresenta l'utente connesso, identifica l'applicazione client e ha come destinazione il blueprint dell'agente. Foundry preautorizza i client proprietari supportati, ad esempio il portale foundry, l'interfaccia della riga di comando e le esperienze di Visual Studio Code, quando crea o aggiorna l'agente. Per un client di proprietà del cliente, configurare la preautorizzazione o ottenere il consenso dell'utente o dell'amministratore.

Un'applicazione riservata può invece richiedere un token solo app per l'audience del blueprint dell'agente usando /.default. Per i token solo app, lo AgentBlueprint schema richiede attualmente un elenco non vuoto token_validation_rules.allowed_clients che contiene l'ID applicazione del chiamante. Se la regola viene omessa o non contiene il chiamante, l'autorizzazione viene negata. Questo elenco elementi consentiti del client è il meccanismo di autorizzazione solo app attualmente supportato e non richiede un ruolo dell'app.

L'autorizzazione per acquisire un token blueprint dell'agente è separata dall'autorizzazione dell'endpoint. La richiesta deve comunque soddisfare le regole di convalida del token dell'endpoint.

Regole di convalida dei token

Dopo che Microsoft Entra ha convalidato il token, lo AgentBlueprint schema può limitare destinatari accettati, tenant, applicazioni client, entità e autorizzazioni delegate. Il servizio fornisce impostazioni predefinite per pubblico, tenant e autorizzazioni delegate per il modello dell'agente sottostante, mentre le regole esplicite consentono di limitare l'accesso per un determinato agente.

Per i token delegati, la preautorizzazione o il consenso controlla se il client può acquisire il token, mentre le regole di convalida del token controllano se l'endpoint lo accetta. È possibile omettere allowed_clients per i token delegati quando non è necessaria una restrizione aggiuntiva del client delegato. Per i token solo app, l'elenco di autorizzazione client non vuoto richiesto controlla quali applicazioni possono chiamare l'agente dopo la convalida del token.

Per le proprietà di configurazione, le impostazioni predefinite e il comportamento di elenco vuoto, vedere Configurare le regole di convalida dei token.

L'accesso allo sviluppo per creare, configurare o testare gli agenti non stabilisce automaticamente l'accesso al blueprint dell'agente dell'utente finale. Al contrario, l'autorizzazione di un client per il blueprint dell'agente non concede a quel client l'accesso di gestione al progetto Foundry.

Autorizzazione di routine

L'invio di routine usa un token per il pubblico Foundry e non supporta lo schema di anteprima AgentBlueprint. Mantieni AzureRbac o il relativo alias Entra configurato per un endpoint che una routine chiama.

autorizzazione del canale servizio Bot

Gli agenti pubblicati in Microsoft Teams o Microsoft 365 usano Activity Protocol e uno schema di autorizzazione Azure servizio Bot. Il flusso di pubblicazione configura normalmente lo schema appropriato. BotServiceRbac e BotServiceTenant presentano una richiesta di accesso nella conversazione in modo che l'utente possa eseguire l'autenticazione prima di interagire con l'agente.

  • Usare BotServiceRbac quando ogni utente necessita dell'autorizzazione Azure applicabile.
  • Usare BotServiceTenant quando gli utenti nel tenant configurato possono accedere all'agente senza assegnazioni RBAC di Foundry individuali.
  • Usare BotService solo per la compatibilità legacy. Non applica una regola di autorizzazione utente aggiuntiva.

Quando si applica Azure RBAC

Gli schemi AzureRbac e BotServiceRbac applicano il controllo degli accessi in base al ruolo di Azure. Altri schemi usano una regola di autorizzazione diversa.

Configuration È necessario Azure RBAC? Regola di autorizzazione
AzureRbac o il relativo Entra alias Yes I client delegati devono essere autorizzati a richiedere il permesso di Foundry applicabile. Il chiamante presenta quindi un token per l'audience Foundry e deve avere un ruolo Azure che consenta l'accesso all'agente.
AgentBlueprint No I client delegati devono essere autorizzati a richiedere il permesso configurato. Il chiamante presenta quindi un token per l'audience del blueprint dell'agente, che deve soddisfare le regole di convalida della procedura.
BotServiceRbac Yes L'utente connesso deve avere un ruolo Azure che consente l'accesso all'agente.
BotServiceTenant No L'utente connesso deve trovarsi nel tenant configurato. Questa regola è una regola del tenant fissa anziché una regola personalizzabile.
BotService No Non viene applicata alcuna regola di autorizzazione utente aggiuntiva dopo che Azure servizio Bot ha convalidato la richiesta del canale.

Contenuti correlati

  • Ultimo aggiornamento: