Amber Web Authorization Framework
API DocumentationRedirectListener Class
(Amber::Web::Authorization::RedirectListener)Provides a helper to allow applications to listen for localhost OAuth redirects. More...
| Header: | #include <RedirectListener> |
Properties
- httpContent : QString
- port : int
- timeout : int
- uri : const QString
Public Functions
| RedirectListener(QObject *parent = nullptr) | |
| ~RedirectListener() | |
| QString | httpContent() const |
| int | port() const |
| void | setHttpContent(const QString &httpContent) |
| void | setPort(int p) |
| void | setTimeout(int timeout) |
| void | startListening() |
| void | stopListening() |
| int | timeout() const |
| QString | uri() const |
Signals
| void | failed() |
| void | httpContentChanged() |
| void | portChanged() |
| void | receivedRedirect(const QString &redirectUri) |
| void | timedOut() |
| void | timeoutChanged() |
| void | uriChanged() |
Detailed Description
Provides a helper to allow applications to listen for localhost OAuth redirects.
Most OAuth flows require user interaction, which is initiated by the client application by opening an authorization URL in the system web browser. Once the user authorizes the application, the web browser will be redirected to the redirect URI specified by the client application.
Most services support either "localhost" or "custom protocol" redirects. This helper is a simple TCP server which listens on a specified port on the localhost address, allowing the application to receive the redirect from the system web browser (which will contain important information from the server which is required to complete the OAuth flow).
Note: the client application will need to specify that it uses a localhost redirect URI in the server-side application configuration (e.g. developer console or similar) in order to successfully make use of this helper.
Also note that the QML API contains flow-specific helpers (e.g. OAuth2AcPkce) which include both the OAuth2 helper and the RedirectListener helper, with the appropriate property bindings set up already, and so this class is mostly of interest to C++ clients or clients who have unusual redirect handling requirements.
See also amberwebauthcppexample.
Property Documentation
httpContent : QString
This property holds this property holds the HTTP content which will be sent to the web browser.
When the helper receives a redirect from the system web browser, it captures the redirect information and then sends back some HTTP content (which will be displayed to the user in the web browser).
The client application should provide HTTP content which is user-friendly and appropriately translated, informing the user that they can close the web browser window and return to using the client application.
The default value will simply display a blank webpage:
"HTTP/1.1 200 OK\\r\\n" "Content-Type: text/html\\r\\n" "Connection: close\\r\\n\\r\\n" "<!DOCTYPE html>\\r\\n" "<html></html>\\r\\n\\r\\n"
Access functions:
| QString | httpContent() const |
| void | setHttpContent(const QString &httpContent) |
Notifier signal:
| void | httpContentChanged() |
port : int
This property holds this property holds the port that the client application wishes the helper to listen on for redirects.
If no value is specified by the client (or if an invalid value is specified) the helper will attempt to listen on an arbitrary valid port above 1024.
The default value is 0 (i.e. the helper will listen on an arbitrary port).
Access functions:
| int | port() const |
| void | setPort(int p) |
Notifier signal:
| void | portChanged() |
timeout : int
This property holds this property holds the amount of time (in seconds) that the listener should wait for redirects for, before it will emit the timedOut() signal.
The timeout timer will be started once startListening() is invoked, and stopped if stopListening() is invoked or if the redirect is received prior to the timeout interval being exceeded.
The value should be high enough to give the user plenty of time to inspect the access being requested by the application and complete the authorization flow in the web browser.
If the timeout is reached, this is usually indicative of an error (for example, the web browser application did not launch successfully).
The default value is 300 (seconds, i.e. five minutes).
A zero or negative value will result in no timeout timer being started.
Access functions:
| int | timeout() const |
| void | setTimeout(int timeout) |
Notifier signal:
| void | timeoutChanged() |
uri : const QString
This property holds this property holds the full URI of the listener.
It will be of the form "http://127.0.0.1:<port>/" where the <port> value will either be the port property value (if the client provided a valid port number via this property) or else an arbitrary valid port, which the helper was able to listen on.
The full URI will only be known after the helper successfully begins to listen, and so this value will change after the client invokes the startListening() method. Thus, the client application should connect to the uriChanged() signal in order to react to changes, in order to set this uri value as the redirectUri property of the OAuth1 or OAuth2 helper being used (or in QML, bind them appropriately).
Access functions:
| QString | uri() const |
Notifier signal:
| void | uriChanged() |
See also startListening().
Member Function Documentation
RedirectListener::RedirectListener(QObject *parent = nullptr)
Constructs a new RedirectListener helper instance, with the specified QObject parent.
RedirectListener::~RedirectListener()
Destroys the RedirectListener helper instance
[signal] void RedirectListener::failed()
This signal is emitted if the helper cannot listen for redirects.
If the port is specified by the client but is unavailable, or if no port was specified and no available port could be found, the helper will be unable to listen for redirects.
[signal] void RedirectListener::receivedRedirect(const QString &redirectUri)
This signal is emitted when the helper receives a redirect from the system web browser.
The redirectUri will contain the full URI, including fragment and query parameters. This can then be parsed (e.g. using the parseRedirectUri() method provided by either OAuth1 or OAuth2 helper types) to extract the meaningful information (bearer code, access token, error message, etc).
void RedirectListener::startListening()
Start listening for redirects from the system web browser.
The client application should call this method in order to make the helper start to listen for redirects. If a port has been specified by the client application, the helper will attempt to listen on that port; otherwise, the helper will attempt to listen on an arbitrary port above 1024.
If the helper is unable to listen (e.g. due to the specified port being unavailable, or due to no ports being available to the application if the port is left as the default 0 value), it will stopListening() and emit the failed() signal.
Otherwise, the helper will listen for up to timeout seconds before emitting the timedOut() signal and stopListening().
If a redirect is received, it will write the httpContent to the socket, and then stopListening() before emitting receivedRedirect().
void RedirectListener::stopListening()
Stop listening for redirects from the system web browser.
This method will be called automatically if the timeout interval is reached when listening for directs, or once a valid redirect is captured.
Clients may call this manually in order to stop listening.
[signal] void RedirectListener::timedOut()
This signal is emitted if the helper does not receive a redirect within the specified timeout interval.
See also timeout.