تُرجمت هذه الصفحة من الإنجليزية بمساعدة الذكاء الاصطناعي. إذا اختلفت النسختان، فالمرجع هو النسخة الإنجليزية.
إدارة الوصول
تجري إدارة وصول الجهات المستدعية مصادقة الجهة المستدعية لجلسة StackQL وتخول كل جملة وفقًا لسياسة. وهي مستقلة عن بيانات اعتماد الموفرين، التي يستمر توفيرها عبر العلامة --auth أو متغيرات البيئة أو جلسات الموفر. وهي معطلة افتراضيًا، وتعمل عمليات النشر التي لا يتم فيها تمكينها كما كانت من قبل. متاحة في StackQL من الإصدار v1.0 فصاعدًا.
راجع أيضًا:
[ العلامات العامة ] [mcp] [whoami] [groups]
تمكين إدارة الوصول
يتم تمكين إدارة الوصول بتشغيل StackQL مع العلامة العامة --access.config التي تشير إلى ملف تكوين JSON. يبدأ المثال واجهة أوامر تفاعلية في الوضع المحمي؛ ويتم تمكين الأمرين exec وmcp بالطريقة نفسها.
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 نفسه وفي دليل كيانات الأمان نفسه.
JWT
تقدم الجهة المستدعية رمزًا مميزًا موقعًا رقميًا، يتم التحقق منه دون اتصال بالشبكة مقابل المفاتيح المقفلة في التكوين. يحدد التكوين الأدنى جهة الإصدار والجمهور اللذين يجب أن يحملهما الرمز المميز، ويسرد مفتاحًا عامًا واحدًا، ويمنح المجموعة readers حق الوصول للقراءة:
{
"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 لكل رمز مميز مقبول مع الموضوع الذي يحدده. يناسب هذا مجموعة صغيرة وثابتة من هويات الخدمات لا يستدعي فيها الأمر تشغيل جهة إصدار للرموز المميزة:
{
"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) الذي يجب أن يكون قد أصدر الشهادة، ويحدد أي اسم بديل للموضوع يحمل الهوية:
{
"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 وإلى القواعد:
{
"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 | روابط كيانات الأمان بالمجموعات. |
وفّر الجداول والهويات والعضويات من خلال اتصال موثوق لإدارة قاعدة البيانات قبل خدمة الاستعلامات المحمية:
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 الخلفية صراحة:
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 | إلغاء مرجعية متغيرات الجلسة والأسرار |
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؛ وتكوين شهادة TLS ومفتاحها على الخادم إلزامي، ولا يعود الطلب الذي لا يحمل بيانات اعتماد أبدًا إلى استخدام الرمز المميز الموجود في بيئة الخادم.
فحص الجهة المستدعية
في جلسة تمت مصادقتها، تعيد الدالة whoami() معرف كيان الأمان وتعيد الدالة groups() مجموعات الدليل كمصفوفة JSON:
SELECT whoami() AS principal, groups() AS memberships;
|-----------|-------------|
| principal | memberships |
|-----------|-------------|
| alice | ["readers"] |
|-----------|-------------|
تتطلب الدالتان جلسة بدأت باستخدام العلامة --access.config.
شروح تفصيلية
يتضمن مستودع StackQL أربعة شروح تفصيلية قابلة للتنفيذ، واحد لكل وضع مصادقة، يشغلها برنامج نصي بلغة Python يوفر دليلًا توضيحيًا ويتحقق من استعلام. لا تحتاج إلى حساب سحابي، وتشغلها مجموعة اختبارات المشروع.