14. Infrastructuur voor authenticatie

Hint

De codesnippers op deze pagina hebben de volgende import nodig als u buiten de console van PyQGIS bent:

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. Introductie 

Verwijzingen voor de gebruiker voor de infrastructuur voor authenticatie kan worden nagelezen in de Gebruikershandleiding in het gedeelte Overzicht authenticatiesysteem.

Dit hoofdstuk beschrijft de beste praktijken om het systeem voor authenticatie te gebruiken uit het perspectief van de ontwikkelaar.

Het systeem voor authenticatie wordt in QGIS Desktop breed gebruikt door gegevensproviders als inloggegevens worden vereist om toegang te krijgen tot een bepaalde bron, bijvoorbeeld wanneer een laag een verbinding maakt met een database voor Postgres.

Er zijn ook een paar widgets in de bibliotheek voor de GUI van QGIS die ontwikkelaars voor plug-ins kunnen gebruiken om de infrastructuur voor de authenticatie gemakkelijk te integreren in hun code:

Een goede verwijzing voor de code is te lezen in de infrastructuur voor de authenticatie tests code.

Waarschuwing

Vanwege de beperkingen voor de beveiliging, waarmee rekening werd gehouden bij het ontwerpen van de infrastructuur voor de authenticatie, wordt alleen een geselecteerde subset van de interne methoden weergegeven in Python.

14.2. Woordenlijst 

Hier zijn enkele definities van de meest voorkomende objecten die worden behandeld in dit hoofdstuk.

Hoofdwachtwoord: Wachtwoord voor toegang tot en ontsleutelen van gegevens die zijn opgeslagen in de QGIS Authentication DB
Authenticatie-database: Een met een Master Password versleutelde Sqlite database qgis-auth.db waar Configuratie voor authenticatie worden opgeslagen. bijv gebruiker/wachtwoord, persoonlijke certificaten en sleutels, Certificate Authorities
Authenticatie DB: Authentication Database
Configuratie voor authenticatie: Een set van gegevens voor authenticatie afhankelijk van de Authentication Method. bijv de methode Basisauthenticatie slaat het paar gebruiker/wachtwoord op.
Configuratie voor authenticatie: Authentication Configuration
Authenticatiemethode: Een specifieke methode die wordt gebruikt om te worden geauthenticeerd. Elke methode heeft zijn eigen protocol dat wordt gebruikt om het bepaalde niveau voor authenticatie te verkrijgen. Elke methode is geïmplementeerd als gedeelde bibliotheek die dynamisch wordt geladen gedurende de init van de infrastructuur voor authenticatie van QGIS.

14.3. QgsAuthManager is het toegangspunt 

De singleton QgsAuthManager is het toegangspunt om de in de versleutelde Authentication DB van QGIS opgeslagen gegevens te gebruiken, d.i. het bestand qgis-auth.db in de actieve map van het gebruikersprofiel.

Deze klasse zorgt voor de interactie met de gebruiker: door te vragen het hoofdwachtwoord in te stellen of door het transparant te gebruiken voor toegang tot opgeslagen versleutelde informatie.

14.3.1. Initialiseren van de beheerder en het hoofdwachtwoord instellen 

Het volgende snippet geeft een voorbeeld om het hoofdwachtwoord in te stellen om toegang te krijgen tot de instellingen voor authenticatie. Opmerkingen in de code zijn belangrijk om het snippet te begrijpen.

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. Vullen van authdb met een nieuw item Configuratie voor authenticatie 

Elk opgeslagen persoonlijk gegeven is een instantie Authentication Configuration van de klasse QgsAuthMethodConfig waar toegang toe wordt verkregen met behulp van een unieke string zoals de volgende:

authcfg = 'fm1s770'

die tekenreeks wordt automatisch gegenereerd bij het maken van een item met de QGIS API of GUI, maar het zou nuttig kunnen zijn om het handmatig in te stellen met een bekende waarde in het geval dat de configuratie moet worden gedeeld (met verschillende inloggegevens) tussen meerdere gebruikers binnen een organisatie.

QgsAuthMethodConfig is de basisklasse voor elke Authentication Method. Elke Authenticatiemethode stelt een configuratie hashmap in waar informatie voor authenticatie zal worden opgeslagen. Hieronder een handig snippet om persoonlijke gegevens voor het PKI-pad op te slaan voor een hypothetische gebruiker 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. Beschikbare authenticatiemethoden 

bibliotheken Authentication Method worden dynamisch geladen gedurende de initialisatie van de beheerder voor de authenticatie. Beschikbare methoden voor authenticatie zijn:

Basic Gebruiker en wachtwoordauthenticatie
EsriToken Op ESRI-token gebaseerde authenticatie
Identity-Cert Authenticatie met Identiteitscertificaat
OAuth2 OAuth2-authenticatie
PKI-Paths Authenticatie met PKI-paden
PKI-PKCS#12 Authenticatie met PKI PKCS#12

14.3.2.2. Autoriteiten vullen 

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-bundels beheren met QgsPkiBundle 

Een handige klasse om PKI-bundels in te pakken die zijn samengesteld uit de keten SslCert, SslKey en CA is de klasse QgsPkiBundle. Hieronder een snippet om wachtwoord beveiligd te verkrijgen:

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

Bekijk de documentatie voor de klasse QgsPkiBundle om cert/key/CAs uit de bundel uit te nemen.

14.3.3. Een item verwijderen uit authdb 

We kunnen een item verwijderen uit de Authentication Database met behulp van zijn identificatie authcfg met het volgende snippet:

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

14.3.4. Uitbreiden van authcfg overlaten aan QgsAuthManager 

De beste manier om een in de Authentication DB opgeslagen Authentication Config te gebruiken is door er naar te verwijzen met de unieke identificatie authcfg. Uitbreiden ervan betekent het converteren van een identificatie naar een volledige set van gegevens. De beste praktijk om opgeslagen Authentication Configs te gebruiken, is om het automatisch te laten worden beheerd door de beheerder van de Authenticatie. Het meest voorkomende gebruik van een opgeslagen configuratie is om te verbinden met een met authenticatie ingeschakelde service zoals een WMS of WFS of naar een verbinding met een DB.

Notitie

Houdt er rekening mee dat niet alle gegevensproviders voor QGIS zijn geïntegreerd in de infrastructuur voor authenticatie. Elke authenticatiemethode, afgeleid van de basisklasse QgsAuthMethod ondersteunt een verschillende set van providers. Bijvoorbeeld: de methode certIdentity() ondersteunt de volgende lijst met providers:

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

Voorbeeld uitvoer:

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

Voor toegang tot, bijvoorbeeld, een WMS-service met behulp van de opgeslagen gegevens die worden geïdentificeerd als authcfg = 'fm1s770', hoeven we slechts de authcfg te gebruiken in de URL voor de gegevensbron zoals in het volgende snippet:

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

In het bovenstaande geval zal de provider wms er zorg voor dragen dat parameter voor de URI authcfg wordt uitgebreid met persoonlijke gegevens net vóór het instellen van de verbinding met HTTP.

Waarschuwing

De ontwikkelaar zou uitbreiding van authcfg moeten overlaten aan de QgsAuthManager, op deze manier zorgt hij er voor dat de uitbreiding niet te vroeg wordt gedaan.

Gewoonlijk wordt een tekenreeks als URI, gebouwd met behulp van de klasse QgsDataSourceURI, gebruikt om een gegevensbron voor QGIS op de volgende manier in te stellen:

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

Notitie

De parameter False is belangrijk om volledige uitbreiding van de ID voor authcfg, die aanwezig is in de URI, te voorkomen.

14.3.4.1. PKI-voorbeelden met andere gegevensproviders 

Andere voorbeelden kunnen direct worden ingelezen in de QGIS tests upstream zoals in test_authmanager_pki_ows of test_authmanager_pki_postgres.

14.4. Plug-ins aanpassen om de infrastructuur voor authenticatie te gebruiken 

Vele plug-ins van derde partijen gebruiken httplib2 of andere bibliotheken van Python voor netwerken om verbindingen van HTTP te beheren, in plaats van ze te integreren met QgsNetworkAccessManager en zijn gerelateerde integratie van de Authentication Infrastructure .

Een hulpfunctie voor Python is gemaakt om deze integratie te faciliteren, genaamd NetworkAccessManager. De code ervan is hier te vinden.

Deze hulpklasse kan worden gebruikt zoals in het volgende snippet:

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. GUI’s voor authenticatie 

In deze alinea zijn de beschikbare GUI’s vermeld die handig zijn om de infrastructuur voor authenticatie te integreren in aangepaste/eigen interfaces.

14.5.1. GUI om persoonlijke gegevens te selecteren 

Indien het noodzakelijk is een Authentication Configuration te selecteren uit de set die is opgeslagen in de Authentication DB is die beschikbaar in de klasse voor de GUI QgsAuthConfigSelect.

en kan worden gebruikt zoals in het volgende snippet:

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

Het bovenstaande voorbeeld is afkomstig uit de broncode van QGIS code. De tweede parameter van de gebruikersinterface verwijst naar het type gegevensprovider. De parameter wordt gebruikt om de compatibele :term:`Authentication Method`en te beperken tot de gespecificeerde provider.

14.5.2. Bewerkers voor GUI authenticatie 

De volledige GUI die wordt gebruikt voor het beheren van persoonlijke gegevens, autoriteiten en om toegang te verkrijgen tot de utilities voor authenticatie wordt beheerd door de klasse QgsAuthEditorWidgets.

en kan worden gebruikt zoals in het volgende snippet:

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

Een geïntegreerd voorbeeld is te vinden in de gerelateerde test.

14.5.3. Bewerker voor GUI autoriteiten 

Een GUI die alleen wordt gebruikt voor het beheren van autoriteiten wordt beheerd door de klasse QgsAuthAuthoritiesEditor.

../../_images/QgsAuthAuthoritiesEditor.png

en kan worden gebruikt zoals in het volgende snippet:

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