OAuth2 / OIDC — ربط خدمة بـ Omniscol
Premiumتخاطب هذه الصفحة إدارة الأنظمة المعلوماتية. وهي تصف Omniscol في دورها خادم تفويض OAuth2 / OpenID Connect: كيف تسجّل خدمة طرف ثالث نفسها عميلا، وكيف يوافق مستخدم على منحها الوصول، وكيف تتلقى الخدمة رمزا مقيّدا بـالصلاحيات الممنوحة.
ما تفعله Omniscol بوصفها خادم OAuth2
تصبح خدمة خارجية — وكيل ذكاء اصطناعي، أو موصل، أو لوحة متابعة — عميلا مصرَّحا به في حسابكم؛ ويقوم مستخدم من المدرسة بـالموافقة على وصولها عبر شاشة موافقة؛ فتتلقى الخدمة عندئذ رمز وصول قصير الأمد، يتحدد إطاره بـالصلاحيات الممنوحة وبحقوق المستخدم.
تختلف هذه الآلية عن تسجيل الدخول الموحد (SSO) للمستخدمين الموصوف في صفحة OIDC / SSO، حيث تكون Omniscol على العكس عميلا لدى مزوّد الهوية لديكم لتسجيل دخول مستخدميكم. أما هنا فـ Omniscol في جهة الخادم: الخدمات هي التي تتصل بها.
يعتمد على هذا الخادم تكاملان في Omniscol:
- MCP — تمر مصادقة وكيل الذكاء الاصطناعي القياسية عبر خادم OAuth2 هذا (راجعوا صفحة MCP — ربط وكيل ذكاء اصطناعي خارجي)؛
- OneRoster — يصادق منتج OneRoster برمز OAuth2 من آلة إلى آلة يصدره الخادم نفسه (راجعوا صفحة OneRoster).
ويمكن لأي خدمة أخرى متوافقة مع OAuth2 / OIDC أن تتصل به بالطريقة نفسها.
الاكتشاف ونقاط الوصول في البروتوكول
تنشر Omniscol بيانات الاكتشاف على عناوين .well-known القياسية، وتُقدَّم
من جذر مجال حسابكم (مثل https://votre-ecole.omniscol.com). ويجد العميل
المتوافق فيها بنفسه جميع نقاط الوصول دون ضبط يدوي:
/.well-known/oauth-authorization-server— بيانات خادم التفويض (RFC 8414)؛/.well-known/openid-configuration— بيانات OpenID Connect (المحتوى نفسه كسابقتها)؛/.well-known/jwks.json— مفاتيح التحقق العامة (JWKS)، وهي تتيح التحقق من توقيعid_token؛/.well-known/oauth-protected-resource— بيانات المورد المحمي (RFC 9728).
تعلن هذه البيانات عن نقاط الوصول في البروتوكول:
/oauth/authorize— طلب التفويض (شاشة تسجيل الدخول ثم شاشة الموافقة)؛/oauth/token— استبدال رمز التفويض برمز وصول، والتجديد؛/oauth/register— التسجيل الديناميكي للعملاء (RFC 7591)؛/oidc/userinfo— معلومات المستخدم المتصل (OIDC)؛/oauth/revoke— إلغاء رمز (RFC 7009).
نقاط الوصول هذه في البروتوكول عامة: فهي غير مقصورة على حسابات Premium ولا يلزم فتحها يدويا. ولا يخص Premium إلا شاشة إدارة العملاء الموصوفة أدناه.
مسارات التفويض
تدعم Omniscol ثلاثة مسارات OAuth2:
- رمز التفويض مع PKCE — المسار الافتراضي لخدمة تعمل باسم مستخدم.
تحوّل الخدمة المستخدم إلى
/oauth/authorize؛ وبعد تسجيل الدخول والموافقة تعيد Omniscol رمز تفويض (صالحا 5 دقائق) تستبدله الخدمة في/oauth/token. وطريقة PKCE المعتمدة هي S256، وresponse_typeالوحيد المقبول هوcode. - التجديد (
refresh_token) — لتمديد وصول مفوَّض دون المرور مجددا بالموافقة. - Client credentials — مسار من آلة إلى آلة، دون مستخدم، يستخدمه خصوصا مستهلكو OneRoster. يصادق العميل مباشرة ويتلقى رمز وصول.
عند الاستبدال يصدر الخادم رمز وصول (Bearer، صالحا ساعة واحدة)، ولمسارات
المستخدم رمز تجديد (صالحا 30 يوما). وعند طلب صلاحية openid يصدر كذلك
id_token موقَّع من OIDC؛ ويُتحقق من توقيعه عبر /.well-known/jwks.json.
أما مسار client_credentials فلا يصدر إلا رمز وصول، دون تجديد ودون id_token.
يُقدَّم رمز الوصول بعد ذلك في ترويسة HTTP
Authorization: Bearer <الرمز>. وفي كل استدعاء تتحقق Omniscol من توقيعه،
وتتأكد من أن العميل ما زال فعال، وأن المستخدم ما زال موجودا
ويملك الدور المطلوب، وأن صلاحيات الرمز تغطي فعلا نقطة الوصول المستدعاة —
وإلا رُفض الاستدعاء.
الصلاحيات والموافقة
الصلاحيات التي تديرونها على عميل هي:
read:basic— قراءة الجداول الزمنية ولوحات التحكم وعمليات الاطلاع (الوحدات الصفحة الرئيسية، الجداول الزمنية، لوحة التحكم، إدارة الجداول الزمنية)؛read:user— قراءة قائمة المستخدمين؛write:data— الكتابة في وحدات الاطلاع نفسها؛admin— وصول إداري (الوحدات الإدارة، إدارة الغياب، إدارة الجداول الزمنية).
ويعرف الخادم أيضا صلاحيات OIDC (openid وemail وprofile) وصلاحيات
OneRoster للقراءة فقط (بالبادئة imsglobal.org). وهذه الأخيرة ذات
امتياز: لا يمكن لعميل أن يمنح نفسه إياها عبر التسجيل الديناميكي؛ بل يجب
أن يجهزها مسؤول في ملف العميل.
الصلاحية الممنوحة فعليا هي تقاطع ما يطلبه العميل وما هو مسجَّل له: فلا
يحصل العميل أبدا على أكثر مما هو مدوَّن في ملفه. وفي مسار المستخدم، تعرض
شاشة الموافقة (/oauth/consent) اسم الخدمة الطالبة وشعارها، مع
قائمة مقروءة بالصلاحيات المطلوبة، والزرين: قبول،
وكذلك رفض. والقبول يصدر رمز التفويض ويعيد المستخدم إلى الخدمة؛ أما
الرفض فيعيده إليها مع الخطأ access_denied.
التسجيل الديناميكي للعملاء
تطبّق نقطة الوصول /oauth/register التسجيل الديناميكي (Dynamic Client
Registration، RFC 7591): يمكن لخدمة متوافقة أن تعلن نفسها بنفسها عميلا، دون
تدخل يدوي مسبق. وهذا ما يتيح لوكيل MCP أن يضبط نفسه انطلاقا من عنوان URL
للخادم وحده.
لا يمكن للتسجيل الديناميكي أن يمنح نفسه صلاحية ذات امتياز (صلاحيات OneRoster):
فهذه تُستبعد بصمت، وإن لم تبق صلاحية صالحة تُمنح read:basic افتراضيا. وتبقى
الصلاحيات ذات الامتياز محجوزة لتجهيز يتولاه مسؤول.
شاشة إدارة عملاء OAuth2
في الحسابات بريميوم، تديرون العملاء من الإدارة ← استيراد / تصدير، قسم OAuth2، عبر الزر OAuth2. ويطلب الوصول أولا كلمة مرور المسؤول — تأكيد إضافي قبل فتح الشاشة.
تعرض الشاشة العملاء المسجَّلين، ولكل منهم حالته (فعال / غير فعال) واسمه وصلاحياته وجهات الاتصال وعناوين URI (الموقع الإلكتروني والشعار وعناوين إعادة التوجيه). ويمكنكم:
- تسجيل عميل — أدخلوا الاسم، و
software_idاختياريا، والصلاحيات، وجهات الاتصال، والموقع الإلكتروني، والشعار، وعناوين إعادة التوجيه. وعند الإنشاء تعرض Omniscolclient_idوclient_secretمرة واحدة فقط. - تعديل عميل — لا تُعدَّل إلا الحقول الآمنة: الاسم والصلاحيات وجهات الاتصال
والموقع الإلكتروني والشعار. أما عناوين إعادة التوجيه و
software_idوالسر فلا تُعدَّل هنا. - تفعيل عميل أو تعطيله — العميل المعطَّل تُرفض رموزه منذ الاستدعاء التالي.
- حذف عميل — الحذف نهائي.
سر العميل
يُعرض client_secret مرة واحدة فقط، عند التسجيل. ولا تحتفظ Omniscol لديها
إلا بـبصمة للسر، لا بالسر نفسه: فلا يمكن إعادة عرضه أو استرجاعه
لاحقا. انسخوه فورا إلى مدير أسرار.
أما client_id فهو حتمي: يشتق من اسم الحساب واسم العميل وبصمة بياناته
التقنية. ولذلك يؤدي تسجيلان متطابقان تماما إلى المعرّف نفسه.
تجديد السر (التدوير)
تدوير السر ممكن: فهو يصدر سرا جديدا، ولا يحتفظ إلا ببصمة السر الجديد،
ولا يعيد هذا السر الجديد إلا مرة واحدة. ويتم عبر نقطة الوصول الخاصة بإدارة
التسجيل الديناميكي (/oauth/register/<client_id>/rotation) ويفترض تقديم
رمز التسجيل الذي سُلِّم للعميل عند تسجيله ديناميكيا. وهو بالتالي لا
يُشغَّل من شاشة الإدارة أعلاه، التي لا تتعامل مع هذا الرمز.
OAuth2 أم مفتاح API: أيهما نختار
تقترح Omniscol آليتين للوصول من الآلات، بنموذجي ثقة مختلفين:
- OAuth2 (هذه الصفحة) — طرف ثالث مسجَّل يحصل، بعد موافقة مستخدم،
على رمز قصير الأمد (ساعة واحدة)، مقيّد بالصلاحيات الممنوحة،
وقابل للتجديد وقابل للإلغاء (بتعطيل العميل). ويغطي مسار
client_credentialsأيضا التواصل من آلة إلى آلة دون مستخدم. وهو الأسلوب المناسب لخدمة طرف ثالث معروفة، ولـ MCP وOneRoster. - مفتاح API (راجعوا صفحة API Omniscol) — رمز مستقل يوقّعه الخادم، ويحمل قائمة بنقاط الوصول المسموح بها، وتسلّمونه أنتم بأنفسكم إلى النظام الخارجي: لا طرف ثالث مسجَّل، ولا شاشة موافقة، ولا تجديد. وهو تفويض من المسؤول لحقوقه الخاصة إلى نظام يتحكم فيه.
وخلاصة القول: مفتاح API مناسب عندما تسلّمون بأنفسكم وصولا إلى نظام تتحكمون فيه؛ وOAuth2 مناسب عندما يجب أن تحصل خدمة طرف ثالث معروفة على وصول مفوَّض ومحدد الصلاحيات وقابل للإلغاء، أو عندما يفرضه البروتوكول (MCP وOneRoster).
طريقة العمل
تسجيل عميل OAuth2
-
افتحوا شاشة OAuth2. في الإدارة ← استيراد / تصدير، قسم OAuth2، انقروا على الزر OAuth2، ثم أدخلوا كلمة مرور المسؤول.
-
سجّلوا العميل. أدخلوا اسمه، وصلاحياته (
read:basicوread:userوwrite:dataوadmin)، وعناوين إعادة التوجيه، وعند الحاجة جهات الاتصال والموقع الإلكتروني والشعار. أما صلاحيات OneRoster فلا تُمنح هنا عبر التسجيل الديناميكي؛ بل تخضع لتجهيز يتولاه مسؤول. -
انسخوا
client_idوclient_secretالمعروضين. ولا يظهر السر إلا مرة واحدة: احفظوه في مدير أسرار. -
من جهة الخدمة، اضبطوا العميل بهذين المعرّفين وبعنوان URL للخادم؛ فالعميل المتوافق يكتشف بنفسه نقاط الوصول عبر
/.well-known/. -
لقطع وصول ما، عودوا إلى الشاشة وعطّلوا العميل أو احذفوه.