QOAuthHttpServerReplyHandler Class

Handles loopback redirects by setting up a local HTTP server. 更多...

头：	`#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 ()
`(从 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
`(从 6.9 起)` void	setCallbackHost (const QString & host )
void	setCallbackPath (const QString & path )
void	setCallbackText (const QString & text )

详细描述

This class serves as a reply handler for OAuth 2.0 authorization processes that use loopback redirection .

The redirect URI is where the authorization server redirects the user-agent (typically, and preferably, the system browser) once the authorization part of the flow is complete. Loopback redirect URIs use http as the scheme and either localhost or an IP address literal as the host (see IPv4 and IPv6 ).

QOAuthHttpServerReplyHandler sets up a localhost server. Once the authorization server redirects the browser to this localhost address, the reply handler parses the redirection URI query parameters, and then signals authorization completion with a signal .

To handle other redirect URI schemes, see QOAuthUriSchemeReplyHandler .

The following code illustrates the usage. First, the needed variables:

QOAuth2AuthorizationCodeFlow m_oauth;
QOAuthHttpServerReplyHandler *m_handler = nullptr;

Followed up by the OAuth setup (error handling omitted for brevity):

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

Finally, we then set up the URI scheme reply-handler:

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

IPv4 and IPv6

If the handler is an any address handler ( AnyIPv4, AnyIPv6, or Any ), the used callback is in the form of http://localhost:{port}/{path} . Handler will first attempt to listen on IPv4 loopback address, and then on IPv6. localhost is used because it resolves correctly on both IPv4 and IPv6 interfaces.

For loopback addresses ( LocalHost or LocalHostIPv6 ) the IP literals ( 127.0.0.1 and ::1 ) are used.

For specific IP addresses the provided IP literal is used directly, for instance: http://192.168.0.123:{port}/{path} in the case of an IPv4 address.

It's also possible to specify the host part of the callback URL manually with setCallbackHost (). For instance you can specify the callback to be localhost.localnet . Naturally you need to ensure that such address is reachable upon redirection.

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

HTTP and HTTPS Callbacks

Since Qt 6.9 it's possible to configure the handler to use https URI scheme instead of http . This is done by providing an appropriate QSslConfiguration 当调用 listen (). Internally the handler will then use QSslServer , and the callback (redirect URL) will be of the form https://{host}:{port}/{path} .

Following example illustrates this:

// Read certificate and private key
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;
}
// Create SSL configuration
QSslConfiguration configuration = QSslConfiguration::defaultConfiguration();
configuration.setLocalCertificate(certificates.at(0));
configuration.setPrivateKey(privateKey);
// Instantiate handler with the SSL configuration
m_handler = new QOAuthHttpServerReplyHandler(1234, this);
m_handler->listen(configuration);

When possible, it is recommended to use other redirect URI options, see Choosing A Reply Handler and Qt OAuth2 浏览器支持 .

The primary use cases for a localhost https handler should be limited to development-time, or tightly controlled and provisioned environments. For example, some Authorization Servers won't allow plain http redirect URIs at all, in which case this can add to development convenience.

From security perspective, while using SSL/TLS does encrypt the localhost traffic, OAuth2 has also other security mechanisms in place such as PKCE . Under no circumstances you should distribute private certificate keys along with the application.

注意： Browsers will issue severe warnings if the certificate is not trusted. This is typical with self-signed certificates, whose use should be limited to development-time.

成员函数文档编制

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

Constructs a QOAuthHttpServerReplyHandler object using parent as a parent object. Calls listen () with port 0 and address LocalHost .

另请参阅 listen ().

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

Constructs a QOAuthHttpServerReplyHandler object using parent as a parent object. Calls listen () 采用 port and address LocalHost .

另请参阅 listen ().

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

Constructs a QOAuthHttpServerReplyHandler object using parent as a parent object. Calls listen () 采用 address and port .

另请参阅 listen ().

`[virtual noexcept]` QOAuthHttpServerReplyHandler:: ~QOAuthHttpServerReplyHandler ()

销毁 QOAuthHttpServerReplyHandler object. Stops listening for connections / redirections.

另请参阅 close ().

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

Returns the name that is used as the host component of the callback () / OAuth2 redirect_uri parameter .

该函数在 Qt 6.9 引入。

另请参阅 setCallbackHost ().

QString QOAuthHttpServerReplyHandler:: callbackPath () const

Returns the path that is used as the path component of the callback () / OAuth2 redirect_uri parameter .

另请参阅 setCallbackPath ().

QString QOAuthHttpServerReplyHandler:: callbackText () const

Returns the text that is used in response to the redirection at the end of the authorization stage.

The text is wrapped in a simple HTML page, and displayed to the user by the browser / user-agent which did the redirection.

The default text is

Callback received. Feel free to close this page.

另请参阅 setCallbackText ().

void QOAuthHttpServerReplyHandler:: close ()

Tells this handler to stop listening for connections / redirections.

另请参阅 listen ().

bool QOAuthHttpServerReplyHandler:: isListening () const

返回 true if this handler is currently listening, and false 否则。

另请参阅 listen () 和 close ().

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

Tells this handler to listen for incoming connections / redirections on address and port 。返回 true if listening is successful, and false 否则。

Active listening is only required when performing the initial authorization phase, typically initiated by a QOAuth2AuthorizationCodeFlow::grant () 调用。

It is recommended to close the listener after successful authorization. Listening is not needed for requesting access tokens or refreshing them.

If this function is called with Null 作为 address , the handler will attempt to listen to LocalHost , and if that fails, LocalHostIPv6 .

另请参阅 IPv4 and IPv6 .

另请参阅 close (), isListening ()，和 QTcpServer::listen ().

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

Tells this handler to listen for incoming https connections / redirections on address and port 。返回 true if listening is successful, and false 否则。

见 HTTP and HTTPS Callbacks for further information.

另请参阅 listen (const QHostAddress &, quint16), close (), isListening (), QSslServer ，和 QTcpServer::listen ().

quint16 QOAuthHttpServerReplyHandler:: port () const

Returns the port on which this handler is listening, otherwise returns 0.

另请参阅 listen () 和 isListening ().

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

设置 host to be used as the hostname component of the callback (). Providing a non-empty host overrides the default behavior, see IPv4 and IPv6 .

该函数在 Qt 6.9 引入。

另请参阅 callbackHost ().

void QOAuthHttpServerReplyHandler:: setCallbackPath (const QString & path )

设置 path to be used as the path component of the callback ().

另请参阅 callbackPath ().

void QOAuthHttpServerReplyHandler:: setCallbackText (const QString & text )

设置 text to be used in response to the redirection at the end of the authorization stage.

另请参阅 callbackText ().

QOAuthHttpServerReplyHandler Class

公共函数

详细描述

IPv4 and IPv6

HTTP and HTTPS Callbacks

成员函数文档编制

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

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

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

[virtual noexcept] QOAuthHttpServerReplyHandler:: ~QOAuthHttpServerReplyHandler ()

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

QString QOAuthHttpServerReplyHandler:: callbackPath () const

QString QOAuthHttpServerReplyHandler:: callbackText () const

void QOAuthHttpServerReplyHandler:: close ()

bool QOAuthHttpServerReplyHandler:: isListening () const

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

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

quint16 QOAuthHttpServerReplyHandler:: port () const

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

void QOAuthHttpServerReplyHandler:: setCallbackPath (const QString & path )

void QOAuthHttpServerReplyHandler:: setCallbackText (const QString & text )

内容

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

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

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

`[virtual noexcept]` QOAuthHttpServerReplyHandler:: ~QOAuthHttpServerReplyHandler ()

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

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