Infrastructuur voor authenticatie¶

Introductie
Woordenlijst
QgsAuthManager is het toegangspunt
Plug-ins aanpassen om de infrastructuur voor authenticatie te gebruiken
GUI’s voor authenticatie

Waarschuwing

Despite our constant efforts, information beyond this line may not be updated for QGIS 3. Refer to https://qgis.org/pyqgis/master for the python API documentation or, give a hand to update the chapters you know about. Thanks.

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.

De meeste van de volgende snippers zijn afgeleid van de code voor de plug-in Geoserver Explorer en de testen daarvan. Dit is de eerste plug-in die de infrastructuur voor authenticatie gebruikte. De code voor de plug-in en de testen daarvan is te vinden via deze link. Andere goede verwijzingen naar code zijn te lezen in de infrastructuur voor authenticatie tests code.

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.

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.

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 = QgsAuthManager.instance()
# check if QgsAuthManager has been already 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.authenticationDbPath():
    # already initilised => 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 check 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" )

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 string wordt automatisch gegenereerd bij het maken van een item met behulp van de API van QGIS of de GUI.

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 = QgsAuthManager.instance()
# set alice PKI data
p_config = QgsAuthMethodConfig()
p_config.setName("alice")
p_config.setMethod("PKI-Paths")
p_config.setUri("https://example.com")
p_config.setConfig("certpath", "path/to/alice-cert.pem" ))
p_config.setConfig("keypath", "path/to/alice-key.pem" ))
# check if method parameters are correctly set
assert p_config.isValid()

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

Beschikbare authenticatiemethoden ¶

Authentication Methods worden dynamisch geladen gedurende de initialisatie van de beheerder voor de authenticatie. De lijst van authenticatiemethoden kan variëren met de evolutie van QGIS, maar de originele lijst met beschikbare methoden is:

Basic Gebruiker en wachtwoordauthenticatie
Identity-Cert Authenticatie met Identiteitscertificaat
PKI-Paths Authenticatie met PKI-paden
PKI-PKCS#12 Authenticatie met PKI PKCS#12

De bovenstaande tekenreeksen identificeren de authenticatiemethoden het het systeem voor authenticatie van QGIS. In het gedeelte Ontwikkeling wordt beschreven hoe een nieuwe C++ Authentication Methodte maken.

Autoriteiten vullen ¶

authMgr = QgsAuthManager.instance()
# 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()

Waarschuwing

Vanwege beperkingen in de interface QT4/OpenSSL, worden bijgewerkte gecachte CA’s ongeveer een minuut later weergegeven in OpenSsl. Hopelijk zal dit zijn opgelost in de infrastructuur voor authenticatie in QT5.

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
boundle = QgsPkiBundle.fromPemPaths( "/path/to/alice-cert.pem",
                                     "/path/to/alice-key_w-pass.pem",
                                     "unlock_pwd",
                                     "list_of_CAs_to_bundle" )
assert boundle is not None
assert boundle.isValid()

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

Item verwijderen uit authdb ¶

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

authMgr = QgsAuthManager.instance()
authMgr.removeAuthenticationConfig( "authCfg_Id_to_remove" )

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:

In [19]: authM = QgsAuthManager.instance()
In [20]: authM.authMethod("Identity-Cert").supportedDataProviders()
Out[20]: ['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(quri.encodedUri(), '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:

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.

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.

Plug-ins aanpassen om de infrastructuur voor authenticatie te gebruiken ¶

Vele plug-ins van derde partijen gebruiken httplib2 om verbindingen met HTTP te maken in plaats van ze te integreren met QgsNetworkAccessManager en de daaraan gerelateerde integratie voor de infrastructuur voor authenticatie. Om deze integratie te faciliteren is een hulpfunctie in Python gemaakt die is 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

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.

GUI om persoonlijke gegevens te selecteren ¶

Indien het noodzakelijk is een Authentication Configuration te selecteren uit een set die is opgeslagen in de Authentication DB is die beschikbaar in de klasse voor de GUI QgsAuthConfigSelect <qgis.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`
gui = QgsAuthConfigSelect( parent, "postgres" )
# add the above created gui in a new tab of the interface where the
# GUI has to be integrated
tabGui.insertTab( 1, gui, "Configurations" )

Het bovenstaande voorbeeld is genomen uit de QGIS bron:source:code <src/providers/postgres/qgspgnewconnection.cpp#L42>. De tweede parameter van de constructor van de GUI verwijst naar het type gegevensprovider. De parameter wordt gebruikt om de compatibele Authentication Methoden te beperken tot de gespecificeerde provider.

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`
gui = QgsAuthConfigSelect( parent )
gui.show()

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

Bewerker voor GUI autoriteiten ¶

Een GUI die alleen wordt gebruikt voor het beheren van autoriteiten wordt beheerd door de klasse QgsAuthAuthoritiesEditor <qgis.gui.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`
gui = QgsAuthAuthoritiesEditor( parent )
gui.show()