14. Infrastructuur voor authenticatie

Hint

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

 1from qgis.core import (
 2  QgsApplication,
 3  QgsRasterLayer,
 4  QgsAuthMethodConfig,
 5  QgsDataSourceUri,
 6  QgsPkiBundle,
 7  QgsMessageLog,
 8)
 9
10from qgis.gui import (
11    QgsAuthAuthoritiesEditor,
12    QgsAuthConfigEditor,
13    QgsAuthConfigSelect,
14    QgsAuthSettingsWidget,
15)
16
17from qgis.PyQt.QtWidgets import (
18    QWidget,
19    QTabWidget,
20)
21
22from 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.

 1authMgr = QgsApplication.authManager()
 2
 3# check if QgsAuthManager has already been initialized... a side effect
 4# of the QgsAuthManager.init() is that AuthDbPath is set.
 5# QgsAuthManager.init() is executed during QGIS application init and hence
 6# you do not normally need to call it directly.
 7if authMgr.authenticationDatabasePath():
 8    # already initialized => we are inside a QGIS app.
 9    if authMgr.masterPasswordIsSet():
10        msg = 'Authentication master password not recognized'
11        assert authMgr.masterPasswordSame("your master password"), msg
12    else:
13        msg = 'Master password could not be set'
14        # The verify parameter checks if the hash of the password was
15        # already saved in the authentication db
16        assert authMgr.setMasterPassword("your master password",
17                                          verify=True), msg
18else:
19    # outside qgis, e.g. in a testing environment => setup env var before
20    # db init
21    os.environ['QGIS_AUTH_DB_DIR_PATH'] = "/path/where/located/qgis-auth.db"
22    msg = 'Master password could not be set'
23    assert authMgr.setMasterPassword("your master password", True), msg
24    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:

 1authMgr = QgsApplication.authManager()
 2# set alice PKI data
 3config = QgsAuthMethodConfig()
 4config.setName("alice")
 5config.setMethod("PKI-Paths")
 6config.setUri("https://example.com")
 7config.setConfig("certpath", "path/to/alice-cert.pem" )
 8config.setConfig("keypath", "path/to/alice-key.pem" )
 9# check if method parameters are correctly set
10assert config.isValid()
11
12# register alice data in authdb returning the ``authcfg`` of the stored
13# configuration
14authMgr.storeAuthenticationConfig(config)
15newAuthCfgId = config.id()
16assert 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:

  1. Basic Gebruiker en wachtwoordauthenticatie

  2. Esri-Token authenticatie op basis van ESRI-tokens

  3. Identity-Cert Authenticatie met Identiteitscertificaat

  4. OAuth2 OAuth2-authenticatie

  5. PKI-Paths Authenticatie met PKI-paden

  6. PKI-PKCS#12 Authenticatie met PKI PKCS#12

14.3.2.2. Autoriteiten vullen

1authMgr = QgsApplication.authManager()
2# add authorities
3cacerts = QSslCertificate.fromPath( "/path/to/ca_chains.pem" )
4assert cacerts is not None
5# store CA
6authMgr.storeCertAuthorities(cacerts)
7# and rebuild CA caches
8authMgr.rebuildCaCertsCache()
9authMgr.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:

1# add alice cert in case of key with pwd
2caBundlesList = []  # List of CA bundles
3bundle = QgsPkiBundle.fromPemPaths( "/path/to/alice-cert.pem",
4                                     "/path/to/alice-key_w-pass.pem",
5                                     "unlock_pwd",
6                                     caBundlesList )
7assert bundle is not None
8# You can check bundle validity by calling:
9# 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:

 1authCfg = 'fm1s770'
 2quri = QgsDataSourceUri()
 3quri.setParam("layers", 'usa:states')
 4quri.setParam("styles", '')
 5quri.setParam("format", 'image/png')
 6quri.setParam("crs", 'EPSG:4326')
 7quri.setParam("dpiMode", '7')
 8quri.setParam("featureCount", '10')
 9quri.setParam("authcfg", authCfg)   # <---- here my authCfg url parameter
10quri.setParam("contextualWMSLegend", '0')
11quri.setParam("url", 'https://my_auth_enabled_server_ip/wms')
12rlayer = 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:

1http = NetworkAccessManager(authid="my_authCfg", exception_class=My_FailedRequestError)
2try:
3  response, content = http.request( "my_rest_url" )
4except My_FailedRequestError, e:
5  # Handle exception
6  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.

../../_images/QgsAuthConfigSelect.png

en kan worden gebruikt zoals in het volgende snippet:

1# create the instance of the QgsAuthConfigSelect GUI hierarchically linked to
2# the widget referred with `parent`
3parent = QWidget()  # Your GUI parent widget
4gui = QgsAuthConfigSelect( parent, "postgres" )
5# add the above created gui in a new tab of the interface where the
6# GUI has to be integrated
7tabGui = QTabWidget()
8tabGui.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.

../../_images/QgsAuthEditorWidgets.png

en kan worden gebruikt zoals in het volgende snippet:

1# create the instance of the QgsAuthEditorWidgets GUI hierarchically linked to
2# the widget referred with `parent`
3parent = QWidget()  # Your GUI parent widget
4gui = QgsAuthConfigSelect( parent )
5gui.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:

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