الهوية الموقّعة

Shayan Taslimتم التحديث

يصدر استدعاء uj.identify عادي من المتصفح، لذا يمكن لأي شخص تعديله. تمنع الهوية الموقّعة الانتحال: يوقّع خادمك JWT قصير الصلاحية بخوارزمية HS256 لإثبات هوية المستخدم، ويمرّر الودجت هذا الرمز إلى UserJot.

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

متى تحتاج إلى ذلك

  • تريد التحقق من أن الملاحظات والأصوات والمحادثات صادرة عن الحساب الحقيقي الذي سجّل الدخول.

  • تريد أن يتمكن العملاء من تعديل منشورات الملاحظات والتعليقات الخاصة بهم وحذفها داخل الأداة (لا يمكن لجلسات uj.identify غير الموقّعة تعديل المحتوى أو حذفه داخل الأداة).

  • فعّلت Require signed tokens ضمن Settings → Login (متاحة في خطتي Starter وProfessional بعد تفعيل Automatic login)، ما يؤدي إلى رفض طلبات identify غير الموقّعة، كما يشترط تضمين عضويات الشركات في الرمز الموقّع (مع تجاهل companies غير الموقّعة من جهة العميل وإصدار تحذير UNSIGNED_COMPANY_IGNORED).

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

Note

إذا كان منتجك يستخدم كلاً من ودجت الويب وSwift SDK، فإن تفعيل اشتراط الرموز الموقّعة يفرض التحقق في كليهما. يستخدم ودجت الويب JWT بخوارزمية HS256 (token)، بينما يستخدم Swift SDK توقيع HMAC-SHA256 ‏signature موقّعًا باستخدام سر مساحة العمل نفسه.

1. أنشئ الرمز على خادمك

وقّع JWT باستخدام HS256 وسر مساحة العمل. اعثر على كلٍّ من معرّف المشروع وسر المشروع في الإعدادات → تسجيل الدخول ضمن الأسرار.

لا توقّع الرموز مطلقًا في المتصفح. احتفظ بالسر على خادمك.

الادعاءات المطلوبة

المطالبة

القيمة

sub

المعرّف الثابت للمستخدم في نظامك. مطلوب.

iss

معرّف مشروع UserJot الخاص بك. مطلوب.

aud

السلسلة النصية userjot حرفيًا. مطلوب.

iat

الطابع الزمني للإصدار، بالثواني منذ Unix epoch. مطلوب.

exp

الطابع الزمني لانتهاء الصلاحية، بالثواني منذ Unix epoch. مطلوب. بحد أقصى ساعة واحدة (3600 ثانية) بعد iat.

الادعاءات الاختيارية التي تم التحقق منها

يمكنك أيضًا تضمين email وfirstName وlastName وavatar وtraits وcompanies. يدعم كل عنصر في companies ما يلي:

JSON
{
  "companies": [
    {
      "id": "acme",
      "name": "ACME Inc.",
      "domain": "acme.com",
      "logo": "https://acme.com/logo.png",
      "traits": { "plan": "enterprise" }
    }
  ]
}

أمثلة للخادم

Node.js

JavaScript
import jwt from 'jsonwebtoken';

export function createUserJotToken(user, secret, projectId) {
  return jwt.sign(
    {
      sub: user.id,
      email: user.email,
      firstName: user.firstName,
      lastName: user.lastName,
      iss: projectId,
      aud: 'userjot'
    },
    secret,
    { algorithm: 'HS256', expiresIn: '1h' }
  );
}

Python

Python
import time
import jwt

def create_userjot_token(user, secret, project_id):
    now = int(time.time())
    return jwt.encode(
        {
            "sub": user["id"],
            "email": user["email"],
            "firstName": user["first_name"],
            "lastName": user["last_name"],
            "iss": project_id,
            "aud": "userjot",
            "iat": now,
            "exp": now + 3600,
        },
        secret,
        algorithm="HS256",
    )

PHP

PHP
<?php

use Firebase\JWT\JWT;

function createUserJotToken(array $user, string $secret, string $projectId): string
{
    $now = time();

    return JWT::encode([
        'sub' => $user['id'],
        'email' => $user['email'],
        'firstName' => $user['firstName'],
        'lastName' => $user['lastName'],
        'iss' => $projectId,
        'aud' => 'userjot',
        'iat' => $now,
        'exp' => $now + 3600,
    ], $secret, 'HS256');
}

Ruby

Ruby
require 'jwt'

def create_userjot_token(user, secret, project_id)
  now = Time.now.to_i

  payload = {
    sub: user[:id],
    email: user[:email],
    firstName: user[:first_name],
    lastName: user[:last_name],
    iss: project_id,
    aud: 'userjot',
    iat: now,
    exp: now + 3600
  }

  JWT.encode(payload, secret, 'HS256')
end

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

2. مرّر الرمز إلى identify

مرّر JWT في الحقل token:

JavaScript
uj.identify({
  token: 'TOKEN_FROM_YOUR_SERVER'
});

يمكنك أيضًا تمرير user وcompanies إلى جانب token لإضافة حقول غير موثّقة؛ وإذا ظهر حقل في كليهما، تكون الأولوية للرمز الموقّع (ما لم يكن Require signed tokens مفعّلًا، إذ يتم تجاهل الشركات غير الموقّعة). أكّد التحقق عبر الوعد المُعاد:

JavaScript
const result = await uj.identify({ token });
result.identityTrust; // 'signed'

تفشل الرموز غير الصالحة ولا يتم الرجوع إلى خيار بديل

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

الهوية الموقّعة والمحادثات

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

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

  • يظل تفعيل اشتراط الرموز الموقّعة يسمح للزوار المجهولين ببدء محادثات كضيوف مرتبطة بالمتصفح؛ فهو يمنع فقط استدعاءات identify غير الموقّعة من الارتباط بحسابات الأعضاء.

تنتقل الهوية إلى صفحاتك العامة

بعد التعرّف على المستخدم، يمرّر الودجت الجلسة تلقائيًا إلى الروابط المؤدية إلى صفحات UserJot العامة (لوحة الأفكار أو خارطة الطريق أو سجل التغييرات أو مركز المساعدة). لكي يصل الزوار إلى تلك الصفحات وهم مسجّلو الدخول مسبقًا، فعّل تسجيل الدخول التلقائي في الإعدادات → تسجيل الدخول (في خطة Starter أو Professional). راجع تسجيل الدخول التلقائي.

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

يُرفض استدعاء identify مع ظهور IDENTIFY_FAILED

  • تحقّق من أن الرمز موقّع باستخدام HS256 وسر المشروع الحالي.

  • تحقّق من أن iss يطابق معرّف المشروع الخاص بك، وأن aud يساوي تمامًا userjot.

  • تحقّق من وجود كلٍّ من iat وexp بصيغة الثواني منذ Unix epoch، ومن أن exp - iat <= 3600.

  • تحقّق من دقة ساعة خادمك (تُرفض الرموز الصادرة في المستقبل إذا تجاوز انحراف الساعة 60 ثانية).

توقفت استدعاءات identify غير الموقّعة عن العمل

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

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