רישום אפליקציית לקוח מותאמת אישית עבור Agent 365 CLI

Agent 365 CLI זקוק לרישום אפליקציית לקוח מותאמת אישית בדייר Microsoft Entra ID שלך כדי לבצע אימות ולנהל תוכניות אב של זהויות סוכן.

מאמר זה מחלק את התהליך לארבעה שלבים עיקריים:

  1. רישום אפליקציה
  2. הגדרת ה-URI להפניה מחדש
  3. העתקת מזהה האפליקציה (לקוח)
  4. קביעת התצורה של הרשאות API נדרשות הרשאות מנהל מערכת
  5. הוספת תביעת התפקיד wids

אם אתה נתקל בבעיות, עיין במקטע פתרון בעיות.

‏‫דרישות מוקדמות‬

לפני שתתחיל, ודא שיש לך גישה למרכז הניהול של Microsoft Entra, ובמידת הצורך, אחד מתפקידי מנהל המערכת הנדרשים למתן הסכמה.

כדי לרשום את האפליקציה

כברירת מחדל, כל משתמש ב-tenant יכול לרשום אפליקציות במרכז הניהול של Microsoft Entra. עם זאת, מנהלי הדייר יכולים להגביל את היכולת הזו. אם אינך יכול לרשום את האפליקציה, פנה למנהל המערכת.

נדרש לך אחד מתפקידי מנהל המערכת האלה עבור 4. קביעת התצורה של הרשאות API.

עצה

אין לך גישת מנהל מערכת? תוכל להשלים בעצמך את שלבים 1-3, ולאחר מכן לבקש ממנהל הדייר להשלים את שלב 4. ספק לו את מזהה האפליקציה (לקוח) משלב 3 וקישור למקטע קביעת התצורה של הרשאות API.

עצה

מנהלי מערכת כלליים יכולים לדלג על הרישום הידני. הפעל את a365 setup requirements, ואם Agent 365 CLIהאפליקציה Agent 365 CLI לא נמצאת בדייר שלך, ה-CLI מבקש ממך ליצור אותה ולהעניק הסכמת מנהל מערכת באופן אוטומטי. הקלד C בהנחיה כדי ליצור את האפליקציה בשלב אחד. אם אתה משתמש בנתיב אוטומטי זה, תוכל לדלג על השלבים במקטע זה.

1. רישום אפליקציה

הוראות אלה מסכמות את ההוראות המלאות ליצירת רישום אפליקציה.

  1. עבור אל מרכז הניהול של Microsoft Entra

  2. בחר רישומי אפליקציות

  3. בחר רישום חדש

  4. הזן:

    • שם: הזן שם בעל משמעות עבור האפליקציה, כגון my-agent-app.my-agent-app. משתמשי האפליקציה רואים שם זה, ותוכל לשנות אותו בכל עת. באפשרותך ליצור כמה רישומי אפליקציות בעלי אותו שם.

      עצה

      כדי להשתמש בזרימת a365 setup all --agent-name ללא קביעת תצורה, תן לאפליקציה את השם המדויק Agent 365 CLIAgent 365 CLI. ה-CLI מחפש את אפליקציית הלקוח באופן אוטומטי לפי שם תצוגה מוכר זה, כך שאין צורך להעתיק את מזהה הלקוח לקובץ תצורה.

    • סוגי חשבונות נתמכים: חשבונות בספריה ארגונית זו בלבד (דייר יחיד)

    • URI להפניה מחדש: בחר לקוח ציבורי/מקורי (מכשירים ניידים ושולחן עבודה) והזן http://localhost:8400/http://localhost:8400/

  5. בחר הרשמה.

בסך הכול, ה-CLI דורש שלושה מזהי URI להפניה מחדש. ה-CLI מוסיף באופן אוטומטי כל URI חסר בעת הפעלת a365 setup requirements:

URI מטרה
http://localhost:8400/ אימות אינטראקטיבי בדפדפן באמצעות Microsoft Authentication Library ‏(MSAL)
http://localhost Microsoft Graph PowerShell SDK Connect-MgGraph
ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id} שימוש ב-Web Account Manager ‏(WAM)

לפרטים, ראה מה ה-CLI מגדיר באופן אוטומטי.

2. הגדרת ה-URI להפניה מחדש

  1. עבור אל מבט כולל והעתק את הערך מזהה אפליקציה (לקוח).
  2. עבור אל אימות (תצוגה מקדימה) ובחר הוספת URI להפניה מחדש.
  3. בחר אפליקציות למכשירים ניידים ולשולחן העבודה והגדר את הערך ל-ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}, כאשר ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}{client-id} הוא הערך מזהה אפליקציה (לקוח) שהעתקת.
  4. בחר קביעת תצורה כדי להוסיף את הערך.

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 בגירסת ביתא וייתכן שלא יהיו גלויות במרכז הניהול של Microsoft Entra. אם הרשאות אלה יהפכו לזמינות באופן כללי בדייר שלך, תוכל להשתמש באפשרות א' עבור כל ההרשאות.

בחר את השיטה המתאימה:

  • אפשרות א: השתמש במרכז הניהול של Microsoft Entra לכל ההרשאות (אם הרשאות הבטא גלויות)
  • אפשרות ב': השתמש ב-Microsoft Graph API כדי להוסיף את כל ההרשאות (מומלץ אם הרשאות הביתא אינן גלויות)

אפשרות א': מרכז הניהול של Microsoft Entra (שיטה רגילה)

השתמש בשיטה זו אם הרשאות הביתא גלויות בדייר שלך.

  1. ברישום האפליקציה, עבור אל הרשאות API.

  2. בחר הוספת הרשאה>Microsoft Graph>הרשאות מואצלות.

    חשוב

    עליך להשתמש בהרשאות מואצלות (ולא בהרשאות אפליקציה). ה-CLI מבצע אימות באופן אינטראקטיבי - אתה נכנס, והוא פועל בשמך. למידע נוסף, ראה סוג הרשאה שגוי.

  3. הוסף את שבע ההרשאות האלה בזו אחר זו:

    הרשאה מטרה
    AgentIdentityBlueprint.ReadWrite.All יצירת שרטוטים, ניהול סודות הלקוח, הרשאות בירושה, אישורי זהות מאוחדים, ומחיקה (API בטא)
    AgentIdentityBlueprintPrincipal.Create יצירת מנהל שירות Blueprint של סוכן ‏(API בגירסת ביתא)
    AgentIdentity.Read.All בדיקת אידמפוטנטיות וחיפוש מנהל השירות של זהות הסוכן (API בגירסת ביתא)
    AgentIdentity.DeleteRestore.All מחיקת מנהלי שירות של זהויות סוכן במהלך ניקוי (API בגירסת ביתא)
    AgentRegistration.ReadWrite.All קריאה וכתיבה של כל רישומי הסוכנים
    Application.Read.All חיפוש מנהל שירות לפי מזהה אפליקציה (תחליף מצומצם יותר ל-Directory.Read.All)
    User.Read קריאת פרופיל המשתמש המחובר לצורך הקצאת בעלים ונותן חסות לתוכנית האב

    הערה

    AgentRegistration.ReadWrite.All נדרשת להגדרת הסוכן. מאמת ה-CLI בודק במפורש אם הרשאה זו קיימת. היא חייבת להיכלל ברישום האפליקציה שלך ולקבל הסכמת מנהל מערכת.

    עבור כל הרשאה:

    • בתיבת החיפוש, הקלד את שם ההרשאה (לדוגמה, AgentIdentityBlueprint.ReadWrite.All).
    • סמן את תיבת הסימון לצד ההרשאה.
    • בחר הוסף הרשאות.
    • חזור על הפעולה עבור כל שבע ההרשאות.

  4. בחר הענקת הסכמת מנהל מערכת עבור [הדייר שלך].

    • מדוע הדבר נדרש? תוכניות אב של זהויות סוכן הן משאבים כלל-דייריים שמשתמשים ואפליקציות מרובים יכולים להפנות אליהם. ללא הסכמה כלל-דיירית, ה-CLI נכשל במהלך האימות.
    • מה קורה אם הפעולה נכשלת? נדרש לך התפקיד מנהל אפליקציות, מנהל אפליקציות ענן או מנהל מערכת כללי. בקש עזרה ממנהל הדייר.

  5. ודא שלצד כל ההרשאות מופיעים סימני ביקורת ירוקים תחת מצב.

אם הרשאות הבטא (AgentIdentityBlueprint.*) אינן גלויות, עבור לאפשרות ב'.

אפשרות ב': Microsoft Graph API ‏(עבור הרשאות ביתא)

השתמש בשיטה זו אם מרכז הניהול של Microsoft Entra אינו מציג את ההרשאות AgentIdentityBlueprint.*.

אזהרה

אם אתה משתמש בשיטת API זו, אל תשתמש לאחר מכן בלחצן "הענק הסכמת מנהל מערכת" במרכז הניהול של Microsoft Entra. שיטת ה-API מעניקה הסכמת מנהל מערכת באופן אוטומטי, והשימוש בלחצן שבמרכז הניהול של Microsoft Entra מוחק את הרשאות הביתא שלך. למידע נוסף, ראה הרשאות ביתא נעלמות.

  1. פתח את Graph Explorer.

  2. היכנס באמצעות חשבון מנהל המערכת שלך (מנהל אפליקציות או מנהל אפליקציות ענן).

  3. הענק הסכמת מנהל מערכת באמצעות Graph API. כדי להשלים שלב זה, דרושים לך:

    • מזהה מנהל שירות. נדרש לך ערך עבור המשתנה SP_OBJECT_ID.
    • מזהה משאב Graph. נדרש לך ערך עבור המשתנה GRAPH_RESOURCE_ID.
    • צור (או עדכן) הרשאות מואצלות באמצעות סוג המשאב oAuth2PermissionGrant עם הערכים של המשתנים SP_OBJECT_ID ו-GRAPH_RESOURCE_ID.

השתמש במידע שבמקטעים הבאים כדי להשלים שלבים אלה.

קבלת מזהה מנהל השירות שלך

מנהל שירות הוא הזהות של האפליקציה שלך בדייר. הוא נדרש לפני שתוכל להעניק הרשאות באמצעות ה-API.

  1. הגדר את השיטה ב-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

  2. בחר הפעלת שאילתה.

    • אם השאילתה מצליחה, הערך שמוחזר הוא 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 שלך

  1. הגדר את השיטה ב-Graph Explorer ל-GET והשתמש בכתובת URL זו:

    https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=id

  2. בחר הפעלת שאילתה.

    • אם השאילתה מצליחה, העתק את הערך id. הערך הזה הוא GRAPH_RESOURCE_ID.
    • אם השאילתה נכשלת עם שגיאת הרשאות, בחר בכרטיסיה שינוי הרשאות, תן הסכמה להרשאות הנדרשות ולאחר מכן בחר שוב הפעלת שאילתה. העתק את הערך id. הערך הזה הוא GRAPH_RESOURCE_ID.

בחירת הרשאות שהוקצו

קריאת API זו מעניקה הסכמת מנהל מערכת כלל-דיירית עבור כל שבע ההרשאות, לרבות הרשאות הביתא שאינן גלויות במרכז הניהול של Microsoft Entra.

  1. הגדר את השיטה ב-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"
}

  2. בחר הפעלת שאילתה.

    • אם תקבל 201 Created תגובה: הצלחה! השדה scope בתגובה מציג את כל שבעת שמות ההרשאות. סיימת!
    • אם השאילתה נכשלת עם שגיאת הרשאות, בחר בכרטיסיה שינוי הרשאות, תן הסכמה להרשאות הנדרשות ולאחר מכן בחר שוב הפעלת שאילתה.
    • אם מתקבלת השגיאה Request_MultipleObjectsWithSameKeyValue: כבר קיימת הענקה. ייתכן שמישהו הוסיף הרשאות קודם לכן. עיין בהמשך בנושא עדכון הרשאות מואצלות.

אזהרה

הערך consentType: "AllPrincipals" בבקשת POSTכבר מעניק הסכמת מנהל מערכת כלל-דיירית. אל תבחר באפשרות "הענק הסכמת מנהל מערכת" במרכז הניהול של Microsoft Entra לאחר השימוש בשיטת API זו - פעולה זו מוחקת את הרשאות הביתא שלך, מכיוון שמרכז הניהול של Microsoft Entra אינו יכול לראות הרשאות ביתא ודורס את ההסכמה שהוענקה באמצעות ה-API כך שתכלול רק את ההרשאות הגלויות.

עדכון הרשאות מואצלות

אם מתקבלת השגיאה Request_MultipleObjectsWithSameKeyValue בעת ביצוע השלבים ליצירת הרשאות מואצלות, השתמש בשלבים אלה כדי לעדכן את ההרשאות המואצלות.

  1. הגדר את השיטה ב-Graph Explorer ל-GET והשתמש בכתובת URL זו:

    https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'SP_OBJECT_ID_FROM_ABOVE'

  2. בחר הפעלת שאילתה. העתק את הערך id מהתגובה. ערך זה הוא YOUR_GRANT_ID.

  3. הגדר את השיטה ב-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"
}

  4. בחר הפעלת שאילתה. אתה אמור לקבל תגובה מסוג 200 OK, כאשר כל שבע ההרשאות מופיעות בשדה scope.

5. הוספת תביעת התפקיד wids

Agent 365 CLI קורא את הקצאות תפקידי הספריה שלך ב-Entra ישירות מאסימון הגישה כדי לקבוע אם יש לך הרשאות מנהל מערכת. לשם כך יש להוסיף את התביעה wids לאסימוני הגישה שמונפקים עבור רישום האפליקציה.

ללא תביעה זו, ה-CLI אינו יכול לזהות את התפקיד שלך וחוזר להצגת הוראות PowerShell עבור כל שלב שדורש הרשאות מנהל מערכת — גם אם אתה מנהל מערכת. השלם שלב זה כדי לקבל את אופן הפעולה הנכון.

  1. ברישום האפליקציה, עבור אל תצורת אסימון.

  2. בחר הוספת תביעה אופציונלית.

  3. עבור סוג אסימון, בחר גישה.

  4. ברשימת התביעות, סמן את התיבה לצד wids.

  5. בחר הוסף.

    אם תתבקש להפעיל את ההרשאה profile של Microsoft Graph כדי לאפשר את התביעה, בחר כן, הוסף.

הערה

התביעה wids מכילה את מזהי GUID של תבניות התפקיד עבור תפקידי ספריית Entra שהוקצו ישירות למשתמש המחובר. ה-CLI משתמש במזהי GUID אלה כדי לזהות את התפקידים מנהל מערכת כללי ומנהל מזהי סוכנים ללא קריאה נוספת ל-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.

‏‫השלבים הבאים‬

לאחר רישום אפליקציית הלקוח המותאמת אישית, השתמש בה עם 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.

אם אינך מקבל את התוצאה הצפויה, אמת כל אחת מהבדיקות הבאות:

בדוק כיצד לאמת Fix
✅ נעשה שימוש במזהה הנכון העתקת את מזהה האפליקציה (לקוח) ולא את מזהה האובייקט עבור אל מבט כולל של האפליקציה במרכז הניהול של Microsoft Entra
✅ הרשאות מואצלות הרשאות מציגות סוג: מאוצלות תחת הרשאות API ראה סוג הרשאה שגוי
✅ כל ההרשאות נוספו ראה את כל ההרשאות המפורטות להלן בצע שוב את שלב 4
✅ ניתנה הסכמת מנהל מערכת לצד כולן מופיע סימן ביקורת ירוק תחת מצב ראה הסכמת מנהל מערכת ניתנה באופן שגוי

הרשאות מואצלות נדרשות:

  • AgentIdentityBlueprint.ReadWrite.All [בטא]
  • AgentIdentityBlueprintPrincipal.Create [בטא]
  • AgentIdentity.Read.All [בטא]
  • AgentIdentity.DeleteRestore.All [בטא]
  • AgentRegistration.ReadWrite.All
  • Application.Read.All
  • User.Read

תסמין: האימות נכשל למרות שהוספת הרשאות.

גורם שורש: לא נתת הסכמת מנהל מערכת, או שנתת אותה באופן שגוי.

פתרון: ברישום האפליקציה במרכז הניהול של Microsoft Entra, עבור אל הרשאות API ובחר הענקת הסכמת מנהל מערכת עבור [הדייר שלך]. ודא שלצד כל ההרשאות מופיעים סימני ביקורת ירוקים תחת מצב.

תסמין: a365 setup all a365 setup allמציג "Successfully ensured delegated application consent", אך מיד לאחר מכן נכשל במהלך יצירת תוכנית האב עם:

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 עבור אפליקציית הלקוח המותאמת אישית (מהפעלה קודמת וחלקית של ההגדרה, או מפעולה קודמת של "הענק הסכמת מנהל מערכת" במרכז הניהול של Microsoft Entra עבור טווחים אחרים), אך ברשומה זו חסר הטווח הנדרש(AgentIdentityBlueprint.ReadWrite.All). ה-CLI מזהה את הטווח החסר ומציג כתובת URL להסכמה כדי שמנהל מערכת ישלים את ההענקה.

פתרון:

שתף את כתובת ה-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 פועל בשמך
אפליקציה ("תפקיד") השירות פועל ללא משתמש אל תשתמש – מיועד רק לשירותי רקע/תהליכים אוטומטיים

מדוע מואצלות?

  • אתה נכנס באופן אינטראקטיבי (אימות בדפדפן)
  • ה-CLI מבצע פעולות בשמך (נתיבי ביקורת מציגים את הזהות שלך)
  • מאובטח יותר - מוגבל להרשאות שלך בפועל
  • מבטיח אחריותיות ותאימות

פתרון:

  1. עבור אל מרכז הניהול של Microsoft Entra> רישומי אפליקציות > האפליקציה שלך > הרשאות API
  2. הסר הרשאות אפליקציה כלשהן. הרשאות אלה מופיעות כאפליקציה בעמודה סוג.
  3. הוסף את אותן הרשאות כהרשאות מואצלות.
  4. הענק שוב הסכמת מנהל מערכת.

תסמין: השתמשת באפשרות ב': Microsoft Graph API (להרשאות בטא) כדי להוסיף הרשאות בטא, אבל הן נעלמות אחרי שבחרת 'הענק הסכמת מנהל' במרכז הניהול של Microsoft Entra.

גורם השורש: מרכז הניהול של Microsoft Entra אינו מציג הרשאות ביתא בממשק המשתמש. בעת בחירת הענקת הסכמת מנהל מערכת, הפורטל מעניק הסכמה רק להרשאות הגלויות ודורס את ההסכמה שהוענקה באמצעות ה-API.

מדוע זה קורה:

  1. אתה משתמש ב-Graph API ‏(אפשרות ב') כדי להוסיף את כל שבע ההרשאות, לרבות הרשאות ביתא.
  2. קריאת ה-API עם consentType: "AllPrincipals" כבר מעניקה הסכמת מנהל מערכת כלל-דיירית.
  3. אתה עובר למרכז הניהול של Microsoft Entra ורואה רק קבוצת משנה של ההרשאות, מכיוון שהרשאות הביתא אינן גלויות בפורטל.
  4. אתה בוחר הענקת הסכמת מנהל מערכת משום שאתה חושב שהדבר נדרש.
  5. מרכז הניהול של Microsoft Entra דורס את ההסכמה שהוענקה באמצעות ה-API כך שתכלול רק את ההרשאות הגלויות.
  6. הרשאות הבטא שלך נמחקו כעת.

פתרון:

  • אל תשתמש בהסכמת מנהל מערכת במרכז הניהול של Microsoft Entra לאחר שיטת ה-API: שיטת ה-API כבר מעניקה הסכמת מנהל מערכת.
  • אם מחקת בטעות הרשאות ביתא, הפעל מחדש את שלב 3 באפשרות ב' (הענקת הסכמת מנהל מערכת באמצעות Graph API) כדי לשחזר אותן. אם מתקבלת השגיאה Request_MultipleObjectsWithSameKeyValue, בצע את השלבים לעדכון הרשאות מואצלות.
  • כדי לוודא שכל שבע ההרשאות מופיעות, בדוק את השדה scope בתגובה של POST או PATCH.

האפליקציה לא נמצאה במהלך האימות

תסמין: ה-CLI מדווח על השגיאות Application not found או Invalid client ID.

פתרון:

  1. ודא שהעתקת את מזהה האפליקציה (לקוח) בתבנית GUID ולא את מזהה האובייקט:

    • עבור אל מרכז הניהול של Microsoft Entra>רישומי אפליקציות> האפליקציה שלך >מבט כולל
    • העתק את הערך תחת מזהה אפליקציה (לקוח)
    • התבנית צריכה להיות: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

  2. ודא שהאפליקציה קיימת בדייר שלך:

    # 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