중요

번역은 여러분이 참여할 수 있는 커뮤니티 활동입니다. 이 페이지는 현재 100.00% 번역되었습니다.

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. 소개 

사용자 지침서의 인증 시스템 개요 문단에서 인증 인프라스트럭처의 사용자 참조 사항들을 읽어볼 수 있습니다.

이 장에서는 개발자 입장에서 이 인증 시스템을 가장 잘 활용할 수 있는 방법을 설명할 것입니다.

어떤 특정 리소스에 접근하려면 인증 정보가 필요할 때마다, 예를 들어 PostgreSQL 데이터베이스에 어떤 레이어를 연결할 때마다, 데이터 제공자는 QGIS 데스크탑에서 인증 시스템을 광범위하게 사용합니다.

플러그인 개발자가 자신의 코드에 인증 인프라스트럭처를 손쉽게 통합할 수 있도록 해주는 위젯 몇 개가 QGIS GUI 라이브러리에 존재합니다:

인증 인프라스트럭처 테스트 코드 에서 괜찮은 코드 참조 사례를 볼 수 있습니다.

경고

인증 인프라스트럭처 설계 시 도입된 보안 제약조건들 때문에, 파이썬에서는 내부 메소드들 가운데 일부 하위 집합만을 사용할 수 있습니다.

14.2. 용어 해설 

이 장에서 가장 자주 취급하는 객체들을 몇 개 정의하겠습니다.

마스터 비밀번호: QGIS 인증 데이터베이스에 저장되어 있는 인증 정보(credential)에 접근해서 복호화할 수 있게 해주는 비밀번호입니다.
인증 데이터베이스: Master Password 가 암호화되어 있는 SQLite 데이터베이스 qgis-auth.db 입니다. 이 데이터베이스에 사용자 이름/비밀번호, 개인 인증서와 키, 인증서 기관(Certificate Authorities) 같은 Authentication Configuration 이 저장되어 있습니다.
인증 DB: Authentication Database
인증 환경설정(Authentication Configuration): Authentication Method 에 따라 달라지는 인증 데이터 집합입니다. 예를 들면 기본 인증 방법은 사용자 이름/비밀번호 쌍을 저장합니다.
인증 환경설정(Authentication Config): Authentication Configuration
인증 방법: 인증을 받기 위해 쓰이는 특정 방법입니다. 각 방법은 인증 수준을 얻는 데 사용되는 고유 프로토콜을 가지고 있습니다. 각 방법은 QGIS 인증 인프라스트럭처 초기 설정 시 동적으로 불러오는 공유 라이브러리로 구현됩니다.

14.3. QgsAuthManager: 입구점 

QgsAuthManager 클래스 단독 개체(singleton)는 예를 들어 활성 사용자 프로파일 폴더 아래 있는 qgis-auth.db 파일 같은 QGIS 암호화 Authentication DB 에 저장되어 있는 인증 정보를 사용하기 위한 입구점(entry point)입니다.

이 클래스는 저장된 암호화 정보에 접근하기 위해 마스터 비밀번호를 설정하라고 요청하거나 또는 마스터 비밀번호를 투명하게 사용하는 방식으로 사용자의 쌍방향 작업을 처리합니다.

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. 새 인증 환경설정 항목으로 인증 DB 채우기 

저장된 모든 인증 정보는 다음과 같은 유일한 문자열을 사용해서 접근하는 QgsAuthMethodConfig 클래스의 Authentication Configuration 인스턴스입니다:

authcfg = 'fm1s770'

QGIS API 또는 GUI를 사용해서 환경설정 항목을 생성할 때 이런 문자열을 자동으로 생성하지만, 어떤 조직 내부에서 사용자 여러 명 사이에서 인증 환경설정을 (서로 다른 인증 정보를 사용해서) 공유해야만 하는 경우 이미 알고 있는 값으로 직접 설정하는 편이 유용할 수도 있습니다.

QgsAuthMethodConfig 클래스는 모든 Authentication Method 의 기저 클래스입니다. 모든 인증 방법은 인증 정보를 저장할 환경설정 해시 맵(configuration hash map)을 설정합니다. 다음은 alice 라는 가상의 사용자에 대한 PKI 경로 인증 정보를 저장할 수 있는 유용한 코드 조각입니다:

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 라이브러리를 동적으로 불러옵니다. 다음 인증 방법을 사용할 수 있습니다:

Basic: 사용자 이름과 비밀번호 인증
EsriToken: ESRI 토큰 기반 인증
Identity-Cert: 신원 인증서 인증
OAuth2: OAuth2(Open Authorization 2.0) 인증
PKI-Paths: PKI 경로 인증
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 번들 관리하기 

QgsPkiBundle 클래스는 SSLCert, SSLKey 및 CA 체인에 대해 구성된 PKI 번들을 패키징하는 편리한 클래스입니다. 다음은 비밀번호를 보호하기 위한 코드 조각입니다:

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

이 번들에서 인증서/키/인증 기관을 추출하려면 QgsPkiBundle 클래스 문서를 참조하세요.

14.3.3. 인증 DB에서 항목 제거하기 

Authentication Database 의 authcfg 식별자를 다음 코드 조각처럼 사용하면 인증 데이터베이스에서 항목 하나를 제거할 수 있습니다:

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

14.3.4. QgsAuthManager에 인증 환경설정 확장을 맡기기 

Authentication DB 에 저장되어 있는 Authentication Config 을 사용하는 최선의 방법은 authcfg 식별자를 사용해서 인증 환경설정을 참조하는 것입니다. 확장이란 이 식별자 하나를 완전한 인증 정보 집합으로 변환하는 것을 말합니다. 저장되어 있는 Authentication Config 들을 사용하는 최선의 방법은 인증 관리자가 자동으로 관리하도록 내버려두는 것입니다. WMS 또는 WFS처럼 인증이 활성화된 서비스 또는 데이터베이스에 연결하는 것이 저장된 환경설정을 사용하는 가장 흔한 방법입니다.

참고

모든 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 예시 

QGIS 테스트 업스트림에 있는 test_authmanager_pki_ows 또는 test_authmanager_pki_postgres 에서 기타 예시를 직접 읽어볼 수 있습니다.

14.4. 플러그인이 인증 인프라스트럭처를 사용하도록 조정하기 

제3자 플러그인 가운데 다수가 HTTP 연결을 관리하기 위해 QgsNetworkAccessManager 클래스 및 관련 통합 인증 인프라스트럭처와 통합하는 대신 httplib2 또는 다른 파이썬 네트워크 작업 라이브러리를 사용하고 있습니다.

이런 통합을 용이하게 하기 위해 NetworkAccessManager 라는 파이썬 도우미 함수가 생성되었습니다. 여기 에서 그 코드를 찾아볼 수 있습니다.

이 도우미 클래스를 다음 코드 조각에서처럼 사용할 수 있습니다:

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 하나를 선택해야 하는 경우 QgsAuthConfigSelect GUI 클래스에서 선택할 수 있습니다.

다음 코드 조각에서와 같이 사용하면 됩니다:

# 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 소스 코드 에서 발췌한 것입니다. GUI 작성자의 두 번째 파라미터는 데이터 제공자 유형을 알려줍니다. 이 파라미터는 지정한 제공자와 호환되는 Authentication Method 들을 제한하기 위해 쓰입니다.

14.5.2. 인증 편집기 GUI 

QgsAuthEditorWidgets 클래스가 인증 정보, 기관을 관리하고 인증 유틸리티들에 접근하는 데 사용되는 완전한 GUI를 관리합니다.

다음 코드 조각에서와 같이 사용하면 됩니다:

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

관련 테스트 에서 통합된 예시를 찾아볼 수 있습니다.

14.5.3. 기관 편집기 GUI 

QgsAuthAuthoritiesEditor 클래스가 기관만을 관리하는 데 사용되는 GUI를 관리합니다.

../../_images/QgsAuthAuthoritiesEditor.png

다음 코드 조각에서와 같이 사용하면 됩니다:

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