قم بتكوين تسجيل الدخول الموحد باِسْتِخْدام معرف Microsoft Entra

يدعم Copilot Studio تسجيل الدخول الأحادي (SSO). يسمح SSO للوكلاء على موقع الويب الخاص بك بتسجيل دخول العملاء إذا كانوا قد سجلوا الدخول بالفعل إلى الصفحة أو التطبيق حيث يتم نشر الْعامِلُ.

على سبيل المثال، تتم استضافة الْعامِلُ على إنترانت الشركة أو فِي تطبيق قام الْمُسْتَخْدِم بتسجيل الدخول إليه بالفعل.

هناك خمس خطوات رئيسية لتكوين SSO ل Copilot Studio:

1. تمكين المصادقة اليدوية لعاملك باِسْتِخْدام معرف Microsoft Entra

2. إنشاء تسجيل تطبيق فِي معرف Microsoft Entra للوحة المخصصة.

3. حدد نطاقا مخصصا لعاملك فِي معرف Microsoft Entra.

4. أضف النطاق المخصص إلى تكوين الْعامِلُ الخاص بك.

5. تكوين التعليمات البرمجية الجانبية لعميل اللوحة المخصصة لتمكين تسجيل الدخول الأحادي.

المتطلبات

• قم بتمكين مصادقة الْمُسْتَخْدِم باِسْتِخْدام Microsoft Entra ID
• إضافة موضوع مصادقة إلى عاملك
• استخدم قماشًا مخصصًا

إشعار

لتكوين تسجيل الدخول الأحادي باِسْتِخْدام موفري OAuth 2.0 الآخرين، راجع تكوين تسجيل الدخول الأحادي مَعَ موفري OAuth العامين.

القنوات المدعومة

يوضح الجدول التالي تفاصيل القنوات التي تدعم تسجيل الدخول الأحادي حاليا. يمكنك اقتراح دعم لقنوات إضافية فِي منتدى أفكار Copilot Studio.

القناة	مدعوم
قنوات خدمة Azure Bot	غير مدعوم
موقع مخصص	مدعوم
موقع تجريبي	غير مدعوم
Facebook	غير مدعوم
Microsoft Teams1	مدعوم
تطبيق الأجهزة المحمولة	غير مدعوم
Customer Service متعددة القنوات2	مدعوم
SharePoint1	مدعوم

¹ إذا كان لديك أيضا قناة Teams ممكنة، فستحتاج إلى اتباع إرشادات التكوين على وثائق تكوين تسجيل الدخول الأحادي باِسْتِخْدام معرف Microsoft Entra للوكلاء فِي وثائق Microsoft Teams . يؤدي الفشل فِي تكوين إعدادات Teams SSO كما هو موضح فِي تلك الصفحة إلى فشل الْمُسْتَخْدِمين دائما فِي المصادقة عند اِسْتِخْدام قناة Teams.

² يتم دعم قناة الدردشة المباشرة فقط. لمزيد من المعلومات، راجع قم بتهيئة عملية تسليم المهام إلى Dynamics 365 Customer Service

مهم

لا يتم دعم تسجيل الدخول الأحادي حاليا عند نشر عامل إلى مدخل Power Apps.

تطبيق الويب

إنشاء تسجيلات التطبيقات لموقع ويب المخصص

لتمكين تسجيل الدخول الأحادي، تحتاج إلى إنشاء تسجيلين منفصلين للتطبيق:

• تسجيل تطبيق مصادقة، والذي يمكن مصادقة مستخدم Microsoft Entra ID لعاملك
• تسجيل تطبيق اللوحة، والذي يمكن تسجيل الدخول الأحادي لصفحة الويب المخصصة

لا نوصي بإعادة اِسْتِخْدام نفس تسجيل التطبيق لكل من عاملك وموقع الويب المخصص لأسباب أمنية.

1. اتبع الإرشادات الواردة فِي تكوين مصادقة الْمُسْتَخْدِم باِسْتِخْدام معرف Microsoft Entra لإنشاء تسجيل تطبيق مصادقة.

2. إنشاء تسجيل تطبيق ثان ليكون بمثابة تسجيل تطبيق اللوحة.

أضف رابط تبادل الرموز

لتحديث إعدادات مصادقة Microsoft Entra ID فِي Copilot Studio، تحتاج إلى إضافة عنوان URL لتبادل الرموز المميزة للسماح لتطبيقك و Copilot Studio بمشاركة المعلومات.

1. في مدخل Microsoft Azure فِي صفحة تسجيل تطبيق المصادقة، انتقل إلى كشف واجهة برمجة التطبيقات.

2. ضمن النطاقات، حدد أيقونة نسخ إلى الحافظة.

3. في Copilot Studio، فِي قَائِمَة التنقل ضمن Settings، حدد Security، ثم حدد لوحة Authentication .

4. بالنسبة إلى عنوان URL لتبادل الرمز المميز (مطلوب لتسجيل الدخول الأحادي)، الصق النطاق الذي نسخته سابقا.

5. حدد حفظ..

تكوين معرف عميل تطبيق اللوحة لعرض قَائِمَة واجهة برمجة التطبيقات

1. في مدخل Microsoft Azure فِي صفحة تسجيل تطبيق المصادقة، انتقل إلى ملخص.

2. انسخ قيمة معرف التطبيق (العميل) ضمن Essentials.

3. في شريط التنقل، حدد ادارة>كشف واجهة برمجة التطبيقات.

4. ضمن تطبيقات العميل المعتمدة، حدد إضافة تطبيق عميل، ثم الصق معرف العميل المنسخ.

5. حدد حفظ..

تكوين تسجيل تطبيق اللوحة

1. بعد إنشاء تسجيل تطبيق اللوحة، انتقل إلى Authentication، ثم حدد Add a platform.

2. ضمن تكوينات النِظَامٌ الأساسي، حدد إضافة نِظَامٌ أساسي، ثم حدد SPA.

3. ضمن Redirect URIs، أدخل عنوان URL لصفحة الويب الخاصة بك؛ على سبيل المثال، http://contoso.com/index.html.

   

4. في قسم المنح الضمنية والتدفقات المختلطة، قم بتشغيل كل من رموز الوصول المميزة (الْمُسْتَخْدِمة للتدفقات الضمنية) والرموز المميزة للمعرف (الْمُسْتَخْدِمة للتدفقات الضمنية والمختلطة) .

5. حدد تكوين.

ابحث عن عنوان URL لنقطة نهاية الرمز المميز لعاملك

1. في Copilot Studio، افتح عاملك ثم حدد القنوات.

2. حدد تطبيق الأجهزة المحمولة.

3. ضمن Token Endpoint، حدد Copy.

   

تكوين تسجيل الدخول الأحادي فِي صفحة الويب الخاصة بك

مهم

لا تتوفر الإجابات التي تم إنشاؤها الذَّكَاءُ الِاصْطِنَاعِيُّ من مصادر بيانات SharePoint وGraph Connector للمستخدمين الضيوف فِي التطبيقات التي تدعم تسجيل الدخول الأحادي.

استخدم التعليمات البرمجية المتوفرة في مستودع Copilot Studio GitHub لإنشاء صفحة ويب لعنون URL لإعادة التوجيه. انسخ التعليمات البرمجية من مستودع GitHub وقم بتعديلها باِسْتِخْدام الإرشادات التالية.

1. انتقل الى صفحة ملخص في وقم بنسخ بوابة Azure ونسخها معرّف التطبيق (العميل) و معرف الدليل (المستأجر) من خلال تسجيلك فِي تطبيق Canvas.

   

2. لتكوين مكتبة مصادقة Microsoft (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. تحقق من تكوين تسجيل الدخول الأحادي بنجاح.

   عند اختبار عاملك، إذا لم يتم تكوين تسجيل الدخول الأحادي بنجاح، فستتم مطالبتك بتسجيل الدخول، ما يمنحك رمز التحقق من الصحة الذي يجب نسخه إلى نافذة الدردشة.

   إذا رأيت مطالبة بتسجيل الدخول، فتحقق من إكمال الخطوات من 1 إلى 5 من هذا الإجراء بشكل صحيح. إذا تم تكوين تسجيل الدخول الأحادي بنجاح، فلن تتم مطالبتك بتسجيل الدخول.

   إشعار

   تتطلب التعليمات البرمجية فِي مستودع GitHub من الْمُسْتَخْدِمين تحديد زر تسجيل الدخول. في الإنتاج، قد تحتاج إلى استبدال وظيفة الزر بحدث أكثر ملاءمة، مثل الانتقال إلى صفحة.

المحتوى ذو الصلة

• تسجيل تطبيق Azure

قديم

نظرة عامة فنية

يوضح الرسم التوضيحي التالي كيفية تسجيل دخول الْمُسْتَخْدِم دون رؤية مطالبة تسجيل الدخول (SSO) فِي Copilot Studio:

1. يدخل مستخدم الْعامِلُ عبارة تؤدي إلى موضوع تسجيل الدخول. تم تصميم موضوع تسجيل الدخول لتسجيل دخول الْمُسْتَخْدِم واِسْتِخْدام الرمز المميز المصادق عليه للمستخدم (User.AccessTokenمتغير).

2. يرسل Copilot Studio مطالبة بتسجيل الدخول للسماح للمستخدم بتسجيل الدخول باِسْتِخْدام موفر الهوية الذي تم تكوينه.

3. تعترض اللوحة المخصصة للعامل مطالبة تسجيل الدخول ويطلب رمزا مميزا نيابة عن (OBO) من Microsoft Entra ID. ترسل اللوحة الرمز المميز إلى الْعامِلُ.

4. عند استلام رمز OBO المميز، يتبادل الْعامِلُ رمز OBO المميز ل "رمز الوصول" ويملأ AuthToken المتغير باِسْتِخْدام قيمة الرمز المميز للوصول. IsLoggedIn يتم تعيين المتغير أيضا فِي هذا الوقت.

إنشاء تسجيل تطبيق فِي معرف Microsoft Entra للوحة المخصصة

لتفعيل خاصية تسجيل الدخول الموحد (SSO)، تحتاج إلى تسجيلين منفصلين للتطبيق:

• واحد لعاملك لتمكين مصادقة الْمُسْتَخْدِم باِسْتِخْدام معرف Microsoft Entra.
• واحد للوحة المخصصة لتمكين تسجيل الدخول الأحادي.

مهم

لا يمكنك إعادة اِسْتِخْدام نفس تسجيل التطبيق لكل من مصادقة الْمُسْتَخْدِم الخاصة بعاملك واللوحة المخصصة.

أنشئ تسجيل تطبيق للوحة الْعامِلُ

1. سجل الدخول إلى مدخل Azure.

2. انتقل إلى تسجيلات التطبيقات، إما عن طريق تحديد الأيقونة أو البحث فِي شريط البحث العلوي.

   

3. حدد تسجيل جديد.

   

4. أدخل اسمًا للتسجيل. قد يكون من المفيد اِسْتِخْدام اسم الْعامِلُ الذي تقوم بتسجيل اللوحة الخاصة به وتضمين "canvas" للمساعدة فِي فصله عن تسجيل التطبيق للمصادقة.

   على سبيل المثال، إذا كان عاملك يسمى "تعليمات مبيعات Contoso"، فقد تسمي تسجيل التطبيق باسم "ContosoSalesCanvas" أو شيء مشابه.

5. ضمن أنواع الحسابات المدعومة، حدد الحسابات فِي أي مستأجر مؤسسي (أي دليل Microsoft Entra ID - متعدد المستأجرين) وحسابات Microsoft شخصية (على سبيل المثال، Skype، Xbox).

6. اترك قسم Redirect URI فارغا فِي الوقت الحالي، أثناء إدخال هذه المعلومات فِي الخطوات التالية. حدد تسجيل.

   

7. بعد اكتمال التسجيل، يتم فتحه فِي صفحة نظرة عامة . انتقل إلى البيان. تأكد من accessTokenAcceptedVersion تعيين إلى 2. إذا لم يكن كذلك، فقم بتغييره إلى 2 ثم حدد حفظ.

قم بإضافة عنوان URL لإعادة التوجيه

1. مع فتح التسجيل، انتقل إلى التصديق ثم حدد أضف منصة.

   

2. على شفرة تكوين الأنظمة الأساسية ، حدد الويب.

   

3. ضمن Redirect URIs، أضف عنوان URL الكامل إلى الصفحة حيث تتم استضافة لوحة الدردشة. ضمن قسم Implicit grant، حدد خانات الاختيار Id Tokens وAccess Tokens.

4. حدد تكوين لتأكيد التغييرات.

   

5. انتقل إلى أذونات واجهة برمجة التطبيقات. حدد منح موافقة المسؤول لـ < اسم المستأجر> ثم نعم.

   مهم

   لتجنب اضطرار الْمُسْتَخْدِمين إلى الموافقة على كل تطبيق، يمكن لشخص معين على الأقل دور مسؤول التطبيق أو مسؤول تطبيق السحابة منح موافقة على مستوى المستأجر لتسجيلات التطبيق الخاص بك.

   

تعريف نطاق مخصص لعاملك

حدد نطاقا مخصصا عن طريق الكشف عن واجهة برمجة تطبيقات لتسجيل تطبيق اللوحة داخل تسجيل تطبيق المصادقة. تسمح لك النطاقات بتحديد أدوار الْمُسْتَخْدِم والمسؤول وحقوق الوصول.

تنشئ هذه الخطوة علاقة ثقة بين تسجيل تطبيق المصادقة للمصادقة وتسجيل التطبيق للوحة المخصصة.

1. افتح تسجيل التطبيق الذي قمت بإنشائه عند تكوين المصادقة.

2. انتقل إلى أذونات واجهة برمجة التطبيقات وتأكد من إضافة الأذونات الصحيحة لعاملك. حدد منح موافقة المسؤول لـ < اسم المستأجر> ثم نعم.

   مهم

   لتجنب اضطرار الْمُسْتَخْدِمين إلى الموافقة على كل تطبيق، يمكن لشخص معين على الأقل دور مسؤول التطبيق أو مسؤول تطبيق السحابة منح موافقة على مستوى المستأجر لتسجيلات التطبيق الخاص بك.

3. انتقل إلى كشف واجهة برمجة التطبيقات وحدد إضافة نطاق.

   

4. أدخل اسما للنطاق، إلى جانب معلومات العرض التي يجب عرضها للمستخدمين عند الوصول إلى شاشة SSO. حدد إضافة مجال.

   

5. حدد إضافة تطبيق عميل.

6. أدخل معرف التطبيق (العميل) من صفحة نظرة عامة لتسجيل تطبيق اللوحة فِي حقل معرف العميل. حدد خانة الاختيار الخاصة بالنطاق المدرج الذي قمت بإنشائه.

7. حدد إضافة تطبيق.

تكوين المصادقة فِي Copilot Studio لتمكين تسجيل الدخول الأحادي

يتم اِسْتِخْدام عنوان URL لتبادل الرمز المميز فِي صفحة تكوين مصادقة Copilot Studio لتبادل رمز OBO المميز للرمز المميز للوصول المطلوب من خلال bot framework.

يستدعي Copilot Studio معرف Microsoft Entra لإجراء التبادل الفعلي.

1. سجل الدخول إلى Copilot Studio.

2. تأكد من تحديد الْعامِلُ الذي تريد تمكين المصادقة له عن طريق تحديد أيقونة الْعامِلُ فِي القَائِمَة العلوية واختيار الْعامِلُ الصحيح.

3. في قَائِمَة التنقل، تحت الاعدادات, حدد الامان. ثم حدد بطاقة المصادقة .

   

4. أدخل URI للنطاق الكامل من صفحة كشف واجهة برمجة التطبيقات لتسجيل تطبيق مصادقة الْعامِلُ فِي حقل عنوان URL لتبادل الرمز المميز. يكون معرّف الموارد الموحد (URI) على النحو التالي: api://1234-4567/scope.name.

   

   

5. حدد حفظ ثم انشر محتوى الْعامِلُ.

تكوين التعليمات البرمجية ل HTML للوحة المخصصة لتمكين تسجيل الدخول الأحادي

قم بتحديث صفحة اللوحة المخصصة حيث يوجد الْعامِلُ لاعتراض طلب بطاقة تسجيل الدخول وتبادل رمز OBO المميز.

1. قم بتهيئة مكتبة مصادقة مايكروسوفت (MSAL) عن طريق إضافة الكود التالي إلى <نص> العلامة في<جزء> الرأس.

2. قم بالتحديث clientId باِسْتِخْدام معرف التطبيق (العميل) لتسجيل تطبيق اللوحة. استبدل <Directory ID> بمعرف الدليل (المستأجر). يمكنك الحصول على هذه المعرفات من صفحة نظرة عامة لتسجيل تطبيق اللوحة.

   <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. أدرج البرنامج النصي <التالي> فِي <قسم النص الأساسي> . يستدعي هذا البرنامج النصي أسلوب لاسترداد 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. أدرج البرنامج النصي <التالي> فِي <قسم النص الأساسي> . 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>
   

نموذج كامل للتعليمات البرمجية

لمزيد من المعلومات، يمكنك العثور على نموذج التعليمات البرمجية الكامل، مَعَ MSAL وتخزين البرامج النصية الشرطية المضمنة بالفعل فِي مستودع GitHub.