En esta página

QOAuthUriSchemeReplyHandler Class

Gestiona redireccionamientos privados/personalizados y con el esquema URI «https». Más...

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

Propiedades

Funciones públicas

QOAuthUriSchemeReplyHandler()
QOAuthUriSchemeReplyHandler(QObject *parent)
QOAuthUriSchemeReplyHandler(const QUrl &redirectUrl, QObject *parent = nullptr)
virtual ~QOAuthUriSchemeReplyHandler() override
void close()
(since 6.9) bool handleAuthorizationRedirect(const QUrl &url)
bool isListening() const
bool listen()
QUrl redirectUrl() const
void setRedirectUrl(const QUrl &url)

Señales

Descripción detallada

Esta clase actúa como gestor de respuestas para los procesos de autorización OAuth 2.0 que utilizan esquemas URI privados/personalizados o HTTPS para la redirección. Gestiona la recepción de la redirección de autorización (también conocida como «callback») y la posterior obtención de tokens de acceso.

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.

El uso de esquemas URI específicos requiere una configuración a nivel del sistema operativo para asociar la URI con la aplicación correcta. La forma de configurar esta asociación varía según el sistema operativo. Véase Platform Support and Dependencies.

Esta clase complementa a QOAuthHttpServerReplyHandler, que gestiona los esquemas http mediante la configuración de un servidor localhost.

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

QOAuth2AuthorizationCodeFlow m_oauth;
QOAuthUriSchemeReplyHandler m_handler;

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

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

Por último, configuramos el gestor de respuestas del esquema URI:

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

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

Esquemas de URI privados/personalizados

Los esquemas URI personalizados suelen utilizar la notación de dominio inverso seguida de una ruta, o en ocasiones un host o un host más una ruta:

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

Esquema URI HTTPS

Con los esquemas URI HTTPS, las URL de redirección son enlaces https normales:

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

Estos enlaces se denominan «Universal Links » en iOS y «App Links» en Android.

Se recomienda el uso de esquemas HTTPS, ya que proporcionan seguridad adicional al obligar a los desarrolladores de aplicaciones a demostrar la propiedad de las URL utilizadas. Esta demostración se realiza alojando un archivo de asociación, que el sistema operativo consultará como parte de su procesamiento interno de URL.

El contenido de este archivo asocia la aplicación con las URL utilizadas. Los archivos de asociación deben ser de acceso público sin redireccionamientos HTTP. Además, el sitio donde se aloja debe contar con certificados válidos y, al menos en el caso de Android, el archivo debe servirse con el tipo de contenid application/json (consulta la guía de configuración de tu servidor).

Además, los enlaces https pueden ofrecer algunas ventajas de usabilidad:

  • La URL https funciona también como un enlace https normal. Si el usuario no tiene instalada la aplicación (ya que la URL no ha sido gestionada por ninguna aplicación), el enlace https puede, por ejemplo, mostrar instrucciones para instalarla.
  • Se puede evitar el cuadro de diálogo de selección de aplicación para abrir la URL y, en su lugar, tu aplicación se abrirá automáticamente

La contrapartida es que esto requiere una configuración adicional, ya que es necesario configurar este archivo de asociación alojado públicamente.

Compatibilidad con plataformas y dependencias

Las plataformas compatibles actualmente son Android, iOS y macOS.

La escucha de esquemas URI se basa en QDesktopServices::setUrlHandler() y QDesktopServices::unsetUrlHandler(). Actualmente, estos los proporciona el módulo Qt::Gui y, por lo tanto, el módulo QtNetworkAuth depende de Qt::Gui. Si QtNetworkAuth se compila sin Qt::Gui, QOAuthUriSchemeReplyHandler no se incluirá.

Android

En Android, los esquemas URI requieren:

  • Configurar « intent-filters » en el manifiesto de la aplicación
  • Opcionalmente, para la verificación automática con esquemas https, alojar un archivo de asociación de sitios assetlinks.json

Consulta también la configuración del archivo de manifiesto de Qt para Android.

iOS y macOS

En iOS y macOS, los esquemas URI requieren:

  • Configuración de la asociación de sitios entitlement
  • Con esquemas https, alojar un archivo de asociación de sitios ( site association file ) (apple-app-site-association)

Windows, Linux

Actualmente no es compatible. Sin embargo, las plataformas y los casos de uso que lo admitan Qt WebEngine pueden seguir utilizando este controlador de respuesta; consulta la documentación sobre compatibilidad de Qt OAuth2 con navegadores para obtener más detalles.

Documentación de propiedades

redirectUrl : QUrl

Esta propiedad contiene la URL utilizada para recibir la redirección o la respuesta de autorización.

Esta propiedad se utiliza como el parámetro «redirect_uri» de OAuth2, que se envía como parte de la solicitud de autorización. El « redirect_uri » se obtiene llamando a QUrl::toString() con las opciones predeterminadas.

La URL debe coincidir con la registrada en el servidor de autorización, ya que es probable que los servidores de autorización rechacen cualquier redirection_uri que no coincida.

Del mismo modo, cuando este controlador recibe la redirección, la URL de redirección debe coincidir con la URL establecida aquí. El controlador compara el esquema, el host, el puerto, la ruta y cualquier parámetro de consulta que formara parte de la URL establecida mediante este método.

La URL solo se gestiona si todos estos elementos coinciden. La comparación de los parámetros de consulta excluye cualquier parámetro de consulta adicional que se haya podido establecer en el lado del servidor, ya que estos contienen los datos reales de interés.

Funciones de acceso:

QUrl redirectUrl() const
void setRedirectUrl(const QUrl &url)

Señal del notificador:

void redirectUrlChanged()

Documentación de funciones de miembro

QOAuthUriSchemeReplyHandler::QOAuthUriSchemeReplyHandler()

Crea un objeto `QOAuthUriSchemeReplyHandler` con ` callback` y ` redirectUrl` vacíos y sin objeto padre. El objeto creado no entra automáticamente en modo de escucha.

[explicit] QOAuthUriSchemeReplyHandler::QOAuthUriSchemeReplyHandler(QObject *parent)

Crea un objeto `QOAuthUriSchemeReplyHandler` con ` parent ` y los parámetros ` callback` ()/ `redirectUrl` (), ambos vacíos. El objeto creado no entra automáticamente en modo de escucha.

[explicit] QOAuthUriSchemeReplyHandler::QOAuthUriSchemeReplyHandler(const QUrl &redirectUrl, QObject *parent = nullptr)

Crea un objeto `QOAuthUriSchemeReplyHandler` y establece ` parent ` como objeto padre y ` redirectUrl ` como URL de redireccionamiento. El objeto creado intenta ponerse a la escucha automáticamente.

Véanse también redirectUrl(), setRedirectUrl(), listen() y isListening().

[override virtual noexcept] QOAuthUriSchemeReplyHandler::~QOAuthUriSchemeReplyHandler()

Elimina el objeto « QOAuthUriSchemeReplyHandler ». Cierra este controlador.

Véase también close().

void QOAuthUriSchemeReplyHandler::close()

Indica a este controlador que deje de escuchar las URL entrantes.

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

[since 6.9] bool QOAuthUriSchemeReplyHandler::handleAuthorizationRedirect(const QUrl &url)

Esta función se utiliza para proporcionar la URL de redireccionamiento que el servidor de autorización facilita al final de la fase de autorización. La URL url facilitada se somete al mismo proceso de comprobación de URL que se describe en redirectUrl.

Proporcionar la URL puede resultar útil en casos en los que esta URL de redireccionamiento se capture por otros medios, por ejemplo, mediante Qt WebEngine o mediante algún otro mecanismo personalizado. De este modo, el uso de dicho agente puede integrarse con el resto del flujo OAuth2.

Este controlador no necesita estar a la escucha, por lo que se recomienda llamar a close() para evitar una escucha innecesaria.

Devuelve ` true ` si la URL coincidió y se gestionó; en caso contrario, devuelve ` false `.

Véase también «Esquemas de URI de redirección con Qt WebEngine ».

Esta función se introdujo en Qt 6.9.

[noexcept] bool QOAuthUriSchemeReplyHandler::isListening() const

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

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

bool QOAuthUriSchemeReplyHandler::listen()

Indica a este controlador que esté atento a las URL entrantes. Devuelve true si la escucha se realiza correctamente y false en caso contrario.

El controlador comparará las URL con redirectUrl(). Si la URL recibida no coincide, se reenviará a QDesktopServices::openURL().

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 oyente tras una autorización satisfactoria. La escucha no es necesaria para acquiring access tokens.

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