QOAuthUriSchemeReplyHandler Class | Qt Network Authorization | Qt 6.11.1
Description: Handles private/custom and https URI scheme redirects.

- Qt 6.11
- Qt Network Authorization
- C++ Classes
- QOAuthUriSchemeReplyHandler
- Qt Network Authorization | Commercial or GPLv3

# QOAuthUriSchemeReplyHandler Class

Handles private/custom and https URI scheme redirects. More...

Header: | `#include <QOAuthUriSchemeReplyHandler>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS NetworkAuth)` `target_link_libraries(mytarget PRIVATE Qt6::NetworkAuth)`
qmake: | `QT += networkauth`
Since: | Qt 6.8
Inherits: | QOAuthOobReplyHandler

- List of all members, including inherited members

## Properties

- redirectUrl : QUrl

## Public Functions

| 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)

## Signals

void | redirectUrlChanged()

## Detailed Description

This class serves as a reply handler for OAuth 2.0 authorization processes that use private/custom or HTTPS URI schemes for redirection. It manages the reception of the authorization redirection (also known as the callback) and the subsequent acquisition of access tokens.

The redirection 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.

The use of specific URI schemes requires configuration at the operating system level to associate the URI with the correct application. The way to set up this association varies between operating systems. See Platform Support and Dependencies.

This class complements QOAuthHttpServerReplyHandler, which handles `http` schemes by setting up a localhost server.

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

     QOAuth2AuthorizationCodeFlow m_oauth;
     QOAuthUriSchemeReplyHandler m_handler;

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

     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_handler.setRedirectUrl(QUrl{"com.example.myqtapp://oauth2redirect"_L1});
     m_oauth.setReplyHandler(&m_handler);

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

### Private/Custom URI Schemes

Custom URI schemes typically use reverse-domain notation followed by a path, or occasionally a host/host+path:

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

### HTTPS URI Scheme

With HTTPS URI schemes, the redirect URLs are regular https links:

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

These links are called Universal Links on iOS and App Links on Android.

The use of https schemes is recommended as it provides additional security by forcing application developers to prove ownership of the URLs used. This proving is done by hosting an association file, which the operating system will consult as part of its internal URL dispatching.

The content of this file associates the application and the used URLs. The association files must be publicly accessible without any HTTP redirects. In addition, the hosting site must have valid certificates and, at least with Android, the file must be served as `application/json` content-type (refer to your server's configuration guide).

In addition, https links can provide some usability benefits:

- The https URL doubles as a regular https link. If the user hasn't installed the application (since the URL wasn't handled by any application), the https link may for example serve instructions to do so.
- The application selection dialogue to open the URL may be avoided, and instead your application may be opened automatically

The tradeoff is that this requires extra setup as you need to set up this publicly-hosted association file.

### Platform Support and Dependencies

Currently supported platforms are Android, iOS, and macOS.

URI scheme listening is based on QDesktopServices::setUrlHandler() and QDesktopServices::unsetUrlHandler(). These are currently provided by Qt::Gui module and therefore QtNetworkAuth module depends on Qt::Gui. If QtNetworkAuth is built without Qt::Gui, QOAuthUriSchemeReplyHandler will not be included.

#### Android

On Android the URI schemes require:

- Setting up intent-filters in the application manifest
- Optionally, for automatic verification with https schemes, hosting a site association file assetlinks.json

See also the Qt Android Manifest File Configuration.

#### iOS and macOS

On iOS and macOS the URI schemes require:

- Setting up site association entitlement
- With https schemes, hosting a site association file (`apple-app-site-association`)

#### Windows, Linux

Currently not supported. However platforms and use cases supporting Qt WebEngine can still use this reply handler - see Qt OAuth2 Browser Support for details.

## Property Documentation

### redirectUrl : QUrl

This property holds the URL used to receive authorization redirection/response.

This property is used as the OAuth2 redirect_uri parameter, which is sent as part of the authorization request. The `redirect_uri` is acquired by calling QUrl::toString() with default options.

The URL must match the one registered at the authorization server, as the authorization servers likely reject any mismatching redirect_uris.

Similarly, when this handler receives the redirection, the redirection URL must match the URL set here. The handler compares the scheme, host, port, path, and any query items that were part of the URL set by this method.

The URL is handled only if all of these match. The comparison of query parameters excludes any additional query parameters that may have been set at server-side, as these contain the actual data of interest.

Access functions:

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

Notifier signal:

void | redirectUrlChanged()

## Member Function Documentation

### QOAuthUriSchemeReplyHandler::QOAuthUriSchemeReplyHandler()

Constructs a QOAuthUriSchemeReplyHandler object with empty callback()/ redirectUrl() and no parent. The constructed object does not automatically listen.

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

Constructs a QOAuthUriSchemeReplyHandler object with parent and empty callback()/redirectUrl(). The constructed object does not automatically listen.

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

Constructs a QOAuthUriSchemeReplyHandler object and sets parent as the parent object and redirectUrl as the redirect URL. The constructed object attempts automatically to listen.

See also redirectUrl(), setRedirectUrl(), listen(), and isListening().

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

Destroys the QOAuthUriSchemeReplyHandler object. Closes this handler.

See also close().

### void QOAuthUriSchemeReplyHandler::close()

Tells this handler to stop listening for incoming URLs.

See also listen() and isListening().

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

This function is used to supply the redirect URL the Authorization Server provides at the end of the authorization stage. The provided url undergoes the same URL matching as described in redirectUrl.

Suppyling the URL can be useful for scenarios where this redirect URL is captured by some other means, for example with Qt WebEngine or through some other custom arrangement. This way such agent usage can be integrated with rest of the OAuth2 flow.

This handler does not need to be listening, and therefore it is recommended to close() the handler to avoid unnecessary listening.

Returns `true` if the URL matched and was handled, `false` otherwise.

See also Redirect URI Schemes with Qt WebEngine.

This function was introduced in Qt 6.9.

### `[noexcept]` bool QOAuthUriSchemeReplyHandler::isListening() const

Returns `true` if this handler is currently listening, and `false` otherwise.

See also listen() and close().

### bool QOAuthUriSchemeReplyHandler::listen()

Tells this handler to listen for incoming URLs. Returns `true` if listening is successful, and `false` otherwise.

The handler will match URLs to redirectUrl(). If the received URL does not match, it will be forwarded to QDesktopServices::openURL().

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

It is recommended to close the listener after successful authorization. Listening is not needed for acquiring access tokens.