التوثيق

البدء

يمنح Authagonal كل مستأجر خادم OIDC متوافقًا تمامًا مع المعايير. يحصل كل مستأجر على عنوان URL خاص بالمُصدِر، ووثيقة اكتشاف، ونقاط نهاية للرموز، دون أي بنية تحتية مشتركة بين المستأجرين. يمكنك الانتقال من الصفر إلى تدفق تسجيل دخول يعمل بالكامل في أقل من 5 دقائق.

إنشاء حساب

سجّل في authagonal.io واختر معرّفًا (slug) لحسابك. يصبح هذا المعرّف نطاق المُصدِر الخاص بك: {slug}.authagonal.io. بعد إنشاء حسابك، تحقق من عنوان بريدك الإلكتروني للبدء.

اختر معرّفًا فريدًا لحسابك أثناء التسجيل

تسجيل عميل

انتقل إلى العملاء في الشريط الجانبي للبوابة وانقر على عميل جديد. أدخل clientId وclientName لتطبيقك. ثم أضف في تبويب عناوين URI الخاص بالعميل عنوان إعادة توجيه واحدًا على الأقل، وهو المكان الذي يُرسَل إليه المستخدمون بعد المصادقة. على سبيل المثال: https://app.example.com/callback. يتطلب العملاء الجدد سرَّ عميل افتراضيًا، لذا لتطبيق متصفح بلا خادم خلفي أوقف طلب سر في تبويب عام.

سجّل عميل OAuth جديدًا في البوابة

أول تسجيل دخول لك

أسرع طريقة للتكامل هي عبر oidc-client-ts، وهي مكتبة عميل OIDC خفيفة لتطبيقات JavaScript وTypeScript.

import { UserManager } from 'oidc-client-ts';

const mgr = new UserManager({
  authority: 'https://acme.authagonal.io',
  client_id: 'my-app',
  redirect_uri: 'https://app.example.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
});

// Redirect to login
mgr.signinRedirect();

// On callback page
const user = await mgr.signinRedirectCallback();
console.log(user.profile); // { sub, email, name, ... }

إذا كنت تفضّل نهجًا بسيطًا دون مكتبة، يمكنك استخدام تدفق رمز التفويض القياسي في OAuth 2.0 مع fetch البسيط:

// 1. Redirect the user to the authorization endpoint
const authorizeUrl = new URL('https://acme.authagonal.io/connect/authorize');
authorizeUrl.searchParams.set('client_id', 'my-app');
authorizeUrl.searchParams.set('redirect_uri', 'https://app.example.com/callback');
authorizeUrl.searchParams.set('response_type', 'code');
authorizeUrl.searchParams.set('scope', 'openid profile email');
authorizeUrl.searchParams.set('code_challenge', codeChallenge);
authorizeUrl.searchParams.set('code_challenge_method', 'S256');
window.location.href = authorizeUrl.toString();

// 2. On the callback page, exchange the code for tokens
const res = await fetch('https://acme.authagonal.io/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: new URLSearchParams(window.location.search).get('code')!,
    redirect_uri: 'https://app.example.com/callback',
    client_id: 'my-app',
    code_verifier: codeVerifier,
  }),
});

const tokens = await res.json();
// tokens.id_token, tokens.access_token (refresh_token only when offline_access is requested and allowed)

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

لوحة التحكم

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

نظرة عامة

في أعلى لوحة التحكم سترى رسالة ترحيب ورابط فتح صفحة تسجيل الدخول المؤدي إلى صفحة تسجيل الدخول المستضافة لمستأجرك. وأسفل البطاقات الإحصائية، يتتبّع مقياس المستخدمون النشطون شهريًا الاستخدام مقارنةً بحد خطتك، ويعرض رابطًا إلى خيارات خطتك بمجرد تجاوزك 80%. وتكتمل الصفحة بمخطط نشاط تسجيل الدخول وموجز النشاط الأخير الذي يعرض أحدث إدخالات التدقيق.

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

مقاييس النشاط

تلخّص ست بطاقات إحصائية حالة مستأجرك بنظرة سريعة:

• المستخدمون النشطون: إجمالي عدد المستخدمين في مستأجرك
• عمليات تسجيل الدخول (24 ساعة): عمليات تسجيل الدخول الناجحة خلال آخر 24 ساعة
• المسجّلون في MFA: نسبة المستخدمين المسجّلين في MFA، مع عدد المسجّلين والعدد الإجمالي
• المحاولات الفاشلة (24 ساعة): عمليات تسجيل الدخول الفاشلة خلال آخر 24 ساعة، مثل بيانات الاعتماد غير الصحيحة أو الحسابات المقفلة أو حالات الرفض بسبب السياسة
• مزامنة SCIM: نشاط التزويد من موفّري الهوية المتصلين، ويُعرض بحالة «خامل» أو بعدد العمليات
• الإنفاق الشهري: الإنفاق حتى الآن هذا الشهر، مع رقم متوقَّع لنهاية الشهر

تقارن بطاقات الـ 24 ساعة آخر 24 ساعة بالـ 24 ساعة التي سبقتها. ويرسم مخطط نشاط تسجيل الدخول عمليات تسجيل الدخول الناجحة والفاشلة يوميًا على مدى 14 أو 30 أو 90 يومًا. وتتحدّث لوحة التحكم كل دقيقة.

بطاقات إحصائية تلخّص آخر 24 ساعة

التنقل السريع

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

العملاء

يمثّل عملاء OAuth التطبيقات التي تُصادق المستخدمين عبر مستأجرك. لكل عميل تهيئته الخاصة لعناوين إعادة التوجيه، والنطاقات، وأنواع المنح، ومدد صلاحية الرموز، وسياسة MFA.

قائمة العملاء

تعرض صفحة العملاء جدولًا بجميع العملاء المسجّلين. يُظهر كل صف clientId، والاسم المعروض، وأنواع المنح المسموح بها كشارات ملونة، وما إذا كان PKCE مفعّلًا. انقر على أي صف لفتح محرّر التهيئة الكامل.

قائمة العملاء مع شارات أنواع المنح ومؤشرات PKCE

إنشاء عميل

انقر على عميل جديد لتسجيل تطبيق جديد. تحتاج إلى تقديم حقلين:

• clientId ، معرّف فريد للعميل (مثل my-spa)
• clientName ، اسم معروض مقروء للبشر

سجّل عميل OAuth جديدًا

حذف عميل

لحذف عميل، انقر على أيقونة سلة المهملات في صفّه ضمن جدول العملاء واكتب معرّف العميل للتأكيد. يُزال العميل نهائيًا ولا يعود بإمكانه تسجيل دخول المستخدمين أو تحديث الرموز. أما رموز الوصول الصادرة بالفعل فلا تُبطَل، وتبقى صالحة حتى تنتهي صلاحيتها.

مرجع تهيئة العميل

لكل عميل مجموعة شاملة من خيارات التهيئة منظّمة في خمسة تبويبات: عام، وعناوين URI، والنطاقات والمنح، والرموز، والأمان.

الإعدادات العامة

العناوين (URIs)

تستخدم حقول URI إدخالًا على هيئة وسوم، اكتب قيمة واضغط Enter أو فاصلة لإضافتها. انقر على علامة X في أي وسم لإزالته.

حقول إدخال على هيئة وسوم لتهيئة العناوين (URIs)

النطاقات وأنواع المنح

مدد صلاحية الرموز

اضبط مدد صلاحية الرموز لكل عميل

عناوين تسجيل الخروج

يمكن للعملاء تسجيل عناوين تسجيل خروج عبر القناة الخلفية والقناة الأمامية معًا. كلاهما أو أحدهما اختياري، اضبط ما يناسب طريقة مسح تطبيقك لجلسته.

سياسة MFA

لكل عميل سياسة MFA خاصة به، تُضبط في تبويب <strong>الأمان</strong> الخاص بالعميل. تقدّم قائمة سياسة MFA المنسدلة ثلاثة خيارات:

سياسة MFA لكل عميل

SSO للمؤسسات

يتيح SSO للمؤسسات لعملائك استخدام موفّر الهوية الخاص بهم. يدعم Authagonal كلًا من اتحاد SAML 2.0 وOIDC مع التوجيه القائم على النطاق، بحيث يُوجَّه المستخدمون تلقائيًا إلى موفّر الهوية الصحيح بناءً على عنوان بريدهم الإلكتروني.

التوجيه القائم على النطاق لـ SSO

اتصالات SAML 2.0

لإنشاء اتصال SAML، انتقل إلى صفحة SSO وحدّد علامة التبويب SAML. قدّم ما يلي:

عند حفظ الاتصال، يجلب Authagonal وثيقة البيانات الوصفية ويستورد شهادة التوقيع الخاصة بموفّر الهوية، وعنوان URL لنقطة نهاية SSO، وصيغة معرّف الاسم. تُحدّث البيانات الوصفية دوريًا لالتقاط عمليات تدوير الشهادات.

إنشاء اتصال SSO بـ SAML 2.0

اتصالات OIDC

لإنشاء اتصال اتحاد OIDC، حدّد علامة التبويب OIDC وقدّم:

إنشاء اتصال اتحاد OIDC

التوجيه القائم على النطاق

يعيد التوجيه القائم على النطاق توجيه المستخدمين تلقائيًا إلى موفّر الهوية الصحيح بناءً على نطاق بريدهم الإلكتروني. عندما يُدخل مستخدم بريده الإلكتروني في صفحة تسجيل الدخول، يتحقق Authagonal مما إذا كان جزء النطاق (مثل acme.com) يطابق allowedDomains لأي اتصال SSO. وإذا تطابق، يُعاد توجيه المستخدم بسلاسة إلى موفّر الهوية الخاص بمؤسسته.

يربط التوجيه القائم على النطاق نطاقات البريد الإلكتروني بموفّري الهوية

تزويد JIT

عندما يسجّل مستخدم الدخول عبر SSO لأول مرة ولم يكن موجودًا بالفعل في مستأجرك، يمكن لـ Authagonal إنشاء حسابه تلقائيًا (التزويد الفوري Just-In-Time). التزويد الفوري JIT معطّل افتراضيًا: فعّله لكل اتصال عبر تحديد تفعيل الإنشاء التلقائي عند أول دخول عند إنشاء الاتصال.

عند تعطيل تزويد JIT، لا يمكن تسجيل الدخول عبر ذلك الاتصال إلا للمستخدمين الذين تم تزويدهم مسبقًا، سواء عبر SCIM أو صفحة المستخدمين في البوابة أو الـ API. يتلقى المستخدمون غير المعروفين خطأ access_denied ويُوجَّهون للتواصل مع المسؤول الخاص بهم.

اتصالات مقيّدة بمنظمة

يمكن أيضًا أن يتبع الاتصال منظمة واحدة داخل مستأجرك بدلًا من المستأجر بأكمله. ولا يُعرض إلا بعد تحديد تلك المنظمة مسبقًا: عبر نطاق مخصص مثبّت عليها، أو معامل organization في رابط تسجيل الدخول، أو عميل مسجّل لتلك المنظمة وحدها. ولا يُعرض أبدًا في صفحة تسجيل دخول على مستوى المستأجر. ويُفحص أيٌّ من هذه المصادر يتقدم وفق هذا الترتيب، من الأعلى أولوية إلى الأدنى.

المستخدمون

تتيح لك صفحة المستخدمين إدارة جميع المستخدمين النهائيين في مستأجرك. يمكنك البحث عن المستخدمين، وعرض تفاصيلهم، ودعوة مستخدمين جدد، ومعرفة كيفية تزويد كل مستخدم.

البحث والترقيم

يطابق شريط البحث معرّف مستخدم أو بريدًا إلكترونيًا مطابقًا تمامًا، أو بادئة البريد الإلكتروني أو الاسم الأول أو اسم العائلة، وتضيّق عوامل التصفية «الكل» و«نشط» و«غير نشط» القائمة حسب الحالة. يجري البحث بتأخير قدره 300 مللي ثانية بحيث تتحدّث النتائج أثناء الكتابة دون إثقال الـ API. تُرقَّم النتائج بمعدل 50 مستخدمًا لكل صفحة، استخدم عناصر التحكم في التنقل أسفل الجدول للانتقال بين الصفحات.

جدول المستخدمين

يعرض جدول المستخدمين الأعمدة التالية لكل مستخدم:

قائمة المستخدمين مع شريط البحث والترقيم

دعوة المستخدمين

انقر على دعوة مستخدم لدعوة شخص إلى مستأجرك. سيتلقى بريدًا إلكترونيًا لتعيين كلمة مروره بنفسه. يتضمن النموذج ما يلي:

دعوة مستخدم جديد

اللغة المفضّلة

لكل مستخدم لغة مفضّلة تتحكم في كل من واجهته المستضافة ورسائل البريد الإلكتروني الخاصة بالمعاملات التي يرسلها له Authagonal (التحقق، وإعادة ضبط كلمة المرور، والترحيب، وغير ذلك). يمكنك تعيينها عند دعوة المستخدم وتغييرها في أي وقت من صفحة تفاصيل المستخدم. إذا لم تكن لدى المستخدم لغة مفضّلة محددة، يعود Authagonal افتراضيًا إلى الإنجليزية. يقدّم المُحدِّد جميع اللغات المدعومة: الإنجليزية، والصينية (المبسّطة)، والألمانية، والفرنسية، والإسبانية، والفيتنامية، والبرتغالية، واليابانية، والعربية، والهندية، والأفريكانية.

عيّن اللغة المفضّلة للمستخدم في صفحة التفاصيل

تفاصيل المستخدم

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

الملف الشخصي

حرّر البريد الإلكتروني، والاسم الأول/الأخير، والهاتف، والشركة، واللغة، والمعرّف الخارجي، وبدّل علامة نشاط المستخدم. يتطلب تغيير البريد الإلكتروني أو علامة تأكيد البريد الإلكتروني مسؤولًا أو مالكًا. يجب أن تبقى تغييرات البريد الإلكتروني فريدة عبر المستأجر، ويُرجع الـ API email_already_in_use إذا كان مستخدمًا.

الأدوار

عيّن الأدوار المعرّفة في صفحة الأدوار وألغِ تعيينها. تُصدَر الأدوار المعيّنة بوصفها المطالبة roles في رموز الهوية والوصول عندما يطلب العميل النطاق roles.

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

اطّلع على كل بيانات اعتماد MFA المسجّلة للمستخدم (تطبيق المصادقة (TOTP)، وWebAuthn/مفاتيح المرور، ورموز الاسترداد)، لكل منها طوابعها الزمنية الخاصة بالتسجيل وآخر استخدام. أزِل بيانات اعتماد فردية، أو أعد ضبط جميع عوامل MFA، ويتطلب كلا الإجراءين مسؤولًا أو مالكًا. تجبر إعادة الضبط المستخدم على إعادة التسجيل عند تسجيل الدخول التالي.

السمات المخصصة

بيانات مفتاح/قيمة اعتباطية مرتبطة بالمستخدم. يجب أن تكون المفاتيح فريدة. تُكشف السمات عبر API الملف الشخصي للمستخدم وعبر SCIM، ويمكن ربطها بمطالبات رمز الوصول عبر تهيئة userClaims لنطاق مخصص.

المؤسسة

المؤسسة التي ينتمي إليها هذا المستخدم. وهي معرّف نصّي حر من عندك، يُصدَر بوصفه مطالبة org_id في رموزه وعلى /connect/userinfo ضمن نطاق profile. لا يشتقّه Authagonal أبدًا: بل يضبطه تطبيق التزويد لديك، أو بيانات اعتماد SCIM التي أنشأت المستخدم، أو يُضبط يدويًا من هنا.

يعرض الرابط المجاور للحقل كل من يشترك في القيمة نفسها، والمرشِّح نفسه متاح على الـ API بصيغة GET /api/v1/users?organizationId=. استخدمه لمعرفة من ينتمي إلى زبون معيّن دون تصفّح الدليل بأكمله.

حذف المستخدم

يزيل المستخدم وجميع بيانات اعتماد MFA الخاصة به نهائيًا. اكتب عنوان البريد الإلكتروني للمستخدم للتأكيد، فلا يمكن التراجع عن ذلك.

المجموعات

تتيح لك المجموعات تنظيم المستخدمين وتضمين عضوية المجموعة في الرموز. يمكن إنشاء المجموعات يدويًا في البوابة أو تزويدها تلقائيًا عبر SCIM من مزوّد هوية خارجي.

قائمة المجموعات

تُسرَد المجموعات في تبويب المجموعات بصفحة SCIM، مع المعلومات التالية:

قائمة المجموعات مع مؤشرات المصدر

إنشاء مجموعة

انقر فوق مجموعة جديدة وأدخِل الاسم المعروض للمجموعة. ينبغي أن تكون أسماء المجموعات وصفية وفريدة داخل المستأجر الخاص بك (مثل "Engineering" و"Billing Admins" و"Beta Testers").

تفاصيل المجموعة والأعضاء

انقر فوق أي مجموعة لفتح عرض التفاصيل. هنا يمكنك رؤية جميع الأعضاء الحاليين وإدارة العضوية:

• إضافة أعضاء: ابحث عن مستخدم بالبريد الإلكتروني أو الاسم وأضِفه إلى المجموعة.
• إزالة الأعضاء: انقر فوق زر الإزالة بجوار أي عضو وأكّد. تُلغى أي أدوار مُنحت عبر المجموعة.

إدارة عضوية المجموعة في عرض التفاصيل

المجموعات في الرموز

عند تفعيل المجموعات في الرموز على عميل وطلب النطاق groups، تتضمن الرموز الصادرة مطالبة groups تسرد الأسماء المعروضة لمجموعات المستخدم:

{
  "sub": "user-123",
  "email": "[email protected]",
  "groups": ["Engineering", "Beta Testers"]
}

الأدوار

تدعم الأدوار التحكم في الوصول المستند إلى الأدوار (RBAC) في تطبيقك. عرّف الأدوار في Authagonal، وخصّصها للمستخدمين، واستخدم مطالبة roles في الرموز لفرض التفويض في منطق تطبيقك.

إدارة الأدوار

تعرض صفحة الأدوار جدولًا بجميع الأدوار المعرّفة مع التحرير المباشر. لكل دور:

إنشاء دور

انقر فوق دور جديد وقدّم اسمًا ووصفًا. ينبغي أن تكون أسماء الأدوار موجزة وأن تتبع اصطلاح تسمية متسقًا عبر تطبيقك (مثل الأحرف الصغيرة مع الشرطات: billing-admin).

التحرير المباشر

تدعم الأدوار التحرير المباشر مباشرةً في الجدول. انقر فوق أيقونة القلم على أي دور للدخول إلى وضع التحرير، فتصبح حقول الاسم والوصف قابلة للتحرير. عدّل القيم، ثم انقر فوق أيقونة علامة الصح للحفظ. تسري التغييرات على الفور.

حذف دور

انقر فوق أيقونة الحذف على أي دور لإزالته. سيُطلب منك التأكيد قبل حذف الدور نهائيًا. لا تؤدي إزالة دور إلى إبطال الرموز الحالية بأثر رجعي، إذ سيغيب الدور عن الرموز الجديدة الصادرة بعد الحذف.

التحرير المباشر للأدوار في جدول الأدوار

الأدوار في الرموز

تُضمَّن الأدوار المخصصة لمستخدم كمطالبة roles في رموز الهوية والوصول عندما يطلب العميل النطاق roles. يمكن لتطبيقك قراءة هذه المطالبة لاتخاذ قرارات التفويض:

{
  "sub": "user-123",
  "email": "[email protected]",
  "roles": ["admin", "billing-admin"]
}

تزويد SCIM

يتيح SCIM 2.0 (نظام إدارة الهوية عبر النطاقات) التزويد التلقائي للمستخدمين والمجموعات من مزوّدي الهوية المؤسسية مثل Okta وAzure AD وOneLogin وJumpCloud. عند ضبطه، تُزامَن حسابات المستخدمين وعضويات المجموعات تلقائيًا من مزوّد الهوية الأعلى إلى المستأجر الخاص بك في Authagonal.

مزامنة دورة حياة مستخدم SCIM مع التزويد إلى الأنظمة التابعة

خطوات الإعداد

اتبع هذه الخطوات لتفعيل تزويد SCIM لعميل:

1. اختر تطبيق العميل: اختر عميل OAuth الذي سيرتبط به تزويد SCIM.
2. أنشئ رمز SCIM: قدّم وصفًا ومدة صلاحية بالأيام، ثم أنشئ الرمز.
3. انسخ الرمز فورًا: تُعرض قيمة الرمز الخام مرة واحدة فقط. انسخها قبل إغلاق مربع الحوار.
4. اضبط مزوّد الهوية لديك: في إعدادات SCIM لمزوّد الهوية، أدخِل عنوان URL الأساسي ورمز الحامل.
5. اختبر مزامنة المستخدمين: شغّل مزامنة اختبارية من مزوّد الهوية وتحقق من ظهور المستخدمين في بوابة Authagonal.

عنوان URL الأساسي لـ SCIM

اضبط مزوّد الهوية لديك بعنوان URL الأساسي التالي:

https://{slug}.authagonal.io/scim/v2

استبدل {slug} بسلَج المستأجر الخاص بك.

صفحة إعداد SCIM مع إنشاء الرموز

إدارة الرموز

تصادق رموز SCIM على طلبات التزويد الواردة من مزوّد الهوية لديك. يمكنك إدارة عدة رموز لكل عميل:

لإبطال رمز، انقر فوق زر إبطال المجاور له. تبقى الرموز المُبطَلة مرئية في القائمة لأغراض التدقيق لكنها تتوقف فورًا عن قبول الطلبات.

إدارة الرموز مع مؤشرات الرموز النشطة والمُبطَلة

اختبار الاتصال

تحقق من أن تكامل SCIM لديك يعمل عبر الاستعلام عن نقطة نهاية ServiceProviderConfig:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://acme.authagonal.io/scim/v2/ServiceProviderConfig

تُعيد الاستجابة الناجحة مستند JSON يصف ميزات SCIM المدعومة: PATCH والتصفية مدعومان، بينما العمليات المجمّعة وتغيير كلمة المرور والفرز وETags غير مدعومة.

ما الذي تراه بيانات الاعتماد

لا ترى بيانات اعتماد SCIM إلا المستخدمين والمجموعات التي زوّدتها هي. فقراءة مستخدم أنشأه موصِّل آخر أو تحديثه أو حذفه تُجيب بـ 404، ولا يُعيد السرد إلا ما يخصّها، ولا يجوز أن تسمّي عضوية المجموعة سوى مستخدمين زوّدهم الموصِّل نفسه. أما الحسابات المُنشأة بأي طريقة أخرى، سواء بواسطة مسؤول أو عبر تسجيل ذاتي أو عبر التزويد الفوري من SSO، فهي غير مرئية لـ SCIM إطلاقًا.

هذا الحد يسري لكل عميل، لا لكل رمز. فبيانات اعتماد اثنتان صادرتان على العميل نفسه هما هوية واحدة بسرّين، وكلٌّ منهما تستطيع تعديل ما أنشأته الأخرى. امنح الموصِّلات غير الموثوقة فيما بينها عميلًا لكل منها. ويُحدَّد نطاق externalId بالطريقة نفسها، فيمكن لموصِّلَين أن يستخدم كلٌّ منهما ext-001 لشخصين مختلفين دون تعارض.

إلغاء التزويد

DELETE /scim/v2/Users/{id} يعطّل الحساب ويضع عليه علامة محذوف. يُحتفظ بالسجل، كما يسمح RFC 7644، لكنه يُجيب بـ 404 على كل عملية لاحقة ويُستبعد من القوائم. تُمسح تسجيلات MFA وعضويات المجموعات الخاصة به، ويُحرَّر ربط externalId، وتُبطَل جميع الرموز الصادرة، فينتهي الوصول فورًا بدلًا من انتهائه عند انقضاء صلاحية الرمز التالي.

إذا أُعيد توظيف الشخص نفسه لاحقًا وأُعيد إنشاؤه، فسيحصل على معرّف مستخدم جديد. لا يُعاد استخدام المعرّفات أبدًا: فالمعرّف هو الـ subject في كل رمز أصدرته حتى الآن، لذا فإن إعادة استخدامه ستمنح الموظف الجديد بصمت سجلَّ صاحبه السابق في كل تطبيق يثق بهذا المعرّف.

وسم المستخدمين المزامَنين بمؤسسة

لا يوفّر SCIM أي وسيلة تتيح للموصِّل أن يذكر أيَّ زبائنك يزامن. لا يعرّف SCIM الأساسي أي سمة للمؤسسة، لذا فإن إنشاء مستخدم عادي يخبرك باسم الشخص وبريده الإلكتروني ولا شيء عمّن ينتمي إليه. وإذا زوّد عدة زبائن مستخدمين داخل مستأجرك، فسيصل مستخدموهم غير قابلين للتمييز بعضهم عن بعض.

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

يُطبَّق الوسم عند إنشاء المستخدم ولا يُطبَّق أبدًا عند تحديث لاحق، لذا لا تستطيع مزامنة تزايدية روتينية أن تنقل حسابًا قائمًا بصمت. وإذا كنت تشغّل كذلك تطبيق تزويد، فإن الوسم الصريح في بيانات الاعتماد هو الذي يفوز: لا تملأ استجابة /try إلا مؤسسة ما تزال فارغة.

المخططات المدعومة

ننفّذ مخططَي SCIM 2.0 الأساسيين User وGroup (RFC 7643). سمات المستخدم المدعومة هي userName وname.givenName وname.familyName وdisplayName وemails وactive وexternalId وpreferredLanguage / locale.

امتداد المستخدم المؤسسي غير مُنفَّذ، لذا تُقبل السمات department وmanager وemployeeNumber وcostCenter وdivision وorganization ثم تُتجاهَل بدلًا من تخزينها، وذلك في الإنشاء والاستبدال وPATCH على حد سواء. يربط كل من Entra وOkta بعضها افتراضيًا، فلا حاجة إلى إزالتها من خريطة السمات لديك. ولنسب مستخدم إلى أحد زبائنك، اضبط المؤسسة على بيانات اعتماد SCIM بدلًا من ذلك: فسمة organization المؤسسية يؤكّدها مزوّد الهوية لدى زبونك، وهي عمدًا لا تصبح org_id الخاص به.

نطاقات OAuth

تتيح النطاقات للعملاء طلب شرائح محددة من بيانات المستخدم أو أذوناته. يدعم Authagonal نطاقات OIDC القياسية والنطاقات المخصصة التي تعرّفها لواجهات API الخاصة بك.

النطاقات المدمجة

النطاقات المخصصة

عرّف نطاقاتك الخاصة في صفحة النطاقات. يصف كل نطاق إذناً أو مورداً يمكن للعميل طلبه (على سبيل المثال، billing.read وorders.write).

مطالبات مخصصة على الرموز

للمطالبات المخصصة شقّان. المصدر هو بيانات خاصة بكل مستخدم: لكل AuthUser قاموس customAttributes يمكنك تعبئته من البوابة (المستخدمون ← المستخدم ← السمات المخصصة) أو عبر SCIM أو عبر خطاف تزويد TCC. أما الإطلاق فهو خاص بكل نطاق: تسمّي قائمة userClaims لكل نطاق المفاتيح التي تسمح بمغادرتها للخادم.

عندما يطلب عميل نطاقات، يمرّ Authagonal على النطاقات الممنوحة، ويوحّد قوائم userClaims الخاصة بها، ولا يُصدر إلا تلك المفاتيح من customAttributes الخاصة بالمستخدم. وتُسقَط المفاتيح غير المعروفة بصمت، فلا يستطيع عميل قراءة سمة بتخمين اسمها. أما مطالبات OIDC القياسية (sub وemail وname وغيرها) فتتبع المواصفة ولا تخضع للقائمة البيضاء.

# 1. On the user (Portal → Users → {user} → Custom Attributes)
department = "engineering"
employee_id = "E-1042"
seat_tier = "enterprise"

# 2. On a custom scope (Portal → Scopes → projects.read)
name        = "projects.read"
userClaims  = ["department", "seat_tier"]   # <-- whitelist

# 3. Client requests scope=openid projects.read
# Decoded access token (relevant fields only):
{
  "sub": "u-9b…",
  "scope": "openid projects.read",
  "department": "engineering",
  "seat_tier":  "enterprise"
  // employee_id is NOT emitted; it's not in the whitelist for any granted scope.
}

إسناد النطاقات إلى العملاء

أضف النطاقات المسموح بها في تبويب العملاء ← النطاقات & المنح. لا يمكن للعميل طلب سوى النطاقات الممنوحة له؛ وتُرفض النطاقات غير المعروفة بـ invalid_scope.

العلامة التجارية

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

المظهر

إعدادات المظهر مع معاينة مباشرة للألوان

معلومات الاتصال

مفاتيح تبديل صفحة تسجيل الدخول

تحكّم في العناصر التي تظهر على صفحة تسجيل الدخول الخاصة بالمستأجر:

مثال على صفحة تسجيل دخول مع تطبيق علامة تجارية مخصصة

CSS مخصص

للتحكم الكامل في مظهر صفحة تسجيل الدخول، قدّم عنوان URL لملف CSS في إعدادات علامتك التجارية. يُحمَّل الملف بعد الأنماط الافتراضية، لذا تكون الأولوية لقواعدك. يجب أن يكون عنوان URL على الأصل نفسه لصفحة تسجيل الدخول، ولا تُحمَّل أوراق الأنماط من الأصول الأخرى.

الوضع الداكن

يأتي تطبيق تسجيل الدخول بسمات فاتحة وداكنة وتابعة للنظام. يختار إعداد الوضع الداكن في صفحة العلامة التجارية القيمة الافتراضية: إيقاف، أو تلقائي (يتبع تفضيل النظام، وهو الافتراضي)، أو فرض. ولا يزال بإمكان المستخدمين الاختيار من مفتاح تبديل على صفحة تسجيل الدخول، ويستمر الاختيار عبر الجلسات. عند الضبط على system، يتتبع التطبيق أحادي الصفحة قيمة prefers-color-scheme بشكل مباشر.

تُعلَن القيم الفاتحة عند :root، وتُحصر التجاوزات الداكنة ضمن .dark. تكون الأولوية دائمًا للعلامة التجارية للمستأجر المضبوطة عبر customCssUrl، لذا تستمر ألوانك بغض النظر عن سمة المستخدم.

الإعدادات

اضبط سياسات الأمان على مستوى المستأجر وخطافات الويب وإعدادات البيئة. تنطبق هذه الإعدادات عالميًا عبر جميع العملاء ما لم تُتجاوز على مستوى العميل.

سياسة كلمات المرور

حدّد متطلبات تعقيد كلمات المرور لجميع المستخدمين في المستأجر الخاص بك، ضمن المستخدمون ← الإعدادات:

ضبط سياسة كلمات المرور

سياسة MFA

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

الجلسة والإقفال

تحكّم في مدة الجلسة وسلوك إقفال الحساب:

ضبط الجلسة والإقفال

خطافات الويب

تتيح لك خطافات الويب التفاعل مع أحداث المصادقة في الوقت الفعلي. هناك حدثان (onUserAuthenticated وonTokenIssued) قابلان للفرض، فهما يُطلَقان افتراضيًا بشكل غير متزامن ولا يحجبان المستخدم، لكن يمكنك اختيار الفرض لكل حدث بحيث ترفض الإجراءَ استجابةٌ خارج نطاق 2xx أو جسمُ {"allow": false}. أما الأحداث المتبقية فهي إشعارات تُطلَق دائمًا بأسلوب إطلاق ونسيان، ولا تحجب أبدًا.

إعدادات إضافية لخطافات الويب:

ضبط أحداث خطاف الويب

التحقق من خطافات الويب

بمجرد ضبط أي عنوان URL لخطاف ويب، يَسُكّ Authagonal سرّ توقيع خاصًا بكل مستأجر (قيمة whsec_… تُعرض للقراءة فقط ضمن الإعدادات ← خطافات الويب). يحمل كل تسليم صادر ترويسة X-Authagonal-Signature: t=<unix>,v1=<hex>، حيث يكون v1 هو HMAC-SHA256(secret, "{t}.{body}") محسوبًا على جسم الطلب الخام. أعِد حسابه على نقطة النهاية لديك وقارنه بزمن ثابت للتأكد من أن الطلب وارد فعلًا من Authagonal ولم يُعبَث به، وارفض عمليات التسليم التي تكون قيمة t فيها قديمة جدًا لمنع هجمات إعادة التشغيل.

import crypto from 'node:crypto';

// rawBody MUST be the exact bytes Authagonal sent: verify before any JSON re-serialization.
function verifyAuthagonalWebhook(signatureHeader, rawBody, signingSecret) {
  const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')));
  const { t, v1 } = parts;

  // Replay protection: reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

نافذة الصيانة

حدّد نافذة صيانة مفضّلة للعمليات المعطِّلة مثل نقل بيانات مستأجرك بين أجزاء التخزين. اختر ساعة بتوقيت UTC (من 0 إلى 23)، وتعرض البوابة أيضًا التوقيت المكافئ في منطقتك الزمنية المحلية للتيسير.

التسجيل والوصول

من يُسمح له بأن يصبح مستخدمًا في مستأجرك، وبأي شروط يمكنه تسجيل الدخول.

الاحتفاظ بالمستخدمين غير النشطين

يمكنك اختياريًا تعطيل الحسابات التي لم تُستخدم ثم حذفها، حتى لا يراكم الدليل هويات خاملة إلى الأبد. وكلا الإجراءين معطّل ما لم تضبطه، والحذف نهائي.

تصدير التدقيق والنسخ الاحتياطية البعيدة

طريقتان لإخراج بياناتك وفق جدول بدلًا من إخراجها عند الطلب. يدفع تصدير التدقيق كل يوم مكتمل من أحداث التدقيق إلى عنوان URL تحدده أنت، موقّعًا حتى تتحقق من أنه وارد منّا، لتغذية نظام SIEM أو أرشيف امتثال. وترسل النسخ الاحتياطية البعيدة نسخًا من نسخك الاحتياطية اليومية والأسبوعية إلى وجهة تتحكم بها أنت، بلا مصادقة أو بمصادقة أساسية أو برمز حامل. يُضبط تصدير التدقيق في تبويب التصدير بصفحة سجل التدقيق، والنسخ الاحتياطية البعيدة في صفحة النسخ الاحتياطية، ويبقى كلاهما ملكًا لك، بمعزل عن النسخ الاحتياطية التي نحتفظ بها نحن.

بيئات الاختبار

تدير صفحة البيئات بيئات الاختبار: بيئات مُسمّاة ومعزولة لكل منها مستخدموها وعملاؤها ومفاتيح التوقيع وتسجيلات MFA والمنح الخاصة بها، ويمكن الوصول إلى كل منها على عنوان URL منفصل. أما العلامة التجارية والخطة والفوترة فمشتركة مع البيئة الفعلية. استخدمها لاختبار تغييرات الإعداد وتكاملات SSO ونقاط نهاية خطافات الويب دون التأثير على المستخدمين الفعليين. يمكنك إنشاء ما يصل إلى 5 بيئات افتراضيًا، ويُحتسب مستخدمو بيئات الاختبار النشطون ضمن MAU لديك.

يمكن الوصول إلى كل بيئة على {name}-{slug}.authagonal.io.

عناصر التحكم في بيئة الاختبار

الفوترة

أدِر اشتراكك وفوترتك عبر صفحة الفوترة في البوابة. تمنحك هذه الصفحة نظرة عامة على خطتك الحالية وتتيح لك الوصول إلى بوابة فوترة Stripe لإدارة طرق الدفع والفواتير وتغييرات الخطة.

معلومات الاشتراك

تعرض صفحة الفوترة تفاصيل اشتراكك الحالي بنظرة واحدة. سترى شارة حالة تشير إلى وضع اشتراكك (active أو trialing أو past_due أو canceled أو unpaid)، إلى جانب اسم خطتك وفترة الفوترة الحالية (تاريخا البدء والانتهاء) وما إذا كان اشتراكك مضبوطًا للإلغاء في نهاية الفترة الحالية.

إدارة الاشتراك

انقر فوق زر إدارة الاشتراك لفتح بوابة فوترة Stripe في نافذة جديدة. من هناك يمكنك تحديث طرق الدفع، وعرض الفواتير وتنزيلها، وتغيير خطتك، أو إلغاء اشتراكك.

إذا لم يكن هناك اشتراك بعد، يظهر بدلًا من ذلك زر دعوة لاتخاذ إجراء إعداد الفوترة، يرشدك خلال اختيار خطة وإدخال تفاصيل الدفع.

تعرض صفحة الفوترة تفاصيل اشتراكك الحالي وتتيح الوصول إلى Stripe

النطاقات المخصصة

قدّم صفحات المصادقة من نطاقك الخاص (مثل auth.yourdomain.com) بدلاً من النطاق الافتراضي {slug}.authagonal.io. تمنح النطاقات المخصصة مستخدميك تجربة مصادقة سلسة تحمل علامتك التجارية.

إضافة نطاق

أدخل اسم المضيف الذي تريد استخدامه في نموذج إضافة النطاق (مثل auth.yourdomain.com). بمجرد إضافته، سيظهر النطاق في قائمة نطاقاتك بحالة pending_verification.

التحقق عبر DNS

أنشئ سجلَّي CNAME اللذين تعرضهما البوابة للنطاق، وكلاهما يشير إلى {slug}.authagonal.io: أحدهما على اسم المضيف نفسه، وهو الذي يخدم حركة المرور ويمكن تمريره عبر وكيل (proxy)، والآخر على _authagonal-challenge. متبوعًا باسم المضيف، وهو الذي يثبت الملكية ويجب أن يكون DNS فقط (بدون وكيل). بمجرد إضافة السجلات، انقر على فحص DNS للتحقق. كما يُعاد فحص النطاقات المعلّقة تلقائيًا.

auth.yourdomain.com.                        CNAME  acme.authagonal.io.
_authagonal-challenge.auth.yourdomain.com.  CNAME  acme.authagonal.io.

شهادات TLS

بمجرد التحقق من نطاقك، تحتاج إلى شهادة TLS كي يتمكن المستخدمون من الاتصال بأمان عبر HTTPS. يدعم Authagonal خيارين:

تلقائي (cert-manager) يوفّر Authagonal شهادات TLS ويجدّدها تلقائياً باستخدام cert-manager. هذا هو الخيار الموصى به لمعظم المستخدمين، ولا يتطلب أي إعداد إضافي.

أحضر شهادتك الخاصة (BYO) ارفع شهادتك ومفتاحك الخاص بصيغة PEM. هذا الخيار مفيد إذا كانت مؤسستك تتطلب شهادات من جهة إصدار شهادات محددة. ويتم تتبّع انتهاء صلاحية الشهادة كي تتمكن من تجديدها قبل انقضائها.

حالة النطاق

يعرض كل نطاق شارة حالة تشير إلى وضعه الحالي: pending_verification (لم يُؤكَّد DNS بعد)، أو verified (تم تأكيد DNS وما زال TLS قيد الانتظار)، أو active (يعمل بالكامل).

تعرض قائمة النطاقات كل نطاق مخصص وحالته الحالية

ارفع شهادة TLS ومفتاحك الخاص بصيغة PEM

المنظمات

المنظمة هي عميل داخل مستأجر. ويظل المستأجر حدّ العزل: بادئة جداول واحدة ومفتاح توقيع واحد، وكل مضيف للمستأجر هو مُصدِر مستقل. أما المنظمة فتقسّم الهوية داخله، بحيث يخدم مستأجر واحد منظمات عملاء كثيرة دون مستأجر لكل عميل.

تعمل المنظمات جنبًا إلى جنب مع النطاقات المخصصة (يمكن تثبيت نطاق على منظمة واحدة) وتطبيقات التزويد (يمكن لتطبيق التزويد وسم مستخدم جديد بمنظمة). راجع دليل تطبيقات متعددة العملاء للاطلاع على النمط الكامل «مستأجر واحد، وعملاء كثيرون بعلامات تجارية مختلفة» الذي وُجدت هذه الميزة من أجله.

النموذج والمعرّفات

لكل منظمة id ثابت لا يتغير (بالشكل org_<32 hex>) يُصدَر كمطالبة الرمز org_id، وslug ثابت وفريد داخل المستأجر يُصدَر كـ org_slug ويقبله معامل التفويض organization. تشترك المعرّفات وslugs في فضاء بحث واحد: فأي slug يطابق معرّف منظمة أخرى يُرفض باعتباره تعارضًا، تمامًا مثل slug مكرر عادي.

العضويات

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

تُسحب roles العضوية من فهرس الأدوار الموجود في المستأجر وتُدمج في مطالبة roles، لكن فقط عندما تكون المنظمة قد حُدّدت صراحةً بواسطة الطلب (راجع تحديد المنظمة في الرمز) ومن صف عضوية نشطة فقط. ولا يصل دور يُشغَل في منظمة إلى رمز صادر لمنظمة أخرى أبدًا.

الدعوة إلى منظمة

يقبل POST /api/v1/users/invite المعاملين الاختياريين organizationId وorganizationRoles. ينشئ استدعاء واحد الحساب بعضوية invited ويرسل بريد دعوة يحمل العلامة التجارية للمنظمة. ويُفتح الرابط على النطاق المخصص المثبّت للمنظمة إن كان لديها نطاق. وعندما يقبل الشخص الدعوة تصبح العضوية active. وتسمية منظمة تتطلب دور مالك أو مسؤول.

تزويد SCIM داخل منظمة

يمكن ربط رمز SCIM بمنظمة (organizationId في POST /api/v1/scim/tokens، أو منتقي المنظمة عند إنشاء رمز). ويجب أن يسمّي المعرّف منظمة موجودة في المستأجر. كل مستخدم ينشئه ذلك الرمز يصبح عضوًا active ويحمل المنظمة كـ org_id. ويُطبَّق الربط عند الإنشاء فقط، وهو يحدد العضوية لا الوصول: فرمزان على عميل واحد يريان مستخدمي بعضهما. وحذف مستخدم، بأي طريقة، يزيل عضوياته.

أعلام السياسة

enabled (مفعّل افتراضيًا): المنظمة المعطّلة لا تُصدر رموزًا لنفسها، ويُتحقق من ذلك عند التفويض وعند كل تجديد، فيوقف تعطيل منظمة الجلسات الحية عند دورة التدوير التالية بدلًا من منع تسجيلات الدخول الجديدة فقط.

requireMembershipForTokens (مفعّل افتراضيًا): يحدد ما إذا كان على المستخدم أن يحمل عضوية نشطة ليُصدَر له رمز لهذه المنظمة. ولا يسري إلا على التحديد الصريح (طلب يسمّي المنظمة، أو تجديد يحملها، أو اتصال مقيّد بمنظمة، أو عميل مقيّد بمنظمة واحدة بالضبط). أما المنظمة الموروثة من الوسم القديم للحساب فحسب فلا يقيّدها هذا العلم أبدًا.

يتيح allowAutoMembership (معطّل افتراضيًا) للمستخدم الانضمام دون دعوة عندما يكون عنوان بريده الإلكتروني المؤكَّد ضمن أحد نطاقات المنظمة الموثَّقة. ويُطبَّق عند التفويض وعند كل تجديد. راجع «نطاقات البريد الإلكتروني والعضوية التلقائية» أدناه.

نطاقات البريد الإلكتروني والعضوية التلقائية

تطالب المنظمة بنطاق بريد إلكتروني وتثبت تحكمها به بسجل DNS من نوع TXT. وعند تفعيل allowAutoMembership، يصبح المستخدم الذي يقع بريده الإلكتروني المؤكَّد ضمن ذلك النطاق عضوًا عند أول تسجيل دخول له بصفته المنظمة.

1. المطالبة به. أرسل POST /api/v1/organizations/{id}/domains مع النطاق. الاستجابة 201 مع recordName (_authagonal-org.acme.com) وrecordValue (authagonal-org-verify=<token>). الرمز عشوائي ولكل مطالبة رمزها.
2. انشر السجل. أضف سجل TXT بذلك الاسم وبالقيمة نفسها تمامًا في DNS الخاص بالنطاق.
3. تحقق منه. يبحث POST /api/v1/organizations/{id}/domains/{domain}/verify عن السجل. وعند التطابق يعيد 200 مع verified: true. وعند عدم التطابق يعيد 409 verification_failed، وليس 200 مع verified: false أبدًا، فلا يخلط عميل يستطلع النجاح بين الإخفاق والنجاح.
4. أزله. يعيد DELETE /api/v1/organizations/{id}/domains/{domain} الاستجابة 204. تبقى العضويات الحالية، ويتوقف فقط الانضمام التلقائي مستقبلًا.

POST /api/v1/organizations/org_7fa2c9e1.../domains
Content-Type: application/json

{ "domain": "acme.com" }

201 Created
{
  "domain": "acme.com",
  "verified": false,
  "verifiedAt": null,
  "createdAt": "2026-10-03T01:02:03Z",
  "recordName": "_authagonal-org.acme.com",
  "recordValue": "authagonal-org-verify=Qm9...base64url"
}

حالات الرفض: 400 domain_invalid (ليس اسم DNS مجردًا)، 409 domain_exists (موجود أصلًا في هذه المنظمة)، 409 domain_taken (تحتفظ به منظمة أخرى في المستأجر)، 404 organization_not_found و404 domain_not_found. ينتمي النطاق إلى منظمة واحدة على الأكثر لكل مستأجر، ويُفحص ذلك مرة أخرى عند التحقق.

قاعدة العضوية التلقائية

يقبل المنتقي مستخدمًا لا يحمل عضوية نشطة عندما تتحقق جميع الشروط التالية:

• حُدّدت المنظمة صراحةً: عبر منحة تجديد محمولة، أو اتصال مقيّد بمنظمة، أو المعامل organization (يوفره تثبيت النطاق)، أو عميل مقيّد بمنظمة واحدة بالضبط. أما الوسم القديم للحساب نفسه فلا ينضم تلقائيًا أبدًا.
• المنظمة مفعّلة وallowAutoMembership قيد التشغيل.
• بريد المستخدم الإلكتروني مؤكَّد، لأن أي شخص يستطيع التسجيل باسم [email protected].
• الجزء من البريد الإلكتروني بعد آخر @، بأحرف صغيرة، مطابق تمامًا لأحد نطاقات المنظمة الموثَّقة. لا توجد مطابقة للنطاقات الفرعية: فالنطاق الموثَّق acme.com لا يقبل [email protected]. طالب بكل نطاق فرعي وتحقق منه على حدة.

ما تكتبه القاعدة قبل تشغيل بوابة العضوية: إذا لم يوجد صف تصبح عضوية active جديدة بلا أدوار؛ والصف invited يُرقّى إلى active مع الإبقاء على أدواره؛ والصف active يُترك كما هو؛ والصف suspended لا يُرقّى أبدًا.

تحديد المنظمة في الرمز

المنظمة التي يُحَلّ إليها الطلب تُحدَّد في مكان واحد بالضبط، فتكون النتيجة نفسها في /connect/authorize وعند كل تجديد وفي منحة الجهاز. الأسبقية من الأعلى إلى الأدنى:

تثبيت النطاق

يمكن تثبيت نطاق مخصص على منظمة واحدة، ليصبح ذلك النطاق الباب الأمامي الخاص بالمنظمة. ويُفرض التثبيت بواسطة وسيط تحديد المستأجر (tenant-resolution middleware) لكل من GET /connect/authorize (يُلحق بسلسلة الاستعلام) وPOST /connect/par (يُعاد كتابة الجسم المدفوع بدلًا من ذلك، لأن PAR يقرأ معاملاته من الحمولة المخزّنة). راجع النطاقات المخصصة للاطلاع على الآلية الكاملة.

PUT /api/v1/custom-domains/auth.acme.com/organization
Content-Type: application/json

{ "organizationId": "org_7fa2c9e1..." }

اتصالات مقيّدة بمنظمة

يمكن أن يتبع اتصال SAML أو OIDC منظمة واحدة. وتسجيل الدخول عبره يحدد تلك المنظمة وينشئ عضوية active عندما لا يكون للمستخدم عضوية. ويُقبل الصف invited: إذ يصبح active ويحتفظ بأدواره ومن دعاه، فلا يحتاج المدعو الذي يسجّل الدخول عبر IdP الخاص به إلى البريد الإلكتروني إطلاقًا. أما العضو suspended فيبقى معلّقًا ويُرفض عند إصدار الرمز. ولا يعتمد هذا على allowAutoMembership ولا على النطاقات، لأن المنظمة حُدّدت أصلًا بواسطة الاتصال.

اسم المنظمة في صفحة تسجيل الدخول

تعرض صفحة تسجيل الدخول تسجيل الدخول إلى {name} تحت اسم التطبيق. ويأتي الاسم من المنظمة نفسها التي تأتي منها العلامة التجارية للصفحة: منظمة النطاق المثبّت، ثم المنظمة التي يسميها طلب التفويض، ثم المنظمة الوحيدة المقيّد بها العميل. ويُخفى عند عدم وجود منظمة، أو عندما يساوي اسم المنظمة اسم التطبيق، فلا يظهر الترويس أبدًا بصيغة «Acme / Signing in to Acme».

تجاوز العلامة التجارية

يُدمج brandingJson الخاص بالمنظمة حقلًا بحقل فوق العلامة التجارية للمستأجر في صفحة تسجيل الدخول: المفتاح الموجود وغير الفارغ يتجاوز، والمفتاح الغائب أو الفارغ يرث، والمفتاح غير المعروف يُتجاهل. وJSON المشوَّه يعود إلى العلامة التجارية للمستأجر مع تسجيل تحذير، ولا يفشل تحميل الصفحة أبدًا.

يحرّر تبويب العلامة التجارية الحقول الـ 21 القابلة للدمج جميعها: المظهر (appName وlogoUrl وprimaryColor وcustomCssUrl)، وألوان الوضعين الفاتح والداكن، وألوان البريد الإلكتروني، وsupportEmail وshowForgotPassword وpoweredBy وlanguages. ويرث كل حقل قيمة المستأجر، وتُعرض كتلميح، أو يتجاوزها، مع عنصر تحكم «مسح» يزيل المفتاح.

الترحيل من وسم المنظمة القديم

قبل وجود المنظمات كان بوسع المستخدم حمل وسم منظمة نصي حر دون أي سجل خلفه. يرحّل POST /api/v1/organizations/backfill ذلك إلى منظمات وعضويات حقيقية، مجمّعةً حسب كل قيمة قديمة مميزة. ويكون تشغيلًا تجريبيًا ما لم يكن جسم الطلب { "dryRun": false }.

• محدود: يفحص 50,000 مستخدم كحد أقصى لكل استدعاء. والاستجابة truncated تعني أن عليك تشغيله مرة أخرى، ويُتخطى المستخدمون الذين رُحّلوا أصلًا في التشغيل التالي.
• متكرر الأثر نفسه (idempotent): تُطابَق القيمة القديمة المميزة التي رُحّلت أصلًا بختم داخلي، لا باسم العرض (القابل للتعديل) للمنظمة، فإعادة تسمية المنظمة الناتجة لاحقًا لا تسبب تكرارًا في التشغيل التالي.

{
  "dryRun": true,
  "organizationsCreated": 3,
  "membershipsCreated": 41,
  "usersSkipped": 0,
  "organizations": [
    { "legacyValue": "acme-corp", "slug": "acme-corp", "users": 22 }
  ],
  "truncated": false
}

جولة في واجهة البوابة

تسرد صفحة المنظمات كل منظمة في المستأجر، 50 في كل مرة مع زر تحميل المزيد، وتتيح منظمة جديدة (slug واسم فقط، وتُضبط أعلام السياسة والنطاقات والعلامة التجارية بعد ذلك) وتدفق ملء من حقل المنظمة القديمة الذي يشغّل الترحيل أعلاه كمعاينة، ثم «تطبيق».

تعرض قائمة المنظمات كل منظمة عميل في المستأجر مع الـ slug والاسم وتاريخ الإنشاء

لصفحة تفاصيل كل منظمة ثلاثة تبويبات: عام (الاسم، والـ slug للقراءة فقط، ومفاتيح السياسة الثلاثة، وبطاقة نطاقات البريد الإلكتروني لإضافة نطاقات البريد الإلكتروني والتحقق منها وإزالتها ونسخ سجل TXT، وحذف يتطلب كتابة الـ slug للتأكيد)، والعلامة التجارية (كل حقل قابل للتجاوز، يرث كل منها قيمة المستأجر أو يتجاوزها)، والأعضاء (الإضافة بالبريد الإلكتروني، مع عرض دعوة عند عدم وجود حساب، وتغيير الحالة والإزالة لكل صف، مع تحميل المزيد).

يسرد تبويب الأعضاء كل عضوية مع حالتها وعنصر تحكم لكل صف لتغييرها أو إزالتها

يتجاوز تبويب العلامة التجارية علامة المستأجر في صفحة تسجيل الدخول حقلًا بحقل لهذه المنظمة

تحمل صفحة النطاقات المخصصة منتقي النطاق ← المنظمة: لكل بطاقة نطاق قائمة منسدلة مضمّنة تسرد منظمات المستأجر بالإضافة إلى خيار «مستأجر (بدون)» الذي يمسح التثبيت، ويُطبَّق فور التغيير. ويظهر المنتقي نفسه عند إضافة نطاق.

منتقي المنظمة المضمّن في بطاقة النطاق يثبّت ذلك النطاق المخصص على منظمة واحدة

أحداث التدقيق

organization.created · organization.updated · organization.deleted · organization.member.added · organization.member.invited · organization.member.joined · organization.member.updated · organization.member.removed · organization.domain_added · organization.domain_verified · organization.domain_removed · organization.backfill · domain.organization_set

التصفح بالصفحات

قائمة المنظمات وقائمة الأعضاء مقسّمتان بمؤشر (cursor) وتعيدان { items, nextCursor }. مرّر limit (الافتراضي 50، ويُقيَّد بين 1 و200) وبعد الصفحة الأولى مرّر nextCursor من الاستجابة السابقة دون تغيير كـ cursor. وقيمة nextCursor الفارغة تعني الصفحة الأخيرة. والمؤشر موضع مفتاحي معتم على معرّف المنظمة (أو معرّف المستخدم للأعضاء)، لذا فإضافة صفوف أو إزالتها بين الاستدعاءات لا تُزيح صفحة ولا تكررها. والمؤشر الذي لم تصدره القائمة هو 400 invalid_cursor.

إدارة المنظمات من مساعد ذكاء اصطناعي

يعرض MCP البوابة المستضاف ثلاث عشرة أداة للمنظمات، وكلها تتطلب دور مسؤول المستأجر: عرض المنظمات وجلب واحدة وإنشاؤها وتحديثها وحذفها؛ وعرض الأعضاء وإضافتهم وتحديثهم وإزالتهم؛ وإضافة نطاقات البريد الإلكتروني والتحقق منها وإزالتها؛ وعرض منظمات مستخدم. وتستدعي العمليات نفسها التي يستدعيها API أعلاه، فلا يمكن لأداة أن تنحرف عن مسارها. راجع شغّل بوابتك من مساعد ذكاء اصطناعي.

مُصدِر واحد لكل مضيف

كل مضيف للمستأجر هو مُصدِر OIDC مستقل. وعندما يُحَلّ مضيف الطلب عبر جدول نطاقات المستأجر، يكون المُصدِر وكل عنوان URL لنقطة نهاية يعلن عنها الاكتشاف هو https://{host}، فيؤكد كل نطاق مخصص نشط iss الخاص به ويبقى مضيف المستأجر الأساسي دون تغيير. مفاتيح التوقيع لكل مستأجر، لذا يقدّم كل مضيف مجموعة المفاتيح نفسها. وهذا ما يتيح لمستأجر واحد أن يخدم عدة عملاء، كلٌّ على نطاقه المخصص بعلامته التجارية والمثبّت على منظمته. راجع النطاقات المخصصة.

إعداد البريد الإلكتروني

اضبط طريقة إرسال المستأجر الخاص بك للرسائل البريدية المعاملاتية، مثل رسائل التحقق وإعادة تعيين كلمة المرور والدعوة. اختر بين المرسِل المشترك الافتراضي، أو نطاق مخصص مُتحقَّق منه عبر Resend، أو خادم SMTP الخاص بك.

الرسائل البريدية المترجَمة

تُرسَل الرسائل البريدية المعاملاتية بلغة المستلِم المفضّلة. تُصمَّم قوالب رسائل التحقق وإعادة تعيين كلمة المرور وتنبيه وجود الحساب والترحيب والدعوة وحذف الحساب والدعم والفوترة بإحدى عشرة لغة: الإنجليزية والألمانية والفرنسية والإسبانية والبرتغالية والفيتنامية والصينية المبسّطة واليابانية والعربية والهندية والأفريكانية. وعند عدم توفر قالب بلغة المستلِم، يعود البريد إلى الإنجليزية.

تُحدَّد اللغة من تفضيل المستلِم المخزَّن عند الإرسال. ويمكن أن يأتي هذا التفضيل من عدة مصادر:

• التسجيل وإنشاء الحساب يُلتقط من اللغة التي اختارها المستخدم على شاشات تسجيل الدخول المُستضافة.
• صفحة المستخدمين في البوابة يضبطها المسؤول عند إنشاء مستخدم أو تعديله.
• التزويد عبر SCIM: يُحدَّد من preferredLanguage (أو locale) الخاص بمزوّد الهوية عند مزامنة المستخدمين عبر SCIM.
• صفحة الحساب ذاتية الخدمة يختارها المستخدم بنفسه عبر /login/account.

مزوّدو البريد الإلكتروني

هوية المرسِل

بريد المرسِل واسمه مشتركان عبر جميع أوضاع المزوّدين. بريد المرسِل مطلوب لمزوّدَي نطاق مخصص (Resend) وSMTP مخصص، ويعود اسم المرسِل إلى اسم التطبيق في العلامة التجارية عند تركه فارغاً.

نطاق Resend المخصص

تحقق من نطاق الإرسال الخاص بك مع Resend مرة واحدة، ثم استخدمه كعنوان "من" لهذا المستأجر. تُعرض سجلات DNS (SPF وDKIM) في لوحة نطاق إرسال مخصص ضمن الإعدادات ← البريد الإلكتروني، ويتحقق منها Resend عند النقر على <strong>التحقق من الإثبات</strong>.

SMTP مخصص

أحضر خادم SMTP الخاص بك، وهو مفيد لعمليات الترحيل الداخلية، أو للمزوّدين غير المشمولين بـ Resend، أو للتثبيت التنظيمي.

نطاق إرسال مخصص

عند استخدام مزوّد نطاق مخصص (Resend)، يمكنك تسجيل نطاقك الخاص كي تصدر الرسائل من علامتك التجارية (مثل [email protected]) بدلاً من @authagonal.io.

1. اذهب إلى الإعدادات ← البريد الإلكتروني واختر مزوّد نطاق مخصص (Resend).
2. أدخل اسم نطاقك وانقر على تسجيل النطاق.
3. أضف سجلات DNS المعروضة (DKIM وSPF ومسار الإرجاع) إلى DNS الخاص بنطاقك.
4. انقر على التحقق من الإثبات، وبمجرد انتشار DNS (عادةً خلال 1 إلى 10 دقائق)، ستتغير حالة النطاق إلى مُتحقَّق منه.

الاختبار

استخدم زر إرسال بريد اختباري في الإعدادات ← البريد الإلكتروني للتحقق من إعدادك. سيُرسَل بريد اختباري إلى عنوان بريد المسؤول الخاص بك باستخدام الإعدادات المحفوظة حالياً.

سجل التدقيق

يوفّر سجل التدقيق سجلاً للقراءة فقط لجميع الإجراءات الإدارية التي تُنفَّذ على المستأجر الخاص بك. يُلتقط كل تغيير يُجرى عبر البوابة أو API مع سياقه الكامل، ما يمنحك مساراً متكاملاً للامتثال واستكشاف الأخطاء وإصلاحها.

أعمدة السجل

الإجراءات المتتبَّعة

تُسجَّل الإجراءات الإدارية التالية في سجل التدقيق:

يوفّر سجل التدقيق سجلاً متكاملاً لجميع الإجراءات الإدارية

النسخ الاحتياطي

ينشئ Authagonal نسخاً احتياطية من بيانات المستأجر الخاص بك تلقائياً وفق جدول يعمل كل ساعة. تشمل النسخ الاحتياطية جميع المستخدمين والمجموعات والأدوار والعملاء واتصالات SSO ورموز SCIM والعلامة التجارية والإعدادات. ويمكنك عرض سجل النسخ الاحتياطي وتنزيل أحدث نسخة احتياطية كاملة من صفحة النسخ الاحتياطي.

كيف يعمل النسخ الاحتياطي

• مرة يوميًا تُدمج النسخ التزايدية التي تُجرى كل ساعة في نسخة احتياطية كاملة جديدة، وفي أيام الأحد تُدمج النسخ الكاملة اليومية في نسخة احتياطية أسبوعية. ويُحتفظ بسبع نسخ يومية وأربع نسخ أسبوعية.
• تُجرى النسخ الاحتياطية التزايدية كل ساعة، وتلتقط فقط الصفوف التي تغيّرت منذ آخر نسخة احتياطية.
• تُخزَّن النسخ الاحتياطية في Azure Blob Storage بالهوية المُدارة نفسها التي يستخدمها المستأجر الخاص بك.
• تُتتبَّع السجلات المحذوفة عبر علامات الحذف وتُدرَج في النسخ الاحتياطية اكتمالاً للتدقيق.

تنزيل النسخ الاحتياطية

انقر على تنزيل الأحدث للحصول على ملف ZIP يحتوي على أحدث نسخة احتياطية كاملة مدمجة مع جميع النسخ الاحتياطية التزايدية اللاحقة. يُصدَّر كل جدول كملف JSONL (كائن JSON واحد لكل سطر).

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

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

كيف يعمل

عند إنشاء مستخدم، يستدعي Authagonal عنوان رد النداء الخاص بتطبيق التزويد لديك باستخدام نمط TCC (Try/Confirm/Cancel). يجب أن يوافق كل تطبيق في مرحلة Try قبل تثبيت أي منها، بحيث يمكن لعدة أنظمة تابعة أن تتفق، أو أن يعترض أحدها، دون ترك حسابات نصف مُنشأة.

متى يعمل التزويد

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

طلب Try

يرسل Authagonal طلب POST بهذا الـ JSON إلى <code>{callbackUrl}/try</code>. والحقول التي لا قيمة لها تُحذف بدلًا من إرسالها بقيمة null.

الحالة الشائعة التي يجدر التخطيط لها هي وصول مستخدم عبر SSO: ليست لديه مؤسسة بعد، ويخبرك federated_connection بأي عميل من عملائك جاء منه.

{
  "transactionId": "8f14e45fceea167a5a36dedd4bea2543",
  "userId": "0f6b1c8e-3d2a-4f51-9e77-2c1a4b5d6e7f",
  "email": "[email protected]",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "customAttributes": {
    "federated_connection": "acme-okta"
  }
}

استجابة Try

يردّ تطبيقك بالرمز 200 وبمحتوى JSON. وهذا المحتوى ليس مجرد إقرار: فهو الطريقة التي يخصّص بها التطبيق التابع المؤسسة والسمات التي تنتهي إلى رموز المستخدم.

{
  "approved": true,
  "organizationId": "org_acme",
  "customAttributes": { "org_role": "member" }
}

وسم المستخدمين بالمؤسسة الصحيحة

حدّد المؤسسة هنا، في مكان واحد، بدلًا من تحديدها عند كل مسار إنشاء. يحمل مستخدم SSO الحقل federated_connection، الذي يحدّد الاتصال الذي وثّق هويته وبالتالي يحدّد العميل، ويظل صحيحًا عندما يوحّد عميل واحد عدة نطاقات بريد. أما المستخدم المدعو فلا اتصال له، لذا طابقه بالدعوة التي أصدرتها. ويصل كلا المسارين إلى /try قبل وجود المستخدم، فتغطيهما قطعة منطق واحدة ولا توجد قاعدتان قد تتباعدان.

// POST {callbackUrl}/try
app.post('/provisioning/try', async (req, res) => {
  const { email, customAttributes } = req.body;

  // An SSO user carries the connection that vouched for them. That is the
  // customer, and it stays right when one customer has several domains.
  const connection = customAttributes?.federated_connection;

  const org = connection
    ? await orgByConnection(connection)
    : await orgByPendingInvite(email);

  if (!org) return res.json({ approved: false, reason: 'No organization for this user' });

  // Stamped on the user and emitted as org_id on every token from now on.
  res.json({ approved: true, organizationId: org.id });
});

إضافة تطبيق تزويد

لإضافة تطبيق تزويد، قدّم اسم التطبيق وعنوان URL لاستدعاء الإرجاع ومفتاح API اختياريًا ومهلة Try اختيارية (بالثواني، القيمة الافتراضية 60، والنطاق من 5 إلى 300، بينما يستخدم Confirm وCancel مهلة قصيرة ثابتة). يُرسَل مفتاح API كرمز Bearer في ترويسة Authorization لكل طلب خطاف ويب، ما يتيح لتطبيقك مصادقة الطلبات الواردة من Authagonal.

الاختبار

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

اختبر تطبيقات التزويد للتحقق من تسليم خطاف الويب ومعالجة الاستجابة

حدود الخطة

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

الفريق

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

قائمة المسؤولين

تعرض قائمة المسؤولين اسم كل عضو في الفريق وعنوان بريده الإلكتروني ودوره وتاريخ إضافته. ويظهر مؤشر "أنت" بجوار صف المستخدم الحالي كي يسهل عليك تمييز حسابك الخاص.

دعوة المسؤولين

لدعوة عضو جديد في الفريق، قدّم عنوان بريده الإلكتروني واسمه ودوره. سيتلقى بريدًا إلكترونيًا يحتوي على رابط لتعيين كلمة مروره وتفعيل حسابه، ويبقى الرابط صالحًا لمدة 7 أيام.

حقول الدعوة

تُنشئ دعوات المسؤولين حسابًا معلّقًا وترسل إلى المدعو رابط تفعيل عبر البريد الإلكتروني.

إزالة المسؤولين

يمكن لمالك المستأجر النقر على إزالة بجوار أي عضو في الفريق لإلغاء صلاحية وصوله. يظهر مربع حوار للتأكيد قبل إتمام الإزالة. ولا يمكنك إزالة نفسك، ويحتفظ المستأجر دائمًا بمالكه.

إدارة مسؤولي البوابة من صفحة الفريق

الدعم

افتح تذكرة دعم مع فريق Authagonal دون مغادرة البوابة. كل تذكرة هي محادثة مترابطة، كي تبقى أنت وفريقنا على الصفحة نفسها من أول إبلاغ حتى الحل.

تذاكرك

تعرض صفحة الدعم كل تذكرة طرحتها، مع ترتيب الأحدث نشاطاً أولاً. استخدم شارة الحالة لترى بلمحة ما الذي ينتظر ردك وما الذي ينتظر ردنا.

تذاكر الدعم الخاصة بك مع الموضوع والحالة والأولوية وآخر نشاط

• يعرض كل صف الموضوع والحالة الحالية (مفتوحة، أو قيد الانتظار، أو محلولة، أو مغلقة) والأولوية ووقت آخر نشاط.
• انقر على تذكرة جديدة لفتح واحدة، ثم امنحها موضوعاً وأولوية ورسالتك الأولى.
• تسهّل شارات الحالة المُرمَّزة بالألوان مسح القائمة بحثاً عن التذاكر التي تحتاج إلى انتباهك.

سلسلة التذكرة

يعرض فتح التذكرة المحادثة كاملةً. تُنشَر الردود بالترتيب، وتظهر الرسائل الجديدة من فريقنا دون إعادة تحميل الصفحة.

سلسلة تذكرة بينك وبين فريق Authagonal

• تُعرَض الرسائل المترابطة بينك وبين فريق Authagonal بترتيب زمني.
• رُدّ ضمن السلسلة وأرفق ملفات لمشاركة السجلات أو لقطات الشاشة أو الإعدادات.
• تتحدّث السلسلة مباشرةً، فيظهر رد فريقنا فور إرساله.
• وإذا رددت على بريد الإشعار بدلاً من ذلك، تُدرَج رسالتك في السلسلة تلقائياً.

مكتب دعم لمستخدميك

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

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

تفعيله

افتح دعم العملاء في البوابة، وانتقل إلى تبويب الإعدادات فيه، وشغّل خيار تفعيل دعم العملاء. هذا التبويب متاح للمالكين والمسؤولين. ولا شيء يظهر لمستخدميك حتى تفعل ذلك.

ما يراه مستخدموك

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

ومع تفعيل التذاكر المجهولة، يظل بإمكان من لا يستطيع تسجيل الدخول فتح واحدة. فيقدّم عنوان بريد إلكتروني ورسالته، ويستعيد رابطًا خاصًا بالمحادثة. وهذا الرابط هو الطريق الوحيد للدخول، فعامله معاملة بيانات الاعتماد: فهو غير قابل للتخمين، وكل من يملكه يستطيع قراءة تلك السلسلة الواحدة والرد عليها.

صندوق وارد المشغّلين

يجيب فريقك من دعم العملاء في القائمة الجانبية للبوابة. وهو مكان منفصل عن تذاكرك الخاصة معنا، ومتاح لدور tenant:support وما فوقه، فيمكنك منح موظف دعم صلاحية الوصول إلى المكتب دون منحه بقية البوابة.

يكتب المستخدمون بلغتهم

تُخزَّن التذكرة باللغة التي كتبها بها المستخدم، ويقرؤها كل شخص في السلسلة بلغته هو. فيرى موظف الدعم لديك الرسالة مترجمةً إلى لغة بوابته، ويرى المستخدم ردّك مترجمًا إلى لغته، ويُحفظ النص الأصلي دائمًا إلى جانبها. وتُكتشف اللغة من الرسالة الأولى وتُثبَّت على التذكرة. وتُحسب الترجمات مرة واحدة لكل لغة ثم يُعاد استخدامها، فلا تعيد السلسلة الطويلة ترجمة نفسها.

المناطق الزمنية

تسجّل التذكرة المنطقة الزمنية التي فتحها المستخدم منها. وعندئذٍ تعرض كل رسالة توقيته المحلي بجوار توقيتك، فيُقرأ ردٌّ في الساعة 14:32 على أنه الساعة 02:32 التي كانها فعلًا لدى من ينتظره. ولا يُعرض شيء حين تكون المنطقة الزمنية مجهولة، كتذكرة وصلت عبر البريد الإلكتروني، أو حين تطابق منطقتك.

خطافات الويب

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

الاستيراد والترحيل

رحّل نظام هوية قائماً إلى مستأجر Authagonal الخاص بك. يُدعم مصدران، Duende IdentityServer (قاعدة بيانات SQL Server) وAuth0 (Management API). ويُجري كلٌّ منهما معاينة للقراءة فقط لتراجع بدقة ما الذي سيُنسخ قبل الالتزام.

الاستيراد من Duende IdentityServer

رحّل العملاء والنطاقات والمستخدمين والأدوار من قاعدة بيانات SQL Server قائمة لـ Duende IdentityServer إلى مستأجر Authagonal الخاص بك. يُجرى الاستيراد على مرحلتين، المعاينة ثم الالتزام، بحيث يمكنك مراجعة ما سيُنسخ قبل إجراء أي تغييرات.

ما الذي يُستورد

يقرأ أداة الاستيراد من جدول ConfigurationDb الخاص بـ Duende ومن جداول ASP.NET Identity، ويكتب الصفوف المُطابَقة في مستأجرك. أما العناصر قصيرة العمر مثل المنح المُخزّنة ورموز الأجهزة ومفاتيح التوقيع فيُتجاوز عنها.

المعاينة قبل الالتزام

الصق سلسلة اتصال ConfigurationDb / IdentityDb الخاصة بـ Duende ثم انقر تشغيل المعاينة. تفتح المعاينة اتصالاً للقراءة فقط وتُحصي كل صف سيُستورَد. ولا تحدث أي عمليات كتابة.

• أعداد الكيانات للعملاء والنطاقات والمستخدمين والأدوار وإسنادات الأدوار.
• تحذيرات التعارض عندما يحتوي المستأجر الهدف بالفعل على عملاء (يُكتب فوق العملاء ذوي ClientIds المطابقة)، أو أدوار، أو نطاقات (يُتجاوز عن ذات الأسماء المطابقة).
• تحذيرات حول الجداول غير المعروفة والأعمدة غير المُطابَقة لتعرف ما الذي سيُسقَط.

لوحة المعاينة مع الأعداد والتحذيرات

تجزئات كلمات المرور

يخزّن Duende كلمات المرور باستخدام ASP.NET Identity V3 (PBKDF2). يتحقق PasswordHasher الخاص بـ Authagonal من هذا التنسيق مباشرةً ويعيد تجزئته إلى التنسيق الأصلي عند أول تسجيل دخول ناجح، فيحتفظ المستخدمون بكلمات مرورهم الحالية دون الحاجة إلى عملية إعادة تعيين.

التوفيق بين معرّفات المستخدمين

إذا كان لدى مستخدم موجود بالفعل في هذا المستأجر نفس البريد الإلكتروني لسجلّ وارد، فإن الاستيراد يُدوّر قيمة userId الخاصة بذلك الحساب إلى sub المصدر قبل الاستيراد، بحيث تُرفَق الأدوار وعمليات تسجيل الدخول والمطالبات المستوردة بالحساب الموجود، وتستمر التطبيقات التي تشير إلى المستخدم بالفعل عبر sub المصدر الخاص به في العمل بعد التحويل. تُحفَظ كلمة المرور والملف الشخصي الحاليان للحساب؛ وتُدمج أدوار المصدر فوقها. تسرد المعاينة كل حساب سيجري التوفيق بشأنه قبل الالتزام.

تشغيل الاستيراد

انقر بدء الاستيراد بعد مراجعة المعاينة. تكتب مرحلة الالتزام العملاء والنطاقات والمستخدمين والأدوار ومراجع تسجيلات الدخول الخارجية في مخازن مستأجرك. ويُكتب فوق العملاء ذوي clientId المطابق، بينما يُتجاوز عن الصفوف ذات scope name أو email أو role name المطابق، فأداة الاستيراد آمنة لإعادة التشغيل.

ما الذي لا يُستورد

• المنح المُخزّنة ورموز الأجهزة والجلسات على جانب الخادم، عناصر قصيرة العمر تُعاد إنشاؤها تلقائياً.
• مفاتيح التوقيع، يُصدر Authagonal مفاتيحه الخاصة لكل مستأجر.
• الأعمدة والجداول المخصصة، أي شيء خارج المخطط القياسي لـ Duende يظهر كتحذير لتعرف أن البيانات قد أُسقطت.
• العملاء المعطّلون، يُستوردون بحالة معطّلة؛ أعد تفعيلهم من صفحة العملاء عند الاستعداد.

الاستيراد من Auth0

اربط Authagonal بـ Management API الخاص بمستأجر Auth0 لديك وانقل تطبيقاتك وواجهات API والأدوار والمستخدمين واتصالات المؤسسات. تُحفظ معرّفات المستخدمين والتطبيقات المستوردة، فتظل مراجع sub وclient_id الحالية قابلة للحلّ بعد التحويل.

ما الذي ستحتاج إليه

أنشئ تطبيق Machine-to-Machine في Auth0 مصرّحاً له باستخدام Management API، مع منحه نطاقات القراءة هذه: read:users، read:clients، read:resource_servers، read:roles، read:connections، read:client_grants. الصق نطاقه ومعرّف العميل وسرّ العميل في نموذج الاستيراد، فهي تُستخدم للاستيراد فقط.

ما الذي يُستورد

كلمات المرور

لا يُعيد Management API الخاص بـ Auth0 تجزئات كلمات المرور أبداً. إذا كان لديك تصدير كلمات المرور المجمّع المدعوم من فريق Auth0 (NDJSON)، فقدّمه، إذ تُستورد تجزئات bcrypt كما هي ويحتفظ مستخدموك بكلمات مرورهم دون إعادة تعيين. كما يحمل ذلك الملف مجموعة مستخدميك الكاملة، متجاوزاً حدّ سرد 1000 مستخدم في واجهة API لدى Auth0. وبدونه، يُستورد المستخدمون كملفات شخصية ويضبطون كلمة مرور جديدة عند أول تسجيل دخول.

مرجع API

يوفّر كل مستأجر خادم OIDC متوافقًا مع المعايير على https://{slug}.authagonal.io. تتبع جميع نقاط النهاية مواصفات OAuth 2.0 وOpenID Connect. يغطّي هذا المرجع كل نقطة نهاية قد يحتاج تطبيقك إلى التفاعل معها.

تدفّق رمز التفويض مع PKCE

اكتشاف OIDC وJWKS

يتيح مستند الاكتشاف لمكتبات عميل OIDC ضبط نفسها تلقائيًا. لا حاجة إلى أي مصادقة لأيٍّ من نقطتي النهاية.

GET /.well-known/openid-configuration

تُعيد مستند تكوين موفّر OpenID. تتضمّن الاستجابة كل البيانات الوصفية التي يحتاجها عميلك للتفاعل مع هذا المستأجر.

GET /.well-known/openid-configuration/jwks

تُعيد مجموعة مفاتيح الويب JSON المستخدَمة للتحقق من تواقيع الرموز. تحتوي الاستجابة على مصفوفة keys تضم مفاتيح EC P-256 العامة (تُوقَّع الرموز بـ ES256)، يتضمّن كل منها الحقول kty (EC) وuse وkid وalg وcrv وx وy.

curl https://acme.authagonal.io/.well-known/openid-configuration

نقطة نهاية التفويض

GET /connect/authorize

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

استجابة النجاح: إعادة توجيه 302 إلى redirect_uri مع معاملي الاستعلام code وstate.

استجابة الخطأ: إعادة توجيه 302 مع معاملات الاستعلام error وerror_description وstate.

طلبات التفويض المدفوعة (PAR)

RFC 9126. بدلًا من وضع كل معاملات التفويض على عنوان URL، يرسل عميلك طلب POST بها إلى /connect/par مع مصادقة العميل المعتادة ويستردّ قيمة request_uri مبهمة قصيرة العمر. ثم يزور المتصفّح /connect/authorize?client_id=...&request_uri=...، فلا يصل أي شيء آخر إلى سجل المتصفّح أو سجلات الخادم أو ترويسات Referer، ويكون الخادم قد تحقّق بالفعل من سلامة المعاملات تحت مصادقة العميل.

POST /connect/par

مصادقة العميل هي نفسها المستخدَمة في /connect/token: مصادقة HTTP الأساسية باستخدام client_id/client_secret، أو بيانات اعتماد مُرمّزة في النموذج. ينشر العملاء العامون دون كلمة سر. يحمل النص نفس المعاملات التي ترسلها عادةً إلى /connect/authorize؛ أما request_uri نفسها فمرفوضة (تسلسل PAR محظور بموجب §2.1 من المواصفة). تُعيد 201 Created.

الاستجابة

في طلب المتابعة GET /connect/authorize?client_id=…&request_uri=…، تُسحَب جميع المعاملات الأخرى من الحمولة المدفوعة ويُتجاهَل أي معاملات استعلام إضافية. يجب أن يطابق client_id في استدعاء التفويض العميل الذي دفع الطلب. وبمجرد استهلاك قيمة request_uri (أو انقضاء expires_in)، تُزال من المخزن.

# 1. Push parameters (server returns request_uri + expires_in)
curl -X POST https://acme.authagonal.io/connect/par \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "response_type=code" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "scope=openid profile email" \
  -d "state=$(openssl rand -hex 16)" \
  -d "code_challenge=YOUR_CODE_CHALLENGE" \
  -d "code_challenge_method=S256"

# 2. Send the user to /authorize with only client_id + request_uri
# https://acme.authagonal.io/connect/authorize?client_id=my-app&request_uri=urn:ietf:params:oauth:request_uri:abc123...

نقطة نهاية الرموز

POST /connect/token

تبادل بيانات الاعتماد بالرموز. يجب أن تستخدم الطلبات Content-Type: application/x-www-form-urlencoded. يمكن توفير مصادقة العميل عبر مصادقة HTTP الأساسية (Authorization: Basic base64(client_id:client_secret)) أو بصفتها معاملات في نص النموذج (client_id + client_secret).

منح رمز التفويض

منح رمز التحديث

منح بيانات اعتماد العميل

منح رمز الجهاز

استجابة الرمز:

curl -X POST https://acme.authagonal.io/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "client_id=my-app" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

نقطة نهاية UserInfo

GET /connect/userinfo

تُعيد مطالبات حول المستخدم المُصادَق عليه. تتطلّب رمز وصول صالحًا يحمل نطاق openid.

curl https://acme.authagonal.io/connect/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

فحص الرموز (RFC 7662)

POST /connect/introspect

يتحقّق من رمز ويعيد بياناته الوصفية. يتطلّب بيانات اعتماد العميل (مصادقة Basic أو معاملات في نص النموذج).

استجابة الرمز النشط:

استجابة الرمز غير النشط: { "active": false }

curl -X POST https://acme.authagonal.io/connect/introspect \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_OR_REFRESH_TOKEN"

إبطال الرموز (RFC 7009)

POST /connect/revocation

يُبطل رمزًا أُصدِر مسبقًا. يتطلّب بيانات اعتماد العميل.

تُعيد نقطة النهاية دائمًا 200 OK، حتى للرموز غير الصالحة أو المُبطَلة بالفعل، وفقًا لمواصفة RFC 7009.

تفويض الأجهزة (RFC 8628)

POST /connect/deviceauthorization

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

الاستجابة:

تدفّق الموافقة: يزور المستخدم verification_uri، ويُدخل user_code، ويوافق على الطلب. وفي غضون ذلك، يستعلم الجهاز من نقطة نهاية الرموز باستخدام device_code.

رموز أخطاء الاستعلام المتكرّر:

curl -X POST https://acme.authagonal.io/connect/deviceauthorization \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-cli" \
  -d "scope=openid profile email"

إنهاء الجلسة / تسجيل الخروج

GET POST /connect/endsession

يسجّل خروج جلسة المستخدم الحالية، ويُخطر كل عميل لديه عنوان URI مسجّل لتسجيل الخروج عبر القناة الخلفية أو الأمامية، ويُبطل المنح المرتبطة بتلك الجلسة. وبدون id_token_hint يطابق الجلسة الحالية، يُطلب من المستخدم أولًا تأكيد تسجيل الخروج.

إذا تم توفير قيمة post_logout_redirect_uri صالحة وطابقت عنوان URI مسجّلًا، فسيتلقّى المستخدم إعادة توجيه 302. وإلا فستؤكّد استجابة JSON أن الجلسة قد أُنهيت.

مرجع API لـ SCIM 2.0

يدعم Authagonal بروتوكول SCIM 2.0 لتزويد المستخدمين والمجموعات تلقائيًا. ويمكن لموفّري الهوية مثل Okta وAzure AD وOneLogin استخدام هذا الـ API للحفاظ على مزامنة مستأجر Authagonal الخاص بك مع دليل شركتك.

عنوان URL الأساسي: https://{slug}.authagonal.io/scim/v2

المصادقة: تتطلّب جميع الطلبات رمز Bearer. أنشئ رمز SCIM في البوابة في صفحة SCIM: اختر العميل الذي يزوّده موفّر الهوية لديك، ثم إنشاء رمز.

الترويسات الشائعة:

تقبل نقاط نهاية القوائم count (القيمة الافتراضية 100، والحد الأقصى 200، و0 يُعيد الإجمالي فقط) والتصفية عبر معامل filter (مثل userName eq "[email protected]"). تُقسَّم صفحات المستخدمين باستخدام cursor: مرّر nextCursor من الاستجابة السابقة. وتقبل المجموعات إما startIndex (يبدأ من 1) أو cursor.

المستخدمون

GET /scim/v2/Users: سرد المستخدمين مع تقسيم اختياري إلى صفحات وتصفية.

GET /scim/v2/Users/{id}: الحصول على مستخدم واحد عبر مُعرّف مستخدم Authagonal الخاص به.

POST /scim/v2/Users: إنشاء مستخدم جديد. تُعيد 201 Created.

PUT /scim/v2/Users/{id}: استبدال كامل لمورد المستخدم. يجب توفير جميع الحقول.

PATCH /scim/v2/Users/{id}: تحديث جزئي باستخدام SCIM PatchOp.

DELETE /scim/v2/Users/{id}: يحذف المستخدم حذفًا ناعمًا (يعطّل الحساب ويُبطل جميع الرموز). تُعيد 204 No Content.

curl -X POST https://acme.authagonal.io/scim/v2/Users \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "[email protected]",
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "displayName": "Jane Smith",
    "active": true,
    "externalId": "ext-12345"
  }'

المجموعات

GET /scim/v2/Groups: سرد جميع المجموعات مع تقسيم اختياري إلى صفحات وتصفية.

GET /scim/v2/Groups/{id}: الحصول على مجموعة واحدة عبر المُعرّف، بما في ذلك قائمة أعضائها.

POST /scim/v2/Groups: إنشاء مجموعة جديدة. تُعيد 201 Created.

PUT /scim/v2/Groups/{id}: استبدال كامل لمورد المجموعة (بما في ذلك قائمة أعضائها).

PATCH /scim/v2/Groups/{id}: تحديث جزئي: إضافة أعضاء أو إزالتهم أو استبدالهم، أو تغيير displayName وexternalId.

DELETE /scim/v2/Groups/{id}: يحذف المجموعة حذفًا نهائيًا. تُعيد 204 No Content.

curl -X PATCH https://acme.authagonal.io/scim/v2/Groups/GROUP_ID \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "add",
        "path": "members",
        "value": [
          { "value": "USER_ID_1" },
          { "value": "USER_ID_2" }
        ]
      }
    ]
  }'

API البوابة (الأتمتة)

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

عنوان URL الأساسي: https://portal-api.<your-domain>/api/v1. تُصادَق الطلبات برمز وصول من نوع Bearer، ويُؤخذ المستأجر من الرمز لا من عنوان URL.

إنشاء بيانات اعتماد لـ API

في البوابة، افتح العملاء ← إنشاء بيانات اعتماد API، واختر مستوى وصول، وامنحها اسمًا. ينشئ Authagonal عميل OAuth من نوع client_credentials مهيأً للعمل مع API البوابة، ويعيد معرّف عميل وسرًّا.

مستويات الوصول

الحصول على رمز

بادل بيانات الاعتماد برمز وصول عند نقطة نهاية الرمز الخاصة بمستأجرك، أي https://<your-tenant>.<your-domain>/connect/token، ثم أرسل الرمز كترويسة Bearer إلى API البوابة. تظل الرموز صالحة لمدة ساعة واحدة.

# 1. Exchange the credential for an access token (your tenant's token endpoint)
curl -X POST https://acme.authagonal.io/connect/token \
  -d grant_type=client_credentials \
  -d client_id=api-3f2a... \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope=tenant:admin

# Response: { "access_token": "ey...", "token_type": "Bearer", "expires_in": 3600 }

# 2. Call the Portal API with the access token
curl https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN"

نقاط النهاية

جميع المسارات نسبية إلى عنوان URL الأساسي وتتطلب رمز وصول من نوع Bearer. النطاق المذكور بجانب كل مجموعة هو الحد الأدنى لمستوى وصول بيانات الاعتماد الذي تحتاجه. يختلف التقسيم إلى صفحات حسب المورد: المستخدمون وسجل التدقيق يقبلان count (من 1 إلى 200، والقيمة الافتراضية 50) وafter المضبوط على continuationToken من الاستجابة السابقة؛ والمجموعات تقبل startIndex وcount؛ والمنظمات تقبل limit وcursor؛ أما العملاء والأدوار والنطاقات فتُعيد كل الصفوف.

GET/api/v1/clientsسرد عملاء OAuth.

GET/api/v1/clients/{id}الحصول على عميل واحد بمعرّفه.

POST/api/v1/clientsإنشاء عميل. يعيد 201 مع سجل العميل. لا تُعاد الأسرار هنا: أنشئ سرًّا عبر POST /api/v1/clients/{clientId}/secrets، الذي يعرضه مرة واحدة.

PUT/api/v1/clients/{id}تحديث عميل (عناوين إعادة التوجيه URIs، أنواع المنح، فترات صلاحية الرموز، متطلبات PKCE/PAR).

DELETE/api/v1/clients/{id}حذف عميل.

POST/api/v1/clients/api-credentialإصدار بيانات اعتماد API البوابة من آلة إلى آلة.

GET/api/v1/usersسرد المستخدمين. يدعم count و search (بادئة البريد الإلكتروني أو الاسم) و organizationId للتصفية على مؤسسة واحدة و after للترقيم بالمؤشر.

GET/api/v1/users/countإجمالي عدد المستخدمين للمستأجر.

GET/api/v1/users/stats/mfaإحصائيات تسجيل MFA.

GET/api/v1/users/{id}الحصول على مستخدم واحد.

POST/api/v1/users/inviteدعوة مستخدم عبر البريد الإلكتروني. يُنشئ حسابًا معلّقًا ويرسل بالبريد رابطًا يعيّن فيه المدعو كلمة مروره بنفسه. ويضيف organizationId وorganizationRoles الاختياريان أيضًا عضوية في منظمة.

PUT/api/v1/users/{id}تحديث مستخدم (الملف الشخصي، البريد الإلكتروني، isActive، emailConfirmed، organizationId). يتطلب تغيير البريد الإلكتروني أو emailConfirmed الدور tenant:admin.

DELETE/api/v1/users/{id}حذف مستخدم.

GET/api/v1/users/{id}/mfaGet a user's enrolled MFA methods.

DELETE/api/v1/users/{id}/mfaReset a user's MFA enrollment. Needs tenant:admin.

GET/api/v1/rolesسرد الأدوار.

POST/api/v1/rolesإنشاء دور.

DELETE/api/v1/roles/{id}حذف دور.

POST/api/v1/roles/assignتعيين دور لمستخدم.

POST/api/v1/roles/unassignإزالة دور من مستخدم.

GET/api/v1/groupsسرد المجموعات.

GET/api/v1/groups/{id}الحصول على مجموعة مع أعضائها.

POST/api/v1/groupsإنشاء مجموعة.

POST/api/v1/groups/{id}/membersإضافة أعضاء إلى مجموعة.

DELETE/api/v1/groups/{groupId}/members/{userId}إزالة عضو من مجموعة.

DELETE/api/v1/groups/{id}حذف مجموعة.

GET/api/v1/group-role-mappingsسرد تعيينات المجموعات إلى الأدوار (الأدوار الممنوحة عند إصدار الرمز بحسب عضوية المجموعة).

GET/api/v1/scopesسرد نطاقات API.

POST/api/v1/scopesإنشاء نطاق.

DELETE/api/v1/scopes/{name}حذف نطاق.

GET/api/v1/saml/connectionsسرد اتصالات SAML.

POST/api/v1/saml/connectionsإنشاء اتصال SAML.

DELETE/api/v1/saml/connections/{id}حذف اتصال SAML.

GET/api/v1/oidc/connectionsسرد اتصالات OIDC.

POST/api/v1/oidc/connectionsإنشاء اتصال OIDC.

DELETE/api/v1/oidc/connections/{id}حذف اتصال OIDC.

GET/api/v1/sso/domainsسرد النطاقات الموجَّهة إلى اتصالات SSO (اكتشاف نطاق الهوية الأصلي).

GET/api/v1/brandingالحصول على العلامة التجارية للمستأجر (الألوان، الشعار، اللغات المدعومة).

PUT/api/v1/brandingتحديث العلامة التجارية للمستأجر.

GET/api/v1/settingsالحصول على إعدادات المستأجر (خطافات الويب، التسجيل العام، سياسة الرموز).

PUT/api/v1/settingsتحديث إعدادات المستأجر.

POST/api/v1/settings/webhook-secret/regenerateتدوير سر توقيع خطاف الويب.

POST/api/v1/settings/test-emailإرسال بريد إلكتروني تجريبي باستخدام إعدادات البريد الإلكتروني الحالية.

GET/api/v1/custom-domainsسرد نطاقات تسجيل الدخول المخصصة وحالة التحقق منها.

POST/api/v1/custom-domainsإضافة نطاق مخصص.

POST/api/v1/custom-domains/{domain}/verifyتشغيل التحقق عبر DNS لنطاق مخصص.

DELETE/api/v1/custom-domains/{domain}إزالة نطاق مخصص.

GET/api/v1/email/domains/{domainId}جلب سجلات DNS لنطاق بريد إلكتروني للمُرسِل وحالة التحقق منه.

GET/api/v1/auditالاستعلام في سجل تدقيق المستأجر.

مثال: دعوة مستخدم

curl -X POST https://portal-api.authagonal.io/api/v1/users/invite \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }'

# 200 OK
# { "userId": "8f3a...", "email": "[email protected]" }

API المنظمات

تتطلب كل المسارات أدناه سياسة TenantAdmin وتقع تحت /api/v1/organizations ما لم يُذكر خلاف ذلك. راجع API البوابة لمعرفة كيفية إصدار بيانات اعتماد. مساران للقوائم مقسّمان بمؤشر: مرّر limit (الافتراضي 50، من 1 إلى 200) وnextCursor السابق كـ cursor؛ وتعيد { items, nextCursor }، والمؤشر الخاطئ هو 400 invalid_cursor. ويحمل كائن المنظمة قائمة domains للقراءة فقط.

شاشات تسجيل الدخول

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

تسجيل الدخول

• تدفق من خطوتين يبدأ بالبريد الإلكتروني: يُدخل المستخدم بريده الإلكتروني وينقر متابعة، ثم يظهر حقل كلمة المرور.
• تظهر أزرار الدخول الموحّد "المتابعة باستخدام {provider}" تلقائيًا عند وجود اتصالات SSO.
• روابط نسيت كلمة المرور وإنشاء حساب، ويمكن إظهار كلٍّ منها أو إخفاؤه.
• اختبار Cloudflare Turnstile اختياري لردع محاولات تسجيل الدخول الآلية.

يُتحكم بها من إدارة البوابة

• تضبط العلامة التجارية الشعار واللون واسم التطبيق والبريد الإلكتروني للدعم وCSS المخصص.
• إظهار أو إخفاء رابطي نسيت كلمة المرور والتسجيل (العلامة التجارية).
• تضيف اتصالات SSO أزرار الدخول الاجتماعي (صفحة SSO).
• مدة الجلسة وعتبات القفل (الإعدادات → الجلسة).

التسجيل

• يجمع الاسم الأول والأخير (اختياري) والبريد الإلكتروني وكلمة المرور.
• قائمة تحقق حيّة لسياسة كلمة المرور تتحدث أثناء كتابة المستخدم، فتتضح المتطلبات قبل الإرسال.
• اختبار Cloudflare Turnstile اختياري.
• رابط "تسجيل الدخول" للمستخدمين الذين لديهم حساب بالفعل.

يُتحكم بها من إدارة البوابة

• إظهار أو إخفاء رابط التسجيل (العلامة التجارية). ولإيقاف التسجيل كليًا، أوقف السماح بالتسجيل العام (الإعدادات → الجلسة).
• تتحكم سياسة كلمة المرور الخاصة بمستأجرك في قائمة التحقق.
• تنسّق العلامة التجارية الشاشة بأكملها.

نسيت كلمة المرور

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

يُتحكم بها من إدارة البوابة

• إظهار أو إخفاء رابط نسيت كلمة المرور (العلامة التجارية).
• يرسل توصيل البريد الإلكتروني الخاص بمستأجرك رسالة إعادة التعيين.
• تنسّق العلامة التجارية الشاشة بأكملها.

إعادة تعيين كلمة المرور

• حقلا كلمة المرور الجديدة وتأكيد كلمة المرور مع قائمة تحقق حيّة لكل قاعدة من المتطلبات.
• حالة واضحة لـ رابط غير صالح أو منتهي الصلاحية عندما لا يعود رمز إعادة التعيين صالحًا.
• حالة نجاح تؤكد تغيير كلمة المرور.

يُتحكم بها من إدارة البوابة

• تتحكم سياسة كلمة المرور الخاصة بمستأجرك في قائمة التحقق.
• تنسّق العلامة التجارية الشاشة بأكملها.

تحدي MFA

• مبدّل طرق بين تطبيق المصادقة ومفتاح المرور ورمز الاسترداد.
• حقل TOTP من 6 أرقام يُرسَل تلقائيًا بمجرد إدخال جميع الأرقام.
• إدخال رمز الاسترداد للمستخدمين الذين فقدوا الوصول إلى تطبيق المصادقة لديهم.
• زر مفتاح المرور للتحقق المدعوم بالعتاد.

يُتحكم بها من إدارة البوابة

• تُضبط سياسة MFA لكل تطبيق على حدة (العملاء → الأمان).
• أي مستخدم لديه عامل مسجَّل يُطالَب به دائمًا، بصرف النظر عن السياسة.

إعداد MFA

• يعرض حالة الطرق المسجَّلة ليعرف المستخدم ما هو مُعدّ بالفعل.
• إعداد تطبيق المصادقة عبر رمز QR، مع مفتاح يدوي بديل، وخطوة تأكيد.
• تسجيل مفتاح المرور للمصادقة المدعومة بالعتاد.
• إنشاء رموز الاسترداد لاستعادة الحساب.
• تخطٍّ اختياري عندما يكون MFA بالخدمة الذاتية لا إلزاميًا.

يُتحكم بها من إدارة البوابة

• تُضبط سياسة MFA لكل تطبيق على حدة، ويفرض الخيار إلزامي الإعداد عند تسجيل الدخول (العملاء → الأمان).
• تنسّق العلامة التجارية الشاشة بأكملها.

تفويض الجهاز

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

يُتحكم بها من إدارة البوابة

• فعّل منح رمز الجهاز على التطبيق (العملاء → النطاقات والمنح).
• اضبط مدة صلاحية رمز الجهاز (العملاء → الرموز).

الموافقة

• تعرض شعار العميل واسمه الطالب.
• قائمة لكل نطاق بعناوين ودّية وسهلة القراءة لكل إذن.
• زرّا السماح والرفض لمنح الوصول أو رفضه.
• تذييل تلميح الموافقة يشرح ما يعنيه القرار.

يُتحكم بها من إدارة البوابة

• فعّل طلب الموافقة لكل تطبيق على حدة (العملاء → عام).
• يأتي الشعار والاسم وعنوان URL من البيانات الوصفية الخاصة بالتطبيق نفسه.
• ترسم العلامة التجارية بطاقة الموافقة.

التطبيقات المتصلة (المنح)

• تسرد كل تطبيق فوّضه المستخدم، مع اسمه ونطاقاته وتاريخ المنح.
• إلغاء وصول تطبيق ما، مع خطوة تأكيد قبل نفاذ الإجراء.
• حالة فارغة ودّية عندما لا يكون المستخدم قد فوّض أي تطبيقات.

يُتحكم بها من إدارة البوابة

• تُملأ القائمة بـ التطبيقات التي تتطلب الموافقة.
• تنسّق العلامة التجارية الشاشة بأكملها.

الحساب

صفحة حساب مستضافة بالخدمة الذاتية على /login/account حيث يدير المستخدمون المسجَّلون ملفهم الشخصي ولغتهم المفضّلة، دون الحاجة إلى الوصول إلى البوابة.

• تحرير الاسم الأول والأخير والشركة والهاتف، ويُعرض عنوان البريد الإلكتروني للقراءة فقط.
• اختيار لغة مفضّلة من اللغات المدعومة، وتعاين الواجهة الاختيار فورًا وتحفظه عند الحفظ.
• تتحكم اللغة المحفوظة في الواجهة المستضافة للمستخدم وفي لغة الرسائل البريدية الإجرائية التي يتلقاها.

يُتحكم بها من إدارة البوابة

• تنسّق العلامة التجارية الشاشة بأكملها.
• اللغة المفضّلة ذاتها قابلة للتحرير من قبل المسؤول في صفحة المستخدمون بالبوابة.

تدفقات المصادقة

تغطي تدفقات المصادقة كيفية تفاعل المستخدمين النهائيين مع مستأجر Authagonal الخاص بك، أي تسجيل الدخول والتسجيل وإعادة تعيين كلمات المرور وإعداد MFA. تستخدم صفحة تسجيل الدخول المستضافة نقاط النهاية هذه، ويمكن استدعاؤها مباشرةً إن كنت تبني واجهة تسجيل دخول مخصصة.

تسجيل الدخول

POST /api/auth/login

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

نص الطلب:

{
  "email": "[email protected]",
  "password": "correct-horse-battery-staple"
}

استجابة النجاح:

استجابة طلب MFA: عندما يكون المستخدم قد سجّل MFA، تتضمن الاستجابة mfaRequired: true إلى جانب challengeId ومصفوفة methods تسرد طرق MFA المتاحة.

استجابة طلب إعداد MFA: عندما تكون سياسة MFA الخاصة بالتطبيق «مطلوبة» ولكن المستخدم لم يسجّل بعد، تتضمن الاستجابة mfaSetupRequired: true مع setupToken لتدفق التسجيل.

استجابات الخطأ:

فحص SSO: إذا كان نطاق البريد الإلكتروني للمستخدم لديه اتصال SSO مهيأ، تعيد نقطة نهاية تسجيل الدخول sso_required مع redirectUrl. ينبغي للعميل إعادة توجيه المستخدم إلى موفّر SSO.

قفل الحساب: بعد maxFailedAttempts من محاولات تسجيل الدخول الفاشلة المتتالية، يُقفل الحساب لمدة lockoutDurationMinutes. كلا القيمتين قابلتان للضبط في إعدادات المستأجر.

التسجيل

POST /api/auth/register

ينشئ حساب مستخدم جديدًا ويرسل بريد تحقق. وما دام خيار <strong>اشتراط بريد إلكتروني مُتحقَّق منه لتسجيل الدخول</strong> (الإعدادات &rarr; الجلسة) مفعّلًا، وهو الإعداد الافتراضي، يجب على المستخدم التحقق من بريده الإلكتروني قبل أن يتمكن من تسجيل الدخول.

نص الطلب:

{
  "email": "[email protected]",
  "password": "a-strong-password-here",
  "firstName": "Jane",
  "lastName": "Smith"
}

النجاح: 201 Created مع userId للحساب الجديد. التسجيل ببريد إلكتروني مستخدَم بالفعل يعيد 201 أيضًا: فنحن لا نكشف أبدًا ما إذا كان البريد الإلكتروني موجودًا (لمنع تعداد الحسابات)، وبدلًا من ذلك نُعلِم صاحب الحساب الحقيقي عبر البريد الإلكتروني.

استجابات الخطأ:

إعادة تعيين كلمة المرور

POST /api/auth/forgot-password

يطلب بريد إعادة تعيين كلمة المرور. تعيد نقطة النهاية دائمًا استجابة نجاح بصرف النظر عن وجود البريد الإلكتروني من عدمه، لمنع تعداد البريد الإلكتروني.

{
  "email": "[email protected]"
}

POST /api/auth/reset-password

يعيد تعيين كلمة مرور المستخدم باستخدام الرمز الوارد في رابط البريد الإلكتروني.

{
  "token": "RESET_TOKEN_FROM_EMAIL",
  "newPassword": "new-strong-password"
}

الآثار الجانبية لإعادة تعيين كلمة المرور بنجاح:

• يُعاد ضبط عدّاد محاولات تسجيل الدخول الفاشلة إلى صفر
• تُلغى جميع رموز التحديث الموجودة
• يُنشأ ختم أمان جديد (ما يُبطل جميع الجلسات الموجودة)

إعداد MFA والتحقق منه

يدعم Authagonal ثلاث طرق لـ MFA: TOTP (تطبيقات المصادقة)، وWebAuthn (مفاتيح الأمان والقياسات الحيوية)، ورموز الاسترداد ذات الاستخدام الواحد.

إعداد TOTP

POST /api/auth/mfa/totp/setup: يعيد <code>setupToken</code> وعنوان URI لبيانات رمز QR ومفتاح إدخال يدوي. يمسح المستخدم رمز QR بتطبيق المصادقة لديه (Google Authenticator، Authy، 1Password، وغيرها)، ثم يؤكد التسجيل.

POST /api/auth/mfa/totp/confirm: يؤكد تسجيل TOTP عبر إرسال <code>setupToken</code> الناتج عن الإعداد مع رمز مكوّن من 6 أرقام من تطبيق المصادقة.

{
  "setupToken": "SETUP_TOKEN_FROM_SETUP_RESPONSE",
  "code": "123456"
}

إعداد WebAuthn

POST /api/auth/mfa/webauthn/setup: يعيد خيارات إنشاء بيانات الاعتماد لـ WebAuthn API. يستدعي المتصفح navigator.credentials.create() بهذه الخيارات.

POST /api/auth/mfa/webauthn/confirm: يؤكد تسجيل WebAuthn عبر إرسال استجابة الإثبات من المتصفح.

رموز الاسترداد

POST /api/auth/mfa/recovery/generate: ينشئ 10 رموز استرداد من 10 أحرف تُستخدم مرة واحدة (بالتنسيق <code>XXXXX-XXXXX</code>). يمكن استخدام كل رمز مرة واحدة بالضبط لتجاوز MFA. يجب تسجيل تطبيق مصادقة أو مفتاح مرور أولًا.

التحقق من MFA

POST /api/auth/mfa/verify: يكمل تحدي MFA بعد تسجيل دخول ناجح بكلمة المرور.

حالة MFA

GET /api/auth/mfa/status: يعيد طرق MFA المسجَّلة حاليًا للمستخدم.

تدفق تسجيل الدخول عبر SSO

يدعم Authagonal اتصالات SSO القائمة على SAML 2.0 وعلى OIDC. يكتشف التوجيه القائم على النطاق تلقائيًا أي موفّر SSO يجب استخدامه بناءً على عنوان البريد الإلكتروني للمستخدم.

فحص SSO

GET /api/auth/[email protected]

تدفق SAML

يُعاد توجيه المستخدم إلى GET /saml/{connectionId}/login الذي يرسل طلب SAML AuthnRequest إلى موفّر الهوية. يصادق موفّر الهوية المستخدم ويرسل استجابة SAML إلى نقطة نهاية خدمة استهلاك التأكيد (ACS). يتحقق Authagonal من التأكيد، وينشئ المستخدم أو يحدّثه، ويوقّع ملف تعريف ارتباط للجلسة.

تتوفر البيانات الوصفية لـ SAML لتهيئة موفّر الهوية لديك على GET /saml/{connectionId}/metadata.

تدفق OIDC

يُعاد توجيه المستخدم إلى GET /oidc/{connectionId}/login الذي يعيد التوجيه إلى موفّر الهوية الأعلى مع PKCE. بعد مصادقة المستخدم، يبادل رد النداء عند /oidc/callback رمز التفويض، ويتحقق من رمز الهوية، وينشئ المستخدم أو يحدّثه.

التزويد في الوقت المناسب (JIT): يدعم تدفقا SAML وOIDC التزويد في الوقت المناسب، وهو معطّل افتراضيًا على كل اتصال (تفعيل الإنشاء التلقائي عند أول دخول). عندما يكون مفعّلًا ولم يكن المستخدم موجودًا بالفعل في المستأجر، يُنشأ تلقائيًا من مطالبات موفّر الهوية. وإن كان موجودًا، تُحدَّث سمات ملفه الشخصي لتطابق أحدث القيم من الموفّر.

Backend-for-Frontend (BFF)

يُبقي BFF رموز OAuth خارج المتصفّح تمامًا. فلا يحمل تطبيق الصفحة الواحدة لديك سوى ملف تعريف ارتباط جلسة من نوع httpOnly، بينما يتولى عميل سرّي على خادمك الخلفي تدفق OpenID Connect ويحتفظ بالرموز على جانب الخادم.

كل ما يستطيع تطبيق الصفحة الواحدة قراءته تستطيع البرمجة النصية عبر المواقع سرقته، ويشمل ذلك رمز وصول في الذاكرة ورمز تحديث في localStorage. كما أن تخزين الرموز في المتصفّح يحدّ من مدة صلاحيتها، لأن رمز تحديث طويل العمر في متناول النصوص البرمجية يمثّل خطرًا دائمًا. ولهذا السبب بالذات توصي بهذا النمط ممارسة IETF الفضلى الحالية OAuth 2.0 for Browser-Based Apps.

وفي المقابل تحصل على جلسة تبقى بعد إعادة تحميل الصفحة دون أي رمز في الأفق، وعلى تحديث للرموز يجري نيابةً عنك على جانب الخادم، وعلى إبطال فوري عبر تسجيل الخروج بالقناة الخلفية، وعلى وكيل مُصادَق عليه بحيث لا تضطر واجهة API لديك أبدًا إلى تحليل رمز كان بإمكان المتصفّح العبث به.

إنشاء العميل

في البوابة، افتح العملاء واختر إنشاء تطبيق BFF. أعطِه عنوان URL الأساسي الذي يُقدَّم منه تطبيقك، مثل https://app.acme.com، فيسجّل Authagonal نيابةً عنك عميلًا سرّيًا مضبوطًا على النحو الصحيح بدلًا من أن يتركك تركّبه بنفسك:

اربطه بخادمك الخلفي

بيئتا تشغيل مدعومتان وتتشاركان البروتوكول الأساسي نفسه: Authagonal.Bff لـ .NET و@authagonal/bff لـ Node، والأخيرة مزوّدة بمحوّلات لـ Express وNext.js. وجّه أيًّا منهما إلى القيم التي أعطتك إياها البوابة للتو. وتحتاج حزمة Node أيضًا إلى cookieSecret خاص بك، تستخدمه لتشفير ملفات تعريف الارتباط الخاصة بها.

// dotnet add package Authagonal.Bff
builder.Services.AddAuthagonalBff(o =>
{
    o.Authority    = "https://acme.authagonal.io";       // your tenant auth host
    o.ClientId     = builder.Configuration["Bff:ClientId"]!;
    o.ClientSecret = builder.Configuration["Bff:ClientSecret"]!;
    o.Scope        = ["openid", "profile", "email", "offline_access"];
    o.PostLogoutRedirectUri = "https://app.acme.com/";
});

// Trust X-Forwarded-Proto from your ingress. With no options, UseForwardedHeaders() changes nothing.
builder.Services.Configure<ForwardedHeadersOptions>(o =>
{
    o.ForwardedHeaders = ForwardedHeaders.XForwardedProto;
    o.KnownNetworks.Clear();
    o.KnownProxies.Clear();
});

var app = builder.Build();

app.UseForwardedHeaders();   // required behind a proxy or ingress, see the note below
app.MapAuthagonalBff();
app.MapFallbackToFile("index.html");   // your SPA
app.Run();

// npm install @authagonal/bff
import express from 'express';
import { authagonalBff } from '@authagonal/bff/express';

const app = express();

app.use(authagonalBff({
  authority: 'https://acme.authagonal.io',
  clientId: process.env.BFF_CLIENT_ID,
  clientSecret: process.env.BFF_CLIENT_SECRET,
  cookieSecret: process.env.BFF_COOKIE_SECRET,   // encrypts the session and login cookies
  scope: ['openid', 'profile', 'email', 'offline_access'],
  postLogoutRedirectUri: 'https://app.acme.com/',
}));

app.listen(8080);

نقاط النهاية

تُركَّب افتراضيًا تحت /bff. ويجب أن تُقدَّم من المصدر نفسه الذي يُقدَّم منه تطبيق SPA لديك، لأن ملف تعريف ارتباط الجلسة هو httpOnly ومقيَّد بالمصدر نفسه: ضعها خلف اسم المضيف نفسه بدلًا من نطاق API منفصل.

من المتصفّح

يجب أن يحمل كل طلب غير تنقّلي ترويسة ثابتة لمكافحة التزوير. وهي تحمي من تزوير الطلب عبر المواقع إلى جانب خاصية SameSite لملف تعريف الارتباط: فإرسال نموذج من موقع آخر لا يستطيع ضبط ترويسة مخصصة، لذا يُرفض أي طلب لا يحملها.

const me = await fetch('/bff/user', {
  headers: { 'X-Authagonal-Bff': '1' },
}).then(r => r.json());

if (!me.isAuthenticated) {
  // Navigate, do not fetch: this is a redirect to your identity provider.
  window.location.href = '/bff/login?returnUrl=' + encodeURIComponent(location.pathname);
}

سجّل الدخول والخروج عبر التنقّل، لا عبر الجلب: location.href = '/bff/login'. فهذه المسارات تجيب بإعادة توجيه إلى مزوّد الهوية لديك، وسلسلة إعادة التوجيه ليست شيئًا يستطيع fetch تتبّعه على نحو مفيد.

استدعاء واجهة API لديك

يستطيع BFF توجيه واجهة API لديك تحت مساره الأساسي وإرفاق رمز وصول الجلسة أثناء المرور. فيرسل المتصفّح ملف تعريف ارتباط، وتستقبل واجهة API لديك رمز حامل تتحقق منه كالمعتاد، ولا شيء من ذلك الرمز مرئي للصفحة ولا قابل للتزوير منها. سجّل وجهة فتصل الطلبات الموجَّهة إلى /bff/api/** إليها مُصادَقًا عليها. واترك القائمة فارغة فيُعطَّل الوكيل تمامًا.

o.Upstreams.Add(new BffUpstream
{
    Prefix        = "/orders",                        // matches /bff/api/orders/**
    TargetBaseUrl = "https://api.internal.acme.com",
    StripPrefix   = false,                            // keep /orders in the forwarded path
});

WebSockets

لا تستطيع مصافحة WebSocket حمل ترويسة مخصصة ولا رمز حامل، لذا لا تفيد ترويسة مكافحة التزوير ولا الوكيل. فعّل التذاكر ليتمكن تطبيق SPA من استدعاء GET /bff/ws-ticket، ووضع التذكرة القصيرة العمر ذات الاستخدام الواحد على عنوان URL للاتصال، ثم استبدالها في واجهة API لديك. سُكَّ تذكرة قبل كل اتصال مباشرةً: فهي تُحذف عند أول استخدام وتنتهي صلاحيتها خلال ثوانٍ.

تسليم رمز إلى المتصفّح عن قصد

الغاية كلها من BFF أن المتصفّح لا يحمل أي رمز، لذا فهذا الخيار اختياري وضيّق. وهو موجود للحالة الوحيدة التي لا يبلغها نموذج ملف تعريف الارتباط: خادم موارد على مصدر آخر، مثل تطبيق تُضمّنه في إطار iframe، ولا بد من استدعائه برمز حامل. وعند تفعيله، يعيد GET /bff/token?resource=… رمزًا مُستبدَلًا: أي رمز الجلسة بعد تضييق نطاقه إلى مورد واحد مدرج في قائمة السماح وتقييده بأي معامل سياق مدرج في قائمة السماح. ولا يرى المتصفّح أبدًا رمز الجلسة نفسه، وما يحصل عليه قصير العمر وذو جمهور واحد. ويُرفض أي طلب يذكر موردًا خارج قائمة السماح، وهو ما يمنع أن يكون هذا مصدرًا عامًا لسَكّ الرموز.

خدمة عدة مستأجرين من BFF واحد

اضبط معامل استعلام للمستأجر فيخدم نشرٌ واحد مستأجرين كثيرين: يختار /bff/login?slug=acme المستأجر، ويوفّر محدِّدٌ مضيفَ المصادقة وبيانات اعتماد العميل الخاصة بذلك المستأجر، وينتقل المفتاح مع ملف تعريف ارتباط الترابط إلى الجلسة، ويحدد تسجيل الخروج بالقناة الخلفية المستأجرَ من مُصدِر الرمز. ويُبقي المحدِّد الافتراضي سلوك المستأجر الواحد مطابقًا بايتًا ببايت، فلا تدفع شيئًا مقابل هذا ما لم تستخدمه.

تشغيل أكثر من نسخة

تعيش الجلسات خلف IBffSessionStore، وهو يستخدم افتراضيًا ذاكرة تخزين مؤقت داخل العملية. وهذا مناسب لنسخة واحدة وخاطئ لعدة نسخ: فالمستخدم الذي يصل طلبه التالي إلى نسخة أخرى يخرج من جلسته. سجّل مخزنًا مشتركًا، مثل Redis عبر IDistributedCache، قبل إضافة BFF.

خيارات تستحق المعرفة

المجموعة الكاملة، بصيغة .NET. وتأخذ حزمة Node الخيارات الأساسية بصيغة camelCase، فيصبح BasePath هو basePath، وSessionLifetime هو sessionLifetimeSeconds. أما PersistentCookie وCorrelationLifetime (الثابت عند 15 دقيقة في Node) وLoginPassthroughParams فهي خاصة بـ .NET فقط.

أدِر بوابتك من مساعد ذكاء اصطناعي

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

إنه اتصال OAuth عادي، لا مفتاح API. يسجّل كل شخص الدخول بصفته هو ويوافق على الوصول، فيستطيع المساعد أن يفعل بالضبط ما يستطيع ذلك الشخص فعله في البوابة، ولا شيء أكثر. ولا يُنشَأ شيء جديد يمكن أن يتسرب، وإبطال مساعد واحد لا يمسّ أحدًا سواه.

تفعيله

افتح الإعدادات وفعّل وصول مساعدي الذكاء الاصطناعي. وهو معطّل إلى أن تفعّله، وما دام معطّلًا فإن نقطة النهاية لا وجود لها أصلًا، لا أنها ترفض الطلبات فحسب. وبمجرد التفعيل، تعرض اللوحة عنوان URL الذي تلصقه في عميل الذكاء الاصطناعي لديك:

https://portal-api.authagonal.io/api/v1/mcp/{your-tenant}

ما يستطيع المساعد فعله

بالضبط ما يستطيع الشخص الذي ربطه فعله، ويُحسم ذلك في كل استدعاء بناءً على رمزه هو. يحصل وكيل tenant:support على الأدوات التشخيصية والأدوات اليومية؛ أما أدوات المسؤول فليست مخفية عنه فحسب، بل تُرفَض إن سمّاها مباشرة. وكل ما هو محجوب داخل البوابة يبقى محجوبًا: فتغيير عنوان البريد الإلكتروني لمستخدم يتطلب دور المسؤول هناك، ويتطلبه هنا أيضًا.

ولأنها منحة عادية، فأنت تديرها بالطريقة العادية: أزِل المساعد من صفحة التطبيقات المُصرَّح لها في حسابك فلا يعود قادرًا على التحديث، فيتوقف عن العمل عند انتهاء صلاحية رمز الوصول الحالي. وكل تغيير يجريه المساعد يُكتب في سجل التدقيق لديك باسم الشخص الذي تصرّف نيابةً عنه، فيكون الأثر هو نفسه الذي تقرأه بالفعل.

الأدوات

ثلاث وثلاثون أداة في هذا الإصدار. ويقرر عميل الذكاء الاصطناعي لديك أيها يفعّل، فيمكنك أن تمنح المساعد أدوات القراءة وحدها إن كان هذا كل ما تريده أن يفعله.

ما لم يُشمَل بعد

حذف المستخدمين، وإنشاء اتصالات SSO أو تعديلها، والفوترة، والنسخ الاحتياطية، وأسرار العملاء، كلها غائبة عن هذا الإصدار. فالحذف مكانه مع طابور المحو لديك، لا بجانبه؛ واتصال SSO كبير الأثر إلى حد أن تعديلًا خاطئًا فيه يقفل الباب أمام قوة عاملة بأكملها، لذا فهي للقراءة فقط في الوقت الحالي؛ وأي أداة تعيد سرّ عميل ستضعه في نص محادثة المساعد. أخبرنا أيًّا من هذه تريد وبأي ترتيب.

مصادقة خادم MCP

إذا كنت تعرض خادم Model Context Protocol، فبإمكان Authagonal أن يكون خادم التفويض خلفه. يتصل مساعد ذكاء اصطناعي، ويسجّل الشخص الذي يقف خلفه الدخول ويمنح الوصول، ويستقبل خادمك رمزًا حاملًا عاديًا تتحقق منه كما تتحقق من أي API آخر.

البديل هو مفتاح API يُلصق في تهيئة المساعد، وهو بيانات اعتماد لا مستخدم خلفه، ولا تاريخ انتهاء له، ولا خطوة موافقة فيه، ولا سبيل معه لإبطال موصّل واحد دون تدوير المفتاح للجميع. أما تنفيذه بواسطة OAuth فيعني أن المنحة تعود إلى شخص محدد بالاسم، وتظهر في سجل التدقيق لديك، ويمكن إبطالها من البوابة دون المساس بأي شيء آخر.

كيف يتم الاتصال

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

لا شيء في هذا التسلسل خاص بـ Authagonal: إنها مواصفة تفويض MCP، المبنية على RFC 9728 لبيانات تعريف المورد، وRFC 8414 لاكتشاف خادم التفويض، وRFC 7591 للتسجيل، وRFC 8707 لتسمية المورد. والموصّل الذي يتبع المواصفة يعمل دون معاملتنا كحالة خاصة.

دع الموصّلات تسجّل نفسها

الموصّل الذي لم تلتقِ به من قبل لا يستطيع استخدام عميل أنشأته يدويًا، فيسجّل عميلًا أثناء التشغيل. وهذا معطّل افتراضيًا. فعّل التسجيل الديناميكي للعملاء في الإعدادات فتظهر نقطة نهاية التسجيل في مستند الاكتشاف لديك؛ واتركه معطّلًا فلا يُعلَن عن نقطة النهاية وترفض الطلبات. وتفعيله يفتح التسجيل لمستأجرك وحده، ولا يفتحه لأي مستأجر آخر أبدًا.

ما ينفّذه خادم MCP لديك

شيئان صغيران، ثم يصبح بعدهما خادم موارد عاديًا. أولًا، انشر بيانات تعريف المورد المحمي التي تسمّي مستأجرك بوصفه خادم التفويض. قدّمها على مسار well-known، وإذا كانت نقطة نهاية MCP لديك على مسار فرعي فقدّمها كذلك بالصيغة المُلحقة بالمسار، لأن العملاء يجرّبون كلتيهما.

GET https://your-app.example/.well-known/oauth-protected-resource

{
  "resource": "https://your-app.example/mcp",
  "authorization_servers": ["https://acme.authagonal.io"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp"]
}

ثانيًا، عندما يصل استدعاء دون رمز صالح، أجب بـ 401 مع ترويسة WWW-Authenticate تشير إلى تلك البيانات التعريفية. هذه الترويسة هي ما يحوّل الرفض إلى اتصال: فبدونها لا يملك العميل أي وسيلة لاكتشاف أين يصادق، ويفشل ببساطة.

// Validate the connector's token like any other resource server.
builder.Services.AddAuthentication().AddJwtBearer("McpBearer", o =>
{
    o.Authority = "https://acme.authagonal.io";              // your tenant
    o.TokenValidationParameters.ValidAudience = "https://your-app.example/mcp";
});

// Unauthenticated? Point the connector at the metadata rather than just refusing.
http.Response.Headers.WWWAuthenticate =
    "Bearer resource_metadata=\"https://your-app.example/.well-known/oauth-protected-resource\"";
return Results.Unauthorized();

النطاقات والخطط والإبطال

عرّف نطاقًا اسمه mcp في صفحة النطاقات لديك، دون قيود أدوار، فيصبح بإمكان موصّل مسجِّل لنفسه طلبه، ويظهر على شاشة الموافقة ليرى المستخدم ما يوافق عليه. وصاحب الرمز (subject) هو الشخص الذي سجّل الدخول، فيستطيع خادمك أن يقرر ما يُسمح لهذا الشخص بالذات بفعله بدلًا من معاملة كل موصّل بالطريقة نفسها. ولا يمكن لموصّل مسجِّل لنفسه طلب النطاقين roles أو groups، لذا ابحث عنهما من جهتك بدلًا من توقّعهما في الرمز.

ولأنها منحة OAuth عادية، يعمل الإبطال بالطريقة العادية: يزيل المستخدم الموصّل من صفحة التطبيقات المُصرَّح لها في حسابه، مما يُسقط منحته ورمز التحديث الخاص به فلا يستطيع التجديد. وتُرفض رموز الوصول الحالية الخاصة به فورًا من قِبل /connect/introspect و/connect/userinfo، أما الخادم الذي يكتفي بالتحقق من JWT محليًا فيقبل الرمز حتى تنتهي صلاحيته. ويسجّل سجل التدقيق كل تسجيل دخول مع العميل الذي جرى من أجله.

بناء واجهة تسجيل دخول مخصصة

استبدل شاشات تسجيل الدخول والتسجيل وإعادة تعيين كلمة المرور وMFA المُستضافة من Authagonal بواجهتك الخاصة، بينما يواصل Authagonal التعامل مع المصادقة وMFA وSSO والجلسات وإصدار الرموز. مساران: استخدم مكتبة مكوّنات React لدينا، أو استدعِ واجهة API للمصادقة مباشرةً من أي إطار عمل. وهي ميزة اختيارية: فعّل أولاً واجهة تسجيل دخول مخصصة ضمن الإعدادات → الجلسة.

شرط مسبق: نطاق مخصص على جذرك

جلسة تسجيل الدخول هي ملف تعريف ارتباط من الطرف الأول، لذا يجب أن تشترك واجهتك وخادم مصادقة Authagonal في نطاق قابل للتسجيل. وجّه نطاق مصادقة مخصصاً إلى Authagonal على الجذر نفسه الذي يعمل عليه تطبيقك، مثل المصادقة على login.acme.com والتطبيق على app.acme.com. ويبقى إعداد واجهة تسجيل الدخول المخصصة معطّلاً حتى يوجد نطاق مخصص نشط.

لا حاجة إلى أي إعداد CORS في العميل لاستدعاءات /api/auth: فبمجرد تفعيل واجهة تسجيل دخول مخصصة، يُقبل تلقائيًا أي أصل على النطاق القابل للتسجيل نفسه لنطاق المصادقة لديك. أضف أصل واجهتك (مثل https://app.acme.com) إلى أصول CORS المسموح بها للعميل (العملاء → عناوين URI) فقط إذا كان المتصفح يُجري تبادل الرموز أيضًا.

React: ‏@authagonal/login

npm i @authagonal/login يشحن منطق المصادقة وواجهة المستخدم في حزمة واحدة، وهي نفسها التي بُني عليها تسجيل الدخول المُستضاف من Authagonal. اختر مستواك:

• تطبيق كامل، أدرج App ونسّقه عبر العلامة التجارية.
• تركيب الصفحات، استخدم LoginPage وMfaChallengePage وResetPasswordPage… داخل تخطيطك الخاص.
• العناصر الأولية والمنطق، ابنِ شاشاتك الخاصة باستخدام AuthLayout/Button/Input وعميل API (login وmfaVerify وforgotPassword …).

import { AuthLayout, Input, Button, login, ApiRequestError } from '@authagonal/login';

// returnUrl: the /connect/authorize URL your login page was opened with
function MyLogin({ returnUrl }: { returnUrl: string }) {
  async function onSubmit(email: string, password: string) {
    try {
      const res = await login(email, password, returnUrl);  // POST /api/auth/login (sets the session cookie)
      if (res.mfaRequired) {/* render your MFA step, then mfaVerify(res.challengeId!, 'totp', code) */}
      else if (res.mfaSetupRequired) {/* enrol first: mfaTotpSetup(res.setupToken) */}
      else window.location.href = returnUrl;                 // resume /connect/authorize
    } catch (e) {
      if (e instanceof ApiRequestError) {/* show e.message; e.error is the error code */}
    }
  }
  return <AuthLayout>{/* your own markup + <Input/> <Button/> */}</AuthLayout>;
}

أي إطار عمل: استدعِ واجهة API للمصادقة

لست على React؟ استدعِ نقاط نهاية تدفق المصادقة مباشرةً (تحت /api/auth)، ثم سلّم إلى تدفق OIDC القياسي /connect/authorize. أرسل credentials: 'include' كي يُخزَّن ملف تعريف ارتباط الجلسة.

# 1. Authenticate (browser fetch; credentials:'include' so the session cookie is stored)
curl -i -X POST https://login.acme.com/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.acme.com" \
  --data '{"email":"[email protected]","password":"..."}'
# (handle {"mfaRequired":true} → POST /api/auth/mfa/verify, then continue)

# 2. Hand off to the OAuth flow: top-level navigation to the authorize endpoint with PKCE:
# https://login.acme.com/connect/authorize?client_id=my-app&redirect_uri=...&response_type=code
#   &scope=openid%20profile%20email&code_challenge=...&code_challenge_method=S256
# The session cookie (same-site) authenticates the user; you get back a code → exchange at /connect/token.

مستأجر واحد، وعملاء كثيرون

نمط لمُكامِل واحد ومستأجر واحد وN عميلًا بعلامات تجارية مختلفة، لكلٍّ نطاق تسجيل دخول خاص ومستخدمون خاصون، دون مستأجر لكل عميل. وهذا ما وُجد التزويد التصريحي والمنظمات لتحويله إلى تغيير في الإعدادات بدلًا من مهمة هندسية.

البنية

• منظمة واحدة لكل عميل، داخل مستأجر واحد.
• نطاق تسجيل دخول واحد بعلامة تجارية لكل عميل، مثبّت كلٌّ منها على منظمة ذلك العميل، فلا يمكن لتسجيل الدخول عليه أن يُصدر رمزًا إلا لتلك المنظمة.
• يُقدَّم التطبيق أيضًا على مضيف لكل عميل، كلها من النشر نفسه: لا شيء في الشيفرة أو البناء أو الصورة يختلف بين العملاء.
• يختار الطرف المعتمِد سلطته من المضيف الذي يعمل عليه، لا من ثابت وقت البناء: تربط الحزمة نفسها نفسها بنطاق تسجيل دخول مختلف بحسب مضيف العميل الذي قدّمها.

خطوة بخطوة

زوّد العميل. استدعِ نقطة نهاية التزويد التصريحي بمواصفة تسمّي المنظمة الجديدة ونطاقها. الاستدعاء متكرر الأثر نفسه (idempotent) ومحدد بالأقسام.

{
  "organizations": [
    { "slug": "acme", "name": "Acme Pty Ltd" }
  ],
  "customDomains": [
    { "domain": "login.acme.example", "organizationSlug": "acme" }
  ]
}

وجّه DNS العميل إلى المستأجر. سجل CNAME واحد من نطاق العميل نفسه، يثبت التحكم والنية، دون رمز TXT.

_authagonal-challenge.login.acme.example.  CNAME  <slug>.<platformDomain>.

وجّه التطبيق إلى مضيف العميل. يحدد الطرف المعتمِد سلطة OIDC الخاصة به لكل طلب، بحسب المضيف الذي يقدّمه حاليًا. والمضيف الذي لا إدخال له في خريطة العملاء يعود إلى الاشتقاق الكلاسيكي لمستأجر واحد، لذا فإضافة عميل هي إضافة بحتة.

export function resolveCustomer(): { authority: string; clientId: string } {
  const cfg = getConfig();
  const customer = cfg.customers?.[window.location.host];
  if (customer) return customer;
  const baseDomain = cfg.baseDomain || window.location.hostname.replace(/^consumer\./, '');
  return { authority: `https://${cfg.tenantSlug}.${baseDomain}`, clientId: cfg.clientId };
}

لا يطلب العميل (client) أي شيء خاص بالمنظمة: لا معامل organization ولا نطاق (scope) لكل عميل. ويتولى تثبيت النطاق تحديد المنظمة بالكامل من جهة الخادم، وهذا ما يجعل عبارة «التطبيق هو الشيفرة نفسها لكل عميل» صحيحة فعلًا.

ما يراه العميل

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

يُرفض مستخدم العميل A الذي يحاول تسجيل الدخول على مضيف العميل B، ولا تُعرض له بيانات العميل B، وذلك بإحدى صورتين بحسب كيفية نشوء التعارض:

• لا يرسل الطرف المعتمِد شيئًا ويصل ببساطة إلى النطاق المثبّت: يوفر التثبيت المنظمة نيابةً عن المستخدم، فيصبح التحديد صريحًا، ويُرفض مستخدم العميل A الذي لا عضوية له في B عند النقطة التي سيُصدَر فيها الرمز.
• يسمّي الطرف المعتمِد منظمة مختلفة بنفسه، فيرفضه مباشرةً وسيط تثبيت النطاق بالخطأ 400، قبل عرض أي صفحة تسجيل دخول.

ضم العميل رقم N+1

عندما يقود Terraform استدعاء التزويد، يصبح ضم عميل آخر تعديلًا في ملف واحد: إدخالًا آخر في مصفوفة organizations، وإدخال نطاق آخر يثبّته، وسجل DNS آخر. لا شيء يتغير في التطبيق أو نشره أو بنائه، ويلتقط المحلِّل المعتمد على المضيف العميل الجديد لحظة وجود إدخاله في الإعدادات.

التنفيذ المرجعي

يختبر مستأجر تطويري دائم هذا النمط كاملًا من البداية إلى النهاية على نطاقي عميلين حقيقيين، مع مجموعة اختبارات شاملة (end-to-end) تزوّد الأعضاء وتفحص العلامة التجارية ومطالبة org_id وتتحقق من صورتي الرفض أعلاه: توثيق قابل للتنفيذ، وليس مجرد وصف.

cd e2e-consumer && DOMAIN=authagonal.dev npx playwright test organizations-domains

تعمل المجموعة افتراضيًا كغيرها من المواصفات، ويمكن تخطيها في بيئة لم تُزوَّد فيها النطاقات المرجعية، لأنها المواصفة الوحيدة في المجموعة التي تعتمد على بنية تحتية خارج سيطرة المستودع نفسه.

الخطط والحدود

يقدّم Authagonal خطة مجانية وأربعة مستويات مدفوعة. تشمل كل خطة جميع ميزات المصادقة. وتختلف الخطط في حد المستخدمين النشطين شهرياً (MAU) وتسعير التجاوز، وتقتصر الخطة المجانية على دعم المجتمع، دون مكتب دعم المستأجر.

مستويات الخطط

المستخدمون النشطون شهرياً (MAU)

المستخدم النشط شهرياً هو أي مستخدم فريد يصادق بنجاح مرة واحدة على الأقل خلال شهر تقويمي (UTC). أما المستخدمون المُزوَّدون عبر SCIM ولم يسجّلوا الدخول فلا يُحتسبون ضمن إجمالي MAU لديك.

التجاوز: إذا كانت خطتك تدعم التجاوز (Pro وما فوقها) وكان التجاوز مفعّلًا لمستأجرك (وهو معطّل افتراضيًا)، يُحتسب المستخدمون الذين يتجاوزون حد MAU بالسعر لكل مستخدم المبيّن في جدول الخطط أعلاه. ويحدّد سقف التجاوز الحد الأقصى لعدد المستخدمين الإضافيين المسموح بهم فوق الحد.

التطبيق: إذا كانت خطتك لا تدعم التجاوز (Free وStarter) أو لم يكن التجاوز مفعّلًا، يحتفظ المستخدمون الذين سجّلوا الدخول بالفعل هذا الشهر بإمكانية الوصول دائمًا. وعندما يتجاوز المستأجر حده لأول مرة، تبدأ فترة سماح مدتها 10 أيام يظل بإمكان المستخدمين الجدد خلالها تسجيل الدخول. وبعدها، يُرفض المستخدمون الذين لم يسجّلوا الدخول هذا الشهر حتى الشهر التالي أو حتى تُرقّي خطتك.