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 를 사용하고, 호스트로 localhost 또는 IP 주소 리터럴을 사용합니다( IPv4 and IPv6 참조).

QOAuthHttpServerReplyHandler는 localhost 서버를 설정합니다. 인증 서버가 브라우저를 이 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 스키마 reply-handler를 설정합니다:

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} 형식을 따르게 됩니다.

다음 예제는 이를 설명합니다:

// 인증서 및 개인 키 읽기
auto certificates = 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 를 호출하거나 이를 새로 고칠 때는 리스닝이 필요하지 않습니다.

이 함수가 address 로 Null 를 받아 호출되면, 핸들러는 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)

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

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

callbackHost()도 참조하십시오 .

void QOAuthHttpServerReplyHandler::setCallbackPath(const QString &path)

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

callbackPath()도 참조하십시오 .

void QOAuthHttpServerReplyHandler::setCallbackText(const QString &text)

인증 단계가 끝날 때 발생하는 리디렉션에 대응하기 위해 ` text `를 설정합니다.

callbackText()도 참조하십시오 .

© 2026 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.