En esta página

QOAuthHttpServerReplyHandler Class

Gestiona las redirecciones de bucle cerrado mediante la configuración de un servidor HTTP local. Más información...

Encabezado: #include <QOAuthHttpServerReplyHandler>
CMake: find_package(Qt6 REQUIRED COMPONENTS NetworkAuth)
target_link_libraries(mytarget PRIVATE Qt6::NetworkAuth)
qmake: QT += networkauth
Heredado de: QOAuthOobReplyHandler

Funciones públicas

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)

Descripción detallada

Esta clase actúa como gestor de respuestas para los procesos de autorización OAuth 2.0 que utilizan la redirección de bucle cerrado.

El URI de redirección es el lugar al que el servidor de autorización redirige al agente de usuario (normalmente, y preferiblemente, el navegador del sistema) una vez completada la parte de autorización del flujo. Los URI de redirección de bucle cerrado utilizan http como esquema y «localhost» o una dirección IP literal como host (véase IPv4 and IPv6).

QOAuthHttpServerReplyHandler configura un servidor en localhost. Una vez que el servidor de autorización redirige el navegador a esta dirección de localhost, el gestor de respuestas analiza los parámetros de consulta del URI de redirección y, a continuación, indica que la autorización se ha completado mediante a signal.

Para gestionar otros esquemas de URI de redirección, consulta QOAuthUriSchemeReplyHandler.

El siguiente código ilustra su uso. En primer lugar, las variables necesarias:

QOAuth2AuthorizationCodeFlow m_oauth;
QOAuthHttpServerReplyHandler *m_handler = nullptr;

A continuación, la configuración de OAuth (se ha omitido el manejo de errores por motivos de brevedad):

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();
});

Por último, configuramos el esquema URI «reply-handler»:

m_oauth.setReplyHandler(m_handler);

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

IPv4 e IPv6

Si el controlador es un controlador de cualquier dirección (AnyIPv4, AnyIPv6, or Any), la llamada de retorno utilizada tiene el formato http://localhost:{port}/{path}. El controlador intentará primero escuchar en la dirección de bucle invertido de IPv4 y, a continuación, en la de IPv6. Se utiliza localhost porque se resuelve correctamente tanto en interfaces IPv4 como IPv6.

Para las direcciones de bucle invertido (LocalHost or LocalHostIPv6) se utilizan los literales IP (127.0.0.1 y ::1).

Para direcciones IP específicas, se utiliza directamente el literal de IP proporcionado; por ejemplo: http://192.168.0.123:{port}/{path} en el caso de una dirección IPv4.

También es posible especificar manualmente la parte del host de la URL de devolución de llamada con setCallbackHost(). Por ejemplo, puedes especificar que la URL de devolución de llamada sea localhost.localnet. Naturalmente, debes asegurarte de que se pueda acceder a dicha dirección tras la redirección.

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

Callbacks HTTP y HTTPS

Desde Qt 6.9 es posible configurar el controlador para que utilice el esquema URI https en lugar de http. Para ello, hay que proporcionar un QSslConfiguration adecuado al llamar a listen(). Internamente, el controlador utilizará entonces QSslServer, y la URL de devolución de llamada (URL de redireccionamiento) tendrá el formato https://{host}:{port}/{path}.

El siguiente ejemplo lo ilustra:

// Leer el certificado y la clave privada
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;
}

// Crear la configuración SSL
QSslConfiguration configuración = QSslConfiguration::defaultConfiguration();
configuration.setLocalCertificate(certificates.at(0));
configuration.setPrivateKey(privateKey);

// Instanciar el controlador con la configuración SSL
m_handler = new QOAuthHttpServerReplyHandler(1234, this);
m_handler->listen(configuración);

Siempre que sea posible, se recomienda utilizar otras opciones de URI de redirección; consulta «Elección de un controlador de respuesta » y «Compatibilidad de Qt con OAuth2 para navegadores».

Los principales casos de uso de un controlador « https » en localhost deben limitarse a la fase de desarrollo o a entornos estrictamente controlados y provisionados. Por ejemplo, algunos servidores de autorización no permiten en absoluto las URI de redirección « http » sin cifrar, en cuyo caso esto puede facilitar el desarrollo.

Desde el punto de vista de la seguridad, aunque el uso de SSL/TLS cifra el tráfico de localhost, OAuth2 también cuenta con otros mecanismos de seguridad, como PKCE. Bajo ninguna circunstancia se deben distribuir claves de certificados privadas junto con la aplicación.

Nota: Los navegadores mostrarán advertencias graves si el certificado no es de confianza. Esto suele ocurrir con los certificados autofirmados, cuyo uso debe limitarse a la fase de desarrollo.

Documentación de las funciones de miembro

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

Crea un objeto `QOAuthHttpServerReplyHandler` utilizando ` parent ` como objeto padre. Llama a ` listen()` con el puerto 0 y la dirección LocalHost.

Véase también listen().

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

Crea un objeto `QOAuthHttpServerReplyHandler` utilizando ` parent ` como objeto padre. Llama a ` listen()` con ` port ` y la dirección ` LocalHost`.

Véase también listen().

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

Crea un objeto `QOAuthHttpServerReplyHandler` utilizando ` parent ` como objeto padre. Llama a ` listen()` con ` address ` y ` port`.

Véase también listen().

[virtual noexcept] QOAuthHttpServerReplyHandler::~QOAuthHttpServerReplyHandler()

Elimina el objeto ` QOAuthHttpServerReplyHandler `. Deja de escuchar conexiones o redireccionamientos.

Véase también close().

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

Devuelve el nombre que se utiliza como componente de host del parámetro` callback()` / ` redirect_uri` de OAuth2.

Esta función se introdujo en Qt 6.9.

Véase también setCallbackHost().

QString QOAuthHttpServerReplyHandler::callbackPath() const

Devuelve la ruta que se utiliza como componente de ruta del parámetro` callback()` / ` redirect_uri` de OAuth2.

Véase también setCallbackPath().

QString QOAuthHttpServerReplyHandler::callbackText() const

Devuelve el texto que se utiliza en la respuesta a la redirección al final de la fase de autorización.

El texto se incluye en una página HTML sencilla y se muestra al usuario a través del navegador o agente de usuario que ha realizado la redirección.

El texto predeterminado es

Callback received. Feel free to close this page.

Véase también setCallbackText().

void QOAuthHttpServerReplyHandler::close()

Indica a este controlador que deje de escuchar conexiones o redirecciones.

Véase también listen().

bool QOAuthHttpServerReplyHandler::isListening() const

Devuelve ` true ` si este controlador está actualmente a la escucha, y ` false ` en caso contrario.

Véanse también listen() y close().

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

Indica a este controlador que escuche las conexiones entrantes y las redirecciones en address y port. Devuelve true si la escucha se realiza correctamente y, en caso contrario, false.

La escucha activa solo es necesaria durante la fase de autorización inicial, que suele iniciarse mediante una llamada a QOAuth2AuthorizationCodeFlow::grant().

Se recomienda cerrar el listener una vez que la autorización se haya realizado con éxito. La escucha no es necesaria para los requesting access tokens ni para su actualización.

Si se invoca esta función con Null como address, el controlador intentará escuchar en LocalHost y, si falla, en LocalHostIPv6.

Véase también IPv4 and IPv6.

Véase también close(), isListening() y QTcpServer::listen().

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

Indica a este controlador que escuche las conexiones entrantes de https y las redirecciones en address y port. Devuelve true si la escucha se realiza correctamente y, en caso contrario, false.

Consulte HTTP and HTTPS Callbacks para obtener más información.

Véase también listen(const QHostAddress &, quint16), close(), isListening(), QSslServer y QTcpServer::listen().

quint16 QOAuthHttpServerReplyHandler::port() const

Devuelve el puerto en el que este controlador está a la escucha; en caso contrario, devuelve 0.

Véase también listen() y isListening().

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

Establece « host » para que se utilice como componente del nombre de host de « callback()». Si se proporciona un « host » no vacío, se anula el comportamiento predeterminado; véase IPv4 and IPv6.

Esta función se introdujo en Qt 6.9.

Véase también callbackHost().

void QOAuthHttpServerReplyHandler::setCallbackPath(const QString &path)

Establece ` path ` para que se utilice como componente de ruta de ` callback()`.

Véase también callbackPath().

void QOAuthHttpServerReplyHandler::setCallbackText(const QString &text)

Establece text para que se utilice en respuesta a la redirección al final de la fase de autorización.

Véase también 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.