Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Registrieren Sie Ihren Agenten, damit er sich mit Microsoft Entra ID authentifizieren und den Zugriff auf APIs anfordern kann. Mit diesem Setup wird eine Identität für Ihren Agent erstellt, die von seinen Installationen oder Replikaten gemeinsam genutzt wird.
Dieses Verfahren verwendet die Microsoft Graph-Betaversion. Konfigurieren Sie für einen Cloud-Agent eine Anmeldeinformation für die Laufzeit. Verwenden Sie für einen Agent, der auf einem Endbenutzergerät installiert ist, die Konfiguration der öffentlichen Clientumleitung ohne Anmeldeinformationen. Ihr Calling-Tutorial identifiziert die benötigten Abschnitte.
Important
Einzelinstanz-Agentidentitäten befinden sich in der Vorschau. Diese Vorschau wird ohne Vereinbarung auf Serviceebene bereitgestellt und wird für Produktionsworkloads nicht empfohlen. Einige Features werden möglicherweise nicht unterstützt oder verfügen über eingeschränkte Funktionen. Weitere Informationen finden Sie unter "Universelle Lizenzbedingungen für Onlinedienste".
Prerequisites
- Ein Microsoft Entra Mandanten, der für die Bereitstellung mit einer Instanz in Microsoft Graph aktiviert ist. Bestätigen Sie die Verfügbarkeit der Vorschau und die Mandantenaktivierung mit Ihrem Microsoft-Ansprechpartner, bevor Sie beginnen. Um Token nach dem Setup anzufordern, vergewissern Sie sich auch, dass die Einzelinstanzauthentifizierung aktiviert ist; Bereitstellung und Authentifizierung sind separat aktiviert.
- Ein Konto, das zum Erstellen und Aktualisieren von Agent-Identitätspausen und Agentidentitäten autorisiert ist, z. B. ein Agent-ID-Administrator.
- Eine separate öffentliche Verwaltungs-App mit einzelinstanzenbasierter Verwaltung mit Administratorzustimmung für die delegierten Microsoft Graph Berechtigungen
AgentIdentityBlueprint.ReadWrite.AllundAgentIdentity.ReadWrite.Alloder die Berechtigung zum Einrichten des Verwaltungsclients. - Ein Administrator, der die Zustimmung zu den Graph-Berechtigungen der Verwaltungs-App erteilen kann.
- Die Objekt-ID eines Benutzers, der als Sponsor des Blueprints zugewiesen werden kann. In den Beispielen wird dieser Benutzer auch als Besitzer festgelegt.
- Bei der interaktiven Anmeldung ist ein Umleitungs-URI für den Clienttyp geeignet. Für die browserbasierte Administratorzustimmung: ein
webUmleitungs-URI, auch wenn der Agent zur Laufzeit nur Clientanmeldeinformationen verwendet. - Für lokale Vertrauliche-Client-Tests, ein X.509-Zertifikat und sicheren Speicher für seinen privaten Schlüssel. Ein in Azure gehosteter Agent kann stattdessen verwaltete Verbundanmeldeinformationen verwenden. Ein nur öffentlicher Client benötigt keine Anmeldeinformationen.
- Für den API-Zugriff werden die Client-ID der Ressourcenanwendung und die IDs der delegierten Berechtigungen oder App-Rollen, die der Agent benötigt, benötigt.
Führen Sie die HTTP-Beispiele wie unten beschrieben über Microsoft Graph PowerShell aus, oder verwenden Sie einen REST-Client, der JSON-Anforderungstexte und Header senden kann. Senden Sie in einem REST-Client das Verwaltungstoken als Bearertoken in der Authorization Kopfzeile jeder Graph-Anforderung. Verwenden Sie niemals das Laufzeitzugriffstoken des Agents für Verwaltungsanforderungen.
Administratorübergabe bestätigen
Bevor Sie Objekte erstellen, stimmen Sie der folgenden Übergabe zu. Die Zustimmung zur Verwaltung und die Api-Zustimmung des Agents sind separate Genehmigungen.
| Wer | Action | Bereit, wenn |
|---|---|---|
| Mandantenadministrator und Microsoft Vertreter. | Vergewissern Sie sich, dass sowohl die Vorschaubereitstellung als auch die Authentifizierung aktiviert sind. | Der Mandant unterstützt Registrierungs- und Tokenanforderungen für dieses Setup. |
| Autorisierter Administrator. | Genehmigen Sie die beiden oben aufgeführten Graph-Berechtigungen des Verwaltungsclients. | Der Operator kann sich bei diesem Client mit beiden genehmigten Scopes anmelden. |
| Entwickler oder autorisierter Operator. | Führen Sie die folgenden Registrierungsschritte aus. | Die Blueprint-Objekt-ID, die Agentidentitätsobjekt-ID und die freigegebene Client-ID werden aufgezeichnet. |
| API-Besitzer und Zustimmungsadministrator. | Geben Sie die API-IDs an, und genehmigen Sie die berechtigungen, die vom aufrufenden Lernprogramm benötigt werden. | Die erforderlichen zur Laufzeit erteilten Berechtigungen werden vor dem ersten API-Aufruf überprüft. |
Senden Sie dem Administrator Ihre Mandanten-ID, Verwaltungsclient-ID und angeforderte API-Berechtigungen. Halten Sie das Arbeitsblatt „Identifier“ bei den Einrichtungsschritten bereit.
Wenn Sie einem lokalen HTTPS-Lernprogramm folgen, vergewissern Sie sich auch, dass das HTTPS-Entwicklungszertifikat auf Ihrem Computer vor der Browseranmeldung als vertrauenswürdig eingestuft wird. Folgen Sie dem Vertrauensprozess Ihrer Organisation, anstatt die TLS-Überprüfung zu deaktivieren.
Einrichten des Verwaltungsclients
Der Verwaltungsclient meldet einen Administrator oder autorisierten Operator an, um die Registrierung des Agents zu erstellen. Sie ist getrennt von der Laufzeitidentität des Agents. Eine vorhandene Azure CLI Anmeldung richtet diesen Verwaltungskontext nicht ein.
Registrieren Sie eine Anwendung im selben Mandanten. Wählen Sie ausschließlich Konten in diesem Organisationsverzeichnis aus. Fügen Sie unter Authentifizierung die Plattform Mobile- und Desktopanwendungen mit der Umleitungs-URI
http://localhosthinzu.Fügen Sie unter API-Berechtigungen diese delegierten Berechtigungen für Microsoft Graph > hinzu:
-
AgentIdentityBlueprint.ReadWrite.All. -
AgentIdentity.ReadWrite.All.
-
Lassen Sie einen autorisierten Administrator die Zustimmung für diese Berechtigungen erteilen. Informationen zur Zustimmung von Administratoren finden Sie unter Berechtigungen und Einwilligung in der Microsoft Identity Platform.
Installieren Sie das Microsoft Graph PowerShell-Authentifizierungsmodul, und melden Sie sich mit der Verwaltungs-App an.
Connect-MgGraphöffnet einen Browser für den angemeldeten Benutzer: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, ScopesVergewissern Sie sich, dass
Account,TenantIdundClientIdden beabsichtigten Bediener, den Mandanten und die Verwaltungs-App kennzeichnen und dassScopesbeide Berechtigungen enthält. Wenn ein Bereich fehlt oder die Zustimmung erneut angefordert wird, beenden Sie den Vorgang, und lassen Sie einen autorisierten Administrator die App-Registrierung und -Zustimmung überprüfen, bevor Sie fortfahren.
Unter Windows verwenden Sie für Ihren benutzerdefinierten Verwaltungsclient die dokumentierte Browseranmeldungsoption, wenn Connect-MgGraph vor der Anmeldung mit Ein Fensterhandle muss konfiguriert werden fehlschlägt:
Set-MgGraphOption -DisableLoginByWAM $true
Führen Sie denselben Connect-MgGraph Befehl erneut aus. Dadurch wird die Authentifizierungs-UI, nicht die Zugriffsanforderungen des Mandanten, geändert; melden Sie sich als autorisierter Operator an und umgehen Sie keine Complianceverweigerung. Die Einstellung wird in PowerShell-Sitzungen beibehalten. Wenn WAM vor dieser Änderung aktiviert wurde, stellen Sie es wieder her Set-MgGraphOption -DisableLoginByWAM $false , wenn Sie fertig sind.
Verwenden Sie Invoke-MgGraphRequest, um die HTTP-Beispiele auszuführen, ohne ein Zugriffstoken zu kopieren oder anzuzeigen. Kopieren Sie z. B. den JSON-Body aus Blueprint erstellen in $body und ersetzen Sie dabei den Sponsor-Platzhalter:
$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
Verwenden Sie für spätere Anforderungen die Methode, den vollständigen URI, die Header und den JSON-Text, der in jedem HTTP-Beispiel angezeigt wird. Lassen Sie -Body bei einer GET-Anforderung weg. Das Modul stellt den Autorisierungsheader bereit. Informationen zur Befehlssyntax finden Sie unter Invoke-MgGraphRequest.
Wenn die Registrierung oder Zustimmung verweigert wird, bitten Sie den Administrator des Mandanten, diese Einrichtung abzuschließen. Erteilen Sie dem Agent diese Verwaltungsberechtigungen nicht, um einen Autorisierungsfehler zu umgehen.
Blueprint erstellen
Der Blueprint ist die Registrierung, die die Authentifizierungseinstellungen und Anmeldeinformationen Ihres Agents enthält.
Erstellen Sie den Blueprint mit
isSingleInstancefestgelegt auftrue. Ersetzen Sie<sponsor-user-object-id>durch die Objekt-ID des Sponsors. Ein Sponsor ist erforderlich; die Besitzerzuweisung ist optional.Behalten Sie
isSingleInstance: truefür dieses Lernprogramm bei: Es erstellt eine Identität für den Agent, einschließlich seiner Installationen oder Replikate. Diese Eigenschaft kann nach der Erstellung nicht mehr geändert werden.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>" ] }Speichern Sie in der
201 CreatedAntwort die folgenden Werte:-
id: Die Objekt-ID des Blueprints, die verwendet wird, um ihn in Microsoft Graph zu adressieren. -
appId: Die Anwendungs-ID (Client-ID), die in OAuth-Anforderungen verwendet wird.
-
Im Beispiel wird ein Einzelmandanten-Blueprint erstellt, bei dem signInAudience auf AzureADMyOrg festgelegt ist.
Bereitstellen der Agentidentität
Erstellen Sie die Identität getrennt von der Blueprint-Registrierung. Folgen Sie der nachstehenden Anweisung direkt; für dieses Setup ist kein Blueprint-Principal erforderlich.
Erstellen Sie die Agent-ID. Setzen Sie auf die
appIddes Blueprints, nicht auf dessenagentIdentityBlueprintId.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>" ] }Speichern Sie die
idder Identität aus der201 CreatedAntwort. Dies ist die Objekt-ID der Agentidentität, nicht die Blueprint-Objekt-ID oder die OAuth-Client-ID.Lesen Sie das Objekt, um das Ergebnis zu überprüfen:
GET https://graph.microsoft.com/beta/servicePrincipals/<agent-identity-object-id>?$select=id,appId,displayName,agentIdentityBlueprintId,instanceModeÜberprüfen Sie die zurückgegebenen Werte:
Property Erwarteter Wert @odata.type#microsoft.graph.agentIdentity.appIdDas appIddes Blueprints.agentIdentityBlueprintIdDie Objekt-ID des Blueprints. instanceModesingleInstance.
Stellen Sie keine neue Identität für jede Installation, jeden Prozess oder jede Benutzersitzung bereit. Sie verwenden dieselbe Client-ID.
Konfigurieren von Umleitungs-URIs
Registrieren Sie für den Autorisierungscodefluss den Umleitungs-URI unter der Plattform, die dem Client entspricht. Ein vertraulicher Client verwendet web; ein öffentlicher Client verwendet publicClient.
Das browserbasierte Administratorzustimmungsverfahren erfordert auch einen web Umleitungs-URI, auch für einen Agent, der zur Laufzeit nur Clientanmeldeinformationen verwendet. Die Umleitungs-URI verarbeitet den Zustimmungs-Callback, nicht die Tokenanforderung für Clientanmeldeinformationen. Überspringen Sie diesen Abschnitt nur, wenn weder autorisierungscodefluss noch browserbasierte Administratorgenehmigung erforderlich ist.
Lesen Sie die aktuelle Umleitungskonfiguration:
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,web,publicClientAktualisieren Sie die entsprechende Umleitungssammlung. Das folgende Beispiel zeigt beide Clienttypen. Schließen Sie nur die Plattformen ein, die Ihr Agent verwendet. Behalten Sie alle vorhandenen Umleitungs-URIs bei, die noch benötigt werden.
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" ] } }Bei erfolgreicher Aktualisierung wird
204 No Contentzurückgegeben. Umleitungs-URI-Auflistungen werden ersetzt, nicht angefügt. Überschreiben Sie eine bestehende Konfiguration nicht mit diesem Beispiel, ohne ihre URIs beizubehalten.
Derselbe Blueprint kann beide Plattformen registrieren. Jede Autorisierungsanforderung verwendet den Umleitungs-URI für den Clienttyp. Ein öffentlicher Client sendet keine Anmeldeinformationen, auch wenn eine vertrauliche Komponente ein Zertifikat auf demselben Blueprint verwendet. Ändern Sie isFallbackPublicClient nicht, um zwischen diesen Autorisierungscodeszenarien zu wechseln.
Hinzufügen eines Zertifikats für vertrauliche Clients
Registrieren Sie bei lokalen Tests vertraulicher Clients nur das öffentliche Zertifikat auf dem Blueprint. Die Laufzeit behält den privaten Schlüssel für die Authentifizierung bei.
Überspringen Sie diesen Abschnitt bei einem ausschließlich öffentlichen Client. Konfigurieren Sie für einen in Azure gehosteten Agent, der den Verbund mit verwalteter Identität verwendet, stattdessen die Verbundanmeldeinformation, und fahren Sie dann mit „API-Berechtigungen deklarieren“ fort.
Für einen Windows Entwicklungscomputer können Sie ein selbstsigniertes Zertifikat erstellen und dessen öffentliches Zertifikat und kennwortgeschützte PFX exportieren. Behalten Sie die PFX außerhalb der Quellstruktur bei. Verwenden Sie das Base64-codierte öffentliche DER-Zertifikat für key unten, nicht die PFX-Datei oder die KOPF- und Fußzeile einer PEM-Datei. Beispiele:
$publicCertificate = Get-PfxCertificate -FilePath "<absolute-path-to-public-cer>"
$publicCertificateBase64 = [Convert]::ToBase64String($publicCertificate.RawData)
Fügen Sie $publicCertificateBase64 in die Registrierungsanforderung ein. Der öffentliche Wert ist keine Anmeldeinformation; die PFX und ihr Kennwort sind es. Verwenden Sie für nicht Windows Entwicklung oder Produktion den Zertifikatausstellungs- und privaten Schlüsselspeicherprozess Ihrer Organisation.
Die aktuelle Zertifikatsammlung lesen:
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,keyCredentialsFügen Sie Ihr öffentliches Zertifikat hinzu, während alle vorhandenen Schlüsselanmeldeinfos beibehalten werden, die noch benötigt werden. Die folgende Anforderung zeigt eine erstregistrierung ohne vorhandene Zertifikate an:
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" } ] }Eine erfolgreiche Aktualisierung liefert
204 No Content. Laden Sie niemals den privaten Schlüssel hoch, oder verteilen Sie ihn mit einem öffentlichen Client.
Informationen zum Zertifikatformat und Hinweise zur Clientassertion finden Sie unter Microsoft Identity Platform-Zertifikatanmeldeinformationen.
Deklarieren Sie die API-Berechtigungen
Deklarieren Sie nur die Berechtigungen, die der Agent benötigt. Wird Scope für eine delegierte Berechtigung und Role für eine Anwendungsberechtigung verwendet. Die Werte in resourceAccess sind Berechtigungs-IDs, die von der Ressourcenanwendung verfügbar gemacht werden, nicht Berechtigungsnamen.
Lesen Sie die aktuellen Deklarationen:
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,requiredResourceAccessFügen Sie die Ressourcen- und Berechtigungseinträge hinzu, wobei vorhandene Deklarationen beibehalten werden, die noch benötigt werden. Das Beispiel zeigt eine delegierte Berechtigung und eine Anwendungsberechtigung; entfernen Sie einen der beiden Einträge, wenn Ihr Agent ihn nicht benötigt.
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" } ] } ] }Ein erfolgreiches Update gibt
204 No Contentzurück.
Diese Deklarationen gewähren keinen Zugriff. Die Zustimmung des Benutzers oder Administrators gewährt delegierte Berechtigungen, und ein Administrator gewährt Anwendungsberechtigungen. Berechtigungen gehören direkt zur Agent-ID.
Wenn der Agent auch Anrufe von einer Front-End-Anwendung empfängt, machen Sie einen Bezeichner-URI und delegierten Scope für den Blueprint verfügbar. Bewahren Sie alle vorhandenen API-Bereiche auf, und setzen Sie requestedAccessTokenVersion auf 2. Das Front-End fordert diesen Scope an, um ein Token abzurufen, dessen Zielgruppe die freigegebene Client-ID ist.
Problembehandlung bei Graph-Anforderungen
Wenn eine Anforderung fehlschlägt, überprüfen Sie den HTTP-Status und die Graph-Fehlerantwort, bevor Sie Berechtigungen ändern oder den Vorgang wiederholen.
| Antwort | Prüfen |
|---|---|
400 Bad Request |
Lesen error.code und error.message. Überprüfen Sie das Anforderungsschema des Endpunkts, erforderliche Sponsorverweise, Objekt-IDs und Eigenschaftswerte. |
401 Unauthorized |
Erwerben Sie ein gültiges Zugriffstoken für Microsoft Graph, und senden Sie es im Authorization-Header. |
403 Forbidden |
Vergewissern Sie sich, dass die Verwaltungs-App über die erforderlichen delegierten Berechtigungen und die Administratorgenehmigung verfügt, der angemeldete Benutzer zur Ausführung des Vorgangs berechtigt ist und der Mandant für die Vorschau aktiviert ist. |
Ausführliche Informationen finden Sie unter Microsoft Graph Fehlerantworten. Wenn Sie sich an einen Administrator oder den Microsoft-Support wenden, geben Sie den HTTP-Status, den Fehlercode und den request-id Antwortheader an. Schließen Sie keine Zugriffstoken oder andere Anmeldeinformationen ein.
Nächster Schritt
Kehren Sie zu dem Lernprogramm zurück, das Sie hier gebracht hat:
- Authentifizieren von Benutzern bei einer ASP.NET Core-Agent-API.
- Rufen Sie eine benutzerdefinierte API als Agent mit ASP.NET Core auf.
- Konfigurieren Sie das Auth SDK-Sidecar.
- Melden Sie sich benutzer von einem Agent auf einem Endbenutzergerät an.
Direkte OAuth-Anforderungen und das Identitätsmodell hinter diesem Setup finden Sie unter Authentifizieren der Instanzmodi für die Agentidentität und die Agent-Identität.