CREATE TOKEN

وثائق Token

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

Syntax:

CREATE TOKEN
    [{VALID UNTIL datetime | VALID FOR interval}]
    [GRANTS (privilege ON object [,...])]

هذا اختصار للأمر ALTER USER <current user> ADD IDENTIFIED WITH sha256_password BY '<random secret>' مع عبارتَي VALID UNTIL و GRANTS نفسيهما، لذا يسلك الرمز سلوك كلمة مرور عادية للمستخدم الحالي:

• يرتبط بالمستخدم — إذ يظهر في system.query_log وsystem.processes باسم المستخدم، ويتوقف عن العمل عند حذف المستخدم، ويفقد حقوق الوصول متى فقدها المستخدم؛
• يمكن تقييده زمنيًا باستخدام VALID UNTIL أو VALID FOR، وتقييد صلاحياته باستخدام GRANTS؛
• يمكن استخدامه مع أي آلية مصادقة تقبل كلمة مرور، مثل الوسيط password في الـ HTTP interface أو الخيار --password في clickhouse-client.

يتطلب إنشاء رمز صلاحية CREATE TOKEN، أو صلاحية ALTER USER على المستخدم الحالي. وهي صلاحية منفصلة لأن الرمز يخفض مستوى أمان الحساب الذي ينتمي إليه: فالمستخدم الذي جرت مصادقته بمفتاح عتادي أو شهادة يمكنه استخدامه لإنشاء كلمة مرور طويلة الأمد للحساب نفسه. وتخوّل الصلاحية نفسها تنفيذ العبارة المكافئة ALTER USER <current user> ADD IDENTIFIED ....

​

النتيجة

يُرجع الاستعلام صفًا واحدًا يتكوّن من عمودين:

العمود	النوع	الوصف
token	String	السر المُولَّد.
valid_until	DateTime64(0)	موعد انتهاء صلاحية الرمز. تعني القيمة 0 أن صلاحيته لا تنتهي أبدًا، وهو نفس الـ encoding المستخدم في العمود valid_until في system.users.

للحصول على السر دون أي formatting، استخدم FORMAT TSVRaw عند تحديده:

CREATE TOKEN VALID FOR INTERVAL 30 DAY GRANTS (SELECT ON db.*) FORMAT TSVRaw

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

​

عبارتا VALID UNTIL و VALID FOR

تحدّان مدة صلاحية الرمز. وتعملان تمامًا مثل العبارتين المقابلتين لهما في طريقة المصادقة الخاصة بـ CREATE USER: فـ VALID UNTIL تأخذ تاريخًا ووقتًا مطلقين، بينما تأخذ VALID FOR فاصلًا زمنيًا يُضاف إلى الوقت الحالي عند تنفيذ الاستعلام.

وفي غياب أيٍّ من العبارتين، تستمر صلاحية الرمز لمدة create_token_default_ttl_seconds، وهي 30 دقيقة افتراضيًا، أي أن الرمز الذي لم يُطلب تمديد مدته يكون قصير الأجل. اضبط هذا الإعداد على 0، أو اكتب VALID UNTIL 'infinity'، لإنشاء رمز لا تنتهي صلاحيته أبدًا.

أمثلة:

• CREATE TOKEN VALID UNTIL '2026-12-31'
• CREATE TOKEN VALID FOR INTERVAL 30 DAY
• CREATE TOKEN VALID UNTIL 'infinity'

​

GRANTS Clause

يقصر حقوق الوصول للجلسات المُصادَق عليها بواسطة الرمز على التقاطع مع الصلاحيات المذكورة. وهو يعمل تمامًا مثل عبارة GRANTSفيCREATE USER`، بما في ذلك قيودها — وعلى وجه الخصوص، يُفرَض هذا الحد على الـ node الذي يستقبل الاستعلام ولا يُمرَّر إلى بقية nodes الـ cluster. ولا تضيف هذه الـ clause أي حقوق وصول إطلاقًا: فالصلاحية التي لم تُمنح للمستخدم تبقى غير متاحة للرمز. وبدون هذه الـ clause يحصل الرمز على كامل حقوق وصول المستخدم.

أمثلة:

• CREATE TOKEN GRANTS (SELECT ON db.table)
• CREATE TOKEN VALID FOR INTERVAL 90 DAY GRANTS (SELECT ON db.table, INSERT ON db.table)

لا ينطبق هذا الحد ولا الحد الزمني على ما تخلّفه جلسات الرمز وراءها — راجع اعتبارات الأمان.

​

إدارة الرموز

الرمز هو طريقة المصادقة خاصة بالمستخدم، ولذلك يظهر في SHOW CREATE USER (مع عبارتَي VALID UNTIL وGRANTS، لكن دون السر) وفي الأعمدة auth_type وauth_params وauth_grants في الجدول system.users.

لا توجد عبارة تحذف رمزًا واحدًا بعينه. ولإلغاء جميع رموز مستخدم ما، استبدل طرق المصادقة الخاصة به، مثلًا عبر ALTER USER <name> IDENTIFIED WITH ...، أو استخدم ALTER USER <name> RESET AUTHENTICATION METHODS TO NEW للإبقاء على أحدث طريقة مضافة فقط. ويُحدَّد عدد طرق المصادقة التي يمكن أن تكون لدى المستخدم في وقت واحد عبر server setting max_authentication_methods_per_user.

يُولَّد السر ويُخزَّن بواسطة الاستعلام نفسه، لذا فإن CREATE TOKEN الذي لا تصل نتيجته إلى العميل — سواء بسبب انقطاع connection أثناء إرسال الـ row، أو بسبب INTO OUTFILE لا يستطيع العميل فتحه — يترك خلفه طريقة المصادقة لا يمكن لأحد استخدامها ومع ذلك تُحتسب ضمن ذلك الحد. فلا أحد يملك هذا السر؛ إذ لا يوجد إلا أثناء تنفيذ الاستعلام. أما الاستعلام الذي يُرفض قبل تنفيذه، بما في ذلك ما تُحدِّد فيه عبارة FORMAT صيغة لا يمكن استخدامها، فلا يضيف شيئًا.

لا يدعم CREATE TOKEN عبارة ON CLUSTER. استخدم تخزين وصول replicated (أو نفّذ الاستعلام على كل node باستخدام العبارة المكافئة ALTER USER ... ADD IDENTIFIED WITH sha256_hash) لكي يعمل الرمز عبر cluster تُخزَّن access entities الخاصة به محليًا.

​

اعتبارات الأمان

يقيّد كل من VALID UNTIL وGRANTS الجلسات التي تُصادَق باستخدام الرمز، لكنهما لا يقيّدان ما تخلّفه تلك الجلسات وراءها:

• يُتحقق من المهلة النهائية عند مصادقة الجلسة باستخدام الرمز، أما الجلسة المفتوحة بالفعل والاستعلام الجاري تنفيذه فلا يُقاطَعان عند انتهاء صلاحية الرمز.
• كل ما تنشئه الجلسة يبقى بعد انقضاء الرمز، وأي كائن يؤدي عملًا من تلقاء نفسه يستمر في أدائه: فـالعرض المُجسَّد القابل للتحديث يستمر في التحديث، والعرض المُجسَّد المرتبط بمحرك جدول متدفق مثل Kafka أو RabbitMQ أو NATS أو S3Queue يستمر في الاستهلاك، والقاموس المزوّد بـLIFETIME يستمر في إعادة التحميل، وذلك بعد وقت طويل من انتهاء صلاحية الرمز. ويؤدي العرض هذا العمل بصلاحيات DEFINER الخاص به، وهو افتراضيًا المستخدم الذي أنشأ العرض - أي بالصلاحيات الكاملة للمستخدم، لا بالصلاحيات التي تركتها له عبارة GRANTS في الرمز.

ولذلك فإن الرمز المسموح له بإنشاء جداول أو عروض أو قواميس يمكنه عمليًا تجاوز كلا الحدّين: إذ يستطيع أن يخلّف وراءه مهمة دائمة تستمر في العمل بعد انقضاء المهلة النهائية وتؤدي، بصلاحيات المستخدم، ما لم يكن مسموحًا للرمز نفسه بأدائه. لذا امنح الرمز ما يحتاجه التطبيق فقط - وهو عادةً SELECT وINSERT على جداول محددة - وأبقِ CREATE TABLE وCREATE VIEW وCREATE DICTIONARY وصلاحيات ACCESS MANAGEMENT خارج عبارة GRANTS الخاصة به إذا أردت للحدود أن تظل سارية.

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