QOAuthUriSchemeReplyHandler Class

Description détaillée

Cette classe sert de gestionnaire de réponse pour les processus d’autorisation OAuth 2.0 qui utilisent des schémas d’URI privés/personnalisés ou HTTPS pour la redirection. Elle gère la réception de la redirection d’autorisation (également appelée « callback ») et l’acquisition subséquente des jetons d’accès.

L'URI de redirection est l'adresse vers laquelle le serveur d'autorisation redirige l'agent utilisateur (généralement, et de préférence, le navigateur du système) une fois que la partie « autorisation » du flux est terminée.

L'utilisation de schémas d'URI spécifiques nécessite une configuration au niveau du système d'exploitation afin d'associer l'URI à l'application appropriée. La procédure de configuration de cette association varie selon les systèmes d'exploitation. Voir Platform Support and Dependencies.

Cette classe complète QOAuthHttpServerReplyHandler, qui gère les schémas http en configurant un serveur localhost.

Le code suivant illustre son utilisation. Tout d’abord, les variables nécessaires :

QOAuth2AuthorizationCodeFlow m_oauth;
QOAuthUriSchemeReplyHandler m_handler;

Puis la configuration OAuth (la gestion des erreurs est omise par souci de concision) :

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

Enfin, nous configurons le gestionnaire de réponse du schéma 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();
}

Schémas d’URI privés/personnalisés

Les schémas URI personnalisés utilisent généralement la notation de domaine inversé suivie d’un chemin d’accès, ou parfois d’un hôte/hôte+chemin d’accès :

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

Schéma d'URI HTTPS

Avec les schémas URI HTTPS, les URL de redirection sont des liens https classiques :

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

Ces liens sont appelés « Universal Links » sur iOS et « App Links » sur Android.

L'utilisation des schémas HTTPS est recommandée car elle offre une sécurité supplémentaire en obligeant les développeurs d'applications à prouver qu'ils sont bien les propriétaires des URL utilisées. Cette preuve s'effectue via l'hébergement d'un fichier d'association, que le système d'exploitation consultera dans le cadre de son traitement interne des URL.

Le contenu de ce fichier associe l’application aux URL utilisées. Les fichiers d’association doivent être accessibles au public sans aucune redirection HTTP. De plus, le site d’hébergement doit disposer de certificats valides et, au moins sur Android, le fichier doit être servi avec le type de contenu « application/json » (reportez-vous au guide de configuration de votre serveur).

Par ailleurs, les liens https peuvent offrir certains avantages en termes d’ergonomie :

• L’URL https fait également office de lien https classique. Si l’utilisateur n’a pas installé l’application (puisque l’URL n’a été gérée par aucune application), le lien https peut, par exemple, lui fournir des instructions pour le faire.
• La boîte de dialogue de sélection d’application pour ouvrir l’URL peut être évitée, et votre application peut à la place s’ouvrir automatiquement

En contrepartie, cela nécessite une configuration supplémentaire, car vous devez mettre en place ce fichier d’association hébergé publiquement.

Prise en charge des plateformes et dépendances

Les plateformes actuellement prises en charge sont Android, iOS et macOS.

L'écoute des schémas URI repose sur les méthodes QDesktopServices::setUrlHandler() et QDesktopServices::unsetUrlHandler(). Celles-ci sont actuellement fournies par le module Qt::GUI ; par conséquent, le module QtNetworkAuth dépend de Qt::GUI. Si QtNetworkAuth est compilé sans Qt::GUI, QOAuthUriSchemeReplyHandler ne sera pas inclus.

Android

Sous Android, les schémas URI nécessitent :

• Configurer l'intent-filters e dans le manifeste de l'application
• En option, pour la vérification automatique avec les schémas https, héberger un fichier d'association de site assetlinks.json

Voir également la configuration du fichier de manifeste Qt pour Android.

iOS et macOS

Sous iOS et macOS, les schémas URI nécessitent :

• Configuration de l'association de site entitlement
• Avec les schémas https, héberger un fichier « site association file » (apple-app-site-association)

Windows, Linux

Non pris en charge pour le moment. Cependant, les plateformes et cas d’utilisation prenant en charge Qt WebEngine peuvent tout de même utiliser ce gestionnaire de réponse – voir la documentation sur la prise en charge de Qt OAuth2 par les navigateurs pour plus de détails.