Condividi tramite

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

Importante

Devi far parte del programma di anteprima Frontier per ottenere l'accesso in anteprima a Microsoft Agent 365. Frontier ti mette in contatto diretto con le ultime innovazioni di Microsoft nell'IA. Le anteprime Frontier sono soggette alle condizioni di anteprima esistenti dei tuoi contratti del cliente. Poiché queste funzionalità sono ancora in fase di sviluppo, la disponibilità e le funzionalità possono cambiare nel tempo.

La CLI dell'Agente 365 richiede una registrazione personalizzata dell'app client nel tuo tenant Microsoft Entra ID per autenticare e gestire i Blueprint dell'Identità dell'Agente.

Prerequisiti

Per registrare l'app (Passaggi 1 e 2):

Per aggiungere permessi e concedere il consenso (Passo 3):

Suggerimento

Non hai accesso da amministratore? Puoi completare tu stesso i passaggi 1-2, poi chiedere al tuo amministratore inquilino di completare il passaggio 3. Fornisci loro il tuo ID Application (client) dal Passo 2 e un link alla sezione Configura i permessi API .

Passo 1: Registra la 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. Inserisci:
    • Nome: Agent365 CLI (o il nome che preferisci)
    • Tipi di account supportati: Solo account in questa directory organizzativa (Singolo tenant)
    • Reindirizza URI: Seleziona Client pubblico/nativo (mobile e desktop) → Inserisci http://localhost:8400/
  5. Selezionare Registra

Passo 2: Copia l'ID dell'applicazione (client)

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

Suggerimento

Non confondere questo valore con l'ID dell'oggetto - ti serve l'ID dell'applicazione (client).

Passo 3: Configura i permessi API

Importante

Per questo passaggio sono necessari privilegi di amministratore. Se sei uno sviluppatore senza accesso amministratore, invia il tuo ID Application (client) dal Passaggio 2 al tuo amministratore tenant e fai completare il Passo 3.

Annotazioni

A dicembre 2025, i due AgentIdentityBlueprint.* permessi sono API beta e potrebbero non essere visibili nel centro amministrativo Microsoft Entra. Se questi permessi diventano generalmente disponibili nel tuo tenant, puoi usare l'Opzione A per tutti i permessi.

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, vai su Permessi 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 Concedere 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 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.

Avvertimento

Se usi questo metodo API, NON usare il pulsante "Concedi il consenso dell'amministratore" del centro amministrativo Microsoft Entra dopo. Il metodo API concede automaticamente il consenso degli amministratori e, usando il pulsante del centro amministrativo Microsoft Entra, si eliminano i permessi beta. Vedi Permessi beta scomparire per i dettagli.

  1. Open Graph Explorer

  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, hai bisogno di:

    • ID del principale del servizio. Ti servirà un SP_OBJECT_ID valore variabile.
    • ID risorsa del grafo. Ti servirà un GRAPH_RESOURCE_ID valore variabile.
    • Creare (o aggiornare) i permessi delegati utilizzando il tipo di risorsa oAuth2PermissionGrant con i SP_OBJECT_ID valori delle variabili e GRAPH_RESOURCE_ID .

Usa le informazioni nelle sezioni seguenti per completare questo processo.

Ottieni il tuo ID di committente di servizio

Un principale di servizio è l'identità della tua app nel tuo tenant, richiesta prima di concedere i permessi tramite API.

  1. Imposta il metodo Esplora Grafi su GET e usa questo URL (sostituisci <YOUR_CLIENT_APP_ID> con il tuo ID client Application effettivo dal Passo 2: 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 è 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 è 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, poi seleziona di nuovo Esegui la query .
    • Se ricevi errori Request_MultipleObjectsWithSameKeyValue: Una sovvenzione esiste già. Forse qualcuno ha aggiunto i permessi prima. Vedi il seguente Aggiorna i permessi delegati.

Avvertimento

La consentType: "AllPrincipals" richiesta POSTgià concede il consenso amministrativo a livello di inquilino. NON selezionare "Concedi consenso amministratore" nel centro amministrazione Microsoft Entra dopo aver usato questo metodo API: farlo cancella i permessi beta perché il centro amministrazione Microsoft Entra non può vedere i permessi beta e sovrascrive il consenso concesso dall'API solo con i permessi visibili.

Aggiornare i permessi delegati

Quando ricevi un Request_MultipleObjectsWithSameKeyValue errore usando i passaggi per Creare i 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 è YOUR_GRANT_ID.

  3. Imposta il metodo Esplora Grafici su PATCH e usa questo URL usando 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.

Risoluzione dei problemi

Questa sezione contiene informazioni su come risolvere errori nella registrazione di app client personalizzate.

Tipo di permesso sbagliato (Delegato vs Applicazione)

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

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

Tipo di autorizzazione Quando usare Come la utilizza la CLI dell'Agente 365
Delegato ("Scope") L'utente si collega in modo interattivo Agent 365 CLI usa questo - Accedi, CLI agisce per tuo conto
Applicazione ("Ruolo") Il servizio funziona senza utente Non usare - Solo per servizi di background/demoni

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 >amministrativo Microsoft EntraRegistrazioni> App Permessi API della tua app >
  2. Rimuovere eventuali permessi applicabili (questi appaiono come "Applicazione" nella colonna Tipo )
  3. Aggiungi gli stessi permessi dei permessi delegati
  4. Concedere nuovamente il consenso dell'amministratore

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

Causa principale: Microsoft Entra admin center non mostra i permessi beta nell'interfaccia utente, quindi quando selezioni Concedi il consenso dell'amministratore, concede solo 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 i permessi beta
  2. La chiamata API che consentType: "AllPrincipals"già concede il consenso amministrativo a livello di tenant
  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. Microsoft Entra admin center sovrascrive il consenso concesso dall'API solo con i tre permessi visibili
  6. I tuoi due permessi beta sono ora cancellati

Soluzione:

  • Non usare mai il consenso amministrativo del centro amministrativo Microsoft Entra dopo il metodo API: Il metodo API già concede il consenso all'amministratore
  • Se hai accidentalmente cancellato i permessi beta, riesegui l'Opzione B Passo 3 (Concedere il consenso dell'amministratore usando Graph API) per ripristinarli. Ricevi un Request_MultipleObjectsWithSameKeyValue errore - segui i passaggi per aggiornare i permessi delegati.
  • Controlla il scope campo nella POST risposta o PATCH per verificare che tutti e cinque i permessi siano elencati

Errori di convalida

La CLI convalida automaticamente la tua app client quando è in esecuzione a365 setup o a365 config init.

Problemi comuni:

  • App non trovata: verifica di aver copiato l'ID dell'applicazione (client) (non l'ID dell'oggetto)
  • Permessi mancanti: Aggiungi tutti e cinque i permessi richiesti
  • Consenso amministrativo non concesso:
  • Tipo di permesso sbagliato: Usa i permessi delegati, non i permessi dell'applicazione

Per una risoluzione dettagliata dei problemi, vedi Registra un'applicazione in Microsoft Entra ID.

Procedure consigliate per la sicurezza

Cosa fare:

  • Usa la registrazione a inquilino singolo
  • Concedere solo i cinque permessi delegati richiesti
  • Autorizzazioni di audit regolarmente
  • Rimuovi l'app quando non è più necessaria

Non farlo:

  • Permessi di concesso di domanda (Usa solo Delegato)
  • Condividi pubblicamente l'ID del cliente
  • Concedere altri permessi non necessari
  • Usa l'app per altri scopi

Passaggi successivi

Ora che hai registrato la tua app client personalizzata, puoi usarla con la CLI Agent 365:

  • Last updated on