14. 認証インフラストラクチャ

ヒント

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. 前書き

認証基盤のユーザーリファレンスはユーザーマニュアル中で 認証システムの概要 段落を参照して下さい。

この章では、開発者の観点から、認証システムを使用するベストプラクティスについて説明します。

認証システムは、例えばレイヤがPostgresデータベースへの接続を確立するときなど、特定のリソースへのアクセスに認証情報が必要なときにデータプロバイダーによってQGIS Desktopで広く使用されています。

また、QGISのguiライブラリには、プラグイン開発者が認証インフラをコードに簡単に統合するために使用できるウィジェットがいくつか用意されています:

• QgsAuthConfigEditor

• QgsAuthConfigSelect

• QgsAuthSettingsWidget

良いコードリファレンスは、認証基盤 tests code から読むことができます。

警告

認証基盤の設計時に考慮されたセキュリティ上の制約により、内部メソッドの選択されたサブセットのみがPythonに公開されます。

14.2. 用語集

これはこの章で扱われる最も一般的なオブジェクトのいくつかの定義です。

マスターパスワード

アクセスを許可し、QGIS認証DBに保存された資格情報を復号化するパスワードです

認証データベース

A Master Password crypted sqlite db qgis-auth.db where Authentication Configuration are stored. e.g user/password, personal certificates and keys, Certificate Authorities

認証DB

認証データベース

認証の設定

認証データの構成は 認証メソッド によって異なります。例えばベーシック認証の場合は、ユーザー/パスワードの対が格納されます。

認証設定

認証設定

認証方法

認証されるためには特別な方法が利用されています。各方法は、認証されるためにそれぞれ独自のプロトコルを利用しています。それぞれの方法は共有ライブラリとしてQGIS認証基盤の初期化中に動的にロードされるように実装されています。

14.3. エントリポイントQgsAuthManager

QgsAuthManager シングルトンは、QGISの暗号化された Authentication DB （アクティブな user profile フォルダー下の qgis-auth.db ファイル）に格納されている認証情報を使用するエントリポイントです。

このクラスは、マスターパスワードの設定を求めたり、暗号化された保存情報にアクセスするためにマスターパスワードを透過的に使用したりすることで、ユーザーとの対話を行います。

14.3.1. マネージャを初期化し、マスターパスワードを設定する

次のコード例は、認証設定へのアクセスを開くために、マスターパスワードを設定する例を示します。コードのコメントは、このコード例を理解するために重要です。

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. 認証データベースに新しい認証構成項目を設定する

保存された資格情報は QgsAuthMethodConfig クラスの Authentication Configuration インスタンスで、次のような一意の文字列を使ってアクセスします:

authcfg = 'fm1s770'

この文字列は、QGIS APIやGUIを使用してエントリーを作成する際に自動的に生成されますが、（異なる資格情報で）組織内の複数のユーザー間で設定を共有する必要がある場合、手動で既知の値に設定することが有用な場合があります。

QgsAuthMethodConfig は任意の Authentication Method のベースクラスです。任意の認証方法は、認証情報が格納されるコンフィギュレーションハッシュマップを設定します。以下は、仮想的なaliceユーザのPKI-path認証情報を格納するための便利なスニペットです:

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. 利用可能な認証方法

Authentication Method ライブラリは、認証マネージャの初期化時に動的にロードされます。利用可能な認証方式は以下の通りです:

1. Basic ユーザーとパスワード認証

2. EsriToken ESRIトークン型認証

3. Identity-Cert アイデンティティ証明書認証

4. OAuth2 OAuth2認証

5. PKI-Paths PKIパス認証

6. PKI-PKCS＃12 PKI PKCS＃12認証

14.3.2.2. 認証局の導入

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. QgsPkiBundleでPKIバンドルを管理する

SslCert、SslKey、CAチェーンで構成されるPKIバンドルをパックする便利なクラスは QgsPkiBundle クラスです。以下は、パスワードで保護されるようにするためのスニペットです:

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

バンドルから証明書/鍵/CAsを取り出すには、 QgsPkiBundle クラスドキュメントを参照してください。

14.3.3. authdbからエントリを削除する

次のスニペットは、authcfg 識別子を使って 認証データベース からエントリを 削除します：

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

14.3.4. QgsAuthManagerにauthcfg展開を残す

The best way to use an Authentication Config stored in the Authentication DB is referring it with the unique identifier authcfg. Expanding, means convert it from an identifier to a complete set of credentials. The best practice to use stored Authentication Configs, is to leave it managed automatically by the Authentication manager. The common use of a stored configuration is to connect to an authentication enabled service like a WMS or WFS or to a DB connection.

注釈

すべてのQGISデータプロバイダーが認証インフラストラクチャに統合されているわけではないことを考慮してください。各認証メソッドは基本クラス QgsAuthMethod から派生し、異なるプロバイダのセットをサポートします。例えば、 certIdentity() メソッドは以下のプロバイダのリストをサポートしています:

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

サンプル出力:

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

例えば、 authcfg = 'fm1s770' で識別される、保存された資格情報を使ってWMSサービスにアクセスするためには、次のコードのように、データ・ソースのURLに authcfg を使う必要があります。

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

上の場合には、 wms プロバイダーは、単にHTTP接続を設定する前に、資格を authcfg URIパラメーターを拡張するために世話をします。

警告

開発者は authcfg の拡張を QgsAuthManager に任せる必要があるでしょう。このようにすれば、拡張が早すぎることはないでしょう。

通常、データソースの設定には QgsDataSourceURI クラスを用いて構築された URI 文字列を以下のように使用することができます:

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

注釈

False パラメーターは、URIで authcfg IDの存在のURI完全な展開を避けるために重要です。

14.3.4.1. 他のデータプロバイダーとPKIの例

その他の例は、 test_authmanager_pki_ows や test_authmanager_pki_postgres というようにQGISテストアップストリームで直接読むことができます。

14.4. 認証インフラストラクチャを使用するようにプラグインを適応させる

多くのサードパーティプラグインは、HTTP接続を管理するために、 QgsNetworkAccessManager とそれに関連する認証基盤の統合の代わりに、httplib2や他のPythonネットワークライブラリを使用しています。

この統合を容易にするために、NetworkAccessManager というPythonのヘルパー関数が作られました。このコードは、ここ にあります。

このヘルパークラスは、次のスニペットのように使うことができます:

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

この段落では、カスタムインターフェイスで認証インフラストラクチャを統合するために役立つ利用可能なGUIが記載されています。

14.5.1. 資格情報を選択するためのGUI

Authentication DB に格納されているセットから Authentication Configuration を選択する必要がある場合は、GUIクラス QgsAuthConfigSelect で利用可能です。

そして次のコードのように使用できます：

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

上記の例は、QGISのソース code から引用しています。GUIコンストラクタの第2パラメータは、データプロバイダタイプを指します。このパラメータは、指定したプロバイダと互換性のある Authentication Method を制限するために使用されます。

14.5.2. 認証エディタのGUI

資格情報、認証局を管理し、認証ユーティリティにアクセスするための完全なGUIは QgsAuthEditorWidgets クラスによって管理されています。

そして次のコードのように使用できます：

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

統合された例は、関連する test で見つけることができます。

14.5.3. 認証局エディタのGUI

認証局だけを管理するためのGUIは QgsAuthAuthoritiesEditor クラスで管理します。

そして次のコードのように使用できます：

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