Registrazione dell'applicazione client personalizzata per CLI di Agent 365

L'interfaccia della riga di comando di Agent 365 necessita di una registrazione personalizzata dell'app client nel tenant Microsoft Entra ID per autenticare e gestire i blueprint di identità dell'agente.

Questo articolo suddivide il processo in quattro passaggi principali:

1. Registra applicazione
2. Imposta l'URI di reindirizzamento
3. Copia l'ID applicazione (client)
4. Configura le autorizzazioni APIRichiede privilegi di amministratore
5. Aggiungere la dichiarazione di ruolo wids

In caso di problemi, consulta la sezione Risoluzione dei problemi.

Prerequisiti

Prima di iniziare, assicurati di avere accesso all'interfaccia di amministrazione di Microsoft Entra e, se necessario, a uno dei ruoli amministrativi richiesti per concedere il consenso.

Per registrare l'app

Per impostazione predefinita, qualsiasi utente nel tenant può registrare le applicazioni nell'Interfaccia di amministrazione di Microsoft Entra. Tuttavia, gli amministratori del tenant possono limitare questa funzionalità. Se non riesci a registrare la tua app, contatta il tuo amministratore.

Per aggiungere autorizzazioni e concedere il consenso

È necessario uno di questi ruoli amministrativi per 4. Configurare le autorizzazioni API.

• Amministratore di applicazioni: consigliato - può gestire le registrazioni e concedere il consenso
• Amministratore di applicazioni cloud: può gestire le registrazioni e concedere il consenso
• Amministratore globale: ha tutti i permessi, ma non è obbligatorio

1. Registrare l'applicazione

Queste istruzioni riassumono le istruzioni complete per creare una registrazione dell'app.

1. Vai a Interfaccia di amministrazione di Microsoft Entra

2. Seleziona Registrazioni app

3. Selezionare Nuova registrazione

4. Immettere

   • Nome: inserisci un nome significativo per la tua app, come my-agent-app. Gli utenti dell'app vedono questo nome e puoi modificarlo in qualsiasi momento. Puoi creare più registrazioni app che hanno lo stesso nome.

     Suggerimento

     Se vuoi utilizzare il flusso a365 setup all --agent-name senza configurazione, assegna all'app esattamente il nome Agent 365 CLI. La CLI individua automaticamente l'app client tramite questo nome visualizzato riconosciuto, quindi non è necessario copiare l'ID client in un file di configurazione.

   • Tipi di account supportati: account solo in questa directory organizzativa (tenant singolo)

   • URI di reindirizzamento: seleziona Client pubblico/nativo (mobile & desktop) e inserisci http://localhost:8400/

5. Selezionare Registra

La CLI richiede in totale tre URI di reindirizzamento. La CLI aggiunge automaticamente quelle mancanti quando esegui:a365 setup requirements

Vedi Cosa configura automaticamente la CLI per dettagli.

2. Imposta l'URI di reindirizzamento

1. Vai su Panoramica e copia il valore ID dell'applicazione (client).
2. Vai ad Autenticazione (anteprima) e quindi seleziona Aggiungi URI di reindirizzamento.
3. Seleziona Applicazioni mobili e desktop e imposta il valore su ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}, dove {client-id} è il valore dell'ID applicazione (client ID) che hai copiato.
4. Seleziona Configura per aggiungere il valore.

3. Copia l'ID applicazione (client)

Dalla pagina Panoramica dell'app, copia l'ID applicazione (client) in formato GUID. Utilizzi questo valore quando esegui a365 setup all o quando crei manualmente a365.config.json.

4. Configurare autorizzazioni API

Scegli il metodo appropriato:

• Opzione A: usa l'interfaccia di amministrazione di Microsoft Entra per tutte le autorizzazioni (se le autorizzazioni beta sono visibili)
• Opzione B: usa l'API di Microsoft Graph per aggiungere tutte le autorizzazioni (consigliato se le autorizzazioni beta non sono visibili)

Opzione A: interfaccia di amministrazione di Microsoft Entra (metodo standard)

Utilizza questo metodo se sono visibili le autorizzazioni beta nel tuo tenant.

1. Nella registrazione app, vai a Autorizzazioni API.

2. Seleziona Aggiungi un'autorizzazione>Microsoft Graph>Autorizzazioni delegate.

   Importante

   Devi usare Autorizzazioni delegate (non Autorizzazioni applicazioni). La CLI si autentica in modo interattivo: accedi e agisce per tuo conto. Per saperne di più, vedi Tipo di autorizzazione errato.

3. Aggiungi queste sette autorizzazioni una per una:

   Autorizzazione	Scopo
   AgentIdentityBlueprint.ReadWrite.All	Creazione blueprint, gestione dei segreti client, autorizzazioni ereditarie, credenziali di identità federate e cancellazione (API beta)
   AgentIdentityBlueprintPrincipal.Create	Creare l'entità servizio del Blueprint dell'agente (API beta)
   AgentIdentity.Read.All	Verifica dell'idempotenza e ricerca dell'entità servizio dell'identità dell'agente (API beta)
   AgentIdentity.DeleteRestore.All	Eliminare le entità servizio dell'identità dell'agente durante la pulizia (API beta)
   AgentRegistration.ReadWrite.All	Leggi e scrivi tutte le registrazioni degli agenti
   Application.Read.All	Ricerca dell'entità servizio tramite ID app (sostituzione più ristretta di Directory.Read.All)
   User.Read	Leggere il profilo dell'utente connesso per l'assegnazione dello sponsor e del proprietario del blueprint

   Nota

   AgentRegistration.ReadWrite.All è necessario per la configurazione dell'agente. Il validatore CLI verifica esplicitamente questa autorizzazione. Deve essere presente nella registrazione dell'app e avere il consenso amministratore concesso.

   Per ogni autorizzazione:

   • Nella casella di ricerca, digita il nome dell'autorizzazione (ad esempio, AgentIdentityBlueprint.ReadWrite.All).
   • Seleziona la casella accanto all'autorizzazione.
   • Seleziona Aggiungi autorizzazioni.
   • Ripeti per tutte e sette le autorizzazioni.

4. Seleziona Concedi consenso amministratore per [il tuo tenant].

   • Perché è richiesto? I modelli di identità dell'agente sono risorse a livello di tenant a cui più utenti e applicazioni possono fare riferimento. Senza consenso a livello di tenant, la CLI fallisce durante l'autenticazione.
   • E se fallisce? È necessario il ruolo Amministratore applicazione, Amministratore applicazione cloud o Amministratore globale. Consulta il tuo amministratore del tenant per assistenza.

5. Verifica che tutte le autorizzazioni mostrino segni di spunta verdi in Stato.

Se le autorizzazioni beta (AgentIdentityBlueprint.*) non sono visibili, procedi all'Opzione B.

Opzione B: API di Microsoft Graph (per autorizzazioni beta)

Usa questo metodo se l'interfaccia di amministrazione di Microsoft Entra non mostra autorizzazioni AgentIdentityBlueprint.*.

1. Apri Graph explorer.

2. Accedi con il tuo account amministratore (Amministratore di applicazioni cloud o Amministratore di applicazioni).

3. Concedi il consenso dell'amministratore tramite API Graph. Per completare questo passaggio, devi:

   • ID entità servizio. Valore delle variabili SP_OBJECT_ID necessario.
   • ID della risorsa Graph. Valore delle variabili GRAPH_RESOURCE_ID necessario.
   • Crea (o aggiorna) le autorizzazioni delegate utilizzando il tipo di risorsa oAuth2PermissionGrant con i valori di variabile SP_OBJECT_ID e GRAPH_RESOURCE_ID.

Utilizza le informazioni nelle sezioni seguenti per completare questi passaggi.

Ottieni il tuo ID dell'entità servizio

Un'entità servizio è l'identità della tua app nel tuo tenant. Devi ottenerlo prima di poter concedere autorizzazioni tramite l'API.

1. Imposta il metodo di Graph Explorer su GET e usa questo URL. Sostituisci <YOUR_CLIENT_APP_ID> con il tuo ID applicazione (client) ID effettivo da Passaggio 3: Copia l'ID applicazione (client):

   https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '<YOUR_CLIENT_APP_ID>'&$select=id
   

2. Seleziona Esegui query.

   • Se la query ha successo, il valore restituito è il tuo SP_OBJECT_ID.

   • Se la query non riesce a causa di un errore di autorizzazioni, seleziona la scheda Modifica autorizzazioni, concedi le autorizzazioni richieste e poi seleziona Esegui nuovamente la query. Il valore restituito è il tuo SP_OBJECT_ID.

   • Se la query restituisce risultati vuoti ("value": []), crea l'entità servizio seguendo questi passaggi:

     1. Imposta il metodo su POST e usa questo URL:

        https://graph.microsoft.com/v1.0/servicePrincipals
        

        Corpo della richiesta (sostituisci YOUR_CLIENT_APP_ID con l'ID client effettivo della tua applicazione):

        {
           "appId": "YOUR_CLIENT_APP_ID"
        }
        

     2. Seleziona Esegui query. Dovresti ricevere una risposta 201 Created. Il valore id restituito è il tuo SP_OBJECT_ID.

Ottieni l'ID della risorsa Graph

1. Imposta il metodo di Graph Explorer su GET e usa questo URL:

   https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=id
   

2. Seleziona Esegui query.

   • Se la query funziona, copia il valore id. Questo valore è GRAPH_RESOURCE_ID.
   • Se la query non riesce a causa di un errore di autorizzazioni, seleziona la scheda Modifica autorizzazioni, concedi le autorizzazioni richieste e poi seleziona Esegui nuovamente la query. Copiare il valore di id. Questo valore è GRAPH_RESOURCE_ID.

Creare autorizzazioni delegate

Questa chiamata API concede il consenso amministratore a livello di tenant per tutte le sette autorizzazioni, incluse le autorizzazioni beta che non sono visibili nell'interfaccia di amministrazione di Microsoft Entra.

1. Imposta il metodo di Graph Explorer su POST e utilizza questo URL e il corpo della richiesta:

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants
   

   Corpo della richiesta:

   {
   "clientId": "<SP_OBJECT_ID>",
   "consentType": "AllPrincipals",
   "principalId": null,
   "resourceId": "<GRAPH_RESOURCE_ID>",
   "scope": "AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprintPrincipal.Create AgentIdentity.Read.All AgentIdentity.DeleteRestore.All AgentRegistration.ReadWrite.All Application.Read.All User.Read"
   }
   

2. Seleziona Esegui query.

   • Se ottieni una risposta 201 Created: operazione completata. Il campo scope nella risposta elenca tutti e sette i nomi delle autorizzazioni. L'operazione è completata.
   • Se la query non riesce a causa di un errore di autorizzazioni, seleziona la scheda Modifica autorizzazioni, acconsenti alle autorizzazioni richieste e quindi seleziona Esegui query nuovamente.
   • Se ricevi l'errore Request_MultipleObjectsWithSameKeyValue: una concessione esiste già. Forse qualcuno ha aggiunto i permessi in precedenza. Vedi l'aggiornamento seguente Aggiornamento autorizzazioni delegate.

Aggiornare autorizzazioni delegate

Quando ricevi un errore Request_MultipleObjectsWithSameKeyValue usando i passaggi per Creare autorizzazioni delegate, utilizza questi passaggi per aggiornare le autorizzazioni delegate.

1. Imposta il metodo di Graph Explorer su GET e usa questo URL:

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'SP_OBJECT_ID_FROM_ABOVE'
   

2. Seleziona Esegui query. Copiare il valore id della risposta. Questo valore è YOUR_GRANT_ID.

3. Imposta il metodo di Graph Explorer su PATCH e usa questo URL con YOUR_GRANT_ID.

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants/<YOUR_GRANT_ID>
   

   Corpo della richiesta:

   {
      "scope": "AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprintPrincipal.Create AgentIdentity.Read.All AgentIdentity.DeleteRestore.All AgentRegistration.ReadWrite.All Application.Read.All User.Read"
   }
   

4. Seleziona Esegui query. Dovresti ricevere una risposta 200 OK con tutte e sette le autorizzazioni nel campo scope.

5. Aggiungere la dichiarazione di ruolo wids

La CLI di Agent 365 legge direttamente le assegnazioni dei ruoli della directory Entra dal token di accesso per determinare se hai privilegi di amministratore. Questo richiede l'aggiunta della wids claim ai token di accesso emessi per la registrazione della tua app.

Senza questa attestazione, la CLI non può rilevare il tuo ruolo e torna a mostrare le istruzioni PowerShell per ogni passaggio che richiede privilegi di amministratore, anche quando sei un amministratore. Completa questo passaggio per ottenere il comportamento corretto.

1. Nella registrazione dell'app, vai su Configurazione token.

2. Seleziona Aggiungi un'attestazione facoltativa.

3. Per Tipo di token, seleziona Accesso.

4. Nell'elenco delle attestazioni, seleziona la casella accanto a wids.

5. Seleziona Aggiungi.

   Se ti viene chiesto di attivare l'autorizzazione profile di Microsoft Graph per abilitare l'attestazione, seleziona Sì, aggiungi.

Procedure consigliate per la sicurezza

Consulta queste linee guida per mantenere la registrazione della tua app sicura e conforme.

Che cosa fare:

• Usa la registrazione a tenant singolo.
• Concedi solo le autorizzazioni delegate necessarie.
• Revisiona regolarmente le autorizzazioni.
• Rimuovi l'app quando non è più necessaria.

Non:

• Concedere autorizzazioni applicazione. Usa solo il delegato.
• Condividere pubblicamente l'ID del client.
• Concedere altre autorizzazioni inutili.
• Usare l'app per altri scopi.

Cosa configura automaticamente la CLI

Quando esegui a365 setup requirements, la CLI convalida la registrazione dell'app e potrebbe dover apportare modifiche. Prima di applicare qualsiasi modifica, la CLI ti mostra un riepilogo e chiede conferma:

WARNING: The CLI needs to make the following changes to your app registration (<app-id>):

  - Add redirect URI(s): http://localhost
  - Enable 'Allow public client flows' (isFallbackPublicClient = true)

Do you want to proceed? (y/N):

Per saltare la richiesta di conferma (ad esempio in un ambiente CI), usa il flag --yes:

a365 setup requirements --yes

La tabella seguente descrive ogni modifica che la CLI potrebbe apportare:

Se rifiuti il prompt, la CLI non modifica la registrazione della tua app. Se sono necessarie modifiche affinché la CLI funzioni, puoi configurarle manualmente nell'Interfaccia di amministrazione di Microsoft Entra o eseguirle nuovamente con --yes.

Passaggi successivi

Dopo aver registrato la tua app client personalizzata, utilizzala con la CLI Agent 365 per completare la configurazione di Agent 365:

Risoluzione dei problemi

Questa sezione descrive come risolvere errori nella registrazione di app client personalizzate.

La convalida della CLI fallisce durante la configurazione

Sintomo: l'esecuzione del comando a365 setup o a365 setup requirements non riesce con errori di validazione riguardo all'app client personalizzata.

Soluzione: usa questo elenco di controllo per verificare che la registrazione della tua app sia corretta:

# Run requirements validation to see validation messages
a365 setup requirements

Risultato atteso: la CLI visualizza Custom client app validation successful.

Se non ottieni il risultato previsto, verifica ciascuno dei punti seguenti:

Autorizzazioni delegate richieste:

• AgentIdentityBlueprint.ReadWrite.All [Beta]
• AgentIdentityBlueprintPrincipal.Create [Beta]
• AgentIdentity.Read.All [Beta]
• AgentIdentity.DeleteRestore.All [Beta]
• AgentRegistration.ReadWrite.All
• Application.Read.All
• User.Read

Consenso amministratore concesso in modo errato

Sintomo: la convalida fallisce anche se sono state aggiunte le autorizzazioni.

Causa principale: non hai concesso il consenso amministratore oppure l'hai concesso in modo non corretto.

Soluzione: nella registrazione dell'app nell'Interfaccia di amministrazione di Microsoft Entra, vai ad Autorizzazioni API e seleziona Concedi consenso amministratore per [il tuo tenant]. Verifica che tutte le autorizzazioni mostrino segni di spunta verdi in Stato.

La creazione del progetto ha esito negativo e viene visualizzato il messaggio "Non è stato concesso il consenso amministratore"

Sintomo: a365 setup all visualizza "consenso delle applicazioni delegate garantito con successo", ma non riesce immediatamente durante la creazione del progetto con:

Admin consent has not been granted for this application.
Share this URL with an Application Administrator or Global Administrator to grant consent:
  https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent?client_id=<client-app-id>

Causa principale: il tenant dispone già di un record oauth2PermissionGrant per l'app client personalizzata (da un'installazione parziale precedente o da un'azione precedente "Concedi consenso amministratore" nell'interfaccia di amministrazione di Microsoft Entra per altri ambiti), ma non dispone dell'ambito (AgentIdentityBlueprint.ReadWrite.All) richiesto. La CLI rileva l'ambito mancante e mostra un URL di consenso per permettere a un amministratore di completare la concessione.

Soluzione:

Condividi l'URL di consenso visualizzato nell'output dell'errore con un Amministratore applicazione o Amministratore globale. L'URL sarà simile al seguente:

https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent?client_id=<client-app-id>

Dopo che l'amministratore ha dato il consenso, riesegui a365 setup all --agent-name <name>.

Se disponi di privilegi di amministratore, puoi aprire direttamente l'URL dal browser per concedere il consenso subito.

Tipo di autorizzazione errato

Sintomo: la CLI fallisce con errori di autenticazione o errori di accesso negato.

Causa principale: hai aggiunto Autorizzazioni applicazione invece di Autorizzazioni delegate.

Questa tabella descrive i diversi tipi di autorizzazioni.

Perché delegata?

• Accedi in modo interattivo (autenticazione tramite browser)
• La CLI esegue le azioni al tuo posto (le tracce di audit mostrano la tua identità)
• Più sicuro: limitato dalle tue autorizzazioni effettive
• Garantisce responsabilità e conformità

Soluzione:

1. Vai all'Interfaccia di amministrazione di Microsoft Entra>Registrazioni app> L'app >Autorizzazioni API
2. Rimuovi tutte le autorizzazioni per le applicazioni. Queste autorizzazioni vengono visualizzate come Applicazione nella colonna Tipo.
3. Aggiungi le stesse autorizzazioni delle autorizzazioni delegate.
4. Concedi nuovamente il consenso amministratore.

Le autorizzazioni beta scompaiono dopo il consenso dell'amministratore dell'interfaccia di amministrazione di Microsoft Entra

Sintomo: hai usato Opzione B: API di Microsoft Graph (per le autorizzazioni Beta) per aggiungere autorizzazioni beta, ma queste scompaiono dopo aver selezionato Concedere il consenso amministratore nell'interfaccia di amministrazione di Microsoft Entra.

Causa principale: l'interfaccia di amministrazione di Microsoft Entra non mostra le autorizzazioni beta nell'interfaccia utente. Quando selezioni Concedi il consenso amministratore, il portale concede il consenso solo per le autorizzazioni visibili e sovrascrive il consenso concesso tramite API.

Perché ciò accade:

1. Utilizzi l'API Microsoft Graph (Opzione B) per aggiungere tutte e sette le autorizzazioni, incluse quelle beta.
2. La chiamata API con consentType: "AllPrincipals"già concede il consenso amministratore a livello di tenant.
3. Vai all'interfaccia di amministrazione di Microsoft Entra e vedi solo un insieme secondario di autorizzazioni perché le autorizzazioni beta sono invisibili nel portale.
4. Seleziona Concedere il consenso amministratore pensando che sia necessario.
5. L'interfaccia di amministrazione di Microsoft Entra sovrascrive il consenso dell'API con solo le autorizzazioni visibili.
6. Le autorizzazioni beta sono ora eliminate.

Soluzione:

• Non usare il consenso amministratore dell'interfaccia di amministrazione di Microsoft Entra dopo il metodo API: il metodo API già concede il consenso amministratore.
• Se elimini accidentalmente le autorizzazioni beta, esegui nuovamente il passaggio 3 dell'Opzione B (concedere il consenso dell'amministratore tramite API di Microsoft Graph) per ripristinarle. Se ricevi un errore Request_MultipleObjectsWithSameKeyValue, segui i passaggi per aggiornare le autorizzazioni delegate.
• Per verificare che tutte e sette le autorizzazioni siano elencati, controlla il campo scope nella risposta POST o PATCH.

App non trovata durante la convalida

Sintomo: la CLI restituisce errori Application not found o Invalid client ID.

Soluzione:

1. Assicurati di aver copiato ID applicazione (client) in formato GUID, non ID oggetto:

   • Vai all'Interfaccia di amministrazione di Microsoft Entra>Registrazioni app> L'app >Panoramica
   • Copiare il valore dell'ID applicazione (client)
   • Il formato deve essere: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

2. Verifica che l'app esista nel tuo tenant:

   # Sign in to the correct tenant
   az login
   
   # List your app registrations
   az ad app list --display-name "<The display name of your app>"
   

Informazioni su come registrare un'applicazione in Microsoft Entra ID.