Back to Qt.io
Contact Us Blog Download Qt

QOAuthHttpServerReplyHandler Class

로컬 HTTP 서버를 설정하여 루프백 리디렉션을 처리합니다. 더 보기...

헤더: #include <QOAuthHttpServerReplyHandler>
CMake: find_package(Qt6 REQUIRED COMPONENTS NetworkAuth)
target_link_libraries(mytarget PRIVATE Qt6::NetworkAuth)
qmake: QT += networkauth
상속합니다: QOAuthOobReplyHandler

공용 함수

QOAuthHttpServerReplyHandler(QObject *parent = nullptr)
QOAuthHttpServerReplyHandler(quint16 port, QObject *parent = nullptr)
QOAuthHttpServerReplyHandler(const QHostAddress &address, quint16 port, QObject *parent = nullptr)
virtual ~QOAuthHttpServerReplyHandler()
(since 6.9) QString callbackHost() const
QString callbackPath() const
QString callbackText() const
void close()
bool isListening() const
bool listen(const QHostAddress &address = QHostAddress::Any, quint16 port = 0)
bool listen(const QSslConfiguration &configuration, const QHostAddress &address = QHostAddress::Any, quint16 port = 0)
quint16 port() const
(since 6.9) void setCallbackHost(const QString &host)
void setCallbackPath(const QString &path)
void setCallbackText(const QString &text)

상세 설명

이 클래스는 루프백 리디렉션을 사용하는 OAuth 2.0 인증 프로세스에 대한 응답 처리기 역할을 합니다.

리디렉션 URI는 인증 서버가 흐름의 인증 부분이 완료되면 사용자 에이전트(일반적으로 시스템 브라우저)를 리디렉션하는 곳입니다. 루프백 리디렉션 URI는 http 을 스키마로 사용하고 로컬 호스트 또는 IP 주소 리터럴을 호스트로 사용합니다( IPv4 and IPv6 참조 ).

QOAuthHttpServerReplyHandler는 로컬 호스트 서버를 설정합니다. 권한 부여 서버가 브라우저를 이 localhost 주소로 리디렉션하면 응답 처리기는 리디렉션 URI 쿼리 매개 변수를 구문 분석한 다음 a signal 로 권한 부여 완료 신호를 보냅니다.

다른 리디렉션 URI 스키마를 처리하려면 QOAuthUriSchemeReplyHandler 을 참조하세요.

다음 코드는 사용법을 설명합니다. 먼저 필요한 변수입니다:

QOAuth2AuthorizationCodeFlow m_oauth;
QOAuthHttpServerReplyHandler *m_handler = nullptr;

그 다음에는 OAuth 설정이 이어집니다(간결성을 위해 오류 처리는 생략):

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

m_handler = new QOAuthHttpServerReplyHandler(1234, this);

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 스키마 응답 핸들러를 설정합니다:

m_oauth.setReplyHandler(m_handler);

// Initiate the authorization
if (m_handler->isListening()) {
    m_oauth.grant();
}

IPv4 및 IPv6

핸들러가 임의 주소 핸들러(AnyIPv4, AnyIPv6, or Any)인 경우 사용되는 콜백은 http://localhost:{port}/{path} 형식입니다. 핸들러는 먼저 IPv4 루프백 주소에서 수신한 다음 IPv6에서 수신하려고 시도합니다. localhost 는 IPv4 및 IPv6 인터페이스 모두에서 올바르게 확인되므로 사용됩니다.

루프백 주소(LocalHost or LocalHostIPv6)의 경우 IP 리터럴(127.0.0.1 및 ::1)이 사용됩니다.

특정 IP 주소의 경우 제공된 IP 리터럴이 직접 사용됩니다(예: IPv4 주소의 경우 http://192.168.0.123:{port}/{path} ).

setCallbackHost()를 사용하여 콜백 URL의 호스트 부분을 수동으로 지정할 수도 있습니다. 예를 들어 콜백을 localhost.localnet 로 지정할 수 있습니다. 물론 리디렉션 시 해당 주소에 도달할 수 있는지 확인해야 합니다.

auto replyHandler = new QOAuthHttpServerReplyHandler(QHostAddress::LocalHost, 1337, this);
replyHandler->setCallbackHost("localhost.localnet"_L1);

HTTP 및 HTTPS 콜백

Qt 6.9부터는 http 대신 https URI 스키마를 사용하도록 핸들러를 구성할 수 있습니다. 이는 listen()를 호출할 때 적절한 QSslConfiguration 을 제공함으로써 이루어집니다. 그러면 내부적으로 핸들러는 QSslServer 을 사용하며 콜백(리디렉션 URL)은 https://{host}:{port}/{path} 형식이 됩니다.

다음 예제는 이를 보여줍니다:

// 인증서 및 개인 키자동 인증서  읽기 = ( QSslCertificate::fromPath(sslCertificateFile);QFile keyFile(sslPrivateKeyFile);if (!keyFile.open(QFile::ReadOnly)) {    qWarning("Cannot open key file");
   return; }QSslKey privateKey(&keyFile, QSsl::Rsa, QSsl::Pem);if (certificates.size()== 0 || privateKey.isNull()) {    qWarning("SSL certificate data invalid");
   return; }// SSL 구성 생성QSslConfiguration configuration = QSslConfiguration::defaultConfiguration(); configuration.setLocalCertificate(certificates.at(0)); configuration.setPrivateKey(privateKey);// SSL 구성으로 핸들러 인스턴스화m_handler = new QOAuthHttpServerReplyHandler(1234, this);  m_handler->listen(configuration);

가능하면 다른 리디렉션 URI 옵션을 사용하는 것이 좋습니다( 응답 핸들러 선택하기 및 Qt OAuth2 브라우저 지원을 참조하세요).

localhost https 핸들러의 주요 사용 사례는 개발 시간 또는 엄격하게 제어되고 프로비저닝된 환경으로 제한되어야 합니다. 예를 들어 일부 권한 부여 서버는 일반 http 리디렉션 URI를 전혀 허용하지 않는데, 이 경우 개발 편의성을 높일 수 있습니다.

보안 관점에서 보면 SSL/TLS를 사용하면 로컬 호스트 트래픽을 암호화하지만, OAuth2에는 PKCE 와 같은 다른 보안 메커니즘도 있습니다. 어떤 경우에도 애플리케이션과 함께 비공개 인증서 키를 배포해서는 안 됩니다.

참고: 인증서를 신뢰할 수 없는 경우 브라우저에서 심각한 경고를 표시합니다. 이는 자체 서명 인증서의 경우 일반적으로 발생하며, 개발 시간에만 사용해야 합니다.

멤버 함수 문서

[explicit] QOAuthHttpServerReplyHandler::QOAuthHttpServerReplyHandler(QObject *parent = nullptr)

parent 를 부모 객체로 사용하여 QOAuthHttpServerReplyHandler 객체를 생성합니다. 포트 0 및 주소 LocalHost 를 사용하여 listen()를 호출합니다.

listen()도 참조하세요 .

[explicit] QOAuthHttpServerReplyHandler::QOAuthHttpServerReplyHandler(quint16 port, QObject *parent = nullptr)

parent 을 부모 객체로 사용하여 QOAuthHttpServerReplyHandler 객체를 생성합니다. port 및 주소 LocalHost 를 사용하여 listen()를 호출합니다.

listen()도 참조하세요 .

[explicit] QOAuthHttpServerReplyHandler::QOAuthHttpServerReplyHandler(const QHostAddress &address, quint16 port, QObject *parent = nullptr)

parent 을 부모 객체로 사용하여 QOAuthHttpServerReplyHandler 객체를 생성합니다. address 및 port 를 사용하여 listen()를 호출합니다.

listen()도 참조하세요 .

[virtual noexcept] QOAuthHttpServerReplyHandler::~QOAuthHttpServerReplyHandler()

QOAuthHttpServerReplyHandler 개체를 삭제합니다. 연결/리디렉션 수신을 중지합니다.

close()도 참조하세요 .

[since 6.9] QString QOAuthHttpServerReplyHandler::callbackHost() const

callback() / OAuth2 redirect_uri 매개변수의 호스트 구성 요소로 사용되는 이름을 반환합니다.

이 함수는 Qt 6.9에 도입되었습니다.

setCallbackHost()도 참조하세요 .

QString QOAuthHttpServerReplyHandler::callbackPath() const

callback() / OAuth2 redirect_uri 매개 변수의 경로 구성 요소로 사용되는 경로를 반환합니다.

setCallbackPath()도 참조하세요 .

QString QOAuthHttpServerReplyHandler::callbackText() const

인증 단계가 끝날 때 리디렉션에 대한 응답으로 사용된 텍스트를 반환합니다.

텍스트는 간단한 HTML 페이지로 래핑되며 리디렉션을 수행한 브라우저/사용자 에이전트에 의해 사용자에게 표시됩니다.

기본 텍스트는 다음과 같습니다.

Callback received. Feel free to close this page.

setCallbackText()도 참조하세요 .

void QOAuthHttpServerReplyHandler::close()

이 핸들러에 연결/리디렉션 수신을 중지하도록 지시합니다.

listen()도 참조하세요 .

bool QOAuthHttpServerReplyHandler::isListening() const

이 핸들러가 현재 수신 중이면 true, 그렇지 않으면 false 을 반환합니다.

listen() 및 close()도 참조하세요 .

bool QOAuthHttpServerReplyHandler::listen(const QHostAddress &address = QHostAddress::Any, quint16 port = 0)

이 핸들러에 address 및 port 에서 들어오는 연결/리디렉션을 수신 대기하도록 지시합니다. 수신에 성공하면 true 을 반환하고 그렇지 않으면 false 을 반환합니다.

액티브 리스닝은 일반적으로 QOAuth2AuthorizationCodeFlow::grant() 호출로 시작되는 초기 인증 단계를 수행할 때만 필요합니다.

인증에 성공한 후에는 리스너를 닫는 것이 좋습니다. requesting access tokens 또는 새로 고침에는 수신이 필요하지 않습니다.

이 함수가 Null 를 address 로 사용하여 호출되면 핸들러는 LocalHost 를 수신하려고 시도하고 실패하면 LocalHostIPv6 을 수신합니다.

IPv4 and IPv6 도 참조하세요.

close(), isListening() 및 QTcpServer::listen()도 참조 하세요.

bool QOAuthHttpServerReplyHandler::listen(const QSslConfiguration &configuration, const QHostAddress &address = QHostAddress::Any, quint16 port = 0)

이 핸들러에 address 및 port 에서 들어오는 https 연결/리디렉션을 수신 대기하도록 지시합니다. 수신에 성공하면 true 을 반환하고 그렇지 않으면 false 을 반환합니다.

자세한 내용은 HTTP and HTTPS Callbacks 을 참조하세요.

listen(const QHostAddress &, quint16), close(), isListening(), QSslServer, 및 QTcpServer::listen()도 참조하세요 .

quint16 QOAuthHttpServerReplyHandler::port() const

이 핸들러가 수신 대기 중인 포트를 반환하고, 그렇지 않으면 0을 반환합니다.

listen() 및 isListening()도 참조하세요 .

[since 6.9] void QOAuthHttpServerReplyHandler::setCallbackHost(const QString &host)

callback()의 호스트 이름 구성 요소로 host 을 사용하도록 설정합니다. 비어 있지 않은 host 을 제공하면 기본 동작이 재정의됩니다 ( IPv4 and IPv6 을 참조하십시오).

이 함수는 Qt 6.9에 도입되었습니다.

callbackHost()도 참조하십시오 .

void QOAuthHttpServerReplyHandler::setCallbackPath(const QString &path)

callback()의 경로 구성 요소로 사용하도록 path 을 설정합니다.

callbackPath()도 참조하세요 .

void QOAuthHttpServerReplyHandler::setCallbackText(const QString &text)

인증 단계가 끝날 때 리디렉션에 대한 응답으로 text 을 사용하도록 설정합니다.

callbackText()도 참조하세요 .

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.