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

*/
