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

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):

• Standardmäßig kann jeder Benutzer im Tenant Anwendungen im Microsoft Entra Admin Center registrieren. Mieteradministratoren können diese Möglichkeit jedoch einschränken.

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

• Eine dieser Verwaltungsrollen ist erforderlich:
  • Anwendungsadministrator: Empfohlen – kann App-Registrierungen verwalten und Zustimmung erteilen
  • Cloud-Anwendungsadministrator: Kann App-Registrierungen verwalten und Zustimmung erteilen
  • Globaler Administrator: Hat alle Berechtigungen, ist aber nicht erforderlich.

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.

Schritt 3: API-Berechtigungen konfigurieren

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.

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.

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.

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

Beta-Berechtigungen verschwinden nach der Zustimmung des Microsoft Entra-Verwaltungszentrums-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:
  • Wenn Sie Option A (nur Microsoft Entra Admin Center) verwendet haben: Wählen Sie Administrator-Erlaubnis im Microsoft Entra Admin Center
  • Wenn Sie Option B (Graph API) verwendet haben: Führen Sie die POST oder PATCH Anfrage erneut aus. Benutzen Sie denEinwilligungsbutton für das Microsoft Entra Admin-Center NICHT.
• 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:

• Fang mit der Agent 365 CLI an – Installiere und konfiguriere die CLI mit deiner Client-App
• Agenten-Blueprint und Instanz einrichten – Erstellen und konfigurieren Sie Ihre Agentenidentität
• Agenten deployen und veröffentlichen – Deployen Sie Ihren Agenten in Azure und veröffentlichen Sie ihn in Microsoft 365