Registrazione personalizzata dell'app client per la CLI dell'Agente 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 fasi principali:

1. Domanda di registrazione
2. Imposta l'URI di Redirect
3. Copia 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 all'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 centro di amministrazione 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. Vai a Microsoft Entra centro amministrativo

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: Solo account in questa directory organizzativa (Tenant singolo)
   • Reindirizza URI: seleziona Public client/native (mobile e desktop) e entra http://localhost:8400/

5. Selezionare Registra

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. Seleziona applicazioni mobili e desktop e imposta il valore su ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}, dove {client-id} è il valore dell'applicazione (client ID) che hai 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

Scegli il metodo appropriato:

• Option A: usare Microsoft Entra interfaccia di amministrazione per tutte le autorizzazioni (se le autorizzazioni beta sono visibili)
• Option B: usare Microsoft Graph API per aggiungere tutte le autorizzazioni (consigliate se le autorizzazioni beta non sono visibili)

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

Usa questo metodo se i permessi beta sono visibili nel tuo tenant.

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

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

   Importante

   DEVI usare i permessi delegati (NON i permessi applicazioni). La CLI si autentica in modo interattivo: accedi e agisce per tuo conto. Vedi Tipo di permesso sbagliato se aggiungi accidentalmente i permessi dell'applicazione.

3. Aggiungi questi cinque permessi uno per uno:

   Autorizzazione	Scopo
   AgentIdentityBlueprint.ReadWrite.All	Gestire le configurazioni di Agent Blueprint (API beta)
   AgentIdentityBlueprint.UpdateAuthProperties.All	Aggiorna i permessi ereditari di Agent Blueprint (beta API)
   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

   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.
   • Ripeti per tutti e cinque i permessi.

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.

Se i permessi beta (AgentIdentityBlueprint.*) non sono visibili, procedere all'Opzione B.

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

Usare questo metodo se le autorizzazioni AgentIdentityBlueprint.* non sono visibili nell'interfaccia di amministrazione di Microsoft Entra.

1. Apri Esploratore Grafico.

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

3. Concedere il consenso dell'amministratore usando Graph API. Per completare questo passaggio, è necessario:

   • ID del servizio principale. Ti serve un SP_OBJECT_ID valore variabile.
   • ID risorsa del grafico. Ti serve un GRAPH_RESOURCE_ID valore variabile.
   • Crea (o aggiorna) i permessi delegati utilizzando il tipo di risorsa oAuth2PermissionGrant con i SP_OBJECT_ID valori variabili e GRAPH_RESOURCE_ID .

Utilizza le informazioni nelle sezioni seguenti per completare questi passaggi.

Ottieni il tuo ID di committente di servizio

Un service principal è l'identità della tua app nel tuo tenant. Ti serve prima di poter concedere i permessi tramite l'API.

1. Imposta il metodo Esploratore Grafici su GET e usa questo URL. Sostituisci <YOUR_CLIENT_APP_ID> con il tuo ID client dell'applicazione effettivo dal Passo 3: Copia l'ID client dell'applicazione:

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

2. Seleziona Esegui interroga.

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

   • Se la query fallisce con un errore di permessi, seleziona la scheda Modifica permessi , acconsenti ai permessi richiesti, poi seleziona di nuovo Esegui consulta . Il valore restituito è il tuo SP_OBJECT_ID.

   • Se la query restituisce risultati vuoti ("value": []), crea il principale del servizio utilizzando i seguenti 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 il vero ID client della tua applicazione):

        {
           "appId": "YOUR_CLIENT_APP_ID"
        }
        

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

Ottieni il tuo ID di risorsa Graph

1. Imposta il metodo Esploratore Grafici 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 interroga.

   • Se la query ha esito positivo, copia il valore id. Questo valore è il tuo GRAPH_RESOURCE_ID.
   • Se la query fallisce con un errore di permessi, seleziona la scheda Modifica permessi , acconsenti ai permessi richiesti, poi seleziona di nuovo Esegui consulta . Copiare il valore id. Questo valore è il tuo GRAPH_RESOURCE_ID.

Crea permessi delegati

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

1. Imposta il metodo Esplora Grafici su POST e usa questo URL e il corpo della richiesta:

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

   Corpo richiesto:

   {
   "clientId": "<SP_OBJECT_ID>",
   "consentType": "AllPrincipals",
   "principalId": null,
   "resourceId": "<GRAPH_RESOURCE_ID>",
   "scope": "Application.ReadWrite.All Directory.Read.All DelegatedPermissionGrant.ReadWrite.All AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All"
   }
   

2. Seleziona Esegui interroga.

   • Se ricevi 201 Created risposta: Successo! Il scope campo nella risposta mostra tutti e cinque i nomi dei permessi. Hai finito.
   • Se la query fallisce con un errore di permessi (probabile DelegatedPermissionGrant.ReadWrite.All), seleziona la scheda Modifica permessi , acconsenti a DelegatedPermissionGrant.ReadWrite.All, e poi seleziona di nuovo Esegui query .
   • Se ricevi errori Request_MultipleObjectsWithSameKeyValue: Una sovvenzione esiste già. Forse qualcuno ha aggiunto i permessi prima. Vedi il seguente aggiornamento dei permessi delegati.

Aggiornare i permessi delegati

Quando ricevi un Request_MultipleObjectsWithSameKeyValue errore usando i passaggi per Creare permessi delegati, usa questi passaggi per aggiornare i permessi delegati.

1. Imposta il metodo Esploratore Grafici su GET e usa questo URL:

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

2. Seleziona Esegui interroga. Copiare il id valore dalla risposta. Questo valore è YOUR_GRANT_ID.

3. Imposta il metodo Exploratore Grafici su PATCH e usa questo URL con YOUR_GRANT_ID.

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

   Corpo richiesto:

   {
      "scope": "Application.ReadWrite.All Directory.Read.All DelegatedPermissionGrant.ReadWrite.All AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All"
   }
   

4. Seleziona Esegui interroga. Dovresti ricevere una 200 OK risposta con tutti e cinque i permessi disponibili sul scope campo.

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.

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 o non riesce con errori di validazione riguardo alla tua 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 [Beta]
• AgentIdentityBlueprint.UpdateAuthProperties.All [Beta]
• Directory.Read.All
• DelegatedPermissionGrant.ReadWrite.All

Consenso amministrativo concesso in modo errato

Sintomo: La validazione fallisce anche se vengono aggiunti permessi.

Causa principale: Il consenso amministrativo non viene concesso, o viene concesso in modo errato.

Soluzione: La soluzione corretta dipende dal metodo che hai usato:

Se usi accidentalmente Microsoft Entra'interfaccia di amministrazione dopo l'opzione B: Elimina le autorizzazioni beta. Segui Aggiorna i permessi delegati per ripristinarli.

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 Microsoft Entra centro di amministrazione>Registrazioni delle 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.

Le autorizzazioni beta scompaiono dopo il consenso dell'amministratore nel portale di amministrazione di Microsoft Entra.

Symptom: hai usato Option B: Microsoft Graph API (For Beta Permissions) per aggiungere autorizzazioni beta, ma scompaiono dopo aver selezionato Concedi consenso amministratore nel centro di amministrazione di Microsoft Entra.

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

Motivo per cui succede:

1. Usare il Graph API (opzione B) per aggiungere tutte e cinque le autorizzazioni, incluse le autorizzazioni beta.
2. La chiamata API consentType: "AllPrincipals"già concede il consenso amministrativo a livello di tenant.
3. Passare all'interfaccia di amministrazione di Microsoft Entra e visualizzare solo tre autorizzazioni perché le autorizzazioni beta sono invisibili.
4. Seleziona Concedi il consenso amministrativo pensando che sia necessario.
5. Microsoft Entra l'interfaccia di amministrazione sovrascrive il consenso concesso all'API con solo le tre autorizzazioni visibili.
6. I tuoi due permessi beta sono ora cancellati.

Soluzione:

• Non utilizzare il consenso amministrativo nel centro di amministrazione di Microsoft Entra dopo il metodo API: il metodo API concede già il consenso amministrativo.
• Se si eliminano accidentalmente le autorizzazioni beta, eseguire di nuovo Option B Passaggio 3 (Concedere il consenso amministratore usando Graph API) per ripristinarli. Se ricevi un Request_MultipleObjectsWithSameKeyValue errore, segui i passaggi per aggiornare i permessi delegati.
• Per verificare che tutti e cinque i permessi siano elencati, controlla il campo nella risposta scope o POST.

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:

   • Vai al Microsoft Entra admin center>Registrazioni app> la tua app >Panoramica
   • 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.