14. Infraestrutura de autenticação

Dica

Os trechos de código desta página precisam das seguintes importações se você estiver fora do console do pyqgis:

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. Introdução 

A referência do usuário da infraestrutura de autenticação pode ser lida no Manual do Usuário no parágrafo Visão Geral do Sistema de Autenticação.

Este capítulo descreve as práticas recomendadas para usar o sistema de autenticação da perspectiva do desenvolvedor.

O sistema de autenticação é amplamente utilizado no QGIS Desktop pelos provedores de dados sempre que são necessárias credenciais para acessar um recurso específico, por exemplo, quando uma camada estabelece uma conexão com um banco de dados Postgres.

Existem também alguns widgets na biblioteca QGIS que os desenvolvedores de complementos podem usar para integrar facilmente a infraestrutura de autenticação ao seu código:

Uma boa referência de código pode ser lida na infraestrutura de autenticação tests code.

Aviso

Devido às restrições de segurança que foram levadas em consideração durante o projeto da infraestrutura de autenticação, apenas um subconjunto selecionado dos métodos internos é exposto ao Python.

14.2. Glossário 

Aqui estão algumas definições dos objetos mais comuns tratados neste capítulo.

Master Password: Senha para permitir acesso e descriptografia de credenciais armazenadas no Banco de Dados de Autenticação QGIS
Banco de Dados de Autenticação: O Master Password banco de dados criptografado sqlite qgis-auth.db onde Authentication Configuration são armazenados, como por exemplo, usuário/senha, certificados e chaves pessoais, Autoridades de Certificação
Banco de Dados de Autenticação: Authentication Database
Configuração de Autenticação: Um conjunto de dados de autenticação, dependendo de Authentication Method, como por exemplo, o Método de autenticação básica armazena o par de usuário/senha.
Configuração de Autenticação: Authentication Configuration
Método de Autenticação: Um método específico usado para se autenticar. Cada método possui seu próprio protocolo usado para obter o nível autenticado. Cada método é implementado como uma biblioteca compartilhada carregada dinamicamente durante o init da infraestrutura de autenticação QGIS.

14.3. QgsAuthManager o ponto de entrada 

O singleton QgsAuthManager é o ponto de entrada para usar as credenciais armazenadas no QGIS Authentication DB criptografado, i.e. o arquivo qgis-auth.db sob a pasta ativa user profile.

Essa classe cuida da interação do usuário: pedindo para definir uma master password ou usando-a de forma transparente para acessar informações armazenadas criptografadas.

14.3.1. Inicie o gerente e defina a master password 

O trecho a seguir fornece um exemplo para definir a master password para abrir o acesso às configurações de autenticação. Os comentários do código são importantes para entender o trecho.

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. Preencha o authdb com uma nova entrada de Configuração de Autenticação 

Qualquer credencial armazenada é uma instância de Authentication Configuration da classe QgsAuthMethodConfig acessada usando uma string exclusiva como a que segue:

authcfg = 'fm1s770'

essa string é gerada automaticamente ao criar uma entrada usando a API ou a GUI do QGIS, mas pode ser útil configurá-la manualmente para um valor conhecido caso a configuração precise ser compartilhada (com credenciais diferentes) entre vários usuários em uma organização.

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. Métodos de Autenticação disponíveis 

Authentication Method libraries are loaded dynamically during authentication manager init. Available authentication methods are:

Basic Autenticação de usuário e senha
EsriToken ESRI token based authentication
Identity-Cert Autenticação de certificado de identidade
Autenticação de OAuth2 OAuth2
PKI-Paths autenticação de caminhos PKI
PKI-PKCS#12 PKI PKCS#12 autenticação

14.3.2.2. Preencher Autoridades 

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. Gerenciar pacotes configuráveis de PKI com QgsPkiBundle 

Uma classe de conveniência para empacotar pacotes configuráveis PKI compostos na cadeia SslCert, SslKey e CA é a classe QgsPkiBundle. A seguir, um trecho para obter uma senha protegida:

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

Consulte a documentação da classe QgsPkiBundle para extrair cert/key/CAs do pacote.

14.3.3. Remover uma entrada de authdb 

Podemos remover uma entrada de Authentication Database usando seu identificador authcfg com o seguinte trecho:

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

14.3.4. Leave authcfg expansion to QgsAuthManager 

A melhor maneira de usar um Authentication Config armazenado em Authentication DB é referenciá-lo com o identificador exclusivo authcfg. Expandir significa convertê-lo de um identificador para um conjunto completo de credenciais. A melhor prática para usar os Authentication Configs armazenados, é deixá-los gerenciados automaticamente pelo gerenciador de autenticação. O uso comum de uma configuração armazenada é conectar-se a um serviço habilitado para autenticação, como um WMS ou WFS ou a uma conexão de banco de dados.

Nota

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

Saída de amostra:

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

Por exemplo, para acessar um serviço WMS usando credenciais armazenadas identificadas com authcfg = 'fm1s770', basta usar o authcfg no URL da fonte de dados, como no seguinte trecho:

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

Em maiúsculas, o provedor wms cuidará para expandir o parâmetro URI authcfg com credencial antes de definir a conexão HTTP.

Aviso

O desenvolvedor precisaria deixar a expansão authcfg para QgsAuthManager, dessa forma ele garantirá que a expansão não seja feita muito cedo.

Geralmente, uma string de URI, criada usando a classe QgsDataSourceURI, é usada para definir uma fonte de dados da seguinte maneira:

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

Nota

O parâmetro False é importante para evitar a expansão completa do URI do ID authcfg presente no URI.

14.3.4.1. Exemplos PKI com outros provedores de dados 

Outro exemplo pode ser lido diretamente nos testes QGIS anteriores, como em test_authmanager_pki_ows ou test_authmanager_pki_postgres.

14.4. Adapte complementos para usar a infraestrutura de autenticação 

Muitos complementos de terceiros estão usando o enableplib2 ou outras bibliotecas de rede Python para gerenciar conexões HTTP em vez de integrar-se com QgsNetworkAccessManager e sua integração relacionada à Infra-estrutura de autenticação.

Para facilitar essa integração, uma função auxiliar Python foi criada chamada NetworkAccessManager. Seu código pode ser encontrado aqui.

Essa classe auxiliar pode ser usada como no seguinte trecho:

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. GUIs de autenticação 

Neste parágrafo, estão listadas as GUIs disponíveis úteis para integrar a infraestrutura de autenticação em interfaces personalizadas.

14.5.1. GUI para selecionar credenciais 

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.

e pode ser usado como no seguinte trecho:

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

O exemplo acima é retirado da fonte do QGIS code. O segundo parâmetro do construtor da GUI refere-se ao tipo de provedor de dados. O parâmetro é usado para restringir os Authentication Methods compatíveis com o provedor especificado.

14.5.2. GUI do Editor de Autenticação 

A GUI completa usada para gerenciar credenciais, autoridades e acessar os utilitários de autenticação é gerenciada pela classe QgsAuthEditorWidgets.

e pode ser usado como no seguinte trecho:

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

An integrated example can be found in the related test.

14.5.3. GUI do Editor de Autoridades 

A GUI used to manage only authorities is managed by the QgsAuthAuthoritiesEditor class.

../../_images/QgsAuthAuthoritiesEditor.png

e pode ser usado como no seguinte trecho:

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