14. البنية التحتية للمصادقة

تلميح

تحتاج مقتطفات الشيفرة في هذه الصفحة إلى الاستيرادات التالية إذا كنت خارج وحدة تحكم pyqgis:

from qgis.core import (
  QgsApplication,
  QgsRasterLayer,
  QgsAuthMethodConfig,
  QgsDataSourceUri,
  QgsPkiBundle,
  QgsMessageLog,
)

from qgis.gui import (
    QgsAuthAuthoritiesEditor,
    QgsAuthConfigEditor,
    QgsAuthConfigSelect,
    QgsAuthSettingsWidget,
)

from qgis.PyQt.QtWidgets import (
    QWidget,
    QTabWidget,
)

from qgis.PyQt.QtNetwork import QSslCertificate

14.1. المقدمة

يمكن قراءة المرجع الخاص بالمستخدم للبنية التحتية للمصادقة في دليل المستخدم ضمن فقرة نظرة عامة على نظام المصادقة.

يصف هذا الفصل أفضل الممارسات لاستخدام نظام المصادقة من منظور المطوّر.

يُستخدم نظام المصادقة على نطاق واسع في QGIS Desktop من قِبل مزوّدي البيانات كلما تطلّب الوصول إلى مورد معيّن بيانات اعتماد، على سبيل المثال عندما تُنشئ طبقة اتصالًا بقاعدة بيانات Postgres.

توجد أيضًا بعض عناصر الواجهة في مكتبة gui الخاصة بـ QGIS يمكن لمطوّري الإضافات استخدامها لدمج البنية التحتية للمصادقة في شيفرتهم بسهولة:

• QgsAuthConfigEditor

• QgsAuthConfigSelect

• QgsAuthSettingsWidget

يمكن الاطلاع على مرجع جيد للشيفرة في tests code الخاصة بالبنية التحتية للمصادقة.

تحذير

بسبب القيود الأمنية التي أُخذت في الحسبان أثناء تصميم البنية التحتية للمصادقة، لا يُتاح لـ Python إلا جزء مختار من الدوال الداخلية.

14.2. المصطلحات

فيما يلي تعريفات لأكثر الكائنات شيوعًا التي يتناولها هذا الفصل.

كلمة المرور الرئيسية

كلمة مرور تتيح الوصول إلى بيانات الاعتماد المخزّنة في قاعدة بيانات المصادقة في QGIS وفك تشفيرها

قاعدة بيانات المصادقة

قاعدة بيانات SQLite باسم qgis-auth.db مشفّرة بـ Master Password تُخزَّن فيها Authentication Configuration، مثل اسم المستخدم/كلمة المرور، والشهادات والمفاتيح الشخصية، وجهات إصدار الشهادات

قاعدة بيانات المصادقة (Authentication DB)

Authentication Database

إعداد المصادقة

مجموعة من بيانات المصادقة تعتمد على Authentication Method. فمثلًا تخزّن طريقة المصادقة الأساسية (Basic) زوج اسم المستخدم/كلمة المرور.

إعداد المصادقة (Authentication Config)

Authentication Configuration

طريقة المصادقة

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

14.3. QgsAuthManager نقطة الدخول

يُعدّ الكائن الوحيد (singleton) QgsAuthManager نقطة الدخول لاستخدام بيانات الاعتماد المخزّنة في Authentication DB المشفّرة في QGIS، أي الملف qgis-auth.db الموجود في مجلد ملف تعريف المستخدم النشط.

يتولى هذا الصنف التفاعل مع المستخدم: إما بطلب تعيين كلمة مرور رئيسية أو باستخدامها بشفافية للوصول إلى المعلومات المخزّنة المشفّرة.

14.3.1. تهيئة المدير وتعيين كلمة المرور الرئيسية

يقدّم المقتطف التالي مثالًا على تعيين كلمة المرور الرئيسية لفتح الوصول إلى إعدادات المصادقة. التعليقات في الشيفرة مهمة لفهم المقتطف.

authMgr = QgsApplication.authManager()

# check if QgsAuthManager has already been initialized... a side effect
# of the QgsAuthManager.init() is that AuthDbPath is set.
# QgsAuthManager.init() is executed during QGIS application init and hence
# you do not normally need to call it directly.
if authMgr.authenticationDatabasePath():
    # already initialized => we are inside a QGIS app.
    if authMgr.masterPasswordIsSet():
        msg = 'Authentication master password not recognized'
        assert authMgr.masterPasswordSame("your master password"), msg
    else:
        msg = 'Master password could not be set'
        # The verify parameter checks if the hash of the password was
        # already saved in the authentication db
        assert authMgr.setMasterPassword("your master password",
                                          verify=True), msg
else:
    # outside qgis, e.g. in a testing environment => setup env var before
    # db init
    os.environ['QGIS_AUTH_DB_DIR_PATH'] = "/path/where/located/qgis-auth.db"
    msg = 'Master password could not be set'
    assert authMgr.setMasterPassword("your master password", True), msg
    authMgr.init("/path/where/located/qgis-auth.db")

14.3.2. إضافة مُدخل جديد لإعداد المصادقة إلى authdb

كل بيانات اعتماد مخزّنة هي نسخة من Authentication Configuration من الصنف QgsAuthMethodConfig، ويُوصَل إليها باستخدام سلسلة نصية فريدة مثل السلسلة التالية:

authcfg = 'fm1s770'

تُولَّد هذه السلسلة تلقائيًا عند إنشاء مُدخل باستخدام QGIS API أو الواجهة الرسومية، لكن قد يكون من المفيد تعيينها يدويًا إلى قيمة معروفة إذا كان يجب مشاركة الإعداد (ببيانات اعتماد مختلفة) بين عدة مستخدمين داخل مؤسسة.

يُعدّ QgsAuthMethodConfig الصنف الأساسي لأي Authentication Method. تعيّن كل طريقة مصادقة خريطة تجزئة (hash map) للإعداد تُخزَّن فيها معلومات المصادقة. فيما يلي مقتطف مفيد لتخزين بيانات اعتماد PKI-path لمستخدم افتراضي اسمه alice:

authMgr = QgsApplication.authManager()
# set alice PKI data
config = QgsAuthMethodConfig()
config.setName("alice")
config.setMethod("PKI-Paths")
config.setUri("https://example.com")
config.setConfig("certpath", "path/to/alice-cert.pem" )
config.setConfig("keypath", "path/to/alice-key.pem" )
# check if method parameters are correctly set
assert config.isValid()

# register alice data in authdb returning the ``authcfg`` of the stored
# configuration
authMgr.storeAuthenticationConfig(config)
newAuthCfgId = config.id()
assert newAuthCfgId

14.3.2.1. طرق المصادقة المتاحة

تُحمَّل مكتبات Authentication Method ديناميكيًا أثناء تهيئة مدير المصادقة. طرق المصادقة المتاحة هي:

الطريقة	وصف	المزوّدون المستهدفون
Basic	المصادقة باسم المستخدم وكلمة المرور	postgres، oracle، ows، wfs، wcs، wms، ogr، gdal، proxy
APIHeader	ترويسات HTTP	ows، wfs، wcs، wms
AWSS3	خدمة التخزين البسيط AWS Simple Storage Service	awss3
EsriToken	مصادقة ESRI المعتمدة على الرموز المميزة (token) لخوادم ArcGIS REST	arcgismapserver, arcgisfeatureserver
Identity-Cert	المصادقة بشهادة الهوية	ows، wfs، wcs، wms، postgres
MapTilerHmacSha256	مصادقة MapTiler HMAC-SHA256	wms، vectortile، xyzvectortiles
OAuth2	مصادقة OAuth2	ows، wfs، wcs، wms
PKI-Paths	المصادقة بمسارات PKI	ows، wfs، wcs، wms، postgres
PKI-PKCS#12	مصادقة PKI PKCS#12	ows، wfs، wcs، wms، postgres

14.3.2.2. إضافة جهات إصدار الشهادات

authMgr = QgsApplication.authManager()
# add authorities
cacerts = QSslCertificate.fromPath( "/path/to/ca_chains.pem" )
assert cacerts is not None
# store CA
authMgr.storeCertAuthorities(cacerts)
# and rebuild CA caches
authMgr.rebuildCaCertsCache()
authMgr.rebuildTrustedCaCertsCache()

14.3.2.3. إدارة حزم PKI باستخدام QgsPkiBundle

الصنف QgsPkiBundle صنف مساعد لتجميع حزم PKI المكوّنة من SslCert وSslKey وسلسلة جهات الإصدار (CA). فيما يلي مقتطف للحصول على حزمة محمية بكلمة مرور:

# add alice cert in case of key with pwd
caBundlesList = []  # List of CA bundles
bundle = QgsPkiBundle.fromPemPaths( "/path/to/alice-cert.pem",
                                     "/path/to/alice-key_w-pass.pem",
                                     "unlock_pwd",
                                     caBundlesList )
assert bundle is not None
# You can check bundle validity by calling:
# bundle.isValid()

راجع توثيق الصنف QgsPkiBundle لاستخراج الشهادة/المفتاح/جهات الإصدار من الحزمة.

14.3.3. حذف مُدخل من authdb

يمكننا حذف مُدخل من Authentication Database باستخدام مُعرّفه authcfg عبر المقتطف التالي:

authMgr = QgsApplication.authManager()
authMgr.removeAuthenticationConfig( "authCfg_Id_to_remove" )

14.3.4. ترك توسيع authcfg لـ QgsAuthManager

أفضل طريقة لاستخدام Authentication Config المخزّن في Authentication DB هي الإشارة إليه بالمعرّف الفريد authcfg. ويعني التوسيع تحويله من معرّف إلى مجموعة كاملة من بيانات الاعتماد. وأفضل ممارسة لاستخدام Authentication Configs المخزّنة هي تركها تُدار تلقائيًا بواسطة مدير المصادقة. والاستخدام الشائع للإعداد المخزّن هو الاتصال بخدمة تتطلب المصادقة مثل WMS أو WFS أو باتصال قاعدة بيانات.

ملاحظة

خذ في الحسبان أن ليس كل مزوّدي البيانات في QGIS مدمجين مع البنية التحتية للمصادقة. فكل طريقة مصادقة مشتقة من الصنف الأساسي QgsAuthMethod تدعم مجموعة مختلفة من المزوّدين. على سبيل المثال، تدعم الدالة certIdentity() قائمة المزوّدين التالية:

authM = QgsApplication.authManager()
print(authM.authMethod("Identity-Cert").supportedDataProviders())

مثال على المخرجات:

['ows', 'wfs', 'wcs', 'wms', 'postgres']

على سبيل المثال، للوصول إلى خدمة WMS باستخدام بيانات اعتماد مخزّنة معرّفة بـ authcfg = 'fm1s770'، يكفي أن نستخدم authcfg في عنوان URL لمصدر البيانات كما في المقتطف التالي:

authCfg = 'fm1s770'
quri = QgsDataSourceUri()
quri.setParam("layers", 'usa:states')
quri.setParam("styles", '')
quri.setParam("format", 'image/png')
quri.setParam("crs", 'EPSG:4326')
quri.setParam("dpiMode", '7')
quri.setParam("featureCount", '10')
quri.setParam("authcfg", authCfg)   # <---- here my authCfg url parameter
quri.setParam("contextualWMSLegend", '0')
quri.setParam("url", 'https://my_auth_enabled_server_ip/wms')
rlayer = QgsRasterLayer(str(quri.encodedUri(), "utf-8"), 'states', 'wms')

في الحالة أعلاه، سيتولى المزوّد wms توسيع المعامل authcfg في URI ببيانات الاعتماد قبل إنشاء اتصال HTTP مباشرةً.

تحذير

ينبغي للمطوّر أن يترك توسيع authcfg للصنف QgsAuthManager، وبذلك يضمن ألا يتم التوسيع مبكرًا أكثر من اللازم.

عادةً تُستخدم سلسلة URI مبنية باستخدام الصنف QgsDataSourceURI لتعيين مصدر بيانات بالطريقة التالية:

authCfg = 'fm1s770'
quri = QgsDataSourceUri("my WMS uri here")
quri.setParam("authcfg", authCfg)
rlayer = QgsRasterLayer( quri.uri(False), 'states', 'wms')

ملاحظة

المعامل False مهم لتجنّب التوسيع الكامل لمعرّف authcfg الموجود في URI.

14.3.4.1. أمثلة PKI مع مزوّدي بيانات آخرين

يمكن قراءة أمثلة أخرى مباشرة في اختبارات QGIS الأصلية مثل test_authmanager_pki_ows أو test_authmanager_pki_postgres.

14.4. تكييف الإضافات لاستخدام البنية التحتية للمصادقة

تستخدم كثير من إضافات الطرف الثالث httplib2 أو مكتبات شبكات أخرى في Python لإدارة اتصالات HTTP بدلًا من التكامل مع QgsNetworkAccessManager وما يرتبط به من تكامل مع البنية التحتية للمصادقة.

لتسهيل هذا التكامل أُنشئت دالة Python مساعدة تُسمى NetworkAccessManager. يمكن العثور على شيفرتها هنا.

يمكن استخدام هذا الصنف المساعد كما في المقتطف التالي:

http = NetworkAccessManager(authid="my_authCfg", exception_class=My_FailedRequestError)
try:
  response, content = http.request( "my_rest_url" )
except My_FailedRequestError, e:
  # Handle exception
  pass

14.5. واجهات المصادقة الرسومية

تُسرد في هذه الفقرة الواجهات الرسومية المتاحة المفيدة لدمج البنية التحتية للمصادقة في واجهات مخصّصة.

14.5.1. واجهة رسومية لاختيار بيانات الاعتماد

إذا كان من الضروري اختيار Authentication Configuration من المجموعة المخزّنة في Authentication DB فإن ذلك متاح في صنف الواجهة الرسومية QgsAuthConfigSelect.

ويمكن استخدامه كما في المقتطف التالي:

# create the instance of the QgsAuthConfigSelect GUI hierarchically linked to
# the widget referred with `parent`
parent = QWidget()  # Your GUI parent widget
gui = QgsAuthConfigSelect( parent, "postgres" )
# add the above created gui in a new tab of the interface where the
# GUI has to be integrated
tabGui = QTabWidget()
tabGui.insertTab( 1, gui, "Configurations" )

المثال أعلاه مأخوذ من code المصدرية لـ QGIS. يشير المعامل الثاني لمُنشئ الواجهة الرسومية إلى نوع مزوّد البيانات، ويُستخدم لتقييد Authentication Methods المتوافقة مع المزوّد المحدد.

14.5.2. واجهة محرّر المصادقة

الواجهة الرسومية الكاملة المستخدمة لإدارة بيانات الاعتماد وجهات الإصدار وللوصول إلى أدوات المصادقة يديرها الصنف QgsAuthEditorWidgets.

ويمكن استخدامه كما في المقتطف التالي:

# create the instance of the QgsAuthEditorWidgets GUI hierarchically linked to
# the widget referred with `parent`
parent = QWidget()  # Your GUI parent widget
gui = QgsAuthConfigSelect( parent )
gui.show()

يمكن العثور على مثال متكامل في test ذي الصلة.

14.5.3. واجهة محرّر جهات الإصدار

واجهة رسومية تُستخدم لإدارة جهات الإصدار فقط يديرها الصنف QgsAuthAuthoritiesEditor.

ويمكن استخدامه كما في المقتطف التالي:

# create the instance of the QgsAuthAuthoritiesEditor GUI hierarchically
#  linked to the widget referred with `parent`
parent = QWidget()  # Your GUI parent widget
gui = QgsAuthAuthoritiesEditor( parent )
gui.show()