Registrazione personalizzata dell'app client per la CLI dell'Agente 365

L'interfaccia della riga di comando di Agent 365 richiede una registrazione personalizzata dell'applicazione client nel tenant di Microsoft Entra ID per autenticare e gestire gli Agent Identity Blueprints.

Questo articolo suddivide il processo in quattro fasi principali:

1. Domanda di registrazione
2. Imposta l'URI di Redirect
3. Copia l'ID applicazione (client)
4. Configurare le autorizzazioni API

Se hai problemi, consulta la sezione Risoluzione dei problemi .

Prerequisiti

Prima di iniziare, assicurarsi di avere accesso a Interfaccia di amministrazione di Microsoft Entra e, se necessario, uno dei ruoli di amministratore necessari per concedere il consenso.

Per registrare l'app

Per impostazione predefinita, qualsiasi utente nel tenant può registrare applicazioni nel Interfaccia di amministrazione di Microsoft Entra. Tuttavia , gli amministratori dei tenant possono limitare questa capacità. Se non puoi registrare la tua app, contatta il tuo amministratore.

Aggiungere permessi e concedere il consenso

Ti serve uno di questi ruoli amministrativi per 4. Configura i permessi dell'API.

• Amministratore dell'Applicazione: Consigliato - può gestire le registrazioni delle applicazioni e concedere il consenso
• Amministratore delle applicazioni cloud: può gestire le registrazioni delle app e concedere il consenso
• Amministratore Globale: Ha tutti i permessi, ma non è obbligatorio

1. Registrazione della domanda

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

1. Passare a Interfaccia di amministrazione di Microsoft Entra

2. Selezionare registrazioni app

3. Seleziona Nuova registrazione

4. Inserire:

   • Nome: inserisci un nome significativo per la tua app, come my-agent-app. Gli utenti dell'app visualizzano questo nome e possono essere modificati in qualsiasi momento. È possibile avere più registrazioni dell'app con lo stesso nome.
   • Tipi di account supportati: account solo in questa directory organizzativa (tenant singolo)
   • Reindirizza URI: seleziona Public client/native (mobile e desktop) e entra http://localhost:8400/

5. Selezionare Registra

L'interfaccia della riga di comando richiede tre URI di reindirizzamento in totale. L'interfaccia della riga di comando aggiunge automaticamente eventuali elementi mancanti durante l'esecuzione a365 config init o a365 setup requirements:

Per informazioni dettagliate, vedere Che cos'è la configurazione automatica dell'interfaccia della riga di comando .

2. Imposta l'URI di reindirizzamento

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

3. Copia dell'ID Applicazione (client)

Dalla pagina Panoramica dell'app, copia l'ID dell'applicazione (client) in formato GUID. Inserisci questo valore quando usi il a365 config init comando.

4. Configurare i permessi API

1. Nella registrazione dell'app passare a Autorizzazioni API.

2. Selezionare Aggiungi un'autorizzazione>Microsoft Graph> Autorizzazionidelegate.

   Importante

   È necessario usare autorizzazioni delegate (non autorizzazioni dell'applicazione). La CLI si autentica in modo interattivo: accedi e agisce per tuo conto. Per altre informazioni, vedere Tipo di autorizzazione errato.

3. Aggiungi queste sei autorizzazioni una alla volta:

   Autorizzazione	Scopo
   AgentIdentityBlueprint.ReadWrite.All	Gestire le configurazioni di Agent Blueprint
   AgentIdentityBlueprint.UpdateAuthProperties.All	Aggiornare le autorizzazioni ereditabili di Agent Blueprint
   Application.ReadWrite.All	Creare e gestire applicazioni e Agent Blueprint
   DelegatedPermissionGrant.ReadWrite.All	Concedere permessi per i progetti degli agenti
   Directory.Read.All	Leggi i dati della directory per la validazione
   User.ReadWrite.All	Creare utenti dell'agente, impostare la posizione di utilizzo e assegnare licenze

   Per ogni permesso:

   • Nella casella di ricerca, digita il nome del permesso (ad esempio, AgentIdentityBlueprint.ReadWrite.All).
   • Seleziona la casella accanto al permesso.
   • Selezionare Aggiungi autorizzazioni.
   • Ripetere per tutte e sei le autorizzazioni.

4. Seleziona Concede il consenso amministrativo per [Il tuo inquilino].

   • Perché è richiesto? I Agent Identity Blueprint sono risorse a livello di tenant a cui più utenti e applicazioni possono fare riferimento. Senza il consenso di tutto il tenant, la CLI fallisce durante l'autenticazione.
   • E se fallisce? Serve un ruolo da Amministratore delle Applicazioni, Amministratore delle Applicazioni Cloud o Amministratore Globale. Chiedi aiuto all'amministratore del tuo inquilino.

5. Verifica che tutti i permessi mostrino segni di spunta verdi sotto Stato.

Procedure consigliate per la sicurezza

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

Cosa fare:

• Usa la registrazione per tenant singolo.
• Concedi solo i permessi delegati richiesti.
• Verifica regolarmente i permessi.
• Rimuovi l'app quando non è più necessaria.

Non farlo:

• Concedere le autorizzazioni per l'applicazione. Usa solo il delegato.
• Condividi pubblicamente l'ID del cliente.
• Concedi altri permessi inutili.
• Usa l'app per altri scopi.

Elementi configurati automaticamente dall'interfaccia della riga di comando

Quando si esegue a365 config init o a365 setup requirements, l'interfaccia della riga di comando convalida la registrazione dell'app e potrebbe essere necessario apportare modifiche. Prima di applicare le modifiche, l'interfaccia della riga di comando visualizza 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 ignorare la richiesta di conferma , ad esempio in un ambiente CI, usare il --yes flag :

a365 config init --yes

La tabella seguente descrive ogni modifica che l'interfaccia della riga di comando può apportare:

Se si rifiuta il prompt, la CLI non modifica la registrazione dell'app. Se sono necessarie modifiche per il funzionamento dell'interfaccia della riga di comando, è possibile configurarle manualmente in Interfaccia di amministrazione di Microsoft Entra o rieseguarle con --yes.

Passaggi successivi

Dopo aver registrato la tua app client personalizzata, usala con la CLI di Agent 365 nel ciclo di sviluppo di Agent 365:

Risoluzione dei problemi

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

La validazione della CLI fallisce durante la configurazione

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

Soluzione: Usa questa checklist per verificare che la registrazione della tua app sia corretta:

# Run configuration to see validation messages
a365 config init

Risultato atteso: Il CLI mostra Custom client app validation successful.

Se non ottieni il risultato atteso, verifica ciascuno dei seguenti controlli:

Permessi delegati richiesti:

• Application.ReadWrite.All
• AgentIdentityBlueprint.ReadWrite.All
• AgentIdentityBlueprint.UpdateAuthProperties.All
• Directory.Read.All
• DelegatedPermissionGrant.ReadWrite.All
• User.ReadWrite.All

Consenso amministrativo concesso in modo errato

Sintomo: La convalida ha esito negativo anche se sono state aggiunte autorizzazioni.

Causa principale: Non hai concesso il consenso dell'amministratore o lo hai fatto in modo errato.

Solution: Nella registrazione dell'app in Interfaccia di amministrazione di Microsoft Entra, vai a API autorizzazioni e seleziona Concedi il consenso dell'amministratore per [Tenant]. Verifica che tutti i permessi mostrino segni di spunta verdi sotto Stato.

Tipo di permesso sbagliato

Sintomo: la CLI fallisce con errori di autenticazione o errori di permesso negati.

Causa principale: hai aggiunto i permessi Application invece dei permessi delegati.

Questa tabella descrive i diversi tipi di permessi.

Perché delegato?

• Accedi in modo interattivo (autenticazione del browser)
• CLI esegue le azioni come te (le audit trail mostrano la tua identità)
• Più sicuro - limitato dai tuoi permessi reali
• Garantisce responsabilità e conformità

Soluzione:

1. Passare a Interfaccia di amministrazione di Microsoft Entra>Registrazioni app> L'app >Autorizzazioni API
2. Rimuovi qualsiasi permesso di applicazione. Questi permessi compaiono come Applicazione nella colonna Tipo .
3. Aggiungi gli stessi permessi dei permessi delegati .
4. Concedi nuovamente il consenso dell'amministratore.

App non trovata durante la validazione

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

Soluzione:

1. Verifica di aver copiato l'ID dell'applicazione (client) in formato GUID, non l'ID dell'oggetto:

   • Passare a Interfaccia di amministrazione di Microsoft Entra>Registrazioni app> L'app >Overview
   • Copia il valore sotto l'ID Applicazione (client)
   • Il formato dovrebbe essere: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

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

   # 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.