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

Die Agent 365 CLI benötigt eine benutzerdefinierte Client-App-Registrierung in Ihrem Microsoft Entra ID Mandanten, um Agent Identity Blueprints zu authentifizieren und zu verwalten.

Dieser Artikel unterteilt den Prozess in vier Hauptschritte:

1. Registrierungsantrag
2. Stellen Sie die Redirect-URI ein
3. Anwendungs-(Client-)ID kopieren
4. Konfigurieren von API-Berechtigungen

Wenn Sie Probleme haben, sehen Sie sich den Abschnitt zur Fehlerbehebung an.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Zugriff auf Microsoft Entra Admin Center haben und bei Bedarf eine der erforderlichen Administratorrollen, um die Zustimmung zu erteilen.

Um die App zu registrieren

Standardmäßig kann jeder Benutzer im Mandanten Anwendungen registrieren im Microsoft Entra Admin Center. Mieteradministratoren können diese Möglichkeit jedoch einschränken. Wenn du deine App nicht registrieren kannst, kontaktiere deinen Administrator.

Berechtigungen hinzufügen und Zustimmung erteilen

Du brauchst eine dieser Verwaltungsrollen für 4. Konfigurieren Sie API-Berechtigungen.

• 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.

1. Anmeldeantrag

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

1. Wechseln Sie zu Microsoft Entra Admin Center

2. Wählen Sie App-Registrierungen

3. Wählen Sie Neue Registrierung aus.

4. Geben Sie Folgendes ein:

   • Name: Geben Sie einen sinnvollen Namen für Ihre App ein, zum Beispiel my-agent-app. App-Benutzer sehen diesen Namen, und Sie können ihn jederzeit ändern. Sie können mehrere App-Registrierungen mit demselben Namen haben.

     Tipp

     Wenn Sie den konfigurationsfreien a365 setup all --agent-name Fluss verwenden möchten, benennen Sie die App genau Agent 365 CLI. Die CLI sucht die Client-App automatisch anhand dieses bekannten Anzeigenamens, sodass Sie die Client-ID nicht in eine Konfigurationsdatei kopieren müssen.

   • Unterstützte Kontotypen:Nur Konten in diesem Organisationsverzeichnis (einzelner Mandant)

   • Umleitungs-URI: Wählen Sie Public-Client/Native (Mobil- und Desktopgeräte) und geben Sie ein http://localhost:8400/

5. Wählen Sie Registrieren aus.

Für die CLI sind insgesamt drei Umleitungs-URIs erforderlich. Die CLI fügt automatisch alle fehlenden Elemente hinzu, wenn Sie ausführen a365 config init oder a365 setup requirements:

Weitere Informationen finden Sie unter "Informationen zur automatischen Konfiguration der CLI ".

2. Setzen Sie die Umleitungs-URI ein

1. Gehe zur Übersicht und kopiere den Wert der Anwendungs-(Client-)ID .
2. Gehe zu Authentifizierung (Vorschau) und wähle "Redirect-URI hinzufügen".
3. Wählen Sie Mobile- und Desktopanwendungen aus, und legen Sie den Wert auf ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id} fest, wobei {client-id} der Application (Client-ID) Wert ist, den Sie kopiert haben.
4. Wähle Konfigurieren, um den Wert hinzuzufügen.

3. Anwendungs-(Client-)ID kopieren

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

4. API-Berechtigungen konfigurieren

Wählen Sie die passende Methode:

• Option A: Für alle Berechtigungen Microsoft Entra Admin Center verwenden (wenn Betaberechtigungen sichtbar sind)
• Option B: Verwenden Sie Microsoft Graph-API, um alle Berechtigungen hinzuzufügen (empfohlen, wenn Betaberechtigungen nicht sichtbar sind)

Option A: Microsoft Entra Admin Center (Standardmethode)

Verwenden Sie diese Methode, wenn Beta-Berechtigungen in Ihrem Mandanten angezeigt werden.

1. Wechseln Sie in Ihrer App-Registrierung zu API-Berechtigungen.

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

   Von Bedeutung

   Sie müssen delegierte Berechtigungen (nicht Anwendungsberechtigungen) verwenden. Die CLI authentifiziert sich interaktiv – du meldest dich an, und es handelt in deinem Namen. Weitere Informationen finden Sie unter "Falscher Berechtigungstyp".

3. Fügen Sie die folgenden zwölf Berechtigungen einzeln hinzu:

   Erlaubnis	Zweck
   AgentIdentityBlueprintPrincipal.Create	Erstellen des Agent Blueprint-Dienstprincipals (Beta-API)
   AgentIdentityBlueprint.ReadWrite.All	Verwaltung der Agenten-Blueprint-Konfigurationen (Beta-API)
   AgentIdentityBlueprint.UpdateAuthProperties.All	Update Agent Blueprint vererbbare Berechtigungen (Beta-API)
   AgentIdentityBlueprint.AddRemoveCreds.All	Hinzufügen oder Entfernen von geheimen Clientschlüsseln und Verbundidentitätsanmeldeinformationen für Blueprints (Beta-API)
   AgentIdentityBlueprint.DeleteRestore.All	Löschen von Agent-Blueprint-Anwendungen während der Bereinigung (Beta-API)
   AgentInstance.ReadWrite.All	Registrieren und Verwalten von Agentinstanzen über die Agentregistrierungs-API (Beta-API)
   AgentIdentity.Create.All	Erstellen von Agentidentitäten aus Blueprints (Beta-API)
   AgentIdentity.DeleteRestore.All	Löschen von Agentidentitätsdienstprinzipale während der Bereinigung (Beta-API)
   AgentRegistrations.ReadWrite.All	Registrieren und Verwalten von Agents über die Agentregistrierungs-API (Beta-API)
   DelegatedPermissionGrant.ReadWrite.All	Erteile Berechtigungen für Agentenentwürfe
   Directory.Read.All	Verzeichnisdaten zur Validierung lesen
   User.Read	Lesen des angemeldeten Benutzerprofils für die Zuweisung des Blueprint-Besitzers

   Hinweis

   AgentRegistrations.ReadWrite.All ist für die Agenteinrichtung erforderlich. Die CLI erwirbt diese Berechtigung im Hintergrund .default , und der Agent 365 CLI-Validator überprüft sie nicht explizit, muss aber in Ihrer App-Registrierung vorhanden sein und die Administratorzustimmung erteilt haben.

   Für jede Berechtigung:

   • Geben Sie im Suchfeld den Berechtigungsnamen ein (zum Beispiel AgentIdentityBlueprint.ReadWrite.All).
   • Haken Sie das Kontrollkästchen neben der Berechtigung an.
   • Wählen Sie "Berechtigungen hinzufügen" aus.
   • Wiederholen Sie diesen Vorgang für alle zwölf Berechtigungen.

4. Wählen Sie Administratoreinwilligung gewähren für [Ihr Mandant] aus.

   • 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, dass alle Berechtigungen grüne Häkchen unter Status anzeigen.

Wenn die Betaberechtigungen (AgentIdentityBlueprint.*) nicht sichtbar sind, fahren Sie mit Option B fort.

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

Verwenden Sie diese Methode, wenn im Microsoft Entra Admin Center keine AgentIdentityBlueprint.* Berechtigungen angezeigt werden.

1. Öffne den Graph Explorer.

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

3. Erteilen Sie der Administratorzustimmung mithilfe von Graph-API. Um diesen Schritt abzuschließen, benötigen Sie Folgendes:

   • Dienstprinzipal-ID. Du brauchst einen variablen SP_OBJECT_ID Wert.
   • Graph-Ressourcen-ID. Du brauchst einen variablen GRAPH_RESOURCE_ID Wert.
   • Delegierte Berechtigungen erstellen (oder aktualisieren), indem Sie den Ressourcentyp oAuth2PermissionGrant durch die Verwendung der Variablenwerte SP_OBJECT_ID und GRAPH_RESOURCE_ID verwenden.

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

Hol dir deine Serviceprinzipal-ID

Ein Dienstprinzipal ist die Identität Ihrer App in Ihrem Mandanten. Du brauchst es, bevor du Berechtigungen über die API erteilen kannst.

1. Setze die Graph Explorer-Methode auf GET und nutze diese URL. Ersetzen Sie <YOUR_CLIENT_APP_ID> durch Ihre tatsächliche Anwendungs-Client-ID aus Schritt 3: Kopiere die Anwendungs-(Client-)ID:

   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, erstellen Sie den Service-Principal durch folgende Schritte:

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

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

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

        {
           "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 . Dieser Wert 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. Dieser Wert ist dein GRAPH_RESOURCE_ID.

Delegierte Berechtigungen erstellen

Dieser API-Aufruf gewährt mandantenweite Administratorzustimmungen für alle zwölf Berechtigungen, einschließlich der Betaberechtigungen, die in 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": "AgentIdentityBlueprintPrincipal.Create AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All AgentIdentityBlueprint.AddRemoveCreds.All AgentIdentityBlueprint.DeleteRestore.All AgentInstance.ReadWrite.All AgentIdentity.Create.All AgentIdentity.DeleteRestore.All AgentRegistrations.ReadWrite.All DelegatedPermissionGrant.ReadWrite.All Directory.Read.All User.Read"
   }
   

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

   • Wenn du eine Antwort bekommst201 Created: Erfolg! Das scope Feld in der Antwort zeigt alle zwölf Berechtigungsnamen an. Sie sind fertig.
   • Wenn die Abfrage mit einem Berechtigungsfehler fehlschlägt (wahrscheinlich), DelegatedPermissionGrant.ReadWrite.Allwähle den Reiter Berechtigungen ändern , genehmige , DelegatedPermissionGrant.ReadWrite.Allund 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 die folgende Aktualisierung der delegierten Berechtigungen.

Delegierte Berechtigungen aktualisieren

Wenn Sie einen Request_MultipleObjectsWithSameKeyValue Fehler erhalten, indem Sie die Schritte zur Erstellung delegierter Berechtigungen verwenden, 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. Dieser Wert 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": "AgentIdentityBlueprintPrincipal.Create AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All AgentIdentityBlueprint.AddRemoveCreds.All AgentIdentityBlueprint.DeleteRestore.All AgentInstance.ReadWrite.All AgentIdentity.Create.All AgentIdentity.DeleteRestore.All AgentRegistrations.ReadWrite.All DelegatedPermissionGrant.ReadWrite.All Directory.Read.All User.Read"
   }
   

4. Wählen Sie "Abfrage ausführen" aus. Sie sollten eine 200 OK Antwort mit allen zwölf Berechtigungen im scope Feld erhalten.

Bewährte Sicherheitsmethoden

Lesen Sie diese Richtlinien, um Ihre App-Registrierung sicher und konform zu halten.

Empfohlene Vorgehensweise:

• Verwenden Sie eine Einzelmieterregistrierung.
• Gewähren Sie nur die erforderlichen delegierten Erlaubnisse.
• Überprüfen Sie regelmäßig die Berechtigungen.
• Entferne die App, wenn sie nicht mehr gebraucht wird.

Nicht:

• Gewähren Sie Anwendungsberechtigungen. Verwenden Sie nur Delegierte.
• Teile die Client-ID öffentlich.
• Erteile weitere unnötige Genehmigungen.
• Nutze die App für andere Zwecke.

Was die CLI automatisch konfiguriert

Wenn Sie a365 config init oder a365 setup requirements ausführen, überprüft die CLI Ihre App-Registrierung und muss möglicherweise Änderungen vornehmen. Vor dem Anwenden von Änderungen zeigt ihnen die CLI eine Zusammenfassung an und fordert eine Bestätigung an:

WARNING: The CLI needs to make the following changes to your app registration (<app-id>):

  - Add redirect URI(s): http://localhost
  - Enable 'Allow public client flows' (isFallbackPublicClient = true)

Do you want to proceed? (y/N):

Um die Bestätigungsaufforderung (z. B. in einer CI-Umgebung) zu überspringen, verwenden Sie das --yes Kennzeichen:

a365 config init --yes

In der folgenden Tabelle werden die einzelnen Änderungen beschrieben, die die CLI möglicherweise vornehmen kann:

Wenn Sie die Eingabeaufforderung ablehnen, ändert die CLI ihre App-Registrierung nicht. Wenn Änderungen erforderlich sind, damit die CLI funktioniert, können Sie sie manuell in Microsoft Entra Admin Center konfigurieren oder mit --yes erneut ausführen.

Nächste Schritte

Nachdem Sie Ihre benutzerdefinierte Client-App registriert haben, verwenden Sie sie mit der Agent 365 CLI im Entwicklungszyklus von Agent 365:

Problembehandlung

Dieser Abschnitt beschreibt, wie man Fehler bei der Registrierung einer benutzerdefinierten Client-App behebt.

Die CLI-Validierung schlägt während der Konfiguration fehl

Symptom: Ausführung des a365 config init Befehls oder a365 setup schlägt mit Fehlern bei der Validierung deiner benutzerdefinierten Client-App fehl.

Lösung: Verwenden Sie diese Checkliste, um zu überprüfen, ob Ihre App-Registrierung korrekt ist:

# Run configuration to see validation messages
a365 config init

Erwartetes Ergebnis: CLI zeigt Custom client app validation successful.

Wenn Sie nicht das erwartete Ergebnis erhalten, überprüfen Sie jede der folgenden Prüfungen:

Erforderliche delegierte Berechtigungen:

• AgentIdentityBlueprintPrincipal.Create [Beta]
• AgentIdentityBlueprint.ReadWrite.All [Beta]
• AgentIdentityBlueprint.UpdateAuthProperties.All [Beta]
• AgentIdentityBlueprint.AddRemoveCreds.All [Beta]
• AgentIdentityBlueprint.DeleteRestore.All [Beta]
• AgentInstance.ReadWrite.All [Beta]
• AgentIdentity.Create.All [Beta]
• AgentIdentity.DeleteRestore.All [Beta]
• DelegatedPermissionGrant.ReadWrite.All
• Directory.Read.All
• User.Read

Admin-Zustimmung fälschlicherweise erteilt

Symptom: Die Überprüfung schlägt fehl, auch wenn Sie Berechtigungen hinzugefügt haben.

Ursache: Sie haben keine Administratorzustimmung erteilt, oder Sie haben sie falsch erteilt.

Solution: Wechseln Sie in Ihrer App-Registrierung in Microsoft Entra Admin Center zu API-Berechtigungen und wählen Sie Grant admin consent for [Your Tenant] aus. Überprüfen Sie, dass alle Berechtigungen grüne Häkchen unter Status anzeigen.

Falscher Berechtigungstyp

Symptom: CLI scheitert bei Authentifizierungsfehlern oder Berechtigungsverweigerungsfehlern.

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

Diese Tabelle beschreibt die verschiedenen Arten von Berechtigungen.

Warum delegiert?

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

Lösung:

1. Wechseln Sie zu Microsoft Entra Admin Center>App-Registrierungen> Ihre App >API-Berechtigungen
2. Entferne alle Anwendungsberechtigungen. Diese Berechtigungen erscheinen als Anwendung in der Typ-Spalte .
3. Füge dieselben Berechtigungen hinzu wie delegierte Berechtigungen .
4. Erteile erneut die Zustimmung des Administrators.

Betaberechtigungen verschwinden nach Administratorzustimmung im Microsoft Entra Verwaltungszentrum

Symptom: Sie haben Option B: Microsoft Graph-API (für Betaberechtigungen) verwendet, um Betaberechtigungen hinzuzufügen, werden jedoch entfernt, nachdem Sie im Microsoft Entra Admin Center Administratorgenehmigung erteilen ausgewählt haben.

Root-Ursache: Microsoft Entra Admin Center zeigt keine Betaberechtigungen auf der Benutzeroberfläche an. Wenn Sie die Zustimmung des Administrators gewähren, gewährt das Portal nur die Zustimmung für die sichtbaren Berechtigungen und überschreibt die von der API erteilte Einwilligung.

Warum dies geschieht:

1. Sie verwenden die Graph-API (Option B) um alle elf Berechtigungen einschließlich Betaberechtigungen hinzuzufügen.
2. Der API-Aufruf gewährt consentType: "AllPrincipals"bereits mandantenweite Admin-Zustimmung.
3. Sie wechseln zu Microsoft Entra Admin Center und sehen nur eine Teilmenge von Berechtigungen, da Betaberechtigungen im Portal nicht sichtbar sind.
4. Du wählst "Administrator-Einwilligung gewähren ", weil du denkst, dass du es brauchst.
5. Microsoft Entra Admin Center überschreibt Ihre von der API erteilte Zustimmung nur mit den sichtbaren Berechtigungen.
6. Ihre Betaberechtigungen werden jetzt gelöscht.

Lösung:

• Verwenden Sie nicht die Administratorzustimmung im Microsoft Entra Admin Center nach der API-Methode: Die API-Methode erteilt bereits die Administratorzustimmung.
• Wenn Sie versehentlich Betaberechtigungen löschen, führen Sie Option B Schritt 3 erneut aus (Erteilen der Administratorzustimmung mithilfe von Graph-API), um sie wiederherzustellen. Wenn Sie einen Request_MultipleObjectsWithSameKeyValue Fehler erhalten, folgen Sie den Schritten zur Aktualisierung delegierter Berechtigungen.
• Um zu überprüfen, ob alle elf Berechtigungen aufgelistet sind, überprüfen Sie das scope Feld in der POST Oder PATCH Antwort.

App wird während der Validierung nicht gefunden

Symptom: Das CLI meldet Application not found oder Invalid client ID Fehler.

Solution:

1. Überprüfen Sie, dass Sie die Anwendungs-(Client-)ID im GUID-Format kopiert haben, nicht die Objekt-ID:

   • Wechseln Sie zu Microsoft Entra Admin Center>App-Registrierungen> Ihre App >Overview
   • Kopieren Sie den Wert unter Application (Client) ID
   • Das Format sollte folgendermaßen sein: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

2. Überprüfen Sie, ob die App in Ihrem Mieter existiert:

   # Sign in to the correct tenant
   az login
   
   # List your app registrations
   az ad app list --display-name "<The display name of your app>"
   

Erfahren Sie, wie Sie eine Anwendung in Microsoft Entra ID.