Erstellen Sie mit Microsoft Graph eine Identität für Ihren Agenten (Vorschau)

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.All und AgentIdentity.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 web Umleitungs-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.

  1. 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://localhost hinzu.

  2. Fügen Sie unter API-Berechtigungen diese delegierten Berechtigungen für Microsoft Graph > hinzu:

    • AgentIdentityBlueprint.ReadWrite.All.
    • AgentIdentity.ReadWrite.All.
  3. 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.

  4. 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, Scopes
    

    Vergewissern Sie sich, dass Account, TenantId und ClientId den beabsichtigten Bediener, den Mandanten und die Verwaltungs-App kennzeichnen und dass Scopes beide 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.

  1. Erstellen Sie den Blueprint mit isSingleInstance festgelegt auf true. Ersetzen Sie <sponsor-user-object-id> durch die Objekt-ID des Sponsors. Ein Sponsor ist erforderlich; die Besitzerzuweisung ist optional.

    Behalten Sie isSingleInstance: true fü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>"
      ]
    }
    
  2. Speichern Sie in der 201 Created Antwort 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.

  1. Erstellen Sie die Agent-ID. Setzen Sie auf die appId des Blueprints, nicht auf dessen agentIdentityBlueprintId.

    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. Speichern Sie die id der Identität aus der 201 Created Antwort. Dies ist die Objekt-ID der Agentidentität, nicht die Blueprint-Objekt-ID oder die OAuth-Client-ID.

  3. 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.
    appId Das appId des Blueprints.
    agentIdentityBlueprintId Die Objekt-ID des Blueprints.
    instanceMode singleInstance.

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.

  1. Lesen Sie die aktuelle Umleitungskonfiguration:

    GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,web,publicClient
    
  2. Aktualisieren 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 Content zurü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.

  1. Die aktuelle Zertifikatsammlung lesen:

    GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,keyCredentials
    
  2. Fü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.

  1. Lesen Sie die aktuellen Deklarationen:

    GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,requiredResourceAccess
    
  2. Fü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 Content zurü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:

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.