14. Authentifizierungsinfrastruktur

Hinweis

Die Codefragmente auf dieser Seite müssen wie folgt importiert werden, wenn Sie sich außerhalb der pyqgis-Konsole befinden:

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. Einführung 

Die Benutzerreferenz der Authentifizierungsinfrastruktur kann im Benutzerhandbuch im Abschnitt :ref`authentication_overview` nachgelesen werden .

In diesem Kapitel werden die Best Practices für die Verwendung des Authentifizierungssystems aus Entwicklersicht beschrieben.

Das Authentifizierungssystem wird in QGIS Desktop häufig von Datenanbietern verwendet, wenn Anmeldeinformationen für den Zugriff auf eine bestimmte Ressource erforderlich sind, z. B. wenn eine Schicht eine Verbindung zu einer Postgres-Datenbank herstellt.

Es gibt auch einige Widgets in der QGIS-GUI-Bibliothek, mit denen Plugin-Entwickler die Authentifizierungsinfrastruktur einfach in ihren Code integrieren können:

A good code reference can be read from the authentication infrastructure tests code.

Warnung

Aufgrund der Sicherheitsbeschränkungen, die beim Entwurf der Authentifizierungsinfrastruktur berücksichtigt wurden, wird Python nur eine ausgewählte Teilmenge der internen Methoden zur Verfügung gestellt!

14.2. Glossar 

Hier finden Sie eine Definition der in diesem Kapitel am häufigsten behandelten Objekte.

Master Password: Kennwort zum Ermöglichen des Zugriffs und zum Entschlüsseln von Anmeldeinformationen, die in der QGIS-Authentifizierungsdatenbank gespeichert sind
Authentifizierungsdatenbank: Eine mit einem Master Password verschlüsselte SQLite-Datenbank, qgis-auth.db in der die Authentifizierungskonfiguration gespeichert ist, z.B. Benutzer / Passwort, persönliche Zertifikate und Schlüssel, Zertifizierungsstellen
Authentication DB: Authentication Database
Authentifikationskonfiguration: A set of authentication data depending on Authentication Method. e.g Basic authentication method stores the couple of user/password.
Authentication Config: Authentication Configuration
Authentication Method: Eine bestimmte Methode zur Authentifizierung. Jede Methode verfügt über ein eigenes Protokoll, mit dem die authentifizierte Ebene erreicht wird. Jede Methode wird als gemeinsam genutzte Bibliothek implementiert, die während der Initialisierung der QGIS-Authentifizierungsinfrastruktur dynamisch geladen wird.

14.3. QgsAuthManager als Einstiegspunkt 

Der QgsAuthManager Singleton ist der Einstiegspunkt für die Verwendung der in der QGIS-verschlüsselten Authentication DB gespeicherten Anmeldeinformationen , dh der qgis-auth.db Datei unter dem aktiven Benutzerprofilordner.

Diese Klasse kümmert sich um die Benutzerinteraktion indem Sie aufgefordert werden, ein Hauptkennwort festzulegen, oder indem Sie es transparent verwenden, um auf verschlüsselte gespeicherte Informationen zuzugreifen.

14.3.1. Initiieren Sie den Manager und legen Sie das Master-Passwort fest 

Der folgende Codeschnippsel enthält ein Beispiel zum Festlegen des Hauptkennworts, um den Zugriff auf die Authentifizierungseinstellungen zu öffnen. Codekommentare sind wichtig, um das Snippet zu verstehen.

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. Die authdb mit einem neuen Eintrag für die Authentifizierungskonfiguration befüllen 

Jeder gespeicherte Berechtigungsnachweis ist eine Authentication Configuration-Instanz der Klasse QgsAuthMethodConfig, auf die mit einer eindeutigen Zeichenfolge wie der folgenden zugegriffen wird:

authcfg = 'fm1s770'

Diese Zeichenfolge wird beim Erstellen eines Eintrags mithilfe der QGIS-API oder -GUI automatisch generiert. Es kann jedoch hilfreich sein, sie manuell auf einen bekannten Wert festzulegen, falls die Konfiguration (mit unterschiedlichen Anmeldeinformationen) von mehreren Benutzern innerhalb einer Organisation gemeinsam genutzt werden muss.

QgsAuthMethodConfig is the base class for any Authentication Method. Any Authentication Method sets a configuration hash map where authentication information will be stored. Hereafter a useful snippet to store PKI-path credentials for a hypothetical alice user:

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. Verfügbare Authentifizierungsmethoden 

Authentication Method-Bibliotheken werden während der Initialisierung des Authentifizierungsmanagers dynamisch geladen. Verfügbare Authentifizierungsmethoden sind:

Basic Benutzer- und Passwortauthentifizierung
EsriToken ESRI token based authentication
Identity-Cert Authentifizierung des Identitätszertifikats
OAuth2 OAuth2-Authentifizierung
PKI-Paths PKI-Pfadauthentifizierung
PKI-PKCS#12 PKI PKCS # 12-Authentifizierung

14.3.2.2. Populate Authorities 

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 Bündel mit QgsPkiBundle verwalten 

Eine Convenience-Klasse zum Packen von PKI-Bundles, die aus SslCert-, SslKey- und CA-Ketten bestehen, ist die Klasse QgsPkiBundle. Nachfolgend ein Ausschnitt, um ein Passwort zu erhalten:

# 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()

Informationen zum Extrahieren von Zertifikaten / Schlüsseln / Zertifizierungsstellen aus dem Bundle finden Sie in der Klassendokumentation zu QgsPkiBundle.

14.3.3. Entfernen eines Eintrags aus authdb 

Wir können einen Eintrag aus der Authentication Database entfernen, indem wir seine authcfg Kennung mit dem folgenden Snippet verwenden:

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

14.3.4. authcfg Erweiterung dem QgsAuthManager überlassen 

Der beste Weg, auf einen verwenden Authentication Config in der gespeicherten Authentication DB zu verweisen besteht in der eindeutigen Kennung authcfg. Erweitern bedeutet, dass es von einem Bezeichner in einen vollständigen Satz von Anmeldeinformationen konvertiert wird. Die beste Vorgehensweise für die Verwendung gespeicherter Authentifizierungskonfigurationen besteht darin, sie automatisch vom Authentifizierungsmanager verwalten zu lassen. Die übliche Verwendung einer gespeicherten Konfiguration besteht darin, eine Verbindung zu einem authentifizierungsfähigen Dienst wie einem WMS oder WFS oder zu einer DB-Verbindung herzustellen.

Bemerkung

Take into account that not all QGIS data providers are integrated with the Authentication infrastructure. Each authentication method, derived from the base class QgsAuthMethod and support a different set of Providers. For example the certIdentity() method supports the following list of providers:

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

Beispielausgabe:

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

Um beispielsweise mit gespeicherten Anmeldeinformationen, die mit authcfg = 'fm1s770' gekennzeichnet sind , auf einen WMS-Dienst zuzugreifen , müssen Sie lediglich die URL in der Datenquelle wie im folgenden Snippet verwenden:

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')

Im obigen Fall achtet der wms Anbieter darauf, den authcfg URI-Parameter unmittelbar vor dem Einstellen der HTTP-Verbindung mit Anmeldeinformationen zu erweitern .

Warnung

Der Entwickler sollte die authcfg Erweiterung der Klasse QgsAuthManager überlassen um sicherzustellen, dass die Erweiterung nicht zu früh erfolgt.

Normalerweise wird eine URI-String, der mit der Klasse QgsDataSourceURI erstellt wurde, folgendermaßen verwendet, um eine Datenquelle festzulegen:

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

Bemerkung

Der Parameter False ist wichtig, um eine vollständige Erweiterung der URI um eine in der URI vorhandene authcfg zu vermeiden.

14.3.4.1. PKI-Beispiele mit anderen Datenanbietern 

Andere Beispiel können direkt in den QGIS-Tests gelesen werden, wie in test_authmanager_pki_ows oder test_authmanager_pki_postgres.

14.4. Plugins an die Authentifizierungsinfrastruktur anpassen 

Viele Plugins von Drittanbietern verwenden httplib2 oder andere Python-Netzwerkbibliotheken, um HTTP-Verbindungen zu verwalten, anstatt sie mit QgsNetworkAccessManager und der zugehörigen Authentifizierungsinfrastruktur zu integrieren.

Um diese Integration zu erleichtern, wurde eine Python-Hilfsfunktion namens NetworkAccessManager erstellt. Den Code finden Sie hier<https://github.com/rduivenvoorde/pdokservicesplugin/blob/master/networkaccessmanager.py>.

Die Hilfsklasse kann wie folgt verwendet werden:

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. Authentifizierungs-GUIs 

In diesem Abschnitt sind die verfügbaren GUIs aufgeführt, die zur Integration der Authentifizierungsinfrastruktur in benutzerdefinierte Schnittstellen von Nutzern sind.

14.5.1. GUI zur Auswahl von Anmeldeinformationen 

Zur Auswahl einer Authentifizierungskonfiguration aus dem in der Authentifizierungsdatenbank gespeicherten Satz ist die GUI-Klasse QgsAuthConfigSelect verfügbar.

Sie kann folgendermaßen verwendet werden:

# 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" )

Das obige Beispiel stammt aus dem QGIS- Quellcode code. Der zweite Parameter des GUI-Konstruktors bezieht sich auf den Datenanbietertyp. Der Parameter wird verwendet, um die kompatiblen Authentication Method s auf den angegebenen Anbieter einzuschränken.

14.5.2. Authentifizierungseditor GUI 

Die vollständige Oberfläche für die Verwaltung von Berechtigungen, Authorities und zum Zugriff auf Authentifizierungswerkzeuge wird mit der Klasse QgsAuthEditorWidgets gesteuert.

Sie kann folgendermaßen verwendet werden:

# 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()

Ein integriertes Beipiel ist im dazugehörigen test zu finden.

14.5.3. Authorities Editor GUI 

Eine GUI, mit der nur Authorities verwaltet werden, steht über die Klasse QgsAuthAuthoritiesEditor zur Verfügung.

../../_images/QgsAuthAuthoritiesEditor.png

Sie kann folgendermaßen verwendet werden:

# 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()