1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qt-oauth2-overview.html
\title Qt OAuth2 Overview
\ingroup explanations-networkauth
\brief An overview of QtNetworkAuth OAuth2
\section1 OAuth2
\l {https://datatracker.ietf.org/doc/html/rfc6749}{RFC 6749 OAuth 2.0}
defines an authorization framework which enables resource authorization
without exposing sensitive user credentials such as passwords.
The OAuth2 framework defines several client types (public and confidential)
as well as flows (implicit, authorization code, and several others).
For typical Qt applications the client type should be considered as
\e {public native} application. The \e {public} implies that the
application isn't trusted to hold secrets, such as passwords, embedded
within the shipped binary.
\l {https://datatracker.ietf.org/doc/html/rfc8252}{RFC 8252 OAuth 2.0 for Native Apps}
further defines the best practices for such applications. Among other things,
it defines the
\l {https://datatracker.ietf.org/doc/html/rfc8252#section-6}{Authorization Code Flow}
as the recommended flow. QtNetworkAuth provides a concrete implementation for
this flow, and it is also the focus of this documentation.
\section1 Qt OAuth2 Classes
QtNetworkAuth provides both concrete and abstract OAuth2 classes.
The abstract classes are intended for implementing custom flows, while
the concrete classes provide a concrete implementation.
To implement an OAuth2 flow with QtNetworkAuth, two classes are needed:
\list
\li A \e {OAuth2 flow implementation} class provides the main API,
and is the orchestrator of the flow. It usually owns one reply handler.
The abstract class is QAbstractOAuth2, and the concrete
implementation is QOAuth2AuthorizationCodeFlow.
\li A \e {Reply handler} class which handles replies from an authorization
server. With authorization code flow, these include authorization,
access token request, and access token refresh.
The results of processing a reply are further handled by the
flow class. The reply handler abstract class is QAbstractOAuthReplyHandler,
and the concrete classes are QOAuthHttpServerReplyHandler and
QOAuthUriSchemeReplyHandler.
\endlist
\section1 Authorization Code Flow
The \l {https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1}{authorization code flow}
is the
\l {https://datatracker.ietf.org/doc/html/rfc8252#section-6}{recommended OAuth2 flow}
for native applications like Qt applications.
The following code snippet provides an example setup:
\snippet src_oauth_replyhandlers.cpp uri-variables
\snippet src_oauth_replyhandlers.cpp uri-oauth-setup
\snippet src_oauth_replyhandlers.cpp uri-handler-setup
\section2 Stages
The Authorization Code Flow has two main stages: resource authorization
(including any necessary user authentication) followed up by an access
token request. These are optionally followed by access token usage and
access token refreshing. The following figure illustrates these stages:
\image oauth2-stages.webp
\list
\li In authorization stage, the user is authenticated, and
the user authorizes the access to resources. This requires browser
interaction by the user.
\li After the authorization the received authorization
code is used to request an access token, and optionally a refresh
token.
\li Once the access token is acquired, the application uses it to
access the resources of interest. The access token is included
in the resource requests, and it is up to the resource server
to verify the token's validity.
\l {https://datatracker.ietf.org/doc/html/rfc6750}{There are several
ways to include the token as part of the requests}, but
including it in the \l {https://datatracker.ietf.org/doc/html/rfc6750#section-2.1}
{HTTP \c Authorization header} is arguably the most common.
\li Access token refreshing. Access tokens typically expire relatively
quickly, say in one hour. If the application received a refresh token
in addition to the access token, the refresh token can be used to
request a new access token. Refresh tokens are long-lived and applications
can persist them to avoid the need for a new authorization stage
(and thus another browser interaction).
\endlist
\section2 Details and Customization
OAuth2 flows are dynamic and following the details can
be tricky at first. The figure below illustrates the main details
of a successful authorization code flow.
\image oauth2-flow-details.webp
For clarity the figure omits some less used signals, but altogether
illustrates the details and main customization points. The customization
points are the various signals/slots the application can catch (and call),
as well as the callback which is settable with
\l QAbstractOAuth::setModifyParametersFunction().
\section2 Choosing A Reply Handler
The decision on which reply hander to use, or to implement,
is dependent on the
\l {https://datatracker.ietf.org/doc/html/rfc6749#appendix-A.6}{redirect_uri}
used. The \c redirect_uri is where the browser is redirected upon concluding
the authorization stage.
In the context of native applications,
\l {https://datatracker.ietf.org/doc/html/rfc8252#section-7}
{RFC 8252 outlines three main types of URI schemes}:
\c loopback, \c https, and private-use.
\list
\li \l{https://datatracker.ietf.org/doc/html/rfc8252#section-7.1}{Private-use URIs}:
Can be used if the OS allows an application to register a custom URI
scheme. An attempt to open an URL with such custom scheme will open the
related native application. See \l QOAuthUriSchemeReplyHandler.
\li \l{https://datatracker.ietf.org/doc/html/rfc8252#section-7.2}{HTTPS URIs}:
Can be used if the OS allows the application to register a custom HTTPS
URL. An attempt to open this URL will open the related native
application. This scheme is recommended if the OS supports it.
See \l QOAuthUriSchemeReplyHandler.
\li \l{https://datatracker.ietf.org/doc/html/rfc8252#section-7.3}{Loopback Interfaces}:
These are commonly used for desktop applications, and applications
during development. The \l QOAuthHttpServerReplyHandler is designed to
handle these URIs by setting up a local server to handle the
redirection.
\endlist
The choice depends on several factors such as:
\list
\li Redirect URIs supported by the authorization server vendor.
The support varies from vendor to vendor, and is often specific
to a particular client type and operating system. Also, the support
may vary depending on whether the application is published or not.
\li Redirect URI schemes supported by the target platform(s).
\li Application-specific usability, security, and other requirements.
\endlist
\quotation \l {https://datatracker.ietf.org/doc/html/rfc8252#section-7.2}
{RFC 8252 recommends using the \c https scheme} for
security and usability advantages over the other methods.
\endquotation
*/
|
