Outdated version of the documentation. Find the latest one here.

Infrastructuur voor authenticatie

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.

Waarschuwing

Authentication system API is more than the classes and methods exposed here, but it’s strongly suggested to use the ones described here and exposed in the following snippets for two main reasons

  1. Authentication API will change during the move to QGIS3
  2. Python bindings will be restricted to the QgsAuthManager class use.

De meeste van de volgende snippets 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
A Master Password crypted sqlite db <user home>/.qgis2/qgis-auth.db where Authentication Configuration are stored. e.g user/password, personal certificates and keys, 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

The QgsAuthManager singleton is the entry point to use the credentials stored in the QGIS encrypted Authentication DB:

<user home>/.qgis2/qgis-auth.db

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

Any stored credential is a Authentication Configuration instance of the QgsAuthMethodConfig class accessed using a unique string like the following one:

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 the base class for any Authentication Method. Any Authentication Method sets a configuration hash map where authentication informations will be stored. Hereafter an useful snippet to store PKI-path credentials for an hypothetic alice user:

authMgr = QgsAuthManager.instance()
# set alice PKI data
p_config = QgsAuthMethodConfig()
p_config.setName("alice")
p_config.setMethod("PKI-Paths")
p_config.setUri("http://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:

  1. Basic Gebruiker en wachtwoordauthenticatie

  2. Identity-Cert Authenticatie met Identiteitscertificaat

  3. PKI-Paths Authenticatie met PKI-paden

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

De bovenstaande tekenreeksen identificeren de authenticatiemethoden het het systeem voor authenticatie van QGIS. In het gedeelte Development 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

A convenience class to pack PKI bundles composed on SslCert, SslKey and CA chain is the QgsPkiBundle class. Hereafter a snippet to get password protected:

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

Refer to QgsPkiBundle class documentation to extract cert/key/CAs from the bundle.

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

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 Identity-Cert method supports the following list of providers:

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

Developer would have to leave authcfg expansion to the QgsAuthManager, in this way he will be sure that expansion is not done too early.

Usually an URI string, build using QgsDataSourceURI class, is used to set QGIS data source in the following way:

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

Many third party plugins are using httplib2 to create HTTP connections instead of integrating with QgsNetworkAccessManager and its related Authentication Infrastructure integration. To facilitate this integration an helper python function has been created called NetworkAccessManager. Its code can be found here.

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

If it’s necessary to select a Authentication Configuration from the set stored in the Authentication DB it is available in the GUI class QgsAuthConfigSelect

../../_images/QgsAuthConfigSelect.png

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

The above example is get from the QGIS source code The second parameter of the GUI constructor refers to data provider type. The parameter is used to restrict the compatible Authentication Methods with the specified provider.

Bewerkers voor GUI authenticatie

The complete GUI used to manage credentials, authorities and to access to Authentication utilities is managed by the class QgsAuthEditorWidgets

../../_images/QgsAuthEditorWidgets.png

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

A GUI used to manage only authorities is managed by the class 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()