التوثيق

البدء

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

إنشاء حساب

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

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

تسجيل عميل

انتقل إلى العملاء في الشريط الجانبي للبوابة وانقر على إنشاء. أدخل clientId وclientName لتطبيقك. ثم اضبط عنوان إعادة توجيه واحدًا على الأقل، وهو المكان الذي يُرسَل إليه المستخدمون بعد المصادقة. على سبيل المثال: 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, tokens.refresh_token

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

لوحة التحكم

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

نظرة عامة

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

الشاشة الرئيسية للوحة التحكم مع مخطط المستخدمين النشطين يوميًا ونظرة عامة على النشاط

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

تعرض لوحة مقاييس النشاط أربع بطاقات إحصائية تلخّص أحداث المصادقة الرئيسية:

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

استخدم عوامل تصفية النطاق الزمني للتبديل بين 24 ساعة و3 أيام و7 أيام و30 يومًا. تتحدّث جميع البطاقات الإحصائية والمخططات لتعكس النافذة المحددة.

مقاييس النشاط مع نطاق زمني قابل للتهيئة

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

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

العملاء

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

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

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

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

إنشاء عميل

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

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

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

حذف عميل

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

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

لكل عميل مجموعة شاملة من خيارات التهيئة منظّمة في عدة أقسام.

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

العناوين (URIs)

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

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

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

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

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

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

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

سياسة MFA

يمكن لكل عميل تجاوز سياسة MFA على مستوى المستأجر بإعداد خاص بكل عميل. تقدّم قائمة سياسة 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) يطابق أي اتصال SSO مهيّأ. وإذا تطابق، يُعاد توجيه المستخدم بسلاسة إلى موفّر الهوية الخاص بمؤسسته.

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

تزويد JIT

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

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

المستخدمون

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

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

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

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

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

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

إنشاء المستخدمين

انقر على إنشاء مستخدم لإضافة مستخدم محلي جديد. يتطلب النموذج ما يلي:

إنشاء مستخدم محلي جديد

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

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

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

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

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

الملف الشخصي

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

الأدوار

عيّن الأدوار المعرّفة في صفحة الأدوار وألغِ تعيينها. تظهر عضوية الأدوار في رموز الهوية والوصول عندما يكون لدى العميل includeRolesInTokens مفعّلًا.

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

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

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

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

حذف المستخدم

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

المجموعات

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

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

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

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

إنشاء مجموعة

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

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

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

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

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

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

عند تفعيل includeGroupsInTokens على عميل، يتضمن رمز الهوية مطالبة groups تحتوي على عضويات المستخدم في المجموعات. يتضمن كل إدخال معرّف المجموعة id واسمها name:

{
  "sub": "user-123",
  "email": "[email protected]",
  "groups": [
    { "id": "grp-001", "name": "Engineering" },
    { "id": "grp-002", "name": "Beta Testers" }
  ]
}

الأدوار

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

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

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

إنشاء دور

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

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

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

حذف دور

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

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

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

تُضمَّن الأدوار المخصصة لمستخدم كمطالبة 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 المدعومة، بما في ذلك العمليات المجمّعة والتصفية وإمكانية تغيير كلمة المرور.

نطاقات 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 في إعدادات علامتك التجارية. يُحمَّل الملف بعد الأنماط الافتراضية، لذا تكون الأولوية لقواعدك.

الوضع الداكن

يأتي تطبيق تسجيل الدخول بسمات فاتحة وداكنة وتابعة للنظام. يختار المستخدمون من مفتاح تبديل على صفحة تسجيل الدخول، ويستمر الاختيار عبر الجلسات. عند الضبط على 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 منفصل. استخدمها لاختبار تغييرات الإعداد وتكاملات SSO ونقاط نهاية خطافات الويب دون التأثير على المستخدمين الفعليين.

يمكن الوصول إلى بيئة الاختبار على {slug}-sandbox.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. بمجرد إضافة سجل DNS، انقر على تحقق للتأكد من انتشار DNS.

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 (يعمل بالكامل)، أو failed (تم اكتشاف مشكلة في الإعداد).

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

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

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

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

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

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

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

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

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

هوية المرسِل

بريد المرسِل واسمه مشتركان عبر جميع أوضاع المزوّدين. بريد المرسِل مطلوب؛ ويعود اسم المرسِل إلى اسم المستأجر عند تركه فارغاً.

نطاق Resend المخصص

تحقق من نطاق الإرسال الخاص بك مع Resend مرة واحدة، ثم استخدمه كعنوان "من" لهذا المستأجر. تُوفَّر سجلات DNS من نوع TXT (SPF وDKIM) عبر صفحة النطاقات، ويتحقق منها Resend تلقائياً.

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 واحد لكل سطر).

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

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

كيف يعمل

عند وقوع حدث متعلق بمستخدم (إنشاء أو مصادقة)، يستدعي Authagonal عنوان رد النداء (callback URL) الخاص بتطبيق التزويد لديك باستخدام نمط TCC (محاولة/تأكيد/إلغاء). يضمن هذا النهج ثلاثي المراحل تزويداً موثوقاً عبر عدة أنظمة لاحقة:

حمولة خطاف الويب

يتضمن كل طلب خطاف ويب حمولة JSON تحتوي على الحقول التالية:

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

لإضافة تطبيق تزويد، قدّم اسماً وعنوان رد نداء (callback URL) ومفتاح API اختيارياً. يُرسَل مفتاح API كرمز Bearer في ترويسة Authorization لكل طلب خطاف ويب، ما يتيح لتطبيقك مصادقة الطلبات الواردة من Authagonal.

الاختبار

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

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

حدود الخطة

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

الفريق

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

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

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

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

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

حقول الدعوة

تُنشئ دعوات المسؤولين مستخدماً مُزوَّداً بالكامل، دون حاجة إلى تبادل رسائل بريدية.

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

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

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

الدعم

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

تذاكرك

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يخزّن 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 تضم مفاتيح RSA العامة، يتضمّن كل منها الحقول kty وuse وkid وalg وn وe.

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

يسجّل خروج جلسة المستخدم الحالية، ويطلق تسجيل الخروج عبر القناة الخلفية لجميع العملاء الذين لديهم BackChannelLogoutUri مسجّل، ويُبطل جميع المنح.

إذا تم توفير قيمة 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.

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

تدعم نقاط نهاية القوائم التقسيم إلى صفحات عبر معاملي الاستعلام startIndex (يبدأ من 1) وcount (بحد أقصى 200)، والتصفية عبر معامل filter (مثل userName eq "[email protected]").

المستخدمون

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} — تحديث جزئي لإضافة أعضاء المجموعة أو إزالتهم.

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. النطاق المذكور بجانب كل مجموعة هو الحد الأدنى لمستوى وصول بيانات الاعتماد الذي تحتاجه. تقبل نقاط نهاية القوائم معاملي الاستعلام startIndex وcount.

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

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

POST/api/v1/clients— إنشاء عميل. يعيد معرّف العميل، وللعملاء السرّيين يعيد سرًّا يُستخدم مرة واحدة.

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

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

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

GET/api/v1/users— سرد المستخدمين. يدعم startIndex وcount والبحث (بادئة البريد الإلكتروني / الاسم).

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

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

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

POST/api/v1/users— إنشاء مستخدم ببريد إلكتروني وكلمة مرور.

PUT/api/v1/users/{id}— تحديث مستخدم (الملف الشخصي، البريد الإلكتروني، حالة التمكين/الحظر).

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

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

DELETE/api/v1/users/{id}/mfa— Reset a user's MFA enrollment.

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— سرد نطاقات البريد الإلكتروني للمُرسِل.

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

مثال: إنشاء مستخدم

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

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

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

هذه هي الشاشات المستضافة التي يراها المستخدمون النهائيون على خادم المصادقة الخاص بمستأجرك. يوفّر 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

ينشئ حساب مستخدم جديدًا. يُرسَل بريد تحقق تلقائيًا، وعلى المستخدم التحقق من بريده الإلكتروني قبل أن يتمكن من تسجيل الدخول.

نص الطلب:

{
  "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 — يعيد عنوان URI لبيانات رمز QR ومفتاح إدخال يدوي. يمسح المستخدم رمز QR بتطبيق المصادقة لديه (Google Authenticator، Authy، 1Password، وغيرها)، ثم يؤكد التسجيل.

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

{
  "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 رموز استرداد من 8 أحرف تُستخدم مرة واحدة. يمكن استخدام كل رمز مرة واحدة بالضبط لتجاوز 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 التزويد في الوقت المناسب. إذا لم يكن المستخدم موجودًا بالفعل في المستأجر، يُنشأ تلقائيًا من مطالبات موفّر الهوية. وإن كان موجودًا، تُحدَّث سمات ملفه الشخصي لتطابق أحدث القيم من الموفّر.

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

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

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

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

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

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';

function MyLogin() {
  async function onSubmit(email: string, password: string) {
    try {
      const res = await login({ email, password });        // POST /login (sets the session cookie)
      if (res.mfaRequired) {/* render your MFA step → mfaVerify(...) */}
      else window.location.href = res.returnUrl;            // hand off to /connect/authorize
    } catch (e) {
      if (e instanceof ApiRequestError) {/* show e.message */}
    }
  }
  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.

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

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

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

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

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

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

التطبيق إذا كانت خطتك لا تدعم التجاوز (Starter)، فلن يتمكن المستخدمون الذين يتجاوزون حد MAU من تسجيل الدخول حتى فترة الفوترة التالية أو حتى ترقّي إلى خطة تدعم التجاوز.