Εγγραφή προσαρμοσμένης εφαρμογής-πελάτη για το Agent 365 CLI

Το Agent 365 CLI χρειάζεται μια προσαρμοσμένη καταχώρηση εφαρμογής-πελάτη στον μισθωτή σας Microsoft Entra ID για να πραγματοποιεί έλεγχο ταυτότητας και να διαχειρίζεται τα blueprints ταυτότητας παράγοντα.

Το άρθρο αυτό χωρίζει τη διαδικασία σε τέσσερα βασικά βήματα:

Καταχώρηση εφαρμογής
Ορίστε την URI ανακατεύθυνσης
Αντιγραφή αναγνωριστικού εφαρμογής (προγράμματος-πελάτη)
Διαμόρφωση δικαιωμάτων APIΑπαιτεί δικαιώματα διαχειριστή
Προσθέστε την αξίωση ρόλου wids

Εάν αντιμετωπίζετε προβλήματα, ανατρέξτε στην ενότητα Αντιμετώπιση προβλημάτων.

Προαπαιτούμενα στοιχεία

Πριν ξεκινήσετε, βεβαιωθείτε ότι έχετε πρόσβαση στο Κέντρο διαχείρισης Microsoft Entra και, αν χρειάζεται, έναν από τους απαιτούμενους ρόλους διαχειριστή για την εκχώρηση συγκατάθεσης.

Για να καταχωρίσετε την εφαρμογή

Από προεπιλογή, οποιοσδήποτε χρήστης στον μισθωτή μπορεί να καταχωρήσει εφαρμογές στο Κέντρο διαχείρισης Microsoft Entra. Ωστόσο, οι διαχειριστές μισθωτών μπορούν να περιορίσουν αυτήν τη δυνατότητα. Εάν δεν μπορείτε να καταχωρίσετε την εφαρμογή σας, επικοινωνήστε με τον διαχειριστή σας.

Χρειάζεστε έναν από αυτούς τους ρόλους διαχειριστή για τη 4. Διαμόρφωση δικαιωμάτων API.

Διαχειριστής εφαρμογής: Συνιστάται - μπορεί να διαχειρίζεται εγγραφές εφαρμογών και να παρέχει συγκατάθεση
Διαχειριστής εφαρμογής Cloud: Μπορεί να διαχειριστεί τις εγγραφές εφαρμογών και να παρέχει συγκατάθεση
Καθολικός διαχειριστής: Έχει όλα τα δικαιώματα, αλλά δεν απαιτείται

Φιλοδώρημα

Δεν έχετε πρόσβαση διαχειριστή; Μπορείτε να ολοκληρώσετε μόνοι σας τα βήματα 1-3 και, στη συνέχεια, να ζητήσετε από τον διαχειριστή μισθωτή σας να ολοκληρώσει το βήμα 4. Δώστε του το αναγνωριστικό εφαρμογής (πελάτη) από το βήμα 3 και έναν σύνδεσμο προς την ενότητα Διαμόρφωση δικαιωμάτων API.

Φιλοδώρημα

Οι καθολικοί διαχειριστές μπορούν να παραλείψουν τη μη αυτόματη εγγραφή. Εκτελέστε a365 setup requirements και, αν η εφαρμογή Agent 365 CLI δεν εντοπιστεί στον μισθωτή σας, το CLI σας προτρέπει να τη δημιουργήσετε και να εκχωρήσετε αυτόματα τη συγκατάθεση διαχειριστή. Πληκτρολογήστε C στην προτροπή για να δημιουργήσετε την εφαρμογή σε ένα μόνο βήμα. Εάν χρησιμοποιείτε αυτήν την αυτοματοποιημένη διαδικασία, μπορείτε να παραλείψετε τα βήματα σε αυτήν την ενότητα.

1. Καταχώρηση εφαρμογής

Αυτές οι οδηγίες συνοψίζουν τις πλήρεις οδηγίες για τη δημιουργία μιας καταχώρησης εφαρμογής.

Μεταβείτε στο Κέντρο διαχείρισης Microsoft Entra
Επιλέξτε Καταχωρίσεις εφαρμογών
Επιλέξτε Νέα καταχώριση
Πληκτρολόγηση:
- Όνομα: Εισαγάγετε ένα περιγραφικό όνομα για την εφαρμογή σας, όπως my-agent-app. Οι χρήστες της εφαρμογής βλέπουν αυτό το όνομα και μπορείτε να το αλλάξετε ανά πάσα στιγμή. Μπορείτε να έχετε πολλές εγγραφές εφαρμογών με το ίδιο όνομα.
  
  Φιλοδώρημα
  
  Αν θέλετε να χρησιμοποιήσετε τη ροή χωρίς ρύθμιση παραμέτρων a365 setup all --agent-name, ονομάστε την εφαρμογή ακριβώς Agent 365 CLI. Το CLI αναζητά αυτόματα την εφαρμογή πελάτη με αυτό το γνωστό εμφανιζόμενο όνομα, επομένως δεν χρειάζεται να αντιγράψετε το αναγνωριστικό πελάτη σε ένα αρχείο διαμόρφωσης.
- Υποστηριζόμενοι τύποι λογαριασμών: Λογαριασμοί μόνο σε αυτόν τον κατάλογο(Μεμονωμένος μισθωτής)
- URI ανακατεύθυνσης: Επιλέξτε Δημόσιος/Εγγενής πελάτης (κινητό & υπολογιστής) και καταχωρίστε http://localhost:8400/
Επιλέξτε Καταχώρηση

Το CLI απαιτεί τρία URI ανακατεύθυνσης συνολικά. Το CLI προσθέτει αυτόματα όσα λείπουν όταν εκτελείτε το a365 setup requirements:

URI	Σκοπός
`http://localhost:8400/`	Βιβλιοθήκη ελέγχου ταυτότητας Microsoft (MSAL) αλληλεπιδραστικός έλεγχος ταυτότητας μέσω προγράμματος περιήγησης
`http://localhost`	Microsoft Graph PowerShell SDK `Connect-MgGraph`
`ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}`	Χρήση του Web Account Manager (WAM)

Δείτε Τι διαμορφώνει αυτόματα το CLI για λεπτομέρειες.

2. Ορίστε την URI ανακατεύθυνσης

Μεταβείτε στην Επισκόπηση και αντιγράψτε την τιμή Αναγνωριστικό εφαρμογής (πελάτης).
Μεταβείτε στην επιλογή Έλεγχος ταυτότητας (προεπισκόπηση) και μετά επιλέξτε Προσθήκη URI ανακατεύθυνσης.
Επιλέξτε Εφαρμογές για κινητά και υπολογιστές και ορίστε την τιμή σε ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}, όπου το {client-id} είναι το αναγνωριστικό εφαρμογής (πελάτη) που αντιγράψατε.
Επιλέξτε Ρύθμιση παραμέτρων για να προσθέσετε την τιμή.

3. Αντιγραφή αναγνωριστικού εφαρμογής (προγράμματος-πελάτη)

Από τη σελίδα Επισκόπηση της εφαρμογής, αντιγράψτε το αναγνωριστικό εφαρμογής (πελάτη) σε μορφή GUID. Χρησιμοποιείτε αυτήν την τιμή κατά την εκτέλεση του a365 setup all ή κατά τη μη αυτόματη δημιουργία του a365.config.json.

Φιλοδώρημα

Μην συγχέετε αυτήν την τιμή με το αναγνωριστικό αντικειμένου — χρειάζεστε το αναγνωριστικό εφαρμογής (πελάτη).

Εάν ονομάσατε την εφαρμογή σας Agent 365 CLI στο βήμα 1, μπορείτε να παραλείψετε αυτό το βήμα κατά τη χρήση του a365 setup all --agent-name. Το CLI επιλύει αυτόματα το αναγνωριστικό πελάτη βάσει του εμφανιζόμενου ονόματος.

4. Ρύθμιση παραμέτρων δικαιωμάτων API

Σημαντικό

Χρειάζεστε δικαιώματα διαχειριστή για αυτό το βήμα. Εάν είστε προγραμματιστής χωρίς πρόσβαση διαχειριστή, στείλτε το Αναγνωριστικό εφαρμογής (πελάτη) από το Βήμα 3 στον διαχειριστή του μισθωτή σας και ζητήστε του να ολοκληρώσει αυτό το βήμα.

Σημείωμα

Από τον Δεκέμβριο του 2025, οι άδειες AgentIdentityBlueprint.*, AgentInstance.* και AgentIdentity.* είναι API σε beta έκδοση και ενδέχεται να μην είναι ορατές στο Κέντρο διαχείρισης Microsoft Entra. Εάν αυτά τα δικαιώματα γίνουν γενικά διαθέσιμα στον μισθωτή σας, μπορείτε να χρησιμοποιήσετε την Επιλογή Α για όλα τα δικαιώματα.

Επιλέξτε την κατάλληλη μέθοδο:

Επιλογή Α: Χρήση του κέντρου διαχείρισης Microsoft Entra για όλα τα δικαιώματα (εάν τα δικαιώματα beta είναι ορατά)
Επιλογή Β: Χρησιμοποιήστε το Microsoft Graph API για να προσθέσετε όλα τα δικαιώματα (συνιστάται εάν τα δικαιώματα beta δεν είναι ορατά)

Επιλογή Α: Κέντρο διαχείρισης Microsoft Entra (Τυπική μέθοδος)

Χρησιμοποιήστε αυτήν τη μέθοδο εάν μπορείτε να δείτε δικαιώματα beta στον μισθωτή σας.

Στην καταχώρηση εφαρμογής, μεταβείτε στη διεύθυνση Άδειες API.
Επιλέξτε Προσθήκη άδειας>Microsoft Graph>Εκχωρημένα δικαιώματα.

Σημαντικό

Πρέπει να χρησιμοποιήσετε Εκχωρημένα δικαιώματα (όχι δικαιώματα εφαρμογής). Το CLI πραγματοποιεί έλεγχο ταυτότητας διαδραστικά - συνδέεστε και ενεργεί για λογαριασμό σας. Για να μάθετε περισσότερα, ανατρέξτε στο θέμα Λανθασμένος τύπος δικαιώματος.

Προσθέστε αυτά τα επτά δικαιώματα ένα προς ένα:

Δικαίωμα	Σκοπός
`AgentIdentityBlueprint.ReadWrite.All`	Δημιουργία Blueprint, διαχείριση μυστικού κωδικού προγράμματος-πελάτη, μεταβιβαζόμενα δικαιώματα, διαπιστευτήρια ομόσπονδης ταυτότητας και διαγραφή (beta API)
`AgentIdentityBlueprintPrincipal.Create`	Δημιουργία της κύριας οντότητας υπηρεσίας παράγοντα Blueprint (beta API)
`AgentIdentity.Read.All`	Έλεγχος αποδοχής και αναζήτηση κύριας οντότητας υπηρεσίας ταυτότητας παράγοντα (beta API)
`AgentIdentity.DeleteRestore.All`	Διαγραφή αρχών υπηρεσίας ταυτότητας παράγοντα κατά την εκκαθάριση (beta API)
`AgentRegistration.ReadWrite.All`	Ανάγνωση και εγγραφή όλων των εγγραφών παράγοντα
`Application.Read.All`	Αναζήτηση κύριας οντότητας υπηρεσίας κατά αναγνωριστικό εφαρμογής (στενότερη αντικατάσταση για το Directory.Read.All)
`User.Read`	Ανάγνωση του προφίλ του συνδεδεμένου χρήστη για ανάθεση κατόχου και χορηγού blueprint

Σημείωμα

Το AgentRegistration.ReadWrite.All απαιτείται για τη ρύθμιση του παράγοντα. Η επικύρωση CLI ελέγχει ρητά για αυτό το δικαίωμα. Πρέπει να υπάρχει στην εγγραφή της εφαρμογής σας και να έχει εγκριθεί η συγκατάθεση διαχειριστή.

Για κάθε δικαίωμα:

Στο πλαίσιο αναζήτησης, πληκτρολογήστε το όνομα του δικαιώματος (για παράδειγμα, AgentIdentityBlueprint.ReadWrite.All).
Επιλέξτε το πλαίσιο ελέγχου δίπλα στο δικαίωμα.
Επιλέξτε Προσθήκη δικαιωμάτων.
Επαναλάβετε και για τα επτά δικαιώματα.

Επιλέξτε Εκχώρηση συναίνεσης διαχειριστή για το [ο μισθωτής σας].
- Γιατί απαιτείται αυτό; Τα blueprints ταυτότητας παράγοντα είναι πόροι σε επίπεδο μισθωτή στους οποίους μπορούν να αναφέρονται πολλοί χρήστες και εφαρμογές. Χωρίς συγκατάθεση σε επίπεδο μισθωτή, το CLI αποτυγχάνει κατά τον έλεγχο ταυτότητας.
- Τι γίνεται αν αποτύχει; Χρειάζεστε τον ρόλο Διαχειριστή Εφαρμογών, Διαχειριστή Cloud Εφαρμογών ή Γενικού Διαχειριστή Ζητήστε βοήθεια από τον διαχειριστή μισθωτή σας.
Βεβαιωθείτε ότι όλα τα δικαιώματα εμφανίζουν πράσινα σημάδια ελέγχου στην περιοχή Κατάσταση.

Εάν τα δικαιώματα beta (AgentIdentityBlueprint.*) δεν είναι ορατά, προχωρήστε στην Επιλογή Β.

Επιλογή Β: Microsoft Graph API (για δικαιώματα beta)

Χρησιμοποιήστε αυτήν τη μέθοδο εάν το Κέντρο διαχείρισης Microsoft Entra δεν εμφανίζει AgentIdentityBlueprint.* δικαιώματα.

Προειδοποίηση

Εάν χρησιμοποιείτε αυτήν τη μέθοδο API, μην χρησιμοποιήσετε το κουμπί "Εκχώρηση συγκατάθεσης διαχειριστή" του Κέντρου διαχείρισης Microsoft Entra στη συνέχεια. Η μέθοδος API εκχωρεί αυτόματα τη συγκατάθεση του διαχειριστή και η χρήση του κουμπιού του κέντρου διαχείρισης Microsoft Entra διαγράφει τα δικαιώματα beta. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Εξαφάνιση δικαιωμάτων beta.

Ανοίξτε το Graph Explorer.
Συνδεθείτε με τον λογαριασμό διαχειριστή σας (Διαχειριστής εφαρμογής ή Διαχειριστής εφαρμογής Cloud).
Παραχωρήστε συγκατάθεση διαχειριστή μέσω Graph API. Για να ολοκληρώσετε αυτό το βήμα, πρέπει να κάνετε τα εξής:
- Αναγνωριστικό κύριας υπηρεσίας. Χρειάζεστε την τιμή της μεταβλητής SP_OBJECT_ID.
- Αναγνωριστικό πόρου του Microsoft Graph. Χρειάζεστε την τιμή της μεταβλητής GRAPH_RESOURCE_ID.
- Δημιουργήστε (ή ενημερώστε) δικαιώματα με ανάθεση χρησιμοποιώντας τον τύπο πόρου oAuth2PermissionGrant με τις τιμές μεταβλητής SP_OBJECT_ID και GRAPH_RESOURCE_ID.

Χρησιμοποιήστε τις πληροφορίες στις ακόλουθες ενότητες για να ολοκληρώσετε αυτά τα βήματα.

Αποκτήστε το αναγνωριστικό κύριας οντότητας υπηρεσίας σας

Η κύρια οντότητα υπηρεσίας είναι η ταυτότητα της εφαρμογής σας στον μισθωτή σας. Την χρειάζεστε για να μπορέσετε να εκχωρήσετε δικαιώματα μέσω του API.

Ορίστε τη μέθοδο Graph Explorer σε GET και χρησιμοποιήστε αυτήν τη διεύθυνση URL. Αντικαταστήστε το <YOUR_CLIENT_APP_ID> με το πραγματικό αναγνωριστικό προγράμματος-πελάτη εφαρμογής από το Βήμα 3: Αντιγραφή αναγνωριστικού εφαρμογής (προγράμματος-πελάτη):
```
https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '<YOUR_CLIENT_APP_ID>'&$select=id
```
Επιλέξτε Εκτέλεση ερωτήματος.
- Αν το ερώτημα εκτελεστεί με επιτυχία, η επιστρεφόμενη τιμή είναι το SP_OBJECT_ID σας.
- Εάν το ερώτημα αποτύχει με σφάλμα δικαιωμάτων, επιλέξτε την καρτέλα Τροποποίηση δικαιωμάτων, δώστε τη συγκατάθεσή σας για τα απαιτούμενα δικαιώματα και στη συνέχεια επιλέξτε ξανά Εκτέλεση ερωτήματος. Η τιμή που επιστρέφεται είναι το SP_OBJECT_ID σας.
- Εάν το ερώτημα επιστρέφει κενά αποτελέσματα ("value": []), δημιουργήστε την κύρια οντότητα υπηρεσίας ακολουθώντας τα παρακάτω βήματα:
  1. Ορίστε τη μέθοδο σε POST και χρησιμοποιήστε αυτήν τη διεύθυνση URL:
```
https://graph.microsoft.com/v1.0/servicePrincipals
```
    Σώμα αιτήματος (αντικαταστήστε το YOUR_CLIENT_APP_ID με το πραγματικό αναγνωριστικό προγράμματος-πελάτη εφαρμογής):
```
{
   "appId": "YOUR_CLIENT_APP_ID"
}
```
  2. Επιλέξτε Εκτέλεση ερωτήματος. Θα πρέπει να λάβετε μια 201 Created απάντηση. Η τιμή id που επιστρέφεται είναι το SP_OBJECT_ID σας.

Λάβετε το αναγνωριστικό πόρου Graph

Ορίστε τη μέθοδο Graph Explorer σε GET και χρησιμοποιήστε αυτήν τη διεύθυνση URL:
```
https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=id
```
Επιλέξτε Εκτέλεση ερωτήματος.
- Αν το ερώτημα επιτύχει, αντιγράψτε την id τιμή. Αυτή η τιμή είναι το GRAPH_RESOURCE_ID σας.
- Εάν το ερώτημα αποτύχει με σφάλμα δικαιωμάτων, επιλέξτε την καρτέλα Τροποποίηση δικαιωμάτων, δώστε τη συγκατάθεσή σας για τα απαιτούμενα δικαιώματα και στη συνέχεια επιλέξτε ξανά Εκτέλεση ερωτήματος. Αντιγράψτε την id τιμή. Αυτή η τιμή είναι το GRAPH_RESOURCE_ID σας.

Δημιουργία εκχωρημένων δικαιωμάτων

Αυτή η κλήση API παρέχει συγκατάθεση διαχειριστή σε ολόκληρο τον tenant για όλες τις επτά άδειες, συμπεριλαμβανομένων των beta αδειών που δεν είναι ορατές στο Κέντρο διαχείρισης Microsoft Entra.

Ορίστε τη μέθοδο Graph Explorer σε POST και χρησιμοποιήστε αυτήν τη διεύθυνση URL και το σώμα αιτήματος:

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

Σώμα αίτησης:

{
"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"
}

Επιλέξτε Εκτέλεση ερωτήματος.
- Εάν λάβετε 201 Created απάντηση: Επιτυχία! Το πεδίο scope της απόκρισης εμφανίζει και τα επτά ονόματα δικαιωμάτων. Είστε έτοιμοι.
- Εάν το ερώτημα αποτύχει λόγω σφάλματος δικαιωμάτων, μεταβείτε στην καρτέλα Τροποποίηση δικαιωμάτων, συναινέστε στα απαιτούμενα δικαιώματα και στη συνέχεια επιλέξτε Εκτέλεση ερωτήματος ξανά.
- Αν λάβετε το σφάλμα Request_MultipleObjectsWithSameKeyValue: Υπάρχει ήδη παραχώρηση. Ίσως κάποιος πρόσθεσε δικαιώματα νωρίτερα. Δείτε την Ενημέρωση εκχωρημένων δικαιωμάτων.

Προειδοποίηση

Το consentType: "AllPrincipals" στην POST αίτηση εκχωρεί ήδη συγκατάθεση διαχειριστή σε επίπεδο μισθωτή. ΜΗΝ επιλέξετε «Παροχή συγκατάθεσης διαχειριστή» στο Κέντρο διαχείρισης Microsoft Entra μετά τη χρήση αυτής της μεθόδου API – αν το κάνετε, διαγράφονται τα δικαιώματα beta, επειδή το Κέντρο διαχείρισης Microsoft Entra δεν μπορεί να δει τα δικαιώματα beta και αντικαθιστά τη συγκατάθεση που δόθηκε μέσω API μόνο με τα ορατά δικαιώματα.

Ενημέρωση εκχωρημένων δικαιωμάτων

Εάν λάβετε ένα σφάλμα Request_MultipleObjectsWithSameKeyValue ακολουθώντας τα βήματα για τη δημιουργία εκχωρημένων δικαιωμάτων, χρησιμοποιήστε αυτά τα βήματα για να ενημερώσετε τα εκχωρημένα δικαιώματα.

Ορίστε τη μέθοδο Graph Explorer σε GET και χρησιμοποιήστε αυτήν τη διεύθυνση URL:
```
https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'SP_OBJECT_ID_FROM_ABOVE'
```
Επιλέξτε Εκτέλεση ερωτήματος. Αντιγράψτε την id τιμή από την απάντηση. Αυτή η τιμή είναι YOUR_GRANT_ID.

Ορίστε τη μέθοδο του Graph Explorer σε PATCH και χρησιμοποιήστε αυτή τη διεύθυνση URL με YOUR_GRANT_ID.

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

Σώμα αίτησης:

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

Επιλέξτε Εκτέλεση ερωτήματος. Θα πρέπει να λάβετε μια 200 OK απάντηση με όλα τα επτά δικαιώματα στο πεδίο scope.

5. Προσθέστε την αξίωση ρόλου wids

Το Agent 365 CLI διαβάζει τις αναθέσεις ρόλων στον κατάλογο Entra απευθείας από το διακριτικό πρόσβασης για να προσδιορίσει αν έχετε δικαιώματα διαχειριστή. Αυτό απαιτεί την προσθήκη της wids αξίωσης στα διακριτικά πρόσβασης που εκδίδονται για την εγγραφή της εφαρμογής σας.

Χωρίς αυτήν την αξίωση, το CLI δεν μπορεί να εντοπίσει τον ρόλο σας και επιστρέφει στην εμφάνιση οδηγιών PowerShell για κάθε βήμα που απαιτεί δικαιώματα διαχειριστή — ακόμη και όταν είστε διαχειριστής. Ολοκληρώστε αυτό το βήμα για να διασφαλίσετε τη σωστή λειτουργία.

Στην εγγραφή της εφαρμογής σας, μεταβείτε στη Διαμόρφωση διακριτικού.
Επιλέξτε Προσθήκη προαιρετικής αξίωσης.
Για Τύπο διακριτικού, επιλέξτε Πρόσβαση.
Επιλέξτε το πλαίσιο δίπλα στο wids.
Επιλέξτε Προσθήκη.

Εάν σας ζητηθεί να ενεργοποιήσετε την άδεια Microsoft Graph profile για να επιτρέψετε την αξίωση, επιλέξτε Ναι, προσθήκη.

Σημείωμα

Η wids αξίωση περιέχει τα GUID του προτύπου ρόλου των ρόλων καταλόγου του Entra που έχουν εκχωρηθεί απευθείας στον συνδεδεμένο χρήστη. Το CLI χρησιμοποιεί αυτά τα GUID για να ανιχνεύει τους ρόλους Global Administrator και Agent ID Administrator χωρίς πρόσθετη κλήση στο Graph API.

Περιορισμός:wids περιλαμβάνει μόνο τους ρόλους που έχουν ανατεθεί απευθείας. Εάν ο μισθωτής σας αναθέτει ρόλους καταλόγου μέσω ομάδων ασφαλείας με δυνατότητα ανάθεσης ρόλων, το CLI ενδέχεται να μην εντοπίσει αυτές τις αναθέσεις ρόλων που βασίζονται σε ομάδες. Η απευθείας ανάθεση ρόλου αποτελεί το πρότυπο τόσο για τον προγραμματιστή αναγνωριστικού παράγοντα όσο και τους ρόλους διαχειριστή.

Βέλτιστες πρακτικές για την ασφάλεια

Ελέγξτε αυτές τις οδηγίες για να διατηρήσετε την εγγραφή της εφαρμογής σας ασφαλή και συμμορφούμενη.

Τι να κάνετε:

Χρησιμοποιήστε την εγγραφή ενός μισθωτή.
Εκχωρήστε μόνο τα απαιτούμενα δικαιώματα.
Ελέγχετε τακτικά τα δικαιώματα πρόσβασης.
Καταργήστε την εφαρμογή όταν δεν χρειάζεται πλέον.

Τι να μην κάνετε:

Μην εκχωρήσετε δικαιώματα εφαρμογής. Χρησιμοποιείτε μόνο εκχωρημένα δικαιώματα.
Μην κοινοποιείτε το αναγνωριστικό πελάτη δημόσια.
Μην εκχωρείτε άλλα περιττά δικαιώματα.
Μην χρησιμοποιήσετε την εφαρμογή για άλλους σκοπούς.

Τι διαμορφώνει αυτόματα το CLI

Όταν εκτελείτε a365 setup requirements, το CLI επικυρώνει την εγγραφή της εφαρμογής σας και ίσως χρειαστεί να κάνει αλλαγές. Πριν εφαρμόσει οποιεσδήποτε αλλαγές, το CLI εμφανίζει μια περίληψη και ζητά επιβεβαίωση:

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

Για να παραλείψετε την προτροπή επιβεβαίωσης (για παράδειγμα, σε περιβάλλον CI), χρησιμοποιήστε τη σημαία --yes:

a365 setup requirements --yes

Ο παρακάτω πίνακας περιγράφει κάθε αλλαγή που μπορεί να κάνει το CLI:

Αλλαγή	Αιτιολογία
Προσθήκη URI ανακατεύθυνσης `http://localhost`	Το Microsoft Graph PowerShell SDK απαιτεί αυτό το URI για τον έλεγχο ταυτότητας του προγράμματος περιήγησης. Χωρίς αυτό, οι λειτουργίες εκχώρησης OAuth2 επιστρέφουν σε ένα διακριτικό που δεν διαθέτει τα απαιτούμενα εξουσιοδοτημένα δικαιώματα και αποτυγχάνουν με το 403.
Προσθήκη URI ανακατεύθυνσης `http://localhost:8400/`	Το MSAL απαιτεί αυτό το URI για αλληλεπιδραστικό έλεγχο ταυτότητας μέσω προγράμματος περιήγησης.
Προσθήκη URI ανακατεύθυνσης `ms-appx-web://Microsoft.AAD.BrokerPlugin/{id}`	Απαιτείται για το Web Account Manager (WAM), έναν μεσολαβητή ελέγχου ταυτότητας του λειτουργικού συστήματος Windows. Μάθετε περισσότερα σχετικά με την απόκτηση διακριτικών που συνδέονται με τη συσκευή.
Ενεργοποιήστε την επιλογή "Να επιτρέπονται δημόσιες ροές προγράμματος-πελάτη"	Απαιτείται για εναλλακτική μέθοδο ελέγχου ταυτότητας με κωδικό συσκευής σε macOS, Linux, Υποσύστημα των Windows για Linux (WSL), περιβάλλοντα χωρίς κεφαλή και ως μέθοδο εναλλακτικής πολιτικής πρόσβασης υπό όρους στα Windows.
Προσθέστε δικαιώματα που λείπουν στην εγγραφή εφαρμογής	Διατηρεί την εγγραφή της εφαρμογής σε συγχρονισμό με τα νεοαπαιτούμενα δικαιώματα μετά από μια ενημέρωση CLI.
Επέκταση εκχώρησης συναίνεσης διαχειριστή	Επεκτείνει την υπάρχουσα παραχώρηση δικαιωμάτων OAuth2 ώστε να περιλαμβάνει τα νέα δικαιώματα που έχουν προστεθεί.

Εάν απορρίψετε την προτροπή, το CLI δεν τροποποιεί την εγγραφή της εφαρμογής σας. Εάν απαιτούνται αλλαγές για τη λειτουργία του CLI, μπορείτε να τις ρυθμίσετε με μη αυτόματο τρόπο στο Κέντρο διαχείρισης Microsoft Entra ή να επαναλάβετε τη διαδικασία με --yes.

Επόμενα βήματα

Μετά την εγγραφή της προσαρμοσμένης εφαρμογής client, χρησιμοποιήστε την με το Agent 365 CLI για να ολοκληρώσετε τη διαμόρφωση του Agent 365:

Ξεκινήστε με την ανάπτυξη του Agent 365

Αντιμετώπιση προβλημάτων

Αυτή η ενότητα περιγράφει τον τρόπο αντιμετώπισης σφαλμάτων κατά την εγγραφή προσαρμοσμένης εφαρμογής πελάτη.

Φιλοδώρημα

Ο Οδηγός αντιμετώπισης προβλημάτων του Agent 365 περιλαμβάνει συστάσεις αντιμετώπισης προβλημάτων υψηλού επιπέδου, βέλτιστες πρακτικές και συνδέσμους για περιεχόμενο αντιμετώπισης προβλημάτων για κάθε μέρος του κύκλου ζωής ανάπτυξης του Agent 365.

Η επικύρωση CLI αποτυγχάνει κατά τη διαμόρφωση

Σύμπτωμα: Όταν εκτελείτε a365 setup ή a365 setup requirements, εμφανίζονται σφάλματα επικύρωσης σχετικά με την προσαρμοσμένη εφαρμογή-πελάτη σας.

Λύση: Χρησιμοποιήστε αυτήν τη λίστα ελέγχου για να επαληθεύσετε ότι η εγγραφή της εφαρμογής σας είναι σωστή:

# Run requirements validation to see validation messages
a365 setup requirements

Αναμενόμενο αποτέλεσμα: Το CLI εμφανίζει Custom client app validation successful.

Εάν δεν λάβετε το αναμενόμενο αποτέλεσμα, επαληθεύστε καθέναν από τους παρακάτω ελέγχους:

Έλεγχος	Πώς να επαληθεύσετε	Διόρθωση
✅ Χρήση σωστού αναγνωριστικού	Αντιγράψατε το αναγνωριστικό εφαρμογής (πελάτη) (όχι το αναγνωριστικό αντικειμένου)	Μεταβείτε στην Επισκόπηση εφαρμογής στο Κέντρο διαχείρισης Microsoft Entra
✅ Εκχωρημένα δικαιώματα	Στα δικαιώματα API εμφανίζεται Τύπος: Εκχωρήθηκε	Δείτε Λανθασμένος τύπος δικαιώματος
✅ Προστέθηκαν όλα τα δικαιώματα	Δείτε όλα τα δικαιώματα που αναφέρονται παρακάτω	Ακολουθήστε ξανά το Βήμα 4
✅ Εκχώρηση συγκατάθεσης διαχειριστή	Όλα εμφανίζουν πράσινο σημάδι επιλογής στη στήλη Κατάσταση	Δείτε τη συγκατάθεση διαχειριστή που χορηγήθηκε εσφαλμένα

Απαιτούμενα εκχωρημένα δικαιώματα:

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

Σύμπτωμα: Η επικύρωση αποτυγχάνει παρόλο που έχετε προσθέσει δικαιώματα.

Βασική αιτία: Δεν παραχωρήσατε συγκατάθεση διαχειριστή ή την παραχωρήσατε εσφαλμένα.

Λύση: Στην καταχώριση της εφαρμογής σας στο Κέντρο διαχείρισης Microsoft Entra, μεταβείτε στα δικαιώματα API και επιλέξτε Εκχώρηση συγκατάθεσης διαχειριστή για [Ο μισθωτής σας]. Βεβαιωθείτε ότι όλα τα δικαιώματα εμφανίζουν πράσινα σημάδια ελέγχου στην περιοχή Κατάσταση.

Σύμπτωμα: a365 setup all εμφανίζει το μήνυμα «Εξασφαλίστηκε με επιτυχία η συγκατάθεση της ανατεθειμένης εφαρμογής», αλλά αποτυγχάνει αμέσως κατά τη δημιουργία του σχεδιαγράμματος με:

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>

Βασική αιτία: Ο μισθωτής σας έχει ήδη μια oauth2PermissionGrant εγγραφή για την προσαρμοσμένη εφαρμογή προγράμματος-πελάτη (από προηγούμενη εκτέλεση μερικής εγκατάστασης ή από προηγούμενη ενέργεια "Grant admin consent" στο Κέντρο διαχείρισης Microsoft Entra για άλλες περιοχές), αλλά αυτή η εγγραφή δεν περιέχει το απαιτούμενο πεδίο (AgentIdentityBlueprint.ReadWrite.All). Το CLI εντοπίζει το εύρος που λείπει και εμφανίζει μια διεύθυνση URL συναίνεσης για έναν διαχειριστή για την ολοκλήρωση της εκχώρησης.

Λύση:

Κοινοποιήστε τον σύνδεσμο συγκατάθεσης που εμφανίζεται στην έξοδο σφάλματος σε έναν Διαχειριστή Εφαρμογών ή Καθολικό Διαχειριστή. Η διεύθυνση URL έχει την εξής μορφή:

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

Αφού ο διαχειριστής δώσει συγκατάθεση, εκτελέστε ξανά το a365 setup all --agent-name <name>.

Εάν έχετε δικαιώματα διαχειριστή, μπορείτε να ανοίξετε τη διεύθυνση URL απευθείας σε ένα πρόγραμμα περιήγησης και να δώσετε συγκατάθεση χωρίς να περιμένετε.

Λάθος τύπος δικαιώματος

Σύμπτωμα: Το CLI αποτυγχάνει με σφάλματα ελέγχου ταυτότητας ή σφάλματα άρνησης δικαιωμάτων.

Βασική αιτία: Προσθέσατε δικαιώματα εφαρμογής αντί για εκχωρημένα δικαιώματα.

Αυτός ο πίνακας περιγράφει τους διαφορετικούς τύπους δικαιωμάτων.

Τύπος άδειας	Πότε να χρησιμοποιηθούν	Πώς το χρησιμοποιεί το Agent 365 CLI
Εκχωρημένο ("Πεδίο")	Ο χρήστης συνδέεται διαδραστικά	Το Agent 365 CLI χρησιμοποιεί αυτό – Εσείς συνδέεστε, το CLI ενεργεί για λογαριασμό σας
Εφαρμογή ("Ρόλος")	Η υπηρεσία εκτελείται χωρίς χρήστη	Να μην χρησιμοποιείται - Μόνο για υπηρεσίες παρασκηνίου/daemons

Γιατί εκχωρημένο;

Συνδέεστε αλληλεπιδραστικά μέσω ελέγχου ταυτότητας προγράμματος περιήγησης
Το CLI εκτελεί ενέργειες ως εσείς (τα αρχεία καταγραφής ελέγχου δείχνουν την ταυτότητά σας)
Πιο ασφαλές - περιορίζεται από τα πραγματικά σας δικαιώματα
Διασφαλίζει λογοδοσία και συμμόρφωση

Λύση:

Μεταβείτε στο Κέντρο διαχείρισης Microsoft Entra>Εγγραφές εφαρμογών> Η εφαρμογή σας >Άδειες API
Καταργήστε τυχόν δικαιώματα εφαρμογής. Αυτά τα δικαιώματα εμφανίζονται ως Εφαρμογή στη στήλη Τύπος.
Προσθέστε τα ίδια δικαιώματα με τα Εκχωρημένα δικαιώματα.
Εκχώρηση συγκατάθεσης διαχειριστή ξανά.

Σύμπτωμα: Χρησιμοποιήσατε την Επιλογή Β: Microsoft Graph API (για δικαιώματα beta) για να προσθέσετε δικαιώματα beta, αλλά αυτά εξαφανίζονται αφού επιλέξετε Εκχώρηση συγκατάθεσης διαχειριστή στο Κέντρο διαχείρισης Microsoft Entra.

Βασική αιτία: Το Κέντρο διαχείρισης Microsoft Entra δεν εμφανίζει δικαιώματα beta στο περιβάλλον εργασίας χρήστη. Όταν επιλέγετε Εκχώρηση συγκατάθεσης διαχειριστή, η πύλη εκχωρεί συγκατάθεση μόνο για τα ορατά δικαιώματα και αντικαθιστά τη συγκατάθεση που έχει εκχωρηθεί από το API.

Γιατί συμβαίνει αυτό:

Χρησιμοποιείτε το Microsoft Graph (Επιλογή Β) για να προσθέσετε και τα επτά δικαιώματα, συμπεριλαμβανομένων των δικαιωμάτων beta.
Η κλήση API με consentType: "AllPrincipals"ήδη εκχωρεί συγκατάθεση διαχειριστή σε όλο τον μισθωτή.
Πηγαίνετε στο Κέντρο διαχείρισης Microsoft Entra και βλέπετε μόνο ένα υποσύνολο των δικαιωμάτων, επειδή τα δικαιώματα beta δεν είναι ορατά στην πύλη.
Επιλέγετε Εκχώρηση συγκατάθεσης διαχειριστή θεωρώντας ότι πρέπει να το κάνετε.
Το κέντρο διαχείρισης Microsoft Entra αντικαθιστά τη συγκατάθεση που έχει εκχωρηθεί από το API μόνο με ορατά δικαιώματα.
Τα δικαιώματα beta έχουν πλέον διαγραφεί.

Λύση:

Μην χρησιμοποιείτε τη λειτουργία συγκατάθεσης διαχειριστή στο κέντρο διαχείρισης Microsoft Entra μετά τη μέθοδο API: Η μέθοδος API εκχωρεί ήδη συγκατάθεση διαχειριστή.
Εάν διαγράψετε κατά λάθος τα δικαιώματα beta, επαναλάβετε την Επιλογή B Βήμα 3 (Χορηγήστε τη διαχειριστική συγκατάθεση μέσω του Microsoft Graph) για να τα επαναφέρετε. Εάν εμφανιστεί κάποιο Request_MultipleObjectsWithSameKeyValue σφάλμα, ακολουθήστε τα βήματα για την Ενημέρωση εκχωρημένων δικαιωμάτων.
Για να επαληθεύσετε ότι εμφανίζονται και τα επτά δικαιώματα, ελέγξτε το πεδίο scope στην απάντηση POST ή PATCH.

Η εφαρμογή δεν βρέθηκε κατά την επικύρωση

Σύμπτωμα: Το CLI αναφέρει σφάλματα Application not found ή Invalid client ID.

Λύση:

Βεβαιωθείτε ότι έχετε αντιγράψει το Αναγνωριστικό εφαρμογής (πελάτης) σε μορφή GUID, και όχι το Αναγνωριστικό αντικειμένου:
- Μεταβείτε στο Κέντρο διαχείρισης Microsoft Entra>Εγγραφές εφαρμογών> Η εφαρμογή σας >Επισκόπηση
- Αντιγράψτε την τιμή κάτω από το Αναγνωριστικό εφαρμογής (πρόγραμμα-πελάτης)
- Η μορφή πρέπει να είναι: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Επαληθεύστε ότι η εφαρμογή υπάρχει στον μισθωτή σας:

# Sign in to the correct tenant
az login

# List your app registrations
az ad app list --display-name "<The display name of your app>"

Ενημερωθείτε για τον τρόπο καταχώρησης αίτησης στο Microsoft Entra ID.

Σχόλια

Ήταν χρήσιμη αυτή η σελίδα;

Last updated on 2026-07-30

Εγγραφή προσαρμοσμένης εφαρμογής-πελάτη για το Agent 365 CLI

Προαπαιτούμενα στοιχεία

Για να καταχωρίσετε την εφαρμογή

Για να προσθέσετε δικαιώματα και να εκχωρήσετε συγκατάθεση

1. Καταχώρηση εφαρμογής

2. Ορίστε την URI ανακατεύθυνσης

3. Αντιγραφή αναγνωριστικού εφαρμογής (προγράμματος-πελάτη)

4. Ρύθμιση παραμέτρων δικαιωμάτων API

Επιλογή Α: Κέντρο διαχείρισης Microsoft Entra (Τυπική μέθοδος)

Επιλογή Β: Microsoft Graph API (για δικαιώματα beta)

Αποκτήστε το αναγνωριστικό κύριας οντότητας υπηρεσίας σας

Λάβετε το αναγνωριστικό πόρου Graph

Δημιουργία εκχωρημένων δικαιωμάτων

Ενημέρωση εκχωρημένων δικαιωμάτων

5. Προσθέστε την αξίωση ρόλου wids

Βέλτιστες πρακτικές για την ασφάλεια

Τι διαμορφώνει αυτόματα το CLI

Επόμενα βήματα

Αντιμετώπιση προβλημάτων

Η επικύρωση CLI αποτυγχάνει κατά τη διαμόρφωση

Η συγκατάθεση διαχειριστή χορηγήθηκε εσφαλμένα

Η δημιουργία blueprint αποτυγχάνει με το μήνυμα «Δεν έχει δοθεί συγκατάθεση διαχειριστή»

Λάθος τύπος δικαιώματος

Τα δικαιώματα beta εξαφανίζονται μετά τη συγκατάθεση διαχειριστή του κέντρου διαχείρισης Microsoft Entra

Η εφαρμογή δεν βρέθηκε κατά την επικύρωση

Σχόλια

Πρόσθετοι πόροι