Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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.Alldi Microsoft Graph delegate eAgentIdentity.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.
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 .In Autorizzazioni API aggiungere queste autorizzazioni delegate Microsoft Graph >:
-
AgentIdentityBlueprint.ReadWrite.All. -
AgentIdentity.ReadWrite.All.
-
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.
Installare il modulo di autenticazione di PowerShell Microsoft Graph e accedere con l'app di gestione.
Connect-MgGraphapre 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, ScopesVerificare che
Account,TenantIdeClientIdidentificare l'operatore, il tenant e l'app di gestione previsti e cheScopesincluda 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.
Creare il progetto con
isSingleInstanceimpostato sutrue. Sostituire<sponsor-user-object-id>con l'ID oggetto dello sponsor. Uno sponsor è obbligatorio; l'assegnazione del proprietario è facoltativa.Mantieni
isSingleInstance: trueper 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>" ] }201 CreatedDalla 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.
Creare l'ID agente. Impostare
agentIdentityBlueprintIdsull'ID oggetto del blueprint, non sul relativoappId.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>" ] }Salva
iddell'identità dalla risposta201 Created. Si tratta dell'ID oggetto dell'identità dell'agente, non dell'ID oggetto del blueprint o dell'ID client OAuth.Leggere l'identità per verificare il risultato:
GET https://graph.microsoft.com/beta/servicePrincipals/<agent-identity-object-id>?$select=id,appId,displayName,agentIdentityBlueprintId,instanceModeControllare i valori restituiti:
Property Valore previsto @odata.type#microsoft.graph.agentIdentity.appIdIl appIddel blueprint.agentIdentityBlueprintIdID oggetto del blueprint. instanceModesingleInstance.
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.
Leggere la configurazione di reindirizzamento corrente:
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,web,publicClientAggiornare 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.
Leggere la raccolta di certificati corrente:
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,keyCredentialsAggiungere 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.
Leggere le dichiarazioni correnti:
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,requiredResourceAccessAggiungere 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:
- Autenticare gli utenti in un'API dell'agente ASP.NET Core.
- Chiamare un'API personalizzata come agente con ASP.NET Core.
- Configurare il sidecar Auth SDK.
- Far accedere gli utenti da un agente su un dispositivo dell'utente finale.
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.