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

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

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

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

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

المتطلبات

إشعار

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

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

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

القناة	مدعوم
قنوات خدمة Azure Bot	غير مدعوم
موقع مخصص	مدعوم
موقع تجريبي	غير مدعوم
Facebook	غير مدعوم
Microsoft Teams¹	مدعوم
تطبيق الأجهزة المحمولة	غير مدعوم
خدمة العملاء متعددة القنوات2	مدعوم
SharePoint¹	مدعوم

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

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

مهم

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

تطبيق الويب
قديم

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

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

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

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

لإنشاء تسجيل تطبيق مصادقة، اتبع الإرشادات الواردة في تكوين مصادقة المستخدم باستخدام Microsoft Entra ID.
إنشاء تسجيل تطبيق ثان ليكون بمثابة تسجيل تطبيق اللوحة.

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

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

في مدخل Microsoft Azure فِي صفحة تسجيل تطبيق المصادقة، انتقل إلى كشف واجهة برمجة التطبيقات.
ضمن النطاقات، حدد أيقونة انسخ إلى الحافظة.
في Copilot Studio، فِي قَائِمَة التنقل ضمن Settings، حدد Security، ثم حدد لوحة Authentication .
لـ عنوان URL لتبادل الرمز المميز (مطلوب لتسجيل الدخول الأحادي)، قم بلصق النطاق الذي قمت بنسخه من قبل.
حدد حفظ..

في مدخل Azure، في صفحة تسجيل تطبيق المصادقة، انتقل إلى Overview.
انسخ قيمة معرف التطبيق (العميل) ضمن Essentials.
في شريط التنقل، حدد ادارة>كشف واجهة برمجة التطبيقات.
ضمن تطبيقات العميل المعتمدة، حدد إضافة تطبيق عميل، ثم الصق معرف العميل المنسخ.
حدد حفظ..

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

بعد إنشاء تسجيل تطبيق كانفاس، انتقل إلى المصادقة، ثم حدد إضافة منصة.
ضمن تكوينات النِظَامٌ الأساسي، حدد إضافة نِظَامٌ أساسي، ثم حدد SPA.
ضمن Redirect URIs، أدخل عنوان URL لصفحة الويب الخاصة بك. على سبيل المثال، http://contoso.com/index.html.
في قسم المنح الضمنية والتدفقات المختلطة، قم بتشغيل كل من رموز الوصول المميزة (الْمُسْتَخْدِمة للتدفقات الضمنية) والرموز المميزة للمعرف (الْمُسْتَخْدِمة للتدفقات الضمنية والمختلطة) .
حدد تكوين.

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

في Copilot Studio، افتح عاملك ثم حدد القنوات.
حدد تطبيق الأجهزة المحمولة.
ضمن Token Endpoint، حدد Copy.

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

مهم

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

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

انتقل إلى صفحة النظرة العامة في بوابة Azure وقم بنسخ معرّف التطبيق (العميل) ومعرّف الدليل (المستأجر) من تسجيل تطبيق Canvas الخاص بك.
لتكوين مكتبة مصادقة 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'     
        },
```
قم بتعيين المتغير theURL إلى عنوان URL لنقطة نهاية الرمز المميز الذي نسخته سابقاً. على سبيل المثال:
```
(async function main() {

    var theURL = "https://<token endpoint URL>"
```

قم بتحرير 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);

احفظ تغييراتك.
تحقق من أنك قمت بتكوين تسجيل الدخول الأحادي بنجاح.

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

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

إشعار

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

تسجيل تطبيق Azure

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

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

رسم توضيحي لتدفق مصادقة تسجيل الدخول الأحادي.

يدخل مستخدم الوكيل عبارة تُفَعِّل موضوع تسجيل الدخول. تم تصميم موضوع تسجيل الدخول لتسجيل دخول الْمُسْتَخْدِم واِسْتِخْدام الرمز المميز المصادق عليه للمستخدم (User.AccessTokenمتغير).
يرسل Copilot Studio مطالبة بتسجيل الدخول للسماح للمستخدم بتسجيل الدخول باستخدام موفر الهوية الذي تم تكوينه.
تعترض اللوحة المخصصة للعامل مطالبة تسجيل الدخول ويطلب رمزا مميزا نيابة عن (OBO) من Microsoft Entra ID. ترسل اللوحة الرمز المميز إلى الْعامِلُ.
عند استلام رمز OBO المميز، يتبادل العامل رمز OBO المميز ل "رمز الوصول" ويملأ AuthToken المتغير باستخدام قيمة الرمز المميز للوصول. IsLoggedIn يتم تعيين المتغير أيضا فِي هذا الوقت.

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

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

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

مهم

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

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

سجل الدخول إلى مدخل Azure.
انتقل إلى تسجيلات التطبيقات، إما عن طريق تحديد الأيقونة أو البحث فِي شريط البحث العلوي.
حدد تسجيل جديد.
أدخل اسمًا للتسجيل. استخدم اسم العامل الذي تقوم بتسجيل اللوحة الخاصة به وقم بتضمين "canvas" للمساعدة في فصله عن تسجيل التطبيق للمصادقة.

على سبيل المثال، إذا كان وكيلك يسمى "مساعد مبيعات Contoso"، يمكنك تسمية تسجيل التطبيق باسم "ContosoSalesCanvas" أو شيء مشابه.
ضمن أنواع الحسابات المدعومة، حدد الحسابات فِي أي مستأجر مؤسسي (أي دليل Microsoft Entra ID - متعدد المستأجرين) وحسابات Microsoft شخصية (على سبيل المثال، Skype، Xbox).
اترك قسم Redirect URI فارغا فِي الوقت الحالي، أثناء إدخال هذه المعلومات فِي الخطوات التالية. حدد تسجيل.
بعد اكتمال التسجيل، يتم فتحه فِي صفحة نظرة عامة . انتقل إلى البيان. تأكد من أن accessTokenAcceptedVersion قد تم تعيينه إلى 2. إذا لم يكن كذلك، فقم بتغييره إلى 2 ثم حدد حفظ.

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

مع فتح التسجيل، انتقل إلى التصديق ثم حدد أضف منصة.
في لوحة Configure platforms ، حدد Web.
ضمن Redirect URIs، أضف عنوان URL الكامل إلى الصفحة حيث تتم استضافة لوحة الدردشة. ضمن قسم Implicit grant، حدد مربعات الاختيار Id Tokens وAccess Tokens.
حدد إعداد لتأكيد التغييرات.
انتقل إلى أذونات واجهة برمجة التطبيقات. حدد منح موافقة المسؤول لـ < اسم المستأجر> ثم نعم.

مهم

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

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

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

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

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

مهم

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

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

استخدم عنوان URL Token Exchange في صفحة إعدادات مصادقة Copilot Studio لاستبدال رمز OBO المميز برمز الوصول المطلوب عبر إطار الآلة.

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

سجل الدخول إلى Copilot Studio.
تأكد من تحديد الْعامِلُ الذي تريد تمكين المصادقة له عن طريق تحديد أيقونة الْعامِلُ فِي القَائِمَة العلوية واختيار الْعامِلُ الصحيح.
في قَائِمَة التنقل، تحت الاعدادات, حدد الامان. ثم حدد بطاقة المصادقة .
أدخل URI للنطاق الكامل من صفحة كشف واجهة برمجة التطبيقات لتسجيل تطبيق مصادقة الوكيل في حقل عنوان URL لتبادل الرموز المميزة. يكون معرّف الموارد الموحد (URI) على النحو التالي: api://1234-4567/scope.name.
حدد حفظ ثم انشر محتوى الْعامِلُ.

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

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

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

قم بتحديث 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>

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

أدرج البرنامج النصي <التالي> فِي <قسم النص الأساسي> . main ضمن الأسلوب ، تضيف هذه التعليمة البرمجية شرطيا إلى الخاص بك store، مَعَ المعرف الفريد للعامل الخاص بك. كما أنه ينشئ معرفا فريدا كمتغير خاص بك userId .

قم بالتحديث <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 وتخزين البرامج النصية الشرطية المضمنة بالفعل في Copilot Studio Samples GitHub repo.

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2026-05-04