QOAuthUriSchemeReplyHandler Class

상세 설명

이 클래스는 리디렉션에 비공개/사용자 정의 또는 HTTPS URI 스키마를 사용하는 OAuth 2.0 인증 프로세스에 대한 응답 핸들러 역할을 합니다. 이 클래스는 인증 리디렉션(콜백이라고도 함)의 수신과 그에 따른 액세스 토큰 획득을 관리합니다.

리디렉션 URI는 플로우의 인증 단계가 완료되면 인증 서버가 사용자 에이전트(일반적으로, 그리고 바람직하게는 시스템 브라우저)를 리디렉션하는 곳입니다.

특정 URI 스키마를 사용하려면 URI를 올바른 애플리케이션과 연결하기 위해 운영 체제 수준에서 구성이 필요합니다. 이 연결을 설정하는 방법은 운영 체제마다 다릅니다. Platform Support and Dependencies 을 참조하십시오.

이 클래스는 로컬호스트 서버를 설정하여 http 스키마를 처리하는 QOAuthHttpServerReplyHandler 를 보완합니다.

다음 코드는 사용법을 보여줍니다. 먼저, 필요한 변수들:

QOAuth2AuthorizationCodeFlow m_oauth;
QOAuthUriSchemeReplyHandler m_handler;

이어서 OAuth 설정입니다(간결함을 위해 오류 처리는 생략했습니다):

m_oauth.setAuthorizationUrl(QUrl(authorizationUrl));
m_oauth.setTokenUrl(QUrl(accessTokenUrl));
m_oauth.setClientIdentifier(clientIdentifier);
m_oauth.setRequestedScopeTokens({scope});

connect(&m_oauth, &QAbstractOAuth::authorizeWithBrowser, this, &QDesktopServices::openUrl);
connect(&m_oauth, &QAbstractOAuth::granted, this, [this]() {
    // Here we use QNetworkRequestFactory to store the access token
    m_api.setBearerToken(m_oauth.token().toLatin1());
    m_handler.close();
});

마지막으로, URI 스키마 reply-handler를 설정합니다:

m_handler.setRedirectUrl(QUrl{"com.example.myqtapp://oauth2redirect"_L1});
m_oauth.setReplyHandler(&m_handler);

// Initiate the authorization
if (m_handler.listen()) {
    m_oauth.grant();
}

비공개/사용자 정의 URI 스키마

사용자 정의 URI 스키마는 일반적으로 리버스 도메인 표기법에 경로를 붙이거나, 때로는 호스트 또는 호스트+경로를 사용합니다:

// Example with path:
com.example.myapp:/oauth2/callback
// Example with host:
com.example.myapp://oauth2.callback

HTTPS URI 스키마

HTTPS URI 스키마를 사용할 경우, 리디렉션 URL은 일반적인 https 링크입니다:

https://myapp.example.com/oauth2/callback

이러한 링크는 iOS에서는 ‘유니버설 링크 ( Universal Links)’, Android에서는 ‘앱 링크(App Links)’라고 합니다.

HTTPS 스키마를 사용하는 것이 권장되는데, 이는 애플리케이션 개발자가 사용된 URL의 소유권을 증명하도록 요구함으로써 추가적인 보안을 제공하기 때문입니다. 이러한 증명은 연관 파일을 호스팅함으로써 이루어지며, 운영 체제는 내부 URL 분배 과정의 일환으로 이 파일을 참조합니다.

이 파일의 내용은 애플리케이션과 사용된 URL을 연결해 줍니다. 연관 파일은 HTTP 리디렉션 없이 공개적으로 접근 가능해야 합니다. 또한, 호스팅 사이트는 유효한 인증서를 보유해야 하며, 적어도 Android의 경우 파일은 application/json 콘텐츠 유형으로 제공되어야 합니다(서버 구성 가이드를 참조하십시오).

또한, https 링크는 다음과 같은 사용 편의상의 이점을 제공할 수 있습니다:

• HTTPS URL은 일반 HTTPS 링크 역할도 겸합니다. 사용자가 애플리케이션을 설치하지 않은 경우(URL이 어떤 애플리케이션으로도 처리되지 않았기 때문), HTTPS 링크는 예를 들어 애플리케이션을 설치하는 방법을 안내할 수 있습니다.
• URL을 열기 위한 애플리케이션 선택 대화상자가 표시되지 않고, 대신 해당 애플리케이션이 자동으로 실행될 수 있습니다.

단, 공개 호스팅되는 이 연관성 파일을 설정해야 하므로 추가적인 설정이 필요하다는 점이 단점입니다.

플랫폼 지원 및 종속성

현재 지원되는 플랫폼은 Android, iOS 및 macOS입니다.

URI 스키마 수신은 QDesktopServices::setUrlHandler() 및 QDesktopServices::unsetUrlHandler()를 기반으로 합니다. 이 기능들은 현재 Qt::Gui 모듈에서 제공되므로 QtNetworkAuth 모듈은 Qt::Gui에 의존합니다. QtNetworkAuth 가 Qt::Gui 없이 빌드된 경우, QOAuthUriSchemeReplyHandler는 포함되지 않습니다.

Android

Android 에서는 URI 스키마를 사용하려면 다음이 필요합니다:

• 애플리케이션 매니페스트에서 intent-filters 설정
• 선택 사항으로, https 스키마를 사용한 자동 인증을 위해 사이트 연결 파일을 호스팅해야 합니다. assetlinks.json

Qt Android 매니페스트 파일 구성도 참조하십시오.

iOS 및 macOS

iOS 및 macOS 에서 URI 스키마를 사용하려면 다음이 필요합니다:

• 사이트 연결 설정 entitlement
• HTTPS 스키마를 사용하는 경우, site association file (apple-app-site-association)을 호스팅해야 합니다.

Windows, Linux

현재 지원되지 않습니다. 그러나 이를 지원하는 플랫폼 및 사용 사례의 경우 Qt WebEngine 이 응답 핸들러를 여전히 사용할 수 있습니다. 자세한 내용은 Qt OAuth2 브라우저 지원 문서를 참조하십시오.