تسجيل الدخول الموحّد

Shayan Taslimتم التحديث

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

تتطلب أوضاع تسجيل الدخول إلى اللوحة (افتراضي وSSO ومعطّل) خطة Professional.

تفعيل SSO

  1. افتح الإعدادات → تسجيل الدخول.

  2. ضمن المصادقة، اضبط تسجيل الدخول إلى اللوحة على SSO.

  3. في مربع الحوار تمكين SSO، أدخل عنوان URL لإعادة التوجيه عبر HTTPS، ثم انقر على تمكين SSO. يمكنك تعديل عنوان URL لاحقًا ضمن عنوان URL لإعادة التوجيه عبر SSO (لمسح عنوان URL لإعادة التوجيه بالكامل، عطّل تسجيل الدخول إلى اللوحة قبل تعطيل SSO).

  4. انسخ معرّف المشروع وسر المشروع من قسم الأسرار.

يجب أن يستخدم عنوان URL لإعادة التوجيه https:// (استخدم نفق HTTPS عند الاختبار محليًا).

أوضاع تسجيل الدخول إلى اللوحة

  • افتراضي: يسجّل الزوار الدخول باستخدام حسابات UserJot العادية.

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

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

آلية عمل تدفق إعادة التوجيه عبر SSO

عندما ينقر زائر على تسجيل الدخول، يفتح UserJot نافذة منبثقة لتسجيل الدخول (ويلجأ إلى إعادة التوجيه في علامة التبويب نفسها إذا حُظر فتح النوافذ المنبثقة) تشير إلى عنوان URL الذي أعددته، مع معاملي الاستعلام state وredirect:

text
https://yourapp.com/userjot/sso?state=OPAQUE_STATE_FROM_USERJOT&redirect=https%3A%2F%2Fapi.userjot.com%2Fauth%2Fsso

كل ما تحتاج نقطة النهاية لديك إلى فعله هو الحفاظ على state:

  1. تقرأ معلمة الاستعلام state.

  2. صادِق على المستخدم في تطبيقك (إذا لم يكن قد سجّل الدخول بعد، فأرسله عبر تدفق تسجيل الدخول لديك وأعِده إلى نقطة النهاية هذه مع state الأصلي).

  3. وقّع JWT من نوع HS256 باستخدام سر المشروع.

  4. أعِد توجيه المتصفح إلى https://api.userjot.com/auth/sso?jwt=<JWT>&state=<STATE>.

لا تعدّل state. فهو صالح للاستخدام مرة واحدة، ومرتبط بجلسة المتصفح، وتنتهي صلاحيته بعد 15 دقيقة.

حمولة JWT

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

المطالبة

مطلوب

الوصف

sub

نعم

معرّف مستخدم ثابت من نظامك

iss

نعم

معرّف المشروع الخاص بك في UserJot، كما هو تمامًا

aud

نعم

النص userjot كما هو تمامًا

exp

نعم

الطابع الزمني لانتهاء الصلاحية بتنسيق Unix (يُنصح بمدة تتراوح بين 5 و15 دقيقة)

iat

لا

الطابع الزمني للإصدار بتنسيق Unix (يجب ألا يكون في المستقبل بما يتجاوز تفاوت الساعة)

email

لا

عنوان البريد الإلكتروني للمستخدم (يُنصح به لربط البريد الإلكتروني والإشعارات)

firstName

لا

الاسم الأول

lastName

لا

اسم العائلة

avatar

لا

عنوان URL للصورة الرمزية

traits

لا

خريطة مسطّحة من أزواج المفتاح والقيمة، تتكوّن من سلاسل نصية أو أرقام أو قيم منطقية أو null

companies

لا

مصفوفة تضم عضويات الشركات

مثال على الحمولة:

JavaScript
const now = Math.floor(Date.now() / 1000);

const payload = {
  sub: 'user_123',
  email: 'jane@example.com',
  firstName: 'Jane',
  lastName: 'Doe',
  iss: 'YOUR_PROJECT_ID',
  aud: 'userjot',
  iat: now,
  exp: now + 10 * 60
};

بيانات الشركة

JSON
{
  "companies": [
    {
      "id": "company_456",
      "name": "Acme Corp",
      "domain": "acme.com",
      "logo": "https://example.com/acme.png",
      "traits": {
        "plan": "enterprise",
        "seats": 42
      }
    }
  ]
}

مثال على نقطة نهاية (Hono)

JavaScript
import { Hono } from 'hono';
import jwt from 'jsonwebtoken';

const app = new Hono();

const USERJOT_PROJECT_ID = process.env.USERJOT_PROJECT_ID;
const USERJOT_PROJECT_SECRET = process.env.USERJOT_PROJECT_SECRET;
const USERJOT_CALLBACK_URL = 'https://api.userjot.com/auth/sso';

app.get('/userjot/sso', async (c) => {
  const state = c.req.query('state');
  if (!state) return c.text('Missing state', 400);

  const user = await getCurrentUser(c);

  const token = jwt.sign(
    {
      sub: user.id,
      email: user.email,
      firstName: user.firstName,
      lastName: user.lastName,
      iss: USERJOT_PROJECT_ID,
      aud: 'userjot'
    },
    USERJOT_PROJECT_SECRET,
    { algorithm: 'HS256', expiresIn: '10m' }
  );

  const callback = new URL(USERJOT_CALLBACK_URL);
  callback.searchParams.set('jwt', token);
  callback.searchParams.set('state', state);

  return c.redirect(callback.toString());
});

تدوير سر المشروع

إذا نقرت على إبطال السر ضمن الإعدادات → تسجيل الدخول → الأسرار، ينشئ UserJot سر مشروع جديدًا فورًا. حدّث نقطة نهاية SSO لديك (بالإضافة إلى أي موقّعات الهوية الموقّعة وSwift SDK) على الفور، لأن الرموز المميّزة الموقّعة بالسر القديم تتوقف عن العمل مباشرةً.

استكشاف الأخطاء وإصلاحها

في مسار النافذة المنبثقة الافتراضي، تُعاد أخطاء الاستدعاء إلى اللوحة وتُعرض داخل نافذة تسجيل الدخول. عندما يلجأ المتصفح إلى إعادة التوجيه في علامة التبويب نفسها (على سبيل المثال، إذا حُظر فتح النوافذ المنبثقة)، يعيد UserJot التوجيه إلى اللوحة مع معامل الاستعلام sso_error:

رمز الخطأ

المعنى

invalid_state

قيمة state مفقودة أو معدّلة أو منتهية الصلاحية (بعد أكثر من 15 دقيقة) أو سبق استخدامها.

invalid_token

عدم تطابق التوقيع، أو خطأ في iss/aud، أو فقدان sub/exp، أو انتهاء صلاحية JWT.

sso_disabled

لم يعد تسجيل الدخول إلى اللوحة مضبوطًا على SSO.

config_error

إعداد SSO لمساحة العمل غير مكتمل (عنوان URL لإعادة التوجيه أو السر مفقود).

invalid_return_to

فشل التحقق من صحة عنوان URL للعودة بعد تسجيل الدخول.

auth_failed / session_error

فشلت المصادقة أو عملية إنشاء الجلسة على الخادم.

هل أجاب هذا عن سؤالك؟