Freigeben über

Registrierung einer benutzerdefinierten Client-App für Agent 365 CLI

Von Bedeutung

Sie müssen Teil des Frontier-Vorschauversionsprogramms sein, um Vorabzugriff auf Microsoft Agent 365 zu erhalten. Frontier verbindet Sie direkt mit den neuesten KI-Innovationen von Microsoft. Frontier-Vorschauversionen unterliegen den bestehenden Vorschauversionsbedingungen Ihrer Kundenvereinbarungen. Da sich diese Funktionen noch in der Entwicklung befinden, können sich ihre Verfügbarkeit und Merkmale im Laufe der Zeit ändern.

Die Agent 365 CLI erfordert eine benutzerdefinierte Client-App-Registrierung in Ihrem Microsoft Entra-ID-Mieter, um die Agent Identity Blueprints zu authentifizieren und zu verwalten.

Voraussetzungen

Zur Registrierung der App (Schritte 1 und 2):

Um Berechtigungen hinzuzufügen und Zustimmung zu erteilen (Schritt 3):

Tipp

Haben Sie keinen Admin-Zugriff? Sie können die Schritte 1-2 selbst abschließen und dann Ihren Mieteradministrator bitten, Schritt 3 zu erfüllen. Gib ihnen deine Anwendungs-(Client-)ID aus Schritt 2 und einen Link zum Abschnitt API-Berechtigungen konfigurieren .

Schritt 1: Antrag registrieren

Diese Anweisungen fassen die vollständigen Anweisungen zur Erstellung einer App-Registrierung zusammen.

  1. Gehe zum Microsoft Entra Admin Center
  2. App-Registrierungen auswählen
  3. Wählen Sie Neue Registrierung aus.
  4. Eintreten:
    • Name: Agent365 CLI (oder Ihr bevorzugter Name)
    • Unterstützte Kontotypen: Konten nur in diesem Organisationsverzeichnis (Einzelmieter)
    • URI: Wählen Sie Public Client/native (mobil & Desktop) → Enter http://localhost:8400/
  5. Wählen Sie Registrieren aus.

Schritt 2: Kopiere die Anwendungs-(Client-)ID

Von der Übersichtsseite der App kopieren Sie die Application (Client) ID (GUID-Format). Geben Sie diesen Wert ein, wenn Sie den a365 config init Befehl verwenden.

Tipp

Verwechsle diesen Wert nicht mit der Objekt-ID – du brauchst die Anwendungs-(Client-)ID.

Schritt 3: API-Berechtigungen konfigurieren

Von Bedeutung

Für diesen Schritt sind Administratorrechte erforderlich. Wenn du Entwickler ohne Administratorzugriff bist, sende deine Anwendungs-(Client-)ID von Schritt 2 an deinen Mieteradministrator und lass ihn Schritt 3 ausfüllen.

Hinweis

Stand Dezember 2025 sind die beiden AgentIdentityBlueprint.* Berechtigungen Beta-APIs und möglicherweise nicht im Microsoft Entra-Verwaltungszentrum sichtbar. Wenn diese Berechtigungen in Ihrem Mieter allgemein verfügbar sind, können Sie Option A für alle Berechtigungen verwenden.

Wählen Sie die passende Methode:

  • Option A: Nutze das Microsoft Entra Admin Center für alle Berechtigungen (sofern die Beta-Berechtigungen sichtbar sind)
  • Option B: Verwenden Sie die Microsoft Graph API, um alle Berechtigungen hinzuzufügen (empfohlen, falls die Beta-Berechtigungen nicht sichtbar sind)

Option A: Microsoft Entra Verwaltungszentrum (Standardmethode)

Verwenden Sie diese Methode, wenn Beta-Berechtigungen in Ihrem Tenant sichtbar sind.

  1. Gehe in deiner App-Registrierung zu API-Berechtigungen

  2. Wählen Sie Berechtigung hinzufügen → Microsoft Graph → Delegierte Berechtigungen

    Von Bedeutung

    Du MUSST delegierte Berechtigungen verwenden (KEINE Anwendungsberechtigungen). Die CLI authentifiziert sich interaktiv – du meldest dich an, und es handelt in deinem Namen. Siehe Falscher Berechtigungstyp, wenn du versehentlich Anwendungsberechtigungen hinzufügst.

  3. Fügen Sie diese fünf Berechtigungen nacheinander hinzu:

    Erlaubnis Zweck
    AgentIdentityBlueprint.ReadWrite.All Verwaltung der Agenten-Blueprint-Konfigurationen (Beta-API)
    AgentIdentityBlueprint.UpdateAuthProperties.All Update Agent Blueprint vererbbare Berechtigungen (Beta-API)
    Application.ReadWrite.All Erstellen und verwalten Sie Anwendungen und Agenten-Blueprints
    DelegatedPermissionGrant.ReadWrite.All Erteile Berechtigungen für Agenten-Blueprints
    Directory.Read.All Verzeichnisdaten zur Validierung lesen

    Für jede Berechtigung:

    • Geben Sie im Suchfeld den Berechtigungsnamen ein (zum Beispiel, AgentIdentityBlueprint.ReadWrite.All)
    • Kreuze das Kästchen neben der Berechtigung an
    • Wählen Sie Berechtigungen hinzufügen aus.
    • Wiederhole das für alle fünf Berechtigungen

  4. Wählen Sie Administrator-Erlaubnis für [Ihr Mieter]

    • Warum ist das erforderlich? Agent Identity Blueprints sind tenant-weite Ressourcen, auf die mehrere Benutzer und Anwendungen zugreifen können. Ohne die Zustimmung des gesamten Mieters scheitert die CLI während der Authentifizierung.
    • Was, wenn es scheitert? Sie benötigen die Rolle Application Administrator, Cloud Application Administrator oder Global Administrator. Bitte deine Mieterverwaltung um Hilfe.

  5. Überprüfen Sie, ob alle Berechtigungen grüne Häkchen unter Status anzeigen

Wenn die Beta-Berechtigungen (AgentIdentityBlueprint.*) nicht sichtbar sind, gehe zu Option B.

Option B: Microsoft Graph API (für Beta-Berechtigungen)

Verwenden Sie diese Methode, wenn AgentIdentityBlueprint.* die Berechtigungen im Microsoft Entra Verwaltungszentrum nicht sichtbar sind.

Warnung

Wenn Sie diese API-Methode verwenden, verwenden Sie danach NICHT den Button "Administrator-Zustimmung erteilen" im Microsoft Entra Admin Center . Die API-Methode gewährt automatisch die Zustimmung des Administrators, und die Nutzung des Microsoft Entra-Admin-Center-Buttons löscht deine Beta-Berechtigungen. Siehe Beta-Berechtigungen verschwinden für Details.

  1. Open Graph Explorer

  2. Melden Sie sich mit Ihrem Admin-Konto an (Anwendungsadministrator oder Cloud-Anwendungsadministrator)

  3. Erteile die Genehmigung des Administrators über die Graph API. Um dies abzuschließen, benötigen Sie:

    • Service principal ID. Du brauchst einen variablen SP_OBJECT_ID Wert.
    • Graph-Ressourcen-ID. Du brauchst einen variablen GRAPH_RESOURCE_ID Wert.
    • Erstellen (oder aktualisieren) delegierte Berechtigungen mit dem Ressourcentyp oAuth2PermissionGrant mit den Variablenwerten und GRAPH_RESOURCE_ID den SP_OBJECT_ID Variablen.

Nutzen Sie die Informationen in den folgenden Abschnitten, um dies abzuschließen.

Hol dir deine Dienstleitungs-ID

Ein Service Principal ist die Identität Ihrer App in Ihrem Tenant, die vor der Erteilung von Berechtigungen über die API erforderlich ist.

  1. Stelle die Graph Explorer-Methode auf GET ein und nutze diese URL (ersetzen <YOUR_CLIENT_APP_ID> Sie sie durch Ihre tatsächliche Anwendungs-Client-ID aus Schritt 2: Anwendungs-(Client-)ID kopieren):

    https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '<YOUR_CLIENT_APP_ID>'&$select=id

  2. Wählen Sie "Abfrage ausführen" aus.

    • Wenn die Abfrage erfolgreich ist, ist der zurückgegebene Wert dein SP_OBJECT_ID.

    • Wenn die Abfrage mit einem Berechtigungsfehler fehlschlägt, wähle den Reiter Berechtigungen ändern , erteile die erforderlichen Berechtigungen und wähle dann erneut Abfrage ausführen . Der zurückgegebene Wert ist dein SP_OBJECT_ID.

    • Wenn die Abfrage leere Ergebnisse ("value": []) liefert, erstelle den Service-Principal mit den folgenden Schritten:

      1. Stelle die Methode auf POST ein und verwende diese URL:

        https://graph.microsoft.com/v1.0/servicePrincipals

        Anfrage-Body (ersetzen YOUR_CLIENT_APP_ID Sie durch Ihre tatsächliche Anwendungs-Client-ID):

        {
   "appId": "YOUR_CLIENT_APP_ID"
}

      2. Wählen Sie "Abfrage ausführen" aus. Du solltest eine Antwort 201 Created bekommen. Der zurückgegebene id Wert ist dein SP_OBJECT_ID.

Hol dir deine Graph-Ressourcen-ID

  1. Setzen Sie die Graph Explorer-Methode auf GET und verwenden Sie diese URL:

    https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=id

  2. Wählen Sie "Abfrage ausführen" aus.

    • Wenn die Abfrage erfolgreich ist, kopieren Sie den Wert id . Das ist dein GRAPH_RESOURCE_ID.
    • Wenn die Abfrage mit einem Berechtigungsfehler fehlschlägt, wähle den Reiter Berechtigungen ändern , erteile die erforderlichen Berechtigungen und wähle dann erneut Abfrage ausführen . Kopieren Sie den id-Wert. Das ist dein GRAPH_RESOURCE_ID.

Delegierte Berechtigungen erstellen

Dieser API-Aufruf gewährt tenant-weite Administratorzustimmung für alle fünf Berechtigungen, einschließlich der beiden Beta-Berechtigungen, die im Microsoft Entra Admin Center nicht sichtbar sind.

  1. Setzen Sie die Graph Explorer-Methode auf POST und verwenden Sie diese URL und diesen Anforderungskörper:

    https://graph.microsoft.com/v1.0/oauth2PermissionGrants

    Anfrage-Teil:

    {
"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. Wählen Sie "Abfrage ausführen" aus.

    • Wenn du eine Antwort bekommst201 Created: Erfolg! Das Feld scope in der Antwort zeigt alle fünf Berechtigungsnamen. Sie sind fertig.
    • Wenn die Abfrage mit einem Berechtigungsfehler fehlschlägt (wahrscheinlich), DelegatedPermissionGrant.ReadWrite.Allwähle den Reiter Berechtigungen ändern , gefiel in DelegatedPermissionGrant.ReadWrite.All, und wähle dann erneut Abfrage ausführen .
    • Wenn du Fehler Request_MultipleObjectsWithSameKeyValuebekommst: Es gibt bereits einen Zuschuss. Vielleicht hat jemand früher Berechtigungen hinzugefügt. Siehe das folgende Update delegierte Berechtigungen.

Warnung

Die consentType: "AllPrincipals" in der POST Anfrage gewährt bereits eine tenant-weite administrative Einwilligung. Wählen Sie im Microsoft Entra Admin Center NICHT "Gewähre Administrator-Einwilligung" aus, nachdem Sie diese API-Methode verwendet haben – dadurch werden Ihre Beta-Berechtigungen gelöscht, weil das Microsoft Entra Admin Center die Beta-Berechtigungen nicht sehen kann und Ihre API-gewährte Zustimmung nur mit den sichtbaren Berechtigungen überschreibt.

Delegierte Berechtigungen aktualisieren

Wenn Sie einen Request_MultipleObjectsWithSameKeyValue Fehler bei den Schritten zur Erstellung delegierter Berechtigungen erhalten, verwenden Sie diese Schritte, um die delegierten Berechtigungen zu aktualisieren.

  1. Setzen Sie die Graph Explorer-Methode auf GET und verwenden Sie diese URL:

    https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'SP_OBJECT_ID_FROM_ABOVE'

  2. Wählen Sie "Abfrage ausführen" aus. Kopieren Sie den id-Wert aus der Antwort. Das ist YOUR_GRANT_ID.

  3. Setze die Graph Explorer-Methode auf PATCH und verwende diese URL mit YOUR_GRANT_ID.

    https://graph.microsoft.com/v1.0/oauth2PermissionGrants/<YOUR_GRANT_ID>

    Anfrage-Teil:

    {
   "scope": "Application.ReadWrite.All Directory.Read.All DelegatedPermissionGrant.ReadWrite.All AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All"
}

  4. Wählen Sie "Abfrage ausführen" aus. Du solltest eine 200 OK Antwort mit allen fünf Berechtigungen im Feld scope erhalten.

Problembehandlung

Dieser Abschnitt enthält Informationen darüber, wie man Fehler bei der Registrierung einer benutzerdefinierten Client-App behebt.

Falscher Berechtigungstyp (Delegiert vs. Anwendung)

Symptom: CLI scheitert bei Authentifizierungsfehlern oder fehlerfreien Berechtigungsfehlern.

Ursache: Du hast Anwendungsberechtigungen statt delegierter Berechtigungen hinzugefügt.

Berechtigungstyp Wann verwendet werden soll Wie Agent 365 CLI es nutzt
Delegiert ("Scope") Der Nutzer meldet sich interaktiv an Agent 365 CLI verwendet dies – Sie melden sich an, CLI handelt in Ihrem Namen
Bewerbung ("Rolle") Der Dienst läuft ohne Benutzer Nicht verwenden – Nur für Hintergrunddienste/Dämonen

Warum delegiert?

  • Sie melden sich interaktiv an (Browser-Authentifizierung)
  • Die CLI führt Aktionen während dir aus (Audit-Trails zeigen deine Identität)
  • Sicherer – begrenzt durch deine tatsächlichen Berechtigungen
  • Gewährleistet Verantwortlichkeit und Einhaltung

Lösung:

  1. Gehe zu Microsoft Entra Admin Center>App-Registrierungen>Deine App-API-Berechtigungen>
  2. Entfernen Sie alle Anwendungsberechtigungen (diese werden in der Typ-Spalte als "Anwendung" angezeigt)
  3. Fügen Sie dieselben Berechtigungen hinzu wie delegierte Berechtigungen
  4. Erteile erneut die Zustimmung des Administrators

Symptom: Du hast Option B: Microsoft Graph API (für Beta-Berechtigungen) verwendet, um Beta-Berechtigungen hinzuzufügen, aber diese sind verschwunden, nachdem ich im Microsoft Entra-Verwaltungszentrum die Administrator-Genehmigung gewähren wollte.

Hauptursache: Das Microsoft Entra Admin Center zeigt keine Beta-Berechtigungen in der Benutzeroberfläche an, sodass beim Auswählen von Administrator-Erlaubnis nur die sichtbaren Berechtigungen gewährt werden und die API-gewährte Zustimmung überschreibt.

Warum dies geschieht:

  1. Du nutzt die Graph-API (Option B), um alle fünf Berechtigungen einschließlich Beta-Berechtigungen hinzuzufügen
  2. Der API-Aufruf gewährt consentType: "AllPrincipals"bereits die tenant-weite Administratorzustimmung
  3. Du gehst ins Microsoft Entra Verwaltungszentrum und siehst nur drei Berechtigungen, weil die Beta-Berechtigungen unsichtbar sind
  4. Du wählst Administrator-Genehmigung gewähren , weil du denkst, du musst
  5. Das Microsoft Entra Admin Center überschreibt deine von der API erteilte Zustimmung mit nur den drei sichtbaren Berechtigungen
  6. Deine beiden Beta-Berechtigungen sind jetzt gelöscht

Lösung:

  • Verwenden Sie niemals die Microsoft Entra-Admin-Center-Admin-Genehmigung nach der API-Methode: Die API-Methode gewährt bereits die Administrator-Einwilligung
  • Wenn du versehentlich die Beta-Berechtigungen gelöscht hast, führe Option B Schritt 3 (Administrator-Erlaubnis über die Graph-API erteilen) erneut aus, um sie wiederherzustellen. Du bekommst einen Request_MultipleObjectsWithSameKeyValue Fehler – folge den Schritten zur Aktualisierung delegierter Berechtigungen.
  • Überprüfen Sie das Feld scope in der POST oder PATCH Antwort, um sicherzustellen, dass alle fünf Berechtigungen aufgeführt sind

Überprüfungsfehler

Die CLI validiert deine Client-App automatisch beim Ausführen a365 setup oder a365 config init.

Häufige Probleme:

  • App nicht gefunden: Überprüfen Sie, ob Sie die Anwendungs-(Client-)ID kopiert haben (nicht die Objekt-ID)
  • Fehlende Berechtigungen: Fügen Sie alle fünf erforderlichen Berechtigungen hinzu
  • Admin-Zustimmung nicht erteilt:
  • Falscher Berechtigungstyp: Verwenden Sie delegierte Berechtigungen, keine Anwendungsberechtigungen

Für detaillierte Fehlerbehebung siehe Anmeldung einer Anwendung in Microsoft Entra ID.

Bewährte Sicherheitsmethoden

Führen Sie folgendes aus:

  • Verwendung der Einzel-Mieter-Registrierung
  • Gewähren Sie nur die fünf erforderlichen delegierten Genehmigungen
  • Überprüfen Sie regelmäßig die Genehmigungen
  • Entferne die App, wenn sie nicht mehr gebraucht wird

Nicht:

  • Anwendungsberechtigungen gewähren (nur delegiert verwenden)
  • Teile die Client-ID öffentlich
  • Erteile weitere unnötige Genehmigungen
  • Nutze die App für andere Zwecke

Nächste Schritte

Jetzt, da Sie Ihre individuelle Client-App registriert haben, können Sie sie mit der Agent 365 CLI verwenden:

  • Last updated on