# إدارة الوصول

> إدارة وصول الجهات المستدعية في StackQL بتفعيل اختياري: مصادقة الجهات المستدعية باستخدام JWT أو رموز مميزة من نوع bearer أو TLS المتبادل أو هوية نظام التشغيل المحلي، وربطها بكيانات أمان ومجموعات في دليل، وتخويل الجمل بقواعد السياسة.

Source: https://stackql.io/ar/command-line-usage/access-management

تجري إدارة وصول الجهات المستدعية مصادقة الجهة المستدعية لجلسة StackQL وتخول كل جملة وفقًا لسياسة.  وهي مستقلة عن بيانات اعتماد الموفرين، التي يستمر توفيرها عبر العلامة `--auth` أو متغيرات البيئة أو [جلسات الموفر](/getting-started/provider-sessions).  وهي معطلة افتراضيًا، وتعمل عمليات النشر التي لا يتم فيها تمكينها كما كانت من قبل.  متاحة في StackQL من الإصدار `v1.0` فصاعدًا.

راجع أيضًا:  
[[ العلامات العامة ]](/command-line-usage/global-flags) [[` mcp `]](/command-line-usage/mcp) [[` whoami `]](/language-spec/functions/session/whoami) [[` groups `]](/language-spec/functions/session/groups)

* * * 

## تمكين إدارة الوصول

يتم تمكين إدارة الوصول بتشغيل StackQL مع العلامة العامة `--access.config` التي تشير إلى ملف تكوين JSON.  يبدأ المثال واجهة أوامر تفاعلية في الوضع المحمي؛ ويتم تمكين الأمرين `exec` و`mcp` بالطريقة نفسها.

```bash
stackql --access.config '{"path": "/etc/stackql/access.json"}' shell
```

تقبل العلامة `--access.config` مغلف JSON بمفتاح واحد هو `path`؛ ويُقبل أيضًا مسار ملف مجرد.  يتم تحميل التكوين مرة واحدة عند بدء التشغيل، لذا دوّر المفاتيح أو السياسة من خلال إعادة تشغيل خاضعة للتحكم.

أثناء تمكين إدارة الوصول، لا تعمل إلا الأوامر `exec` و`shell` و`mcp` و`version`؛ أما الأوامر الأخرى، بما فيها `registry`، فترفض العمل بدلًا من تجاوز المسار المحمي.  ويرفض العمل أيضًا الأمر `srv` ونوع الخادم `reverse_proxy` في MCP، لأن تبعية بروتوكول الاتصال الخاص بـ PostgreSQL لا تعرض بعد أدلة المصادقة لكل اتصال.  ترفض جملتا SQL `AUTH` و`AUTH REVOKE` العمل في الوضع المحمي؛ لذا وفّر بيانات اعتماد الموفرين من خلال تكوين المضيف بدلًا من ذلك.  يعيد الأمر `exec` المحمي الذي يفشل حالة الخروج `1` بعد عرض الخطأ.

## أوضاع المصادقة

يحدد ملف التكوين قيمة واحدة للحقل `type`: `jwt` (الافتراضي عند حذفه) أو `bearer` أو `mtls` أو `local_os`.  التكوين بتنسيق JSON صارم: يتم رفض الحقول غير المعروفة والحقول التي تنتمي إلى وضع آخر.  تشترك جميع الأوضاع في الحقل `rules` نفسه وفي [دليل كيانات الأمان](#principal-directory) نفسه.

### JWT

تقدم الجهة المستدعية رمزًا مميزًا موقعًا رقميًا، يتم التحقق منه دون اتصال بالشبكة مقابل المفاتيح المقفلة في التكوين.  يحدد التكوين الأدنى جهة الإصدار والجمهور اللذين يجب أن يحملهما الرمز المميز، ويسرد مفتاحًا عامًا واحدًا، ويمنح المجموعة `readers` حق الوصول للقراءة:

```json
{
  "type": "jwt",
  "issuer": "https://identity.example",
  "audience": "stackql",
  "keys": [
    {"kid": "primary", "algorithm": "EdDSA", "public_key_pem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"}
  ],
  "rules": [
    {"subject": "group:readers", "resource": "host/sql/read", "action": "execute"}
  ]
}
```

جهة الإصدار والجمهور والمفاتيح العامة مقفلة في التكوين؛ ولا يوجد اكتشاف OIDC.  الخوارزميات المقبولة هي `EdDSA` و`RS256` و`RS384` و`RS512` و`PS256` و`PS384` و`PS512` و`ES256` و`ES384` و`ES512`، ويجب ألا يقل طول مفاتيح RSA عن 2048 بت.  يرتبط كل مفتاح بالخوارزمية المكونة له.  يتم رفض الرموز المميزة التي لها معرف مفتاح غير معروف، أو توقيع غير صالح، أو تاريخ انتهاء صلاحية مفقود أو سابق، أو قيمة `nbf` أو `iat` في المستقبل، أو جهة إصدار أو جمهور غير صحيح.  لا يتم استخدام مطالبات المجموعات وعناوين URL التي يحملها الرمز المميز للثقة أو لعضوية الدليل.

### رمز مميز ثابت من نوع bearer

تقدم الجهة المستدعية رمزًا مميزًا غير شفاف، ويسرد التكوين ملخص SHA-256 لكل رمز مميز مقبول مع الموضوع الذي يحدده.  يناسب هذا مجموعة صغيرة وثابتة من هويات الخدمات لا يستدعي فيها الأمر تشغيل جهة إصدار للرموز المميزة:

```json
{
  "type": "bearer",
  "issuer": "local-tokens",
  "tokens": [{"subject": "alice", "sha256": "<64 hexadecimal characters: the SHA-256 of the token>"}],
  "rules": [{"subject": "group:readers", "resource": "host/sql/read", "action": "execute"}]
}
```

يتم تكوين ملخص SHA-256 لكل رمز مميز فقط، ويجب أن تكون الملخصات فريدة.  يتطلب تغيير الملخصات المكونة إعادة التشغيل.

### TLS المتبادل

يتم تحديد هوية الجهة المستدعية من خلال شهادة العميل التي تقدمها عبر وسيلة النقل HTTPS في MCP.  يحمل التكوين المرجع المصدق (CA) الذي يجب أن يكون قد أصدر الشهادة، ويحدد أي اسم بديل للموضوع يحمل الهوية:

```json
{
  "type": "mtls",
  "issuer": "client-certificates",
  "client_ca_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
  "certificate_identity": "uri_san",
  "rules": [{"subject": "group:readers", "resource": "host/sql/read", "action": "execute"}]
}
```

يتم التحقق من سلسلة شهادات العميل مقابل الحقل `client_ca_pem`، ويؤخذ موضوع الهوية من SAN واحد تحديدًا من النوع المكون، `uri_san` أو `dns_san`.  لا يوجد بديل احتياطي يعتمد على Common Name.  يتوفر TLS المتبادل عبر وسيلة النقل HTTPS في MCP فقط.

### هوية نظام التشغيل المحلي

لا يتم تبادل أي بيانات اعتماد: الموضوع هو هوية نظام التشغيل التي تعمل بها عملية StackQL.  لا يحتاج التكوين إلا إلى تسمية في الحقل `issuer` وإلى القواعد:

```json
{
  "type": "local_os",
  "issuer": "this-host",
  "rules": [{"subject": "group:readers", "resource": "host/sql/read", "action": "execute"}]
}
```

موضوع الهوية هو قيمة UID الفعلية في Unix أو قيمة SID في Windows لعملية StackQL، بما في ذلك قيم UID الرقمية للحاويات التي ليس لها إدخال في passwd.  لا يتم تقديم أي بيانات اعتماد ويتم تجاهل متغير البيئة `STACKQL_CALLER_TOKEN`.  هذا الوضع محلي فقط: يتم رفضه للجهات المستدعية عبر HTTP.  لا تمنح العضوية في مجموعات نظام التشغيل حق الوصول؛ بل تمنحه العضوية في الدليل فقط.

### الموعد النهائي للجلسة

لا يوجد للاستعلامات افتراضيًا موعد نهائي مشتق من المصادقة.  يتم التحقق من بيانات الاعتماد وتحديث العضوية في الدليل لكل جملة جديدة، لذا لا يمكن لبيانات اعتماد منتهية الصلاحية بدء عمل جديد، لكن انتهاء الصلاحية لا يقطع جملة تم تخويلها بالفعل.  عيّن `"enforce_session_deadline": true` للإلغاء عند بلوغ `max_session_seconds` (القيمة الافتراضية `300`، والحد الأقصى `86400`)، مع تقصير المدة عند انتهاء صلاحية JWT أو الشهادة.  لا يجدد هذا الرموز المميزة.

## دليل كيانات الأمان

يتم ربط الهويات بكيانات الأمان، وكيانات الأمان بالمجموعات، في أربعة جداول في واجهة SQL الخلفية المكونة (SQLite أو PostgreSQL):

| الجدول | المحتويات |
|--|--|
| `stackql_access_principals` | معرف كيان الأمان وكائن JSON من سمات السلاسل النصية.  تحدد السمة `tenant` مساحة الاسم لحالة IaC في مرحلة المعاينة. |
| `stackql_access_identities` | ربط زوج `(issuer, subject)` الذي تم التحقق منه بمعرف كيان الأمان. |
| `stackql_access_groups` | معرفات المجموعات. |
| `stackql_access_memberships` | روابط كيانات الأمان بالمجموعات. |

وفّر الجداول والهويات والعضويات من خلال اتصال موثوق لإدارة قاعدة البيانات قبل خدمة الاستعلامات المحمية:

```sql
INSERT INTO stackql_access_principals (id, attributes) VALUES ('alice', '{}');
INSERT INTO stackql_access_groups (id) VALUES ('readers');
INSERT INTO stackql_access_identities (issuer, subject, principal_id)
VALUES ('https://identity.example', 'alice', 'alice');
INSERT INTO stackql_access_memberships (principal_id, group_id) VALUES ('alice', 'readers');
```

استخدم جهة الإصدار والموضوع الفعليين للوضع: بالنسبة إلى هوية نظام التشغيل المحلي قد تكون القيمة `('this-host', '1000')`، وبالنسبة إلى TLS المتبادل `('client-certificates', 'spiffe://example/alice')`.  حدّد واجهة SQL الخلفية صراحة:

```bash
stackql --access.config '{"path":"/etc/stackql/access.json"}' \
  --sqlBackend '{"dbEngine":"postgres_tcp","dsn":"postgres://runtime@localhost/stackql?sslmode=require","sqlDialect":"postgres"}' \
  exec 'SELECT whoami(), groups();'
```

ينتج الدليل لقطة غير قابلة للتغيير لكل جملة.  الإبطال هو تنفيذ `DELETE FROM stackql_access_memberships` على اتصال الإدارة؛ وترى الجملة التالية اللقطة الجديدة.  تؤدي الهويات غير المعروفة وغياب المخطط والبيانات غير جيدة التكوين وانقطاع الدليل جميعها إلى رفض الوصول.  لا يمكن لجمل SQL المحمية العادية الوصول إلى جداول الدليل.  أبق عمليات الكتابة على العضوية على اتصال الإدارة، واحم ملف قاعدة البيانات، واستخدم امتيازات منفصلة لقاعدة البيانات للإدارة ولوقت التشغيل حيثما تدعمها واجهة SQL الخلفية.

## قواعد السياسة

تمنح كل قاعدة إجراء `action` واحدًا على مورد `resource` واحد لموضوع `subject` بالشكل `group:<group id>`.  استخدم معرفات الأساليب والعمليات المجمعة من مستندات الموفرين الموثوقة؛ ويمنح حرف البدل للعمليات أساليب تعديل البيانات بالإضافة إلى عمليات القراءة.

تمتلك المجموعة `readers` ضمنيًا قدرة SQL للقراءة الآمنة الخاصة بالمضيف.  تتطلب عمليات القراءة من كيانات الأمان خارج تلك المجموعة `host/sql/read`، وتتطلب الجمل الأخرى `execute` على `host/sql/<statement kind>`.  تتطلب عمليات الموفرين واستخدام بيانات الاعتماد دائمًا قواعد صريحة، ومنح الوصول إلى مجموعة لا يمنح الوصول إلى أساليبها الأساسية.  عمليات تحقق إضافية على المضيف:

| المورد | الإجراء | النطاق |
|--|--|--|
| `host/sql/read` | `execute` | جمل القراءة خارج مجموعة القراء الضمنية |
| `host/sql/exec` | `execute` | جملة `EXEC` الأصلية، بما في ذلك `EXEC` المتداخلة |
| `host/iac/run`، `host/iac/destroy` | `execute` | علاقات IaC في مرحلة المعاينة، رغم استخدامها بناء جملة `SELECT` |
| `host/function/<name>` | `execute` | الدوال خارج قائمة السماح الصغيرة للدوال المعروفة بأنها نقية |
| `host/backend` | `read` | علاقات واجهة SQL الخلفية المخزنة والخارجية غير الشفافة |
| `host/credentials` | `reload` | الأداة `reload_credentials` في MCP |
| `session/variables` | `read` | إلغاء مرجعية [متغيرات الجلسة](/getting-started/session-variables) والأسرار |
| `session/config` | `write` | `SET` و`UNSET` |

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

## نقاط الدخول

| المصادقة | `exec` و`shell` وMCP عبر stdio | MCP عبر HTTPS |
|--|--|--|
| JWT | متغير البيئة `STACKQL_CALLER_TOKEN` | رأس الطلب `Authorization: Bearer` |
| رمز مميز ثابت من نوع bearer | متغير البيئة `STACKQL_CALLER_TOKEN` | رأس الطلب `Authorization: Bearer` |
| نظام التشغيل المحلي | قيمة UID أو SID الفعلية للعملية؛ بدون بيانات اعتماد | مرفوض |
| TLS المتبادل | مرفوض: لا يوجد اتصال TLS تم التحقق منه | سلسلة شهادات العميل التي تم التحقق منها وSAN واحد مكون |

وفّر بيانات اعتماد الرمز المميز المحلي من خلال بيئة العملية، ولا توفرها أبدًا كقيمة حرفية في SQL أو كوسيطة في سطر الأوامر.  عبر HTTPS، تحل أداة التحقق من الجهة المستدعية محل تقييد bearer المشترك القائم على `auth_token_env_var` الموضح في [مصادقة عملاء HTTP](/command-line-usage/mcp#http-client-authentication)؛ وتكوين شهادة TLS ومفتاحها على الخادم إلزامي، ولا يعود الطلب الذي لا يحمل بيانات اعتماد أبدًا إلى استخدام الرمز المميز الموجود في بيئة الخادم.

## فحص الجهة المستدعية

في جلسة تمت مصادقتها، تعيد الدالة `whoami()` معرف كيان الأمان وتعيد الدالة `groups()` مجموعات الدليل كمصفوفة JSON:

```sql
SELECT whoami() AS principal, groups() AS memberships;
```

```
|-----------|-------------|
| principal | memberships |
|-----------|-------------|
| alice     | ["readers"] |
|-----------|-------------|
```

تتطلب الدالتان جلسة بدأت باستخدام العلامة `--access.config`.

## شروح تفصيلية

يتضمن مستودع StackQL [أربعة شروح تفصيلية قابلة للتنفيذ](https://github.com/stackql/stackql/blob/main/docs/examples/access-management/README.md)، واحد لكل وضع مصادقة، يشغلها برنامج نصي بلغة Python يوفر دليلًا توضيحيًا ويتحقق من استعلام.  لا تحتاج إلى حساب سحابي، وتشغلها مجموعة اختبارات المشروع.
