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 können 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 registrations

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.
   • Unterstützte Kontotypen: Konten nur in diesem Organisationsverzeichnis (Einzelmieter)
   • 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.

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 Desktop-Anwendungen aus und setzen Sie den Wert auf ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}, wobei {client-id} der von Ihnen kopierte Anwendungswert (Client-ID) ist.
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: Verwenden Sie Microsoft Entra Admin Center für alle Berechtigungen (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 Tenant sichtbar sind.

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

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

   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 Agentenentwürfe
   Directory.Read.All	Verzeichnisdaten zur Validierung lesen

   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 dies für alle fünf Berechtigungen.

4. Wählen Sie Administrator-Genehmigung für [Ihr(e) Mandant] gewähren.

   • 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 Beta-Berechtigungen (AgentIdentityBlueprint.*) nicht sichtbar sind, gehe zu Option B.

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

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

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 fünf Berechtigungen, einschließlich der beiden Betaberechtigungen, 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 , 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": "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.

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 von Anwendungsberechtigungen. Verwenden Sie nur Delegierte.
• Teile die Client-ID öffentlich.
• Erteile weitere unnötige Genehmigungen.
• Nutze die App für andere Zwecke.

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:

• Application.ReadWrite.All
• AgentIdentityBlueprint.ReadWrite.All [Beta]
• AgentIdentityBlueprint.UpdateAuthProperties.All [Beta]
• Directory.Read.All
• DelegatedPermissionGrant.ReadWrite.All

Admin-Zustimmung fälschlicherweise erteilt

Symptom: Die Validierung schlägt fehl, obwohl Berechtigungen hinzugefügt werden.

Ursache: Die Zustimmung des Administrators wird nicht erteilt oder wird fälschlicherweise erteilt.

Lösung: Die korrekte Lösung hängt davon ab, welche Methode du verwendet hast:

Wenn Sie Microsoft Entra Admin Center versehentlich nach Option B verwenden: Sie löschen Ihre Betaberechtigungen. Folgen Sie den delegierten Berechtigungen von Update , um sie wiederherzustellen.

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 registrations> 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 der Admin-Zustimmung im Microsoft Entra Admin Center.

Symptom: Sie haben Option B: Microsoft Graph API (Für Betaberechtigungen) verwendet, um Betaberechtigungen hinzuzufügen, verschwinden jedoch, nachdem Sie Administratorzustimmung erteilen im Microsoft Entra-Admin-Center 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. Mit dem Graph API (Option B) fügen Sie alle fünf Berechtigungen einschließlich Betaberechtigungen hinzu.
2. Der API-Aufruf gewährt consentType: "AllPrincipals"bereits mandantenweite Admin-Zustimmung.
3. Sie wechseln zum Microsoft Entra Admin Center und sehen nur drei Berechtigungen, da die Betaberechtigungen unsichtbar sind.
4. Du wählst "Administrator-Einwilligung gewähren ", weil du denkst, dass du es brauchst.
5. Microsoft Entra Admin Center überschreibt Ihre API-erteilte Zustimmung mit nur den drei sichtbaren Berechtigungen.
6. Deine beiden Beta-Berechtigungen sind jetzt gelöscht.

Lösung:

• Verwenden Sie keine Microsoft Entra Admin Center-Administrator-Einwilligung nach der API-Methode: Die API-Methode erteilt bereits Administrator-Einwilligung.
• 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, dass alle fünf Berechtigungen aufgeführt sind, prü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 zum Microsoft Entra Admin Center>App registrations> 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.