Creare un'identità per l'agente con Microsoft Graph (anteprima)

Registra l'agente in modo che possa autenticarsi con Microsoft Entra ID e richiedere l'accesso alle API. Questa configurazione crea un'unica identità per l'agente, condivisa tra le sue installazioni o repliche.

Questa procedura usa Microsoft Graph beta. Per un agente cloud, configurare le credenziali per il runtime. Per un agente installato su un dispositivo dell'utente finale, usa la configurazione di reindirizzamento del client pubblico senza credenziale. L'esercitazione sulle chiamate identifica le sezioni di cui hai bisogno.

Importante

Le identità dell'agente a istanza singola sono in anteprima. Questa anteprima viene fornita senza un contratto di servizio e non è consigliata per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o avere funzionalità vincolate. Per altre informazioni, vedere Condizioni di licenza universali per i servizi online.

Prerequisites

  • Tenant di Microsoft Entra abilitato per il provisioning a istanza singola in Microsoft Graph. Verificare la disponibilità in anteprima e l'abilitazione del tenant con il rappresentante Microsoft prima di iniziare. Per richiedere token dopo l'installazione, verificare anche che l'autenticazione a istanza singola sia abilitata; il provisioning e l'autenticazione vengono abilitati separatamente.
  • Un account autorizzato a creare e aggiornare i progetti di identità dell'agente e le identità dell'agente, ad esempio un Agent ID Administrator.
  • Un'app di gestione pubblica a tenant singolo separata con il consenso dell'amministratore per le autorizzazioni AgentIdentityBlueprint.ReadWrite.All di Microsoft Graph delegate e AgentIdentity.ReadWrite.Allo l'autorizzazione per configurare il client di gestione.
  • Amministratore che può concedere il consenso alle autorizzazioni Graph dell'app di gestione.
  • ID oggetto di un utente che può essere assegnato come sponsor del progetto. Gli esempi assegnano anche l'utente come proprietario.
  • Per l'accesso interattivo, un URI di reindirizzamento appropriato per il tipo di client. Per il consenso dell'amministratore basato su browser, è necessario un URI di reindirizzamento web, anche se l'agente usa solo le credenziali client in fase di esecuzione.
  • Per i test locali del client riservato, sono necessari un certificato X.509 e l'archiviazione sicura della relativa chiave privata. Un agente ospitato in Azure può usare invece una credenziale federata con identità gestita. Un client pubblico non necessita di credenziali.
  • Per l'accesso all'API, l'ID client dell'applicazione risorsa e gli ID delle autorizzazioni delegate o dei ruoli dell'app di cui l'agente ha bisogno.

Eseguire gli esempi HTTP tramite Microsoft Graph PowerShell come descritto di seguito oppure usare un client REST in grado di inviare corpi e intestazioni di richiesta JSON. In un client REST, inviare il token di gestione come token bearer nell'intestazione Authorization di ogni richiesta Graph. Non usare mai il token di accesso di runtime dell'agente per le richieste di gestione.

Confermare l'handoff dell'amministratore

Prima di creare oggetti, accettare il passaggio di consegne seguente. Il consenso amministrativo e il consenso dell'API di runtime dell'agente sono approvazioni separate.

Chi Action Pronto quando
Amministratore tenant e rappresentante Microsoft. Verificare che sia il provisioning in anteprima che l'autenticazione siano abilitati. Il tenant supporta le richieste di registrazione e token per questa configurazione.
Amministratore autorizzato. Approvare le due autorizzazioni graph del client di gestione elencate in precedenza. L'operatore può accedere a tale client con entrambi gli ambiti autorizzati.
Sviluppatore o operatore autorizzato. Completare i passaggi di registrazione seguenti. Vengono registrati l'ID oggetto del blueprint, l'ID oggetto identità dell'agente e l'ID client condiviso.
Proprietario dell'API e amministratore del consenso. Specificare gli identificatori API e approvare le autorizzazioni richieste dall'esercitazione chiamante. Le autorizzazioni runtime necessarie vengono verificate prima della prima chiamata API.

Inviare all’amministratore l'ID tenant, l'ID client di gestione e le autorizzazioni API richieste. Mantenere il foglio di lavoro dell'identificatore insieme ai passaggi di installazione.

Se si segue un'esercitazione HTTPS locale, verificare anche che il certificato HTTPS di sviluppo sia considerato attendibile nel computer prima dell'accesso al browser. Seguire il processo di attendibilità dell'organizzazione anziché disabilitare la convalida TLS.

Configurare il client di gestione

Il client di gestione consente l'accesso a un amministratore o a un operatore autorizzato per creare la registrazione dell'agente. È separato dall'identità di runtime dell'agente. Un accesso interfaccia della riga di comando di Azure esistente non stabilisce questo contesto di gestione.

  1. Registra un'applicazione nello stesso tenant. Seleziona solo gli Account in questa directory organizzativa. In Autenticazione aggiungere la piattaforma applicazioni per dispositivi mobili e desktop con l'URI http://localhostdi reindirizzamento .

  2. In Autorizzazioni API aggiungere queste autorizzazioni delegate Microsoft Graph >:

    • AgentIdentityBlueprint.ReadWrite.All.
    • AgentIdentity.ReadWrite.All.
  3. Chiedere a un amministratore autorizzato di concedere il consenso a queste autorizzazioni. Per informazioni sul consenso dell'amministratore, vedere Autorizzazioni e consenso nella Microsoft Identity Platform.

  4. Installare il modulo di autenticazione di PowerShell Microsoft Graph e accedere con l'app di gestione. Connect-MgGraph apre un browser per l'utente connesso:

    Install-Module Microsoft.Graph.Authentication -Scope CurrentUser
    
    Connect-MgGraph `
      -ClientId "<management-app-client-id>" `
      -TenantId "<tenant-id>" `
      -Scopes "AgentIdentityBlueprint.ReadWrite.All", "AgentIdentity.ReadWrite.All" `
      -ContextScope Process
    
    $context = Get-MgContext
    if (-not $context -or -not $context.Account) {
        throw "Microsoft Graph sign-in didn't establish a delegated management context. Stop before creating objects."
    }
    $context | Select-Object Account, TenantId, ClientId, Scopes
    

    Verificare che Account, TenantIde ClientId identificare l'operatore, il tenant e l'app di gestione previsti e che Scopes includa entrambe le autorizzazioni. Se un ambito manca o viene richiesto di nuovo il consenso, arrestare e chiedere a un amministratore autorizzato di verificare la registrazione e il consenso dell'app prima di continuare.

In Windows, se Connect-MgGraph non riesce prima di eseguire l'accesso con un handle di finestra deve essere configurato, usare l'opzione di accesso del browser documentata per il client di gestione personalizzato:

Set-MgGraphOption -DisableLoginByWAM $true

Eseguire di nuovo lo stesso comando Connect-MgGraph. Questa modifica l'interfaccia utente di autenticazione, non i requisiti di accesso del tenant; completare l'accesso come operatore autorizzato e non ignorare un rifiuto di conformità. L'impostazione persiste tra le sessioni di PowerShell. Se WAM è stato abilitato prima di questa modifica, ripristinarlo al Set-MgGraphOption -DisableLoginByWAM $false termine.

Usare Invoke-MgGraphRequest per eseguire gli esempi HTTP senza copiare o visualizzare un token di accesso. Ad esempio, copiare il corpo JSON da Crea il blueprint in $body, sostituendo il segnaposto sponsor:

$body = @'
<JSON-request-body>
'@

$blueprint = Invoke-MgGraphRequest -Method POST `
    -Uri "https://graph.microsoft.com/beta/applications" `
    -Headers @{ "OData-Version" = "4.0" } `
    -ContentType "application/json" -Body $body

$blueprintObjectId = $blueprint.id
$agentClientId = $blueprint.appId

Per le richieste successive, usare il metodo, l'URI completo, le intestazioni e il corpo JSON visualizzati in ogni esempio HTTP. Omettere -Body per una richiesta GET. Il modulo fornisce l'intestazione di autorizzazione. Per la sintassi dei comandi, vedere Invoke-MgGraphRequest.

Se la registrazione o il consenso viene negato, chiedere all'amministratore del tenant di completare questa configurazione. Non concedere queste autorizzazioni di gestione all'agente per risolvere un errore di autorizzazione.

Creare il blueprint

Il blueprint è la registrazione che contiene le credenziali e le impostazioni di autenticazione dell'agente.

  1. Creare il progetto con isSingleInstance impostato su true. Sostituire <sponsor-user-object-id> con l'ID oggetto dello sponsor. Uno sponsor è obbligatorio; l'assegnazione del proprietario è facoltativa.

    Mantieni isSingleInstance: true per questa esercitazione: crea un'identità per l'agente, incluse le installazioni o le repliche. Questa proprietà non può essere modificata dopo la creazione.

    POST https://graph.microsoft.com/beta/applications
    OData-Version: 4.0
    Content-Type: application/json
    
    {
      "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
      "displayName": "Contoso Operations Agent",
      "signInAudience": "AzureADMyOrg",
      "isSingleInstance": true,
      "sponsors@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>"
      ],
      "owners@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>"
      ]
    }
    
  2. 201 Created Dalla risposta salvare i valori seguenti:

    • id: ID oggetto del blueprint, usato per identificarlo in Microsoft Graph.
    • appId: ID applicazione (client), usato nelle richieste OAuth.

L'esempio crea un progetto a tenant singolo con signInAudience impostato su AzureADMyOrg.

Effettuare il provisioning dell'identità dell'agente

Creare l'identità separatamente dalla registrazione del blueprint. Seguire la richiesta seguente direttamente; questa configurazione non richiede un'entità di progetto.

  1. Creare l'ID agente. Impostare agentIdentityBlueprintId sull'ID oggetto del blueprint, non sul relativo appId.

    POST https://graph.microsoft.com/beta/servicePrincipals/microsoft.graph.agentIdentity
    OData-Version: 4.0
    Content-Type: application/json
    
    {
      "displayName": "Contoso Operations Agent",
      "agentIdentityBlueprintId": "<blueprint-object-id>",
      "sponsors@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>"
      ]
    }
    
  2. Salva id dell'identità dalla risposta 201 Created. Si tratta dell'ID oggetto dell'identità dell'agente, non dell'ID oggetto del blueprint o dell'ID client OAuth.

  3. Leggere l'identità per verificare il risultato:

    GET https://graph.microsoft.com/beta/servicePrincipals/<agent-identity-object-id>?$select=id,appId,displayName,agentIdentityBlueprintId,instanceMode
    

    Controllare i valori restituiti:

    Property Valore previsto
    @odata.type #microsoft.graph.agentIdentity.
    appId Il appId del blueprint.
    agentIdentityBlueprintId ID oggetto del blueprint.
    instanceMode singleInstance.

Non effettuare il provisioning di una nuova identità per ogni installazione, processo o sessione utente. Usano lo stesso ID client.

Configurare gli URI di reindirizzamento

Per il flusso del codice di autorizzazione, registrare l'URI di reindirizzamento nella piattaforma corrispondente al client. Un client riservato usa web; un client pubblico usa publicClient.

La procedura di consenso dell'amministratore basata su browser richiede anche un web URI di reindirizzamento, anche per un agente che usa solo le credenziali client in fase di esecuzione. Il reindirizzamento gestisce il callback di consenso, non la richiesta di token delle credenziali client. Ignora questa sezione solo se non è necessario né il flusso del codice di autorizzazione né il consenso dell'amministratore basato su browser.

  1. Leggere la configurazione di reindirizzamento corrente:

    GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,web,publicClient
    
  2. Aggiornare la raccolta di reindirizzamento appropriata. L'esempio seguente mostra entrambi i tipi di client; includere solo le piattaforme usate dall'agente. Mantenere tutti gli URI di reindirizzamento esistenti ancora necessari.

    PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id>
    OData-Version: 4.0
    Content-Type: application/json
    
    {
      "@odata.type": "#microsoft.graph.agentIdentityBlueprint",
      "web": {
        "redirectUris": [
          "https://agent.contoso.com/signin"
        ]
      },
      "publicClient": {
        "redirectUris": [
          "http://localhost"
        ]
      }
    }
    

    Un aggiornamento riuscito restituisce 204 No Content. Le raccolte URI di reindirizzamento vengono sostituite, non aggiunte. Non copiare questo esempio su una configurazione esistente senza conservarne gli URI.

Lo stesso modello può registrare entrambe le piattaforme. Ogni richiesta di autorizzazione usa l'URI di reindirizzamento per il tipo di client. Un client pubblico non invia credenziali, anche se un componente riservato usa un certificato nello stesso schema. Non cambiare isFallbackPublicClient per passare da questi scenari di codice di autorizzazione.

Aggiungere un certificato per i client confidential

Per i test locali del client riservato, registrare solo il certificato pubblico nel blueprint. Il runtime mantiene la chiave privata per l'autenticazione.

Ignora questa sezione per un client solo pubblico. Per un agente ospitato Azure usando la federazione delle identità gestite, configurare invece le credenziali federate, quindi continuare con Dichiarare le autorizzazioni API.

Per un computer di sviluppo Windows, è possibile creare un certificato autofirmato ed esportare il certificato pubblico e il file PFX protetto da password. Mantieni il file PFX fuori dall'albero del codice sorgente. Usare il certificato pubblico DER con codifica Base64 qui sotto per key, non il PFX né l'intestazione e il piè di pagina di un file PEM. Ad esempio:

$publicCertificate = Get-PfxCertificate -FilePath "<absolute-path-to-public-cer>"
$publicCertificateBase64 = [Convert]::ToBase64String($publicCertificate.RawData)

Incollare $publicCertificateBase64 nella richiesta di registrazione. Il valore pubblico non è una credenziale; pfx e la relativa password sono. Per lo sviluppo o la produzione non Windows, usare il processo di rilascio dei certificati e di archiviazione delle chiavi private dell'organizzazione.

  1. Leggere la raccolta di certificati corrente:

    GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,keyCredentials
    
  2. Aggiungere il certificato pubblico mantenendo le credenziali della chiave esistenti ancora necessarie. La richiesta seguente mostra una registrazione iniziale senza certificati esistenti:

    PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id>
    OData-Version: 4.0
    Content-Type: application/json
    
    {
      "@odata.type": "#microsoft.graph.agentIdentityBlueprint",
      "keyCredentials": [
        {
          "type": "AsymmetricX509Cert",
          "usage": "Verify",
          "key": "<base64-encoded-DER-certificate>",
          "displayName": "Contoso Operations Agent certificate"
        }
      ]
    }
    

    Un aggiornamento riuscito restituisce 204 No Content. Non caricare mai la chiave privata né distribuirla con un client pubblico.

Per indicazioni sul formato del certificato e sull'asserzione client, vedere Microsoft Identity Platform certificate credentials.

Dichiarare le autorizzazioni dell'API

Dichiarare solo le autorizzazioni/permessi di cui l'agente ha bisogno. Usare Scope per un'autorizzazione delegata e Role per un'autorizzazione dell'applicazione. I valori in resourceAccess sono ID autorizzazione esposti dall'applicazione della risorsa, non i nomi delle autorizzazioni.

  1. Leggere le dichiarazioni correnti:

    GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,requiredResourceAccess
    
  2. Aggiungere le voci di risorsa e autorizzazione, mantenendo le dichiarazioni esistenti ancora necessarie. L'esempio mostra un'autorizzazione delegata e un'autorizzazione dell'applicazione; rimuovere una delle due voci se l'agente non ne ha bisogno.

    PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id>
    OData-Version: 4.0
    Content-Type: application/json
    
    {
      "@odata.type": "#microsoft.graph.agentIdentityBlueprint",
      "requiredResourceAccess": [
        {
          "resourceAppId": "<resource-app-id>",
          "resourceAccess": [
            {
              "id": "<delegated-permission-id>",
              "type": "Scope"
            },
            {
              "id": "<app-role-id>",
              "type": "Role"
            }
          ]
        }
      ]
    }
    

    Un aggiornamento riuscito restituisce 204 No Content.

Queste dichiarazioni non concedono l'accesso. Il consenso dell'utente o dell'amministratore concede autorizzazioni delegate e un amministratore concede autorizzazioni applicazione. Le autorizzazioni appartengono direttamente all'ID agente.

Se l'agente riceve anche chiamate da un'applicazione front-end, esporre un URI identificatore e un ambito delegato nel blueprint. Mantenere eventuali ambiti API esistenti e impostare requestedAccessTokenVersion su 2. Il front-end richiede tale ambito per ottenere un token il cui gruppo di destinatari è l'ID client condiviso.

Risolvere i problemi delle richieste Graph

Se una richiesta ha esito negativo, esaminare lo stato HTTP e la risposta di errore graph prima di modificare le autorizzazioni o ripetere l'operazione.

Risposta Seleziona
400 Bad Request Leggere error.code e error.message. Controllare lo schema delle richieste dell'endpoint, i riferimenti sponsor obbligatori, gli ID oggetto e i valori delle proprietà.
401 Unauthorized Acquisire un token di accesso valido per Microsoft Graph e inviarlo nell'intestazione Authorization.
403 Forbidden Verificare che l'app di gestione disponga delle autorizzazioni delegate necessarie e del consenso amministratore, che l'utente connesso sia autorizzato per l'operazione e che il tenant sia abilitato per l'anteprima.

Per informazioni dettagliate, vedere risposte di errore di Microsoft Graph. Quando si contatta un amministratore o il supporto Microsoft, includere lo stato HTTP, il codice di errore e request-id l'intestazione della risposta. Non includere token di accesso o altre credenziali.

Passaggio successivo

Torna all'esercitazione che ti ha portato qui:

Per le richieste OAuth dirette e il modello di identità alla base di questa configurazione, vedere Autenticare l'identità dell'agente e Modalità di istanza del progetto dell'identità dell'agente.