קבע תצורה של כניסה יחידה באמצעות Microsoft Entra ID

Copilot Studio תומך בכניסה יחידה (SSO). SSO מאפשר לסוכנים באתר האינטרנט שלך להכניס לקוחות אם הם כבר נכנסו לדף או לאפליקציה שבהם הסוכן נפרס.

לדוגמה, הסוכן מתארח באינטראנט הארגוני או באפליקציה שהמשתמש כבר נכנס אליה.

יש חמישה שלבים עיקריים לקביעת התצורה של SSO עבור Copilot Studio:

1. אפשר אימות ידני עבור הסוכן שלך באמצעות Microsoft Entra ID

2. צור רישום יישום ב-Microsoft Entra ID עבור בד הציור המותאם אישית שלך.

3. הגדר טווח מותאם אישית עבור הסוכן שלך ב-Microsoft Entra ID.

4. הוסף את הטווח המותאם אישית לתצורת הסוכן שלך.

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

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

• אפשר אימות משתמשים באמצעות Microsoft Entra ID
• הוסף נושא אימות לסוכן שלך
• השתמש בבד ציור מותאם אישית

הערה

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

ערוצים נתמכים

הטבלה הבאה מפרטת את הערוצים שתומכים כעת ב-SSO. תוכל להציע תמיכה בערוצים נוספים בפורום הרעיונות של Copilot Studio.

ערוץ	נתמך
ערוצי‎ ‎שירות‎ ‎הבוט‎ ‎של‎ ‎אזור	לא נתמך
אתר אינטרנט מותאם אישית	נתמך
אתר הדגמה	לא נתמך
Facebook	לא נתמך
Microsoft Teams1	נתמך
אפליקציה‎ למכשירים ניידים	לא נתמך
ריבוי ערוצים עבור Customer Service2	נתמך
SharePoint1	נתמך

¹ אם אתה מפרסם בערוץ Teams, עליך לפעול לפי הוראות קביעת התצורה בתיעוד קביעת תצורה של כניסה יחידה באמצעות Microsoft Entra ID עבור סוכנים ב-Microsoft Teams. אם לא תקבע את הגדרות SSO של Teams בהתאם להוראות בדף זה, אימות המשתמשים שלך ייכשל תמיד בעת השימוש בערוץ Teams.

^‎2‎ ‎רק‎ ‎ערוץ‎ ‎הצ‎'‎אט‎ ‎החי‎ ‎נתמך‎. למידע נוסף, ראה הגדרת מסירה ל-Dynamics 365 Customer Service.

חשוב

SSO אינו נתמך כרגע כאשר סוכן מתפרסם בפורטל Power Apps.

יישום אינטרנט

צור רישומי יישומים עבור אתר האינטרנט המותאם אישית שלך

כדי לאפשר SSO, צור שני רישומי יישומים נפרדים:

• רישום יישום אימות, שמאפשר אימות משתמשים באמצעות Microsoft Entra ID עבור הסוכן שלך
• רישום יישום בד ציור, שמאפשר SSO עבור דף האינטרנט המותאם אישית שלך

מסיבות אבטחה, אל תשתמש שוב באותו רישום יישום גם עבור הסוכן וגם עבור אתר האינטרנט המותאם אישית שלך.

1. כדי ליצור רישום יישום אימות, פעל לפי ההוראות בקביעת תצורה של אימות משתמשים באמצעות Microsoft Entra ID.

2. צור רישום יישום שני שישמש כרישום יישום בד הציור שלך.

הוסף כתובת URL להחלפת אסימונים

כדי לעדכן את הגדרות האימות של Microsoft Entra ID ב-Copilot Studio, הוסף את כתובת ה-URL להחלפת אסימונים כדי לאפשר לאפליקציה שלך ול-Copilot Studio לשתף מידע.

1. בפורטל Azure, בדף הרישום של אפליקציית האימות שלך, עבור אל חשיפת API.

2. תחת טווחים, בחר בסמל העתקה ללוח.

3. ב-Copilot Studio, בתפריט הניווט תחת הגדרות, בחר אבטחה ולאחר מכן בחר באריח אימות.

4. עבור כתובת URL להחלפת אסימונים (נדרשת עבור SSO), הדבק את הטווח שהעתקת קודם לכן.

5. בחר Save.

קבע את התצורה של מזהה הלקוח של יישום בד הציור שלך כדי לחשוף תפריט API

1. בפורטל Azure, בדף רישום אפליקציית האימות שלך, עבור אל מבט כולל.

2. העתק את הערך מזהה יישום (לקוח) תחת עיקרי.

3. בסרגל הניווט, בחר ניהול>חשיפת API.

4. תחת יישומי לקוח מורשים, בחר הוסף אפליקציית לקוח, ולאחר מכן הדבק את מזהה הלקוח שהועתק.

5. בחר Save.

קבע את התצורה של רישום יישום בד הציור שלך

1. לאחר שתיצור את רישום יישום בד הציור, עבור אל אימות ולאחר מכן בחר הוספת פלטפורמה.

2. תחת תצורות פלטפורמה, בחר הוספת פלטפורמה, ולאחר מכן בחר SPA.

3. תחת מזהי URI להפניה מחדש, הזן את כתובת ה-URL של דף האינטרנט שלך. לדוגמה, http://contoso.com/index.html.

   

4. במקטע הענקה משתמעת וזרימות היברידיות, הפעל גם את אסימוני גישה (משמשים לזרימות משתמעות) וגם את אסימוני מזהה (משמשים לזרימות משתמעות והיברידיות).

5. בחר קביעת תצורה.

אתר את כתובת ה-URL של נקודת הקצה של האסימון של הסוכן שלך

1. ב-Copilot Studio, פתח את הסוכן שלך ולאחר מכן בחר ערוצים.

2. בחר אפליקציה למכשירים ניידים.

3. תחת נקודת קצה של אסימון, בחר העתקה.

   

קבע את התצורה של SSO בדף האינטרנט שלך

חשוב

משתמשים אורחים אינם יכולים לגשת לתשובות שנוצרו באמצעות בינה מלאכותית ממקורות נתונים של SharePoint ושל Graph Connector באפליקציות שבהן SSO מופעל.

השתמש בקוד שמופיע במאגר GitHub של Copilot Studio Samples כדי ליצור דף אינטרנט עבור כתובת ה-URL להפניה מחדש. העתק את הקוד ממאגר GitHub ושנה אותו באמצעות ההוראות הבאות.

1. עבור לדף מבט כולל בפורטל Azure והעתק את מזהה היישום (לקוח) ואת מזהה הספרייה (דייר) מרישום יישום בד הציור שלך.

   

2. כדי לקבוע את התצורה של Microsoft Authentication Library ‏(MSAL):

   • הקצה את clientIdלמזהה היישום (לקוח) שלך.
   • הקצה את authority לכתובת https://login.microsoftonline.com/ והוסף את מזהה הספרייה (לקוח) שלך בסוף.

   לדוגמה:

   var clientApplication;
       (function (){
       var msalConfig = {
           auth: {
               clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
               authority: 'https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'     
           },
   

3. הגדר את המשתנה theURL לכתובת ה-URL של נקודת הקצה של האסימון שהעתקת קודם לכן. לדוגמה:

   (async function main() {
   
       var theURL = "https://<token endpoint URL>"
   

4. ערוך את הערך של userId כך שיכלול קידומת מותאמת אישית. לדוגמה:

   var userId = clientApplication.account?.accountIdentifier != null ? 
           ("My-custom-prefix" + clientApplication.account.accountIdentifier).substr(0, 64) 
           : (Math.random().toString() + Date.now().toString()).substr(0,64);
   

5. שמור את השינויים שלך.

6. ודא שקבעת בהצלחה את התצורה של SSO.

   בעת בדיקת הסוכן שלך, אם התצורה של SSO לא נקבעה בהצלחה, תתבקש להיכנס. תהליך הכניסה מספק לך קוד אימות שעליך להעתיק לחלון הצ'אט.

   אם אתה רואה בקשת כניסה, ודא שהשלמת כראוי את שלבים 1 עד 5 בהליך זה. אם התצורה של SSO נקבעה בהצלחה, לא תתבקש להיכנס.

   הערה

   הקוד במאגר GitHub מחייב משתמשים לבחור בלחצן הכניסה. בסביבת ייצור, ייתכן שתרצה להחליף את הפונקציונליות של הלחצן באירוע מתאים יותר, כגון ניווט לדף.

תוכנית Teams

מבט כולל טכני

האיור הבא מציג כיצד משתמש נכנס מבלי לראות בקשת כניסה (SSO) ב-Copilot Studio:

1. משתמש הסוכן מזין ביטוי שמפעיל נושא כניסה. נושא הכניסה נועד להכניס את המשתמש ולהשתמש באסימון המאומת של המשתמש (המשתנה User.AccessToken).

2. Copilot Studio שולח בקשת כניסה כדי לאפשר למשתמש להיכנס באמצעות ספק הזהויות שהוגדר עבורו.

3. בד הציור המותאם אישית של הסוכן מיירט את הנחיית הכניסה ומבקש אסימון בשם המשתמש (OBO) מ-Microsoft Entra ID. בד הציור שולח את האסימון לסוכן.

4. עם קבלת אסימון OBO, הסוכן מחליף את אסימון OBO ב"אסימון גישה" וממלא את המשתנה AuthToken באמצעות הערך של אסימון הגישה. המשתנה IsLoggedIn מוגדר גם הוא בשלב זה.

צור רישום יישום ב-Microsoft Entra ID עבור בד הציור המותאם אישית שלך

כדי לאפשר SSO, דרושים לך שני רישומי יישומים נפרדים:

• אחד עבור הסוכן שלך, כדי לאפשר אימות משתמשים באמצעות Microsoft Entra ID.
• אחד עבור בד הציור המותאם אישית שלך, כדי לאפשר SSO.

חשוב

לא ניתן להשתמש שוב באותו רישום יישום גם עבור אימות המשתמשים של הסוכן וגם עבור בד הציור המותאם אישית שלך.

צור רישום יישום עבור בד הציור של הסוכן

1. היכנס אל פורטל Azure.

2. עבור אל רישומי אפליקציות, באמצעות בחירת הסמל או חיפוש בסרגל החיפוש העליון.

   

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

   

4. הזן שם עבור הרישום. השתמש בשם הסוכן שאת בד הציור שלו אתה רושם, וכלול את "בד ציור" כדי לעזור להפריד אותו מרישום היישום המשמש לאימות.

   לדוגמה, אם הסוכן שלך נקרא "Contoso sales help", תוכל לתת לרישום האפליקציה את השם "ContosoSalesCanvas" או שם דומה.

5. תחת סוגי חשבונות נתמכים, בחר חשבונות בכל דייר ארגוני (כל ספריית Microsoft Entra ID - ריבוי דיירים) וחשבונות Microsoft אישיים (לדוגמה, סקייפ, Xbox).

6. השאר בשלב זה את המקטע URI להפניה מחדש ריק, מכיוון שתזין מידע זה בשלבים הבאים. בחר הירשם.

   

7. לאחר השלמת הרישום, נפתח הדף מבט כולל. עבור אל מניפסט. וודא ש-accessTokenAcceptedVersion מוגדר כ-2. אם לא, שנה אותו ל-2 ולאחר מכן בחר שמירה.

הוסף את כתובת ה-URL להפניה מחדש

1. כאשר הרישום פתוח, עבור אל אימות ולאחר מכן בחר הוספת פלטפורמה.

   

2. בחלונית קביעת תצורה של פלטפורמות, בחר אינטרנט.

   

3. תחת מזהי URI להפניה מחדש, הוסף את כתובת ה-URL המלאה של הדף שבו מתארח בד הציור של הצ'אט. תחת המקטע הענקה משתמעת, בחר בתיבות הסימון אסימוני מזהה ואסימוני גישה.

4. בחר קביעת תצורה כדי לאשר את השינויים.

   

5. עבור אל הרשאות API. בחר באפשרות הענקת הסכמת מנהל עבור <שם הדייר שלך>, ולאחר מכן בחר כן.

   חשוב

   כדי למנוע ממשתמשים את הצורך להסכים לכל אפליקציה, אדם שהוקצה לו לפחות התפקיד מנהל אפליקציות או מנהל אפליקציות ענן יכול להעניק הסכמה כלל-דיירית לרישומי האפליקציות שלך.

   

הגדר טווח מותאם אישית עבור הסוכן שלך

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

שלב זה יוצר יחסי אמון בין רישום אפליקציית האימות המשמש לאימות לבין רישום האפליקציה של בד הציור המותאם אישית שלך.

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

2. עבור אל הרשאות API וודא שההרשאות הנכונות נוספו עבור הסוכן שלך. בחר באפשרות הענקת הסכמת מנהל עבור <שם הדייר שלך>, ולאחר מכן בחר כן.

   חשוב

   כדי למנוע ממשתמשים את הצורך להסכים לכל אפליקציה, אדם שהוקצה לו לפחות התפקיד מנהל אפליקציות או מנהל אפליקציות ענן יכול להעניק הסכמה כלל-דיירית לרישומי האפליקציות שלך.

3. עבור אל חשיפת API ובחר הוספת טווח.

   

4. הזן שם עבור הטווח, יחד עם פרטי התצוגה שהמשתמשים רואים כאשר הם מגיעים למסך SSO. בחר הוספת טווח.

   

5. בחר הוסף יישום לקוח.

6. הזן בשדה מזהה לקוח את מזהה היישום (לקוח) מהדף מבט כולל של רישום יישום בד הציור. בחר בתיבת הסימון של הטווח הרשום שיצרת.

7. בחר הוסף יישום.

קבע את תצורת האימות ב-Copilot Studio כדי לאפשר SSO

השתמש בכתובת URL להחלפת אסימונים בדף תצורת האימות של Copilot Studio כדי להחליף את אסימון OBO באסימון הגישה המבוקש באמצעות מסגרת ה-Bot.

Copilot Studio מבצע קריאה ל-Microsoft Entra ID כדי לבצע את ההחלפה בפועל.

1. היכנס ל-Copilot Studio.

2. ודא שבחרת בסוכן שעבורו ברצונך לאפשר אימות, על-ידי בחירת סמל הסוכן בתפריט העליון ובחירת הסוכן הנכון.

3. בתפריט הניווט, תחת הגדרות, בחר אבטחה. לאחר מכן בחר בכרטיסיה אימות.

   

4. הזן בשדה כתובת URL להחלפת אסימונים את ה-URI המלא של הטווח מהדף חשיפת API עבור רישום אפליקציית האימות של הסוכן. ה-URI מופיע בתבנית api://1234-4567/scope.name.

   

   

5. בחר שמירה ולאחר מכן פרסם את תוכן הסוכן.

קבע את התצורה של קוד ה-HTML של בד הציור המותאם אישית שלך כדי לאפשר SSO

עדכן את דף בד הציור המותאם אישית שבו נמצא הסוכן כדי ליירט את הבקשה לכרטיס הכניסה ולהחליף את אסימון OBO.

1. קבע את התצורה של Microsoft Authentication Library ‏(MSAL) על-ידי הוספת הקוד הבא לתג <script> במקטע <head>.

2. עדכן את clientId באמצעות מזהה היישום (לקוח) עבור רישום יישום בד הציור. החלף את <Directory ID> במזהה הספרייה (לקוח). קבל מזהים אלה (IDs) מהדף מבט כולל של רישום יישום בד הציור.

   <head>
    <script>
      var clientApplication;
        (function () {
          var msalConfig = {
              auth: {
                clientId: '<Client ID [CanvasClientId]>',
                authority: 'https://login.microsoftonline.com/<Directory ID>'
              },
              cache: {
                cacheLocation: 'localStorage',
                storeAuthStateInCookie: false
              }
          };
          if (!clientApplication) {
            clientApplication = new Msal.UserAgentApplication(msalConfig);
          }
        } ());
    </script>
   </head>
   

3. הכנס את ה-<סקריפט> הבא במקטע <body>. קובץ Script זה קורא לפעולת שירות כדי לאחזר את resourceUrl ולהחליף את האסימון הנוכחי שלך באסימון שהתבקש על-ידי הנחיית OAuth.

   <script>
   function getOAuthCardResourceUri(activity) {
     if (activity &&
          activity.attachments &&
          activity.attachments[0] &&
          activity.attachments[0].contentType === 'application/vnd.microsoft.card.oauth' &&
          activity.attachments[0].content.tokenExchangeResource) {
            // asking for token exchange with Microsoft Entra ID
            return activity.attachments[0].content.tokenExchangeResource.uri;
      }
   }
   
   function exchangeTokenAsync(resourceUri) {
     let user = clientApplication.getAccount();
      if (user) {
        let requestObj = {
          scopes: [resourceUri]
        };
        return clientApplication.acquireTokenSilent(requestObj)
          .then(function (tokenResponse) {
            return tokenResponse.accessToken;
            })
            .catch(function (error) {
              console.log(error);
            });
            }
            else {
            return Promise.resolve(null);
      }
   }
   </script>
   

4. הכנס את ה-<סקריפט> הבא במקטע <body>. בתוך mainפעולת השירות הראשית, קוד זה מוסיף תנאי למאגר שלךstore, עם המזהה הייחודי של הסוכן. זה גם יוצר מזהה ייחודי כמשתנה userId שלך.

5. עדכן את <BOT ID> באמצעות מזהה הסוכן שלך. כדי לראות את מזהה הסוכן ב-Copilot Studio, עבור לדף ערוצים של הסוכן ובחר אפליקציה למכשירים ניידים.

   <script>
       (async function main() {
   
           // Add your BOT ID below 
           var BOT_ID = "<BOT ID>";
           var theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;
   
           const {
               token
           } = await fetchJSON(theURL);
   
           var directline = await fetchJSON(regionalChannelSettingsURL).then(res=> res.channelUrlsById.directline); 
   
           const directLine = window.WebChat.createDirectLine({
               domain: `${directline}v3/directline`,
               token
           });
   
           var userID = clientApplication.account?.accountIdentifier != null ?
               ("Your-customized-prefix-max-20-characters" + clientApplication.account.accountIdentifier).substr(0, 64) :
               (Math.random().toString() + Date.now().toString()).substr(0, 64); // Make sure this will not exceed 64 characters 
           const store = WebChat.createStore({}, ({
               dispatch
           }) => next => action => {
               const {
                   type
               } = action;
               if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
                   dispatch({
                       type: 'WEB_CHAT/SEND_EVENT',
                       payload: {
                           name: 'startConversation',
                           type: 'event',
                           value: {
                               text: "hello"
                           }
                       }
                   });
                   return next(action);
               }
               if (action.type === 'DIRECT_LINE/INCOMING_ACTIVITY') {
                   const activity = action.payload.activity;
                   let resourceUri;
                   if (activity.from && activity.from.role === 'bot' &&
                       (resourceUri = getOAuthCardResourceUri(activity))) {
                       exchangeTokenAsync(resourceUri).then(function(token) {
                           if (token) {
                               directLine.postActivity({
                                   type: 'invoke',
                                   name: 'signin/tokenExchange',
                                   value: {
                                       id: activity.attachments[0].content.tokenExchangeResource.id,
                                       connectionName: activity.attachments[0].content.connectionName,
                                       token,
                                   },
                                   "from": {
                                       id: userID,
                                       name: clientApplication.account.name,
                                       role: "user"
                                   }
                               }).subscribe(
                                   id => {
                                       if (id === 'retry') {
                                           // The agent was not able to handle the invoke, so display the oauthCard
                                           return next(action);
                                       }
                                       // else: tokenexchange successful and we do not display the oauthCard
                                   },
                                   error => {
                                       // an error occurred to display the oauthCard
                                       return next(action);
                                   }
                               );
                               return;
                           } else
                               return next(action);
                       });
                   } else
                       return next(action);
               } else
                   return next(action);
           });
   
           const styleOptions = {
   
               // Add styleOptions to customize Web Chat canvas
               hideUploadButton: true
           };
   
           window.WebChat.renderWebChat({
                   directLine: directLine,
                   store,
                   userID: userID,
                   styleOptions
               },
               document.getElementById('webchat')
           );
       })().catch(err => console.error("An error occurred: " + err));
   </script>
   

קוד דוגמה מלא

תוכל למצוא את הקוד לדוגמה המלא, כאשר קובצי ה-Script המותנים של MSAL ושל המאגר כבר כלולים, במאגר GitHub של Copilot Studio Samples.

תוכן קשור

• רישום של היישום Azure