Many applications need to interact with remote services to provide their functionality to the user. One industry-standard mechanism by which the remote service can delegate authorization for specific actions to the application is called OAuth. The OAuth2 specification, for example, describes flows whereby an application can ask a service to allow it to perform some specific types of operations (known as the "scope") on behalf of the user. The system browser is then used to provide the user with an interactive session with the remote service, whereby the user is asked to permit (by logging in) or deny (by cancelling) the request. If permitted by the user, the application is returned an "access token" which it must use as proof of authorization when performing operations (for example, requesting certain data from the remote service).

Note that the application must have been registered with the remote service (which is done manually via the service's website) and have a valid "consumer_key" (OAuth1.0a) or "client_id" (OAuth2) which identifies it.

The Amber Web Authorization Framework provides both C++ and QML API which allows application developers to easily integrate OAuth1.0a and OAuth2 flows into their application, including a simple TCP server which can listen for web-browser redirects.

Using the Amber Web Authorization Framework

Regardless of whether the application is using the QML or C++ API, the basic steps for using OAuth in their application is the same:

• Construct the redirect listener (to capture a redirect from the browser)
• Construct the appropriate (i.e., OAuth1 or OAuth2) helper and set its properties
• If using OAuth1.0a, ask the OAuth1 helper to request a temporary token
• Ask the OAuth helper to generate an authorization URL
• Open the generated URL in the system web browser
• Wait for the user to authorize the application
• The redirect listener will then capture the redirect, and the OAuth helper will emit a signal containing the access token

After receiving an access token, the application must use this token in all subsequent requests to the remote service, by specifying an appropriate "Authorization" header in those requests.

For OAuth2 enabled services, this is as simple as setting the "Authorization" header value to "Bearer <token>", but for OAuth1 it is more complicated, and so some helper API is provided by the Amber Web Authorization Framework to generate the appropriate authorization header for a specific request, given the OAuth1 token (and token secret) previously provided to the application. See Amber::Web::Authorization::OAuth1::generateAuthorizationHeader() for more information about this.

C++ API

The C++ API consists of the following classes:

• the RedirectListener
• the OAuth1 helper
• the OAuth2 helper
• the Error type

Note that the OAuth2 specification describes multiple different possible flows depending on the type of application. The OAuth2 helper supports a variety of different flows; the application developer must choose the one they want to use, and provide values for the appropriate properties as required by that flow. See the FlowType documentation for more information on this topic.

The RedirectListener is a very simple TCP server which can be used to capture redirects from the system browser (which will include the access token if the user authorized the application) by listening on a localhost port. The client application may use an instance of this type to handle the redirect, or alternatively it can implement its own redirect handling (e.g. with custom protocol).

To use the C++ API, the client application should use the "amberwebauthorization.pc" pkgconfig file.

e.g. in a qmake-based project you should add the following line to your pro file:

 PKGCONFIG += amberwebauthorization

In order for PkgConfig to work, you need to have either

 CONFIG += sailfishapp

or

 CONFIG += link_pkgconfig

in your pro file. Note: You should only add either sailfishapp or link_pkgconfig, but not both.

You'll also need to add the following to your RPM SPEC file.

 BuildRequires:  pkgconfig(amberwebauthorization)

If your project is using a YAML file to generate your SPEC file, don't edit your SPEC file, but instead amend the YAML file to add amberwebauthorization to the PkgConfigBR section, like this:

 PkgConfigBR:
   - amberwebauthorization

You can then use the headers in your code depending on the functionality you need access to. Refer to the class documentation for which headers to include.

 #include <oauth1.h>
 #include <oauth2.h>
 #include <redirectlistener.h>

QML API

The QML API is provided through the Amber.Web.Authorization import namespace, and it includes the C++ classes, and can be used in the same way. In addition, the it also provides some flow-specific helpers which expose different properties depending on the requirements of the flow, and which automatically instantiate a RedirectListener by default, to simplify usage by client applications.

The QML types exposed in the QML API are as follows:

• RedirectListener
• OAuth1, base OAuth1 helper type
• OAuth10a, for OAuth1.0a flows
• OAuth2, base OAuth2 helper type
• OAuth2Ac, for OAuth2 Authorization Code flows
• OAuth2AcPkce, for OAuth2 Authorization Code With PKCE flows
• OAuth2Implicit, for OAuth2 Implicit flows

Note that the vast majority of client applications should use the OAuth2 Authorization Code With PKCE flow, i.e. OAuth2AcPkce type.

Examples

Please see the amberwebauthcppexample and amberwebauthqmlexample for examples of how to use the APIs.