NG ConnectionPack Guide


Authentication


Before the user will be able to authenticate himself to the service, you, as a developer should register your application following the procedure, described in Application Registration section. After that you should receive two string values: ClientID and Secret, which should be copied in the corresponding properties of used NG ConnectionPack components.

 

Its important to understand that the application registration and end-user authentication are two completely different things. While registering the application is done via your own developer's account during application developing, end-user authentication happens at run-time using user's account. And so, user's authentication, makes user's account resources, such as user's cloud files, accessible from your application.

 

Scopes

 

In addition to ClientID and Secret settings, access scopes can be specified using Scopes property. Access scopes are strings that denote special permissions, which allows your application to perform some operations with user's data. For example, Google Drive service has full access scope, which allow to read and write files, and, as well, read-only scope, which allow only read files. Usually scopes are quite long strings in a form of web links. For example, Google Drive supports the following scopes:

 

https://www.googleapis.com/auth/drive

https://www.googleapis.com/auth/drive.readonly

https://www.googleapis.com/auth/drive.appfolder

https://www.googleapis.com/auth/drive.file

https://www.googleapis.com/auth/drive.install

https://www.googleapis.com/auth/drive.metadata

https://www.googleapis.com/auth/drive.metadata.readonly

https://www.googleapis.com/auth/drive.photos.readonly

https://www.googleapis.com/auth/drive.scripts

 

Several access scopes can be combined to declare functionality, required by application. In NG ConnectionPack all supported scopes are declared additionally as string constants inside corresponding service classes. For example, TNGGDrive.DRIVE or TNGGDrive.READONLY scopes. As well, NG ConnectionPack provides special design-time editor dialog for Scopes property, which simplifies scopes setup:

 

clip0035

 

Please read corresponding service's documentation to learn about supported scopes.

 

Authentication user interface

 

Authentication is performed using special built-in modal dialog, which is shown by the NG ConnectionPack code on demand. The corresponding REST service login page is shown to the user along with your registered application name, logo and required access rights. After successful user login, the service provides so called access_token (and some other info), which is used subsequently to sign Http requests.

 

clip0036

 

clip0037

 

Access_token is used as a session identifier, and usually has a limited working time. This time can be different in different REST services, usually from 5 minutes to one hour (some services provides long running access_token values, e.g. Dropbox). Working time period is also returned as a result of authentication process, and after this period has been elapsed, the token should be reacquired. NG ConnectionPack do this automatically, without displaying the dialog to the user. To acquire new access_token NG ConnectionPack performs special Htpp request providing so called refresh_token, which is also received as part of authentication result.

 

The process of refreshing token can be repeated almost infinite amount of times. So, the user will be able to use the application for a long time without re-logging in via authentication dialog. Because of this, the authentication state should be stored/loaded between application runs. NG ConnectionPack provides SaveState and LoadState methods, and its strongly recommended to use there methods.

 

In addition to preventing the user from logging in each time your application there is another important reason to persist authentication state betwen application runs: for some services the amount of tokens, which can be returned, is limited, and thus the requirement of storing authentication info between application runs are stated explicitly in the service's documentation.

 

Since it hard to predict, when the token will need to be refreshed at run-time, NG ConnectionPack makes the check before any HTTP request to the service. This implies, that initial authentication dialog can be shown as a result of such check. So, basically, NG ConnectionPack does not provide a way to explicitly show the dialog, but instead it provides RefreshAccess method, which can be called explicitly to ensure that authentication state is ok.

 

If the user closes authentication dialog via standard close button on the window header before the authentication process finishes (thus canceling authentication), EAbort standard exception will be raised. This means that the execution of code will be interrupted as with any usual exception, but there will be no UI error message. Please read about EAbort exception class and the corresponding Abort procedure in the Delphi documentation.

 

Its good to provide the possibility for the user to log out explicitly. ResetToken service's method can be used to achieve this. After ResetToken method call all current authentication information will be reset, and the user will be forced to authenticate again via authentication dialog.

 

Built-in authentication UI

 

NG ConnectionPack provides several different built-in realizations of abstract TAuthUI class. There two ways, which differs by features. One of the described below units should be explicitly used in user's project to enable  corresponding AuthUI implementation.

 

Contained web view

 

Units:

 

NG.Connection.VclAuth.pas (for VCL projects)

NG.Connection.FmxAuth.pas (for FMX projects)

 

This authentication UI shows modal dialog with the browser view inside. The code is able to intercept page navigation events, and so, non-localhost redirect URLs are supported. From 2020 version localhost URLs are also supported in this implementation.

 

Some time ago Google prohibit authentication using contained web view (TWebBrowser), because of security considerations, so, this way will not work with Google services.

 

clip0036

 

Supported platforms:

 

Windows

iOS

 

System browser

 

Units:

 

NG.Connection.SysVclAuth.pas (for VCL projects)

NG.Connection.SysFmxAuth.pas (for FMX projects)

 

This new (2020) authentication UI shows modal task dialog, which is able to open authentication web page in system browser. Using system browser, as opposed to contained web view, is the suggested way of performing authentication due to its higher security level. As well, users often have all authentication parameters (user names and passwords) pre-saved in the system browser, and so there no need to re-enter it many times. The code is not able to intercept page navigation events, and so, only localhost redirect URLs are supported.

 

clip0039

 

After successful authorization the browser will be redirected to specified localhost address, and built-in local HTTP server will respond with the following page (text can be localized via resource-strings):

 

clip0040

 

Supported platforms:

 

Windows

 

Redirect URLs

 

Redirect URLs to localhost is supported in the following two ways: http://localhost or http://127.0.0.1. Built-in tiny HTTP server is activated during authentication process to catch redirects to local URLs. Its port number can be specified in different ways:

 

http://localhost - (no port number) default 80 port number will be used by local HTTP server.

http://localhost:8000 - explicitly specified port number will be used by local HTTP server.

http://localhost:[port] - (auto port number) local HTTP server will choose available port automatically.

 

So far dynamic port number scheme is supported only by Google services, and in this case redirect URLs should be specified as follows:

 

"http://localhost:[port]" - in component's RedirectUrl property.

"http://localhost" - (without port number) in Application Registration parameters.

 

Custom authentication UI

 

NG ConnectionPack provides TAuthUI abstract base class for those who want to implement his own customized authentication user interface. This is an advanced task, and NG ConnectionPack source code should be used as a reference implementation. After descending and implementing your own class from TAuthUI base class, TRestService.OnGetAuthUIClass event should be used to specify, that your custom class should be used instead of the built-in dialog.

 

In the case, when several services are connected into a group, which implies a shared authentication process, the event will be raised for all service components in the group in an unspecified order.

 

Google API key authentication

 

Google services provides an additional ability to authenticate using API Key method instead of described above OAuth 2.0 method. Moreover, some advanced services requires to use this way. Please read the corresponding services documentation for more details.

 

NGBeforeOAuth global callback

 

NG ConnectionPack provides NGBeforeOAuth(var Cancel, var Error) global callback, which can be used to intercept "on demand" authentication. Set Cancel parameter to True to silently cancel authentication process, and, additionally, Error parameter to some non-empty string to raise the error.