FAQ Using TRestOAuth
The TRestOAuth component is for handling 0Auth authorization to web apps, by several means. Beware OAuth is really a concept with differing implementations, so that implementation may not always be straight forward. OAuth1 and 1A were originally developed for Twitter and use cryptography, OAuth2 is a simpler and easier to implement version now widely used by most cloud services without any cryptography (other than SSL).
The conceptual issue about OAuth is that applications should not know any login details. The login need to be entered through a browser, which then redirects to a fixed URL which includes an Authorization Code that is subsequently exchanged for an Access Token that can used by the REST client. This is really all designed for interactive applications, on mobile platforms in particular.
Originally it was considered allowable for native applications to display an embedded browser window in the application to capture the Authorization Code during redirect. But that potentially means the application can also capture the login as well so is no longer best practice, see RFC8252, and some apps will block the embedded window.
The preferred authorization method is for the native application to launch the standard browser and redirect to localhost where a small web server runs to capture the Authorization Code. That is how TRestOAuth works, transparently to the user, capturing the Authorization Code and using it for a token grant to get an Access Token. Note that Authorization Codes expire in a few minutes and immediately they are exchanged for a token.
The Access Token is then sent with all HTTPS REST requests as an 'Authorization: Bearer' header.
Access Tokens have a limited life and usually expire within one to 24 hours. To avoid user interaction, the token exchange process usually offers a Refresh Token which can be used to get another Access Token, and this is automatically handled by TRestOAuth, by refreshing the Access Token before it expires, allowing your application to keep running. Store the Refresh Token securely, since it's a potential security risk.
Sometimes the Refresh Token has the same life as the Access Token, with Google Accounts the Refresh Token remains valid for a few months until the account is disabled or changed, avoiding needing to login again or refresh within the expiry period. Beware with Google the Refresh Token is only returned once after initial login, not after each refresh. Google may also need to approve applications offering OAuth2, and may show consent warnings during the login process to get an Authorization Code until this is done.
https://developers.google.com/identity/protocols/OAuth2
Setting up OAuth is complex and requires a lot more information than just a site user name and password. You normally need to access the desired site and create an app or client (terminology varies) but will always involve creating a client ID and client secret, and a redirect URL which will be the local web server. The default redirect used by TRestOAuth is http:/localhost:8080/. There are also two API URLs, one for the authorization endpoint (displayed in the browser) and then the token exchange endpoint for REST requests. Some sites may provide OAuth2 details with the URL (host)/.well-known/openid-configuration as Json, ie: https://accounts.google.com/.well-known/openid-configuration . Finally, OAuth may require the token Scope to be specified, it's purpose or access rights depending on the server.
Note that in addition to granting tokens using an Authorization Code from a browser login, some OAuth implementations may support grants for client credentials alone (ID and secret, without a login) or directly for login and password (and client ID and secret) which is by far the easiest to use, but not often available, both are supported by TRestOAuth.
