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

La CLI dell'Agente 365 necessita di una registrazione personalizzata dell'app client nel tuo tenant Microsoft Entra ID per autenticare e gestire i Blueprint dell'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 Application (client)
4. Configurare le autorizzazioni API

Se hai problemi, consulta la sezione Risoluzione dei problemi .

Prerequisiti

Prima di iniziare, assicurati di avere accesso al centro amministrativo Microsoft Entra e, se necessario, a uno dei ruoli amministrativi richiesti per concedere il consenso.

Per registrare l'app

Di default, qualsiasi utente nel tenant può registrare le applicazioni nel centro amministrativo 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 della Candidatura: Consigliato - può gestire le registrazioni 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 al centro amministrativo Microsoft Entra

2. Seleziona le 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 (Singolo tenant)
   • 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 Application (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:

• Opzione A: Usa il centro amministrativi Microsoft Entra per tutti i permessi (se i permessi beta sono visibili)
• Opzione B: Usa l'API Microsoft Graph per aggiungere tutti i permessi (consigliato se i permessi beta non sono visibili)

Opzione A: centro amministrativo 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. Seleziona Aggiungi un permesso>Microsoft Graph>Permessi delegati.

   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	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: API Microsoft Graph (per permessi beta)

Usa questo metodo se AgentIdentityBlueprint.* i permessi non sono visibili nel centro amministrativo di Microsoft Entra.

1. Apri Esploratore Grafico.

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

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

   • ID del principale del servizio. Ti serve un SP_OBJECT_ID valore variabile.
   • ID risorsa del grafo. 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 principale di servizio è l'identità della tua app nel tuo inquilino. 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 Application effettivo dal Passo 3: Copia ID Application (client):

   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 successo, copia il id valore. 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 amministrativo a livello di tenant per tutte e cinque le autorizzazioni, inclusi i due permessi beta che non sono visibili nel centro amministrativo 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 Aggiorna i 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 valore id della 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 a inquilino 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 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: Esecuzione a365 config init di comandi o a365 setup fallimento 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: Visualizzazioni Custom client app validation successfulCLI .

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 il centro amministrativo Microsoft Entra dopo l'Opzione B: Elimini i permessi 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. Vai al centro > App > della tua app >
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.

I permessi beta scompaiono dopo il consenso dell'amministratore del centro amministrativo Microsoft Entra

Sintomo: Hai usato l'Opzione B: Microsoft Graph API (per i permessi Beta) per aggiungere i permessi beta, ma questi scompaiono dopo aver selezionato Concede il consenso amministratore nel centro amministrativo Microsoft Entra.

Causa principale: il centro di amministrazione Microsoft Entra non mostra i permessi 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. Usi l'API Graph (Opzione B) per aggiungere tutti e cinque i permessi, inclusi quelli beta.
2. La chiamata API concede già il consenso amministrativo a livello di tenant.consentType: "AllPrincipals"
3. Vai al centro amministrazione Microsoft Entra e vedi solo tre permessi perché i permessi beta sono invisibili.
4. Seleziona Concede il consenso amministrativo pensando di averne bisogno.
5. Il centro amministrativo Microsoft Entra sovrascrive il tuo consenso concesso dall'API con solo i tre permessi visibili.
6. I tuoi due permessi beta sono ora cancellati.

Soluzione:

• Non usare il consenso amministrativo del centro amministrativo Microsoft Entra dopo il metodo API: il metodo API già concede il consenso amministratore.
• Se cancelli accidentalmente i permessi beta, riesegui l'Opzione B Passo 3 (Concedere il consenso dell'amministratore tramite 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 scope campo nella POST risposta o PATCH op.

App non trovata durante la validazione

Sintomo: Report o Invalid client ID errori CLIApplication not found.

Soluzione:

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

   • Vai su Microsoft Entra admin center>Registrazioni> app Panoramica della tua app >
   • Copia il valore sotto l'ID Application (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>"
   

Scopri come registrare una domanda in Microsoft Entra ID.