> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> دليل حول المصادقة القائمة على JWT والمستخدمين المؤقتين في ClickHouse Cloud

# المصادقة باستخدام JWT

export const CloudOnlyBadge = () => {
  return <div className="cloudBadge">
            <div className="cloudIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path fillRule="evenodd" clipRule="evenodd" d="M5.33395 12.6667H12.3739C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00004 12.3739 8.00004H12.0839V7.33337C12.0839 5.12671 10.2906 3.33337 8.08395 3.33337C6.09928 3.33337 4.45395 4.78537 4.14195 6.68204C2.55728 6.76271 1.29395 8.06204 1.29395 9.66671C1.29395 11.3234 2.63728 12.6667 4.29395 12.6667H5.33395Z" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            {'متاح فقط في ClickHouse Cloud'}
        </div>;
};

يمكن لـ ClickHouse مصادقة المستخدمين باستخدام JSON Web Tokens ‏(JWTs). وعلى عكس موفّرات المصادقة الخارجية الأخرى مثل [LDAP](/ar/concepts/features/security/external-authenticators/ldap) أو [Kerberos](/ar/concepts/features/security/external-authenticators/kerberos)، فإن المصادقة عبر JWT لا تتحقق من هوية المستخدمين الموجودين مسبقًا. وبدلًا من ذلك، تُنشئ **مستخدمين مؤقتين** ديناميكيًا من المطالبات المضمّنة في كل رمز مميز. ولا يوجد هؤلاء المستخدمون إلا في الذاكرة، ويحصلون على صلاحيات وصول مشتقة من مطالبات الـ رمز المميز، وتتم إزالتهم تلقائيًا بعد انتهاء صلاحية الـ رمز المميز.

وهذا يجعل المصادقة عبر JWT مختلفة جذريًا عن الطرق المعتمدة على password أو الشهادات: فلا توجد عبارة `CREATE USER ... IDENTIFIED WITH jwt`، وأي محاولة لذلك تؤدي إلى ظهور استثناء. ويُدار مستخدمو JWT بالكامل وفقًا لدورة حياة الـ رمز المميز.

<div id="overview">
  ## نظرة عامة
</div>

يعمل تدفق المصادقة على النحو التالي:

1. يقدّم عميل رمز JWT موقّعًا عبر إحدى آليات النقل المدعومة (ترويسة HTTP ‏`Authorization: Bearer`، أو البروتوكول الأصلي عبر TCP، أو الحقل `jwt` في gRPC).
2. يتحقق ClickHouse من توقيع الرمز المميز.
3. يُتحقق من المطالبات المطلوبة (`exp`, `iat`, `iss`, `sub`, `aud`).
4. يُنشأ مستخدم مؤقت في الذاكرة مع صلاحيات وصول مشتقة من مطالبات الرمز المميز `clickhouse:grants` و`clickhouse:roles`، ومتقاطعة مع حدّ الصلاحيات.
5. عند انتهاء صلاحية الرمز المميز، تزيل مهمة جمع البيانات المهملة في الخلفية هذا المستخدم.

<div id="token-claims">
  ## مطالبات الرمز المميز
</div>

<div id="required-claims">
  ### المطالبات المطلوبة
</div>

يجب أن يحتوي كل JWT يُقدَّم إلى ClickHouse على المطالبات التالية:

| المطالبة | الوصف                                                                             |
| -------- | --------------------------------------------------------------------------------- |
| `alg`    | خوارزمية التوقيع (مطالبة في الترويسة). القيم المدعومة: `HS256` و`RS256` و`ES256`. |
| `exp`    | وقت انتهاء الصلاحية. يحدّد `valid_until` للمستخدم المؤقت.                         |
| `iat`    | وقت الإصدار. يُستخدم لمنع إعادة استخدام الرموز المميزة الأقدم للهوية نفسها.       |
| `iss`    | الجهة المُصدِرة. يُطابَق مع الجهة المُصدِرة المتوقعة لدى المزوّد.                 |
| `sub`    | المعرّف. يصبح جزءًا من اسم المستخدم المُنشأ.                                      |
| `aud`    | الجمهور المستهدف. يُطابَق مع الجمهور المستهدف المتوقع لدى المزوّد.                |

تكون مطالبة `kid` في الترويسة (معرّف المفتاح) مطلوبة أيضًا عند استخدام تحليل المفاتيح المستند إلى JWKS.

<Info>
  **يدعم وضع JWKS مفاتيح RSA فقط**

  في حين أن موفّري المفاتيح الثابتة يقبلون أيًا من `HS256` أو `RS256` أو `ES256`، فإن الموفّرين المستندين إلى JWKS لا يقبلون إلا JWKs التي تكون فيها قيمة `kty` هي `RSA` (أي الرموز المميزة الموقّعة باستخدام `RS256`). ولا يمكن التحقق من الرموز المميزة الموقّعة بمفاتيح HMAC (`HS256`) أو EC (`ES256`) باستخدام endpoint لـ JWKS، لذلك سيتم رفضها.
</Info>

<div id="other-recognized-claims">
  ### مطالبات أخرى معترف بها
</div>

| المطالبة | الوصف                                                                                                  |
| -------- | ------------------------------------------------------------------------------------------------------ |
| `nbf`    | وقت "ليس قبل". هذه المطالبة ليست مطلوبة، ولكن إذا كانت موجودة، فسيتم رفض الرموز المميزة قبل هذا الوقت. |
| `jti`    | محجوزة. تُقبل في الرموز المميزة، ولكن لا يُتحقق منها أو تُستخدم حاليًا.                                |

<div id="optional-claims">
  ### المطالبات الاختيارية
</div>

| المطالبة                                                                                                                     | الاسم الافتراضي     | الوصف                                                                                                                                    |
| ---------------------------------------------------------------------------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| الامتيازات                                                                                                                   | `clickhouse:grants` | مصفوفة JSON تضم مقاطع من عبارة SQL `GRANT`، مثل `["SELECT ON db.*", "INSERT ON db.table1"]`. ويُفسَّر كل عنصر على أنه متن عبارة `GRANT`. |
| الأدوار                                                                                                                      | `clickhouse:roles`  | مصفوفة JSON لأسماء الأدوار المراد إسنادها، مثل `["analyst", "reader"]`.                                                                  |
| يمكن إعادة تعيين أسماء المطالبات الافتراضية إلى أسماء مطالبات مخصّصة إذا كان موفّر الهوية لديك يستخدم اصطلاحات تسمية مختلفة. |                     |                                                                                                                                          |

<div id="example-token-header-and-payload">
  ### مثال على رأس الرمز المميز وحمولته
</div>

```json theme={null}
{
  "alg": "RS256",
  "kid": "my-key-id"
}
```

```json theme={null}
{
  "iss": "https://idp.example.com",
  "sub": "jane.doe",
  "aud": "my-clickhouse-cluster",
  "exp": 1719504000,
  "iat": 1719500400,
  "clickhouse:grants": ["SELECT ON analytics.*", "INSERT ON analytics.events"],
  "clickhouse:roles": ["analyst"]
}
```

<div id="ephemeral-user-behavior">
  ## سلوك المستخدم المؤقت
</div>

يختلف مستخدمو JWT عن مستخدمي ClickHouse العاديين في عدة نواحٍ مهمة.

<div id="identity-and-naming">
  ### الهوية والتسمية
</div>

يتلقى كل مستخدم JWT معرّف UUID حتميًا يُحتسب من مطالبات `iss` و`sub` و`aud`. ويظل هذا المعرّف **ثابتًا** عبر عمليات تسجيل الدخول. لذا فإن المستخدم الذي يسجّل الدخول عدة مرات باستخدام رموز مميزة مختلفة (ولكن مع issuer وsubject وaudience نفسها) يحصل دائمًا على معرّف UUID نفسه.

أما اسم المستخدم فهو **غير ثابت**. ويُنشأ على النحو التالي:

```text theme={null}
JWT::<issuer>::<audience>::<subject>::<claims_hash>
```

يتغيّر الجزء `<claims_hash>` كلما تغيّرت المطالبات `clickhouse:roles` أو `clickhouse:grants`. وهذا يعني أن الرموز المميّزة ذات مجموعات الأدوار أو الامتيازات المختلفة تُنتِج أسماء مستخدمين مختلفة حتى للهوية نفسها.

<div id="access-rights">
  ### صلاحيات الوصول
</div>

تُحتسب صلاحيات الوصول الفعلية على النحو التالي:

```text theme={null}
effective_rights = permission_limit ∩ (token_grants ∪ token_roles)
```

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

<div id="token-freshness">
  ### حداثة الرمز المميز
</div>

يتتبّع ClickHouse مطالبة `iat` ‏(وقت الإصدار) لأحدث رمز مميز تمت مصادقته لكل هوية مستقرة. وإذا قُدِّم رمز مميز بقيمة `iat` تساوي القيمة المخزنة أو تسبقها، يعيد الخادم استخدام المستخدم المؤقت الحالي من دون إعادة تقييم المطالبات. ويمنع ذلك الرموز المميزة الأقدم من تقليص أذونات المستخدم.

<div id="lifetime-and-garbage-collection">
  ### دورة الحياة وجمع البيانات المهملة
</div>

يتم إنشاء المستخدمين المؤقتين عند مصادقة الرمز المميز لأول مرة، ثم تُزيلهم مهمة جمع البيانات المهملة في الخلفية بعد انقضاء `valid_until` (المشتق من `exp`). ويتم التحكم في الفاصل الزمني لـ GC بواسطة المعلَمة `gc_interval` (الافتراضي: 5 دقائق).

بين مرات تشغيل GC، قد يظل المستخدمون منتهو الصلاحية ظاهرين في `system.users`، لكن لن يعودوا قادرين على المصادقة.

<div id="persistent-access-assignments">
  ### تعيينات صلاحيات الوصول الدائمة
</div>

نظرًا لأن معرّف UUID ثابت، يمكنك إسناد ملفات تعريف الإعدادات، والحصص، وسياسات الصفوف، وسياسات إخفاء الأعمدة إلى مستخدم JWT باستخدام عبارات SQL. وتظل هذه التعيينات محفوظة في مخزن التحكم في الوصول (على القرص أو في ZooKeeper)، وتبقى سارية بعد انتهاء صلاحية الرمز المميز وإعادة المصادقة.

استخدم اسم المستخدم الحالي للإشارة إلى المستخدم:

```sql theme={null}
ALTER SETTINGS PROFILE my_profile ADD TO 'JWT::ClickHouse::my-service-id::jane.doe::<claims-hash>';
```

<Note>
  يمكن العثور على اسم المستخدم ومعرّف UUID لهوية معيّنة في العمودين `name` و`id` في `system.users` ما دام المستخدم نشطًا.
</Note>

لاحظ أن `ALTER USER` لا يعمل مباشرةً مع مستخدمي JWT، لأنهم للقراءة فقط. لإسناد ملفات تعريف الإعدادات أو الحصص أو السياسات، استخدم عبارات `ALTER SETTINGS PROFILE` أو `ALTER QUOTA` أو `ALTER ROW POLICY` كما هو موضح أعلاه.

<div id="differences-from-regular-users">
  ## الاختلافات عن المستخدمين العاديين
</div>

| الميزة                                | مستخدمو JWT                                    | المستخدمون العاديون                 |
| ------------------------------------- | ---------------------------------------------- | ----------------------------------- |
| الإنشاء                               | تلقائي من مطالبات الرمز                        | عبارة `CREATE USER`                 |
| التخزين                               | في الذاكرة فقط (مؤقت)                          | القرص أو ZooKeeper أو ملف الإعدادات |
| `CREATE USER ... IDENTIFIED WITH jwt` | غير مدعوم (يؤدي إلى استثناء)                   | جميع أنواع المصادقة الأخرى مدعومة   |
| `ALTER USER` / `DROP USER`            | غير مدعوم                                      | مدعوم                               |
| النسخ الاحتياطي والاستعادة            | غير مشمولين                                    | مشمولان                             |
| اسم المستخدم                          | يُنشأ تلقائيًا، وغير ثابت                      | يختاره المسؤول، وثابت               |
| معرّف UUID                            | يُشتق حتميًا من `iss`+`sub`+`aud`              | عشوائي عند الإنشاء                  |
| مدة الصلاحية                          | مقيّدة بـ `exp` الخاص بالرمز                   | حتى يُحذف صراحةً                    |
| صلاحيات الوصول                        | مشتقة من مطالبات الرمز، ومقيّدة بحدّ الصلاحيات | تُمنح صراحةً عبر `GRANT`            |
| قيود المضيف                           | تهيئة الشبكة الخاصة بكل موفّر                  | عبارة `HOST` لكل مستخدم             |
| ملفات تعريف الإعدادات                 | يمكن إسنادها بواسطة معرّف UUID (بشكل دائم)     | قابلة للتهيئة مباشرةً               |
| الحصص وسياسات الصفوف                  | يمكن إسنادها بواسطة معرّف UUID (بشكل دائم)     | قابلة للتهيئة مباشرةً               |
| الأدوار الافتراضية                    | غير قابلة للتهيئة                              | قابلة للتهيئة                       |

<div id="sql-security-definer-views">
  ## طرق العرض SQL SECURITY DEFINER
</div>

عندما ينشئ مستخدم JWT مؤقت طريقة عرض باستخدام `SQL SECURITY DEFINER`، ينشئ الخادم تلقائيًا نسخة ظل دائمة من هذا المستخدم لتكون مُعرِّف طريقة العرض. ويتميّز هذا المستخدم الظل بما يلي:

* يحمل الاسم `<original_jwt_username>:definer`
* لديه `NO_AUTHENTICATION` (ولا يمكن استخدامه لتسجيل الدخول)
* يحتفظ بحقوق الوصول نفسها التي كانت لدى مستخدم JWT الأصلي وقت إنشاء طريقة العرض

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

<div id="client-usage">
  ## استخدام العميل البرمجي
</div>

<div id="passing-token-directly">
  ### تمرير رمز مميز مباشرةً
</div>

استخدم الخيار `--jwt` مع `clickhouse-client` للمصادقة باستخدام رمز مميز تم الحصول عليه مسبقًا:

```bash theme={null}
clickhouse-client --host your-instance.clickhouse.cloud --secure --jwt '<your_jwt_token>'
```

<Note>
  الخيار `--jwt` لا يمكن استخدامه مع `--user`. عند تحديد `--jwt`، يُشتق اسم المستخدم من الرمز المميّز.
</Note>

<div id="http-interface">
  ### واجهة HTTP
</div>

أرسل الرمز المميز كـ Bearer token في ترويسة `Authorization`:

```bash theme={null}
curl -H 'Authorization: Bearer <your_jwt_token>' \
    'https://your-instance.clickhouse.cloud:8443/?query=SELECT+currentUser()'
```

<Warning>
  أرسل دائمًا رموز JWT عبر HTTPS. إن رمز Bearer المُرسَل عبر HTTP غير المشفّر يكون مكشوفًا لأي شخص على مسار الشبكة، ويُعدّ ذلك بمثابة تسريب لبيانات الاعتماد.
</Warning>

<div id="oauth2-device-code-login">
  ### تسجيل الدخول باستخدام رمز جهاز OAuth2
</div>

يدعم `clickhouse-client` مسار رمز جهاز OAuth2 التفاعلي عبر الخيار `--login`. بالنسبة إلى نقاط النهاية في ClickHouse Cloud، يُجري العميل تلقائيًا عملية تبادل الرموز المميزة للحصول على JWT خاص بـ ClickHouse. تُحدَّث الرموز المميزة تلقائيًا أثناء الجلسة. وعند الحصول على رمز مميز جديد، يعيد العميل الاتصال تلقائيًا.

```bash theme={null}
clickhouse-client --host your-instance.clickhouse.cloud --login
```

<div id="clickhouse-cloud-built-in">
  ## مُصادِق JWT المضمّن في ClickHouse Cloud
</div>

تأتي كل خدمة في ClickHouse Cloud مع مُصادِق JWT مُعرَّف مسبقًا يُستخدم في SQL Console ومع تدفّق `--login` في `clickhouse-client`. يُضبط هذا المُصادِق على النحو التالي:

| المَعلمة         | القيمة                                                         |
| ---------------- | -------------------------------------------------------------- |
| `iss` (issuer)   | `ClickHouse`                                                   |
| `aud` (audience) | معرّف UUID الخاص بالخدمة (ويظهر في عنوان URL لوحدة تحكم Cloud) |
| `sub` (subject)  | عنوان البريد الإلكتروني لحسابك في ClickHouse Cloud             |

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

لا تحتاج إلى تهيئة أي شيء لاستخدام هذا المُصادِق. إذ يُوفَّر تلقائيًا عند إنشاء الخدمة.

<div id="interserver-communication">
  ## الاتصال بين الخوادم
</div>

عندما يُعاد توجيه الاستعلام إلى сегмент أو نسخة متماثلة أخرى، يُضمَّن رمز JWT في بروتوكول الاتصال بين الخوادم. وتُعيد العقدة البعيدة المصادقة على الرمز بشكل مستقل، وتُنشئ مستخدمًا مؤقتًا خاصًا بها.

<div id="troubleshooting">
  ## استكشاف الأخطاء وإصلاحها
</div>

* **لم تُمنح صلاحيات الوصول:** قد يفتقر الدور أو المستخدم المشار إليه إلى الامتيازات المطلوبة. تأكد من أن الأدوار المشار إليها في `clickhouse:roles` موجودة وتتضمن الامتيازات المناسبة.
* **رُفض الرمز المميز:** تحقّق من أن `iss` و`aud` وخوارزمية التوقيع في الرمز المميز لديك تطابق ما يتوقعه موفّر JWT. إذا كان JWKS مستخدمًا، فتأكد من أن `kid` الخاص بالرمز المميز يطابق مفتاحًا في مجموعة مفاتيح الموفّر.
* **يختفي المستخدم بين الاستعلامات:** يُزال المستخدمون المؤقتون بعد انتهاء صلاحية الرمز المميز. استخدم عميلًا يدعم تحديث الرمز المميز (مثل وضع `--login`) للجلسات طويلة الأمد.
* **يفشل `CREATE USER ... IDENTIFIED WITH jwt`:** هذا متوقع. لا يمكن إنشاء مستخدمي JWT عبر DDL، إذ تُدار بالكامل من خلال دورة حياة الرمز المميز.