Benutzerdefinierte Client-App-Registrierung für Agent 365 CLI

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

Dieser Artikel unterteilt den Prozess in vier Hauptschritte:

  1. Anwendung registrieren
  2. Redirect URI festlegen
  3. Anwendungs(client)-ID kopieren
  4. API-Berechtigungen konfigurierenAdministratorrechte erforderlich
  5. Hinzufügen des Rollenaufrufs „wids“

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

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Zugriff auf das Microsoft Entra Admin Center und, falls erforderlich, auf eine der benötigten Admin-Rollen zum Erteilen von Zustimmung haben.

So registrieren Sie die App

Standardmäßig kann jeder Benutzer im Mandanten Anwendungen registrieren im Microsoft Entra Admin Center. Mandantenadministratoren können diese Funktion jedoch einschränken. Wenn Sie Ihre App nicht registrieren können, wenden Sie sich an Ihren Administrator.

Für 4. API-Berechtigungen konfigurieren benötigen Sie eine der folgenden Administratorrollen.

Trinkgeld

Sie haben keinen Admin Zugriff? Sie können die Schritte 1–3 selbst abschließen und dann Ihren Mandantenadministrator bitten, Schritt 4 durchzuführen. Übermitteln Sie Ihrem Mandantenadministrator Ihre Anwendungs-(Client-)ID aus Schritt 3 sowie einen Link zum Abschnitt API-Berechtigungen konfigurieren.

Trinkgeld

Globale Administratoren können die manuelle Registrierung überspringen. Führen Sie a365 setup requirements aus und falls die Agent 365 CLI-App in Ihrem Mandanten nicht gefunden wird, fordert die CLI Sie auf, sie zu erstellen und automatisch die Administratorzustimmung zu erteilen. Führen Sie C an der Eingabeaufforderung aus, um die App in einem einzigen Schritt zu erstellen. Wenn Sie diesen automatisierten Pfad verwenden, können Sie die Schritte in diesem Abschnitt überspringen.

1. Anwendung registrieren

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

  1. Gehen Sie zum Microsoft Entra Admin Center

  2. Wählen Sie App-Registrierungen

  3. Wählen Sie Neue Registrierung aus

  4. Ergebnis:

    • Name: Geben Sie einen sinnvollen Namen für Ihre App ein, zum Beispiel my-agent-app. App-Benutzern wird dieser Name angezeigt, und Sie können ihn jederzeit ändern. Sie können mehrere App-Registrierungen mit demselben Namen erstellen.

      Trinkgeld

      Wenn Sie den konfigurationsfreien a365 setup all --agent-name-Flow verwenden möchten, benennen Sie die App exakt Agent 365 CLI. Die CLI erkennt die Clientanwendung automatisch anhand dieses bekannten Anzeigenamens, sodass das manuelle Kopieren der Client-ID in eine Konfigurationsdatei entfällt.

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

    • Umleitungs-URI: Wählen Sie Öffentlicher Client/nativ (mobil & Desktop) und geben Sie http://localhost:8400/ ein

  5. Wählen Sie Registrieren aus

Die CLI erfordert insgesamt drei Redirect-URIs. Die CLI fügt automatisch alle fehlenden Redirect-URIs hinzu, wenn Sie a365 setup requirements ausführen:

URI Verwendungszweck
http://localhost:8400/ Microsoft Authentication Library (MSAL) (MSAL) interaktive Browser-Authentifizierung
http://localhost Microsoft Graph PowerShell SDK Connect-MgGraph
ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id} Web Account Manager (WAM) verwenden

Weitere Informationen finden Sie unter Was die CLI automatisch konfiguriert.

2. Legen Sie die Redirect URI fest

  1. Wählen Sie Überblick aus, und kopieren Sie den Wert von Anwendungs(client)-ID.
  2. Gehen Sie zu Authentifizierung (Vorschauversion) und wählen Sie Redirect URI hinzufügen aus.
  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ählen Sie Konfigurieren aus, um den Wert hinzuzufügen.

3. Anwendungs(client)-ID kopieren

Kopieren Sie auf der Übersichtsseite der App die Anwendungs-ID (Client-ID) im GUID-Format. Sie verwenden diesen Wert beim Ausführen von a365 setup all oder beim manuellen Erstellen von a365.config.json.

Trinkgeld

Verwechseln Sie diesen Wert nicht mit Objekt-ID — Sie benötigen die Anwendungs-(Client-)ID.

Wenn Sie Ihre App Agent 365 CLI in Schritt 1 genannt haben, können Sie diesen Schritt beim Verwenden von a365 setup all --agent-name überspringen. Die CLI löst die Client-ID automatisch anhand des Anzeigenamens auf.

4. API-Berechtigungen konfigurieren

Wichtig

Für diesen Schritt benötigen Sie Administratorrechte. Wenn Sie Entwickler ohne Administratorzugriff sind, senden Sie Ihre Anwendungs-(Client-)ID aus Schritt 3 an Ihren Mandantenadministrator und bitten Sie ihn, diesen Schritt auszuführen.

Anmerkung

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

Wählen Sie die geeignete Methode aus:

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

Option A: Microsoft Entra Admin Center (Standardmethode)

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

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

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

    Wichtig

    Sie müssen Delegierte Berechtigungen verwenden (keine Anwendungsberechtigungen). Die CLI authentifiziert sich interaktiv – Sie melden sich an, und sie handelt in Ihrem Namen. Um mehr zu erfahren, siehe Falscher Berechtigungstyp.

  3. Fügen Sie diese sieben Berechtigungen nacheinander hinzu:

    Berechtigung Verwendungszweck
    AgentIdentityBlueprint.ReadWrite.All Blueprint-Erstellung, Verwaltung von Client-Geheimnissen, vererbbare Berechtigungen, föderierte Identitätszugangsdaten und Löschung (Beta-API)
    AgentIdentityBlueprintPrincipal.Create Erstellen des Agent Blueprint service principal (Beta-API)
    AgentIdentity.Read.All Idempotenzprüfung und Suche nach dem Dienstprinzipal der Agent-Identität (Beta-API)
    AgentIdentity.DeleteRestore.All Agenten-Identitäts-Service-Prinzipale während der Bereinigung löschen (Beta-API)
    AgentRegistration.ReadWrite.All Alle Agentenregistrierungen lesen und schreiben
    Application.Read.All Nachschlagen des Service Principals anhand der App-ID (schmalerer Ersatz für Directory.Read.All)
    User.Read Profil des angemeldeten Benutzers auslesen, um Blaupauseneigentümer und Sponsorzuweisung zu ermitteln

    Anmerkung

    AgentRegistration.ReadWrite.All ist für die Agenteneinrichtung erforderlich. Der CLI-Validator prüft diese Berechtigung explizit. Die Berechtigung muss in Ihrer App-Registrierung vorhanden sein und die Administratorzustimmung erhalten haben.

    Für jede Berechtigung:

    • Geben Sie im Suchfeld den Berechtigungsnamen ein (z. B. AgentIdentityBlueprint.ReadWrite.All).
    • Aktivieren Sie das Kontrollkästchen neben der Berechtigung.
    • Wählen Sie Zugriffsrechte hinzufügen.
    • Wiederholen Sie dies für alle sieben Berechtigungen.

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

    • Warum ist dies erforderlich? Agent-Identitätsblaupausen sind mandantenweite Ressourcen, auf die mehrere Benutzer und Anwendungen verweisen können. Ohne mandantenweite Zustimmung schlägt die CLI während der Authentifizierung fehl.
    • Was passiert, wenn es fehlschlägt? Sie benötigen die Rolle Anwendungsadministrator, “Cloud Application Administrator oder Global Administrator. Bitten Sie Ihren Mandant-Administrator um Hilfe.

  5. Stellen Sie sicher, dass alle Berechtigungen unter Status grüne Häkchen anzeigen.

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

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

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

Warnung

Wenn Sie diese API-Methode verwenden, klicken Sie anschließend nicht auf die Schaltfläche Administrator-Einwilligung 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. Weitere Informationen finden Sie unter Beta-Berechtigungen verschwinden.

  1. Öffnen Sie den Graph-Tester.

  2. Melden Sie sich mit Ihrem Administratorkonto an (Application Administrator oder Cloudanwendungsaministrator).

  3. Erteilen Sie die Administrator-Einwilligung mithilfe der Graph-API. Sie benötigen zum Abschluss dieses Schrittes Folgendes:

    • Dienstprinzipal-ID. Sie benötigen einen SP_OBJECT_ID Variablenwert.
    • Graph-Ressourcen-ID. Sie benötigen einen GRAPH_RESOURCE_ID Variablenwert.
    • Erstellen oder aktualisieren Sie delegierte Berechtigungen, indem Sie den oAuth2PermissionGrant resource type mit dem SP_OBJECT_ID und GRAPH_RESOURCE_ID Variablenwerten verwenden.

Verwenden Sie die Informationen in den folgenden Abschnitten, um diese Schritte auszuführen.

Rufen Sie Ihre Dienstprinzipal-ID ab

Ein Dienstprinzipal ist die Identität Ihrer App in Ihrem Mandanten. Sie benötigen sie, bevor Sie Berechtigungen über die API erteilen können.

  1. Stellen Sie die Methode im Graph Explorer auf GET und verwenden Sie diese URL. Ersetzen Sie <YOUR_CLIENT_APP_ID> durch Ihre tatsächliche Anwendungs-Client-ID aus Schritt 3: Kopieren Sie 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, erhalten Sie als Ergebnis Ihre SP_OBJECT_ID.

    • Wenn die Abfrage mit einem Berechtigungsfehler fehlschlägt, wählen Sie die Registerkarte Berechtigungen ändern, stimmen Sie den erforderlichen Berechtigungen zu und wählen Sie dann erneut Abfrage ausführen. Der zurückgegebene Wert ist Ihr SP_OBJECT_ID.

    • Wenn die Abfrage keine Ergebnisse ("value": []) zurückgibt, erstellen Sie den Dienstprinzipal mithilfe der folgenden Schritte:

      1. Setzen Sie die Methode auf POST und verwenden Sie diese URL:

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

        Anforderungstext (Ersetzen Sie YOUR_CLIENT_APP_ID durch Ihre tatsächliche Anwendungs-Client-ID):

        {
   "appId": "YOUR_CLIENT_APP_ID"
}

      2. Wählen Sie Abfrage ausführen aus. Sie sollten eine 201 Created Antwort erhalten. Der id zurückgegebene Wert ist Ihr SP_OBJECT_ID.

Rufen Sie Ihre Graph-Ressourcen-ID ab

  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 id Wert. Dieser Wert ist Ihr GRAPH_RESOURCE_ID.
    • Wenn die Abfrage mit einem Berechtigungsfehler fehlschlägt, wählen Sie die Registerkarte Berechtigungen ändern, stimmen Sie den erforderlichen Berechtigungen zu und wählen Sie dann erneut Abfrage ausführen. Kopieren Sie den id-Wert. Dieser Wert ist Ihr GRAPH_RESOURCE_ID.

Erstellen Sie delegierte Berechtigungen

Dieser API-Aufruf gewährt mandantweite Administratoreinwilligung für alle sieben Berechtigungen, einschließlich der 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

    Anforderungstext.

    {
"clientId": "<SP_OBJECT_ID>",
"consentType": "AllPrincipals",
"principalId": null,
"resourceId": "<GRAPH_RESOURCE_ID>",
"scope": "AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprintPrincipal.Create AgentIdentity.Read.All AgentIdentity.DeleteRestore.All AgentRegistration.ReadWrite.All Application.Read.All User.Read"
}

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

    • Wenn Sie 201 Created Antwort erhalten: Erfolg! Das scope Feld in der Antwort zeigt alle sieben Berechtigungsnamen. Der Vorgang ist abgeschlossen.
    • Wenn die Abfrage mit einem Berechtigungsfehler fehlschlägt, öffnen Sie die Registerkarte Berechtigungen ändern, stimmen den erforderlichen Berechtigungen zu und führe dann die Abfrage erneut aus.
    • Wenn Sie Fehler erhalten Request_MultipleObjectsWithSameKeyValue: Es gibt bereits eine Zuweisung. Vielleicht hat jemand zuvor Berechtigungen hinzugefügt. Fügen Sie die folgenden delegierten Berechtigungen hinzu.

Warnung

Die consentType: "AllPrincipals" in der POST-Anfrage gewährt bereits eine mandantenweite Administratoreinwilligung. WÄHLEN SIE NICHT „Administrator-Einwilligung gewähren“ im Microsoft Entra Admin Center aus, nachdem Sie diese API-Methode verwendet haben – andernfalls werden Ihre Beta-Berechtigungen gelöscht, da das Microsoft Entra Admin Center Beta-Berechtigungen nicht erkennt und Ihre per API erteilte Einwilligung mit nur den sichtbaren Berechtigungen überschreibt.

Aktualisieren Sie delegierte Berechtigungen

Wenn Sie einen Request_MultipleObjectsWithSameKeyValue Fehler bei der Nutzung dieses Schrittes erhalten, verwenden Sie Delegierte Berechtigungen erstellen, um diese Schritte zu Nutzen, um die delegierte 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 lautet YOUR_GRANT_ID.

  3. Setzen Sie die Graph Explorer-Methode auf PATCH und verwenden diese URL mit YOUR_GRANT_ID.

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

    Anforderungstext.

    {
   "scope": "AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprintPrincipal.Create AgentIdentity.Read.All AgentIdentity.DeleteRestore.All AgentRegistration.ReadWrite.All Application.Read.All User.Read"
}

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

5. Hinzufügen des Rollenaufrufs „wids“

Die Agent 365 CLI liest Ihre Entra-Verzeichnis-Rollenzuweisungen direkt aus dem Zugriffstoken aus, um festzustellen, ob Sie Administratorrechte haben. Dies erfordert das Hinzufügen des wids Anspruchs zu den Zugriffstoken, die für Ihre App-Registrierung ausgestellt werden.

Ohne diesen Anspruch kann die CLI Ihre Rolle nicht erkennen und zeigt für jeden Schritt, der Administratorrechte erfordert, PowerShell-Anweisungen an – selbst wenn Sie Administrator sind. Führen Sie diesen Schritt aus, um das gewünschte Verhalten zu erzielen.

  1. Gehen Sie in Ihrer App-Registrierung zu Token-Konfiguration.

  2. Wählen Sie Optionalen Anspruch hinzufügen aus.

  3. Wählen Sie Tokentyp und Zugriff aus.

  4. Aktivieren Sie das Kästchen neben wids in der Liste der Ansprüche.

  5. Wählen Sie Add aus

    Wenn Sie aufgefordert werden, die Microsoft Graph-Berechtigung profile zur Aktivierung des Anspruchs zu aktivieren, wählen Si Ja, hinzufügen.

Anmerkung

Der wids-Aufruf enthält die Rollenvorlagen-GUIDs der Entra-Verzeichnisrollen, die dem angemeldeten Benutzer direkt zugewiesen sind. Die CLI verwendet diese GUIDs, um die Rollen des globalen Administrators und des Agent-ID-Administrators ohne einen zusätzlichen Graph-API-Aufruf zu erkennen.

Einschränkung:wids spiegelt nur die direkt zugewiesenen Rollen wider. Wenn Ihr Mandant Verzeichnisrollen über rollenzuweisende Sicherheitsgruppen zuweist, erkennt die CLI diese gruppenbasierten Rollenzuweisungen möglicherweise nicht. Die direkte Rollenzuweisung ist das Standardverfahren sowohl für Agent ID Entwickler als auch für Administratorrollen.

Bewährte Vorgehensweisen zur Sicherheit

Überprüfen Sie diese Richtlinien, um Ihre App-Registrierung sicher und regelkonform zu halten.

Empfohlene Vorgehensweise:

  • Verwenden Sie die Einzelmandant-Registrierung.
  • Gewähren Sie nur die erforderlichen delegierten Berechtigungen.
  • Überprüfen Sie regelmäßig die Berechtigungen.
  • Entfernen Sie die App, wenn sie nicht mehr benötigt wird.

Vermeiden Sie Folgendes:

  • Gewähren Sie Anwendungsberechtigungen. Verwenden Sie nur delegierte.
  • Teilen Sie die Client-ID öffentlich.
  • Erteilen Sie weitere unnötige Genehmigungen.
  • Nutzen Sie die App für andere Zwecke.

Was die CLI automatisch konfiguriert

Wenn Sie a365 setup requirements ausführen, überprüft die CLI Ihre App-Registrierung und muss möglicherweise Änderungen vornehmen. Bevor die CLI Änderungen vornimmt, zeigt sie eine Zusammenfassung und bittet um Bestätigung:

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 zu überspringen (z. B. in einer CI-Umgebung), verwenden Sie die --yes Kennzeichnung:

a365 setup requirements --yes

Die folgende Tabelle beschreibt die möglichen Änderungen, die die CLI vornehmen könnte:

Änderung Ursache
Umleitungs-URL hinzufügen http://localhost Das Microsoft Graph PowerShell SDK erfordert diese URI für die Browser-Authentifizierung. Fehlt sie, fallen OAuth2-Berechtigungsoperationen auf ein Token zurück, dem die erforderlichen delegierten Berechtigungen fehlen, und werden mit einem 403-Fehler abgelehnt.
Umleitungs-URL hinzufügen http://localhost:8400/ MSAL benötigt diesen URI für die interaktive Browserauthentifizierung.
Umleitungs-URL hinzufügen ms-appx-web://Microsoft.AAD.BrokerPlugin/{id} Erforderlich für den Web Account Manager (WAM), einen Authentifizierungsbroker unter Windows. Erfahren Sie mehr über das Abrufen von Geräte gebundenen Token.
Aktivieren Sie Öffentliche Client-Flows zulassen Erforderlich für den Fallback der Gerätecodeauthentifizierung unter macOS, Linux, Windows Subsystem für Linux (WSL), monitorlose Umgebungen und als Fallback für bedingte Zugriffsrichtlinien unter Windows.
Fehlende Berechtigungen der App-Registrierungen hinzufügen Hält die App-Registrierung nach einem CLI-Update mit den neu benötigten Berechtigungen auf dem neuesten Stand.
Administratorzustimmung erteilen Erweitert die bestehende OAuth2-Berechtigungsgewährung, um neu hinzugefügte Berechtigungen einzuschließen.

Wenn Sie die Aufforderung ablehnen, nimmt die CLI keine Änderungen an Ihrer App-Registrierung vor. Wenn Änderungen erforderlich sind, damit die CLI funktioniert, können Sie sie manuell im Microsoft Entra Verwaltungszentrum konfigurieren oder mit --yesneu ausführen.

Nächste Schritte,

Nachdem Sie Ihre benutzerdefinierte Client-App registriert haben, verwenden Sie sie mit der Agent 365 CLI, um die Agent 365-Konfiguration abzuschließen:

Erste Schritte mit Agent 365 Entwicklung

Problembehandlung

In diesem Abschnitt wird beschrieben, wie Fehler bei der Registrierung einer benutzerdefinierten Client-App behoben werden können.

Trinkgeld

Die Agent 365 Troubleshooting-Anleitung enthält übergeordnete Empfehlungen zur Fehlerbehebung, Best Practices und Links zu Inhalten zur Fehlerbehebung für jeden Abschnitt des Entwicklungszyklus von Agent 365.

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

Symptom: Die Ausführung des Befehls a365 setup oder a365 setup requirements schlägt mit Prüfungsfehlern bezüglich Ihrer benutzerdefinierten Client-App fehl.

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

# Run requirements validation to see validation messages
a365 setup requirements

Erwartetes Ergebnis: Die CLI zeigt Custom client app validation successful an.

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

Überprüfen Zur Überprüfung Fix
✅ Korrekte ID verwendet Sie haben die Anwendungs-ID (Client-ID) (nicht die Objekt-ID) kopiert Gehen Sie zur App Übersicht unter Microsoft Entra Admin Center
✅ Delegierte Berechtigung Berechtigungen zeigen Typ: Delegiert in API-Berechtigungen Siehe Falscher Berechtigungstyp
✅ Alle Berechtigungen hinzugefügt Siehe alle unten aufgeführten Berechtigungen Führen Sie Schritt 4 erneut aus
✅ Administratoreinwilligung erteilen Bei allen wird unter „Status“ ein grünes Häkchen angezeigt Siehe Administratoreinwilligung fälschlicherweise erteilt

Erforderliche delegierte Berechtigungen:

  • AgentIdentityBlueprint.ReadWrite.All [Beta]
  • AgentIdentityBlueprintPrincipal.Create [Beta]
  • AgentIdentity.Read.All [Beta]
  • AgentIdentity.DeleteRestore.All [Beta]
  • AgentRegistration.ReadWrite.All
  • Application.Read.All
  • User.Read

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

Eigentliche Ursache: -Sie haben die Admin-Zustimmung nicht erteilt oder sie falsch erteilt.

Lösung:Gehen Sie in Ihrer App-Registrierung zu Microsoft Entra Admin Center, gehen Sie zu API-Berechtigungen und wählen Administratoreinwilligung für [Ihren Mandant]. Stellen Sie sicher, dass alle Berechtigungen unter Status grüne Häkchen anzeigen.

Symptom: a365 setup all druckt „Delegierte Anwendungseinwilligung erfolgreich sichergestellt“, schlägt dann aber während der Blaupausenerstellung sofort fehl mit:

Admin consent has not been granted for this application.
Share this URL with an Application Administrator or Global Administrator to grant consent:
  https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent?client_id=<client-app-id>

Ursache: Ihr Mandant verfügt bereits über einen oauth2PermissionGrant-Datensatz für Ihre benutzerdefinierte Client-App (aus einer früheren, teilweisen Einrichtung oder einer früheren Aktion „Administratoreinwilligung erteilen“ im Microsoft Entra Admin Center für andere Bereiche), wobei in diesem Datensatz der erforderliche Bereich (AgentIdentityBlueprint.ReadWrite.All) jedoch nicht vorhanden ist. Die CLI erkennt den fehlenden Umfang und zeigt eine Zustimmungs-URL an, damit ein Administrator die Zustimmung abschließen kann.

Lösung:

Teilen Sie die in der Fehlerausgabe angezeigte Zustimmungs-URL mit einem Anwendungsadministrator oder einem globalen Administrator. Die URL sieht folgendermaßen aus:

https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent?client_id=<client-app-id>

Nachdem der Administrator die Zustimmung erteilt hat, führen Sie a365 setup all --agent-name <name> erneut aus.

Wenn Sie über Administratorrechte verfügen, können Sie die URL direkt in einem Browser öffnen, um die Zustimmung unverzüglich zu erteilen, ohne warten zu müssen.

Siehe Falscher Berechtigungstyp

Symptom: CLI scheitert bei Authentifizierungsfehlern oder Berechtigungsfehlern.

Ursache: Sie haben Anwendungsberechtigungen statt Delegierte Berechtigungen hinzugefügt.

Diese Tabelle beschreibt die verschiedenen Berechtigungstypen.

Berechtigungstyp Verwendung Wie Agent 365 CLI es nutzt
Delegiert (Umfang) Nutzer meldet sich interaktiv an Agent 365 CLI verwendet dies – Sie melden sich an, die CLI handelt in Ihrem Namen
Anwendungsrolle (Rolle) Der Dienst wird ohne Benutzer ausgeführt Nicht verwenden – Nur für Hintergrunddienste/Daemons

Warum delegierte Berechtigungen?

  • Sie melden sich interaktiv an (Browser-Authentifizierung)
  • Die CLI führt Aktionen als Sie aus (Audit-Trails zeigen Ihre Identität)
  • Mehr Sicherheit – nur im Rahmen Ihrer tatsächlichen Berechtigungen
  • Gewährleistet Verantwortlichkeit und Compliance

Lösung:

  1. Gehen Sie zu Microsoft Entra Admin Center>App Registrierung> Ihre App >API-Berechtigungen
  2. Entfernen Sie alle Anwendungsberechtigungen. Diese Berechtigungen erscheinen als Anwendung in der Spalte Typ.
  3. Fügen Sie dieselben Berechtigungen als Delegierte Berechtigungen hinzu.
  4. Administratoreinwilligung wieder erteilen.

Symptom: Sie haben Option B: Microsoft Graph-API (für Beta-Berechtigungen) verwendet, um Beta-Berechtigungen hinzuzufügen, doch diese verschwinden, nachdem Sie im Microsoft Entra Admin Center Administratorzustimmung erteilen ausgewählt haben.

Hauptursache: Im Microsoft Entra Admin Center werden Beta-Berechtigungen nicht in der Benutzeroberfläche angezeigt. Wenn Sie Administratoreinwilligung gewähren auswählen, erteilt das Portal die Zustimmung nur für die sichtbaren Berechtigungen und überschreibt die per API erteilte Zustimmung.

Warum das passiert:

  1. Sie verwenden die Microsoft Graph-API (Option B), um alle sieben Berechtigungen, einschließlich Beta-Berechtigungen, hinzuzufügen.
  2. Der API-Aufruf mit consentType: "AllPrincipals"gewährt bereits eine mandantenweite Administratoreinwilligung.
  3. Sie gehen zum Microsoft Entra Admin Center und sehen nur eine Teilmenge der Berechtigungen, da Beta-Berechtigungen im Portal nicht angezeigt werden.
  4. Sie wählen Administratoreinwilligung gewähren aus, weil Sie denken, dass es notwendig ist.
  5. Das Microsoft Entra Admin Center überschreibt Ihre über die API erteilte Einwilligung durch nur die sichtbaren Berechtigungen.
  6. Die Beta-Berechtigungen wurden jetzt gelöscht.

Lösung:

  • Verwenden Sie keine Microsoft Entra Admin Center-Administratoreinwilligung nach der API-Methode: Die API-Methode erteilt bereits Administratoreinwilligung.
  • Wenn Sie versehentlich Beta-Berechtigungen löschen, führen Sie Option B, Schritt 3 (Admin-Einwilligung über die Microsoft Graph-API erteilen) erneut aus, um sie wiederherzustellen. Wenn Sie einen Request_MultipleObjectsWithSameKeyValue-Fehler erhalten, folgen Sie den Schritten zur Aktualisierung der delegierten Berechtigungen.
  • Um zu überprüfen, ob alle sieben Berechtigungen aufgeführt sind, sehen Sie sich das scope Feld in der POST oder PATCH Antwort an.

App wird während der Validierung nicht gefunden

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

Lösung:

  1. Stellen Sie sicher, dass Sie die Anwendungs-(Client-)ID im GUID-Format und nicht die Objekt-ID kopiert haben:

    • Gehen Sie zur Microsoft Entra Admin Center>App-Registrierung> Ihre App >Übersicht
    • Kopieren Sie den Wert unter Anwendungs-(Client-) ID
    • Das Format sollte wie folgt lauten: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

  2. Überprüfen Sie, ob die App in Ihrem Mandanten 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, wie eine Anwendung in Microsoft Entra ID registriert wird.

  • Last updated on