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

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

   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 sechs Berechtigungen einzeln hinzu:

   Erlaubnis	Zweck
   AgentIdentityBlueprint.ReadWrite.All	Verwalten von Agent-Blueprint-Konfigurationen
   AgentIdentityBlueprint.UpdateAuthProperties.All	Aktualisieren von vererbbaren Berechtigungen des Agent-Blueprints
   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
   User.ReadWrite.All	Erstellen von Agentbenutzern, Festlegen des Verwendungsorts und Zuweisen von Lizenzen

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

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:

• Application.ReadWrite.All
• AgentIdentityBlueprint.ReadWrite.All
• AgentIdentityBlueprint.UpdateAuthProperties.All
• Directory.Read.All
• DelegatedPermissionGrant.ReadWrite.All
• User.ReadWrite.All

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.

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.