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 while 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.

Authetication is performed using special buil-tin 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.

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 along 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.

Custom Authentication User Interface

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.