Table of Contents

Authentication

TTMSFNCCloudGoogleGmail talks to Gmail over OAuth 2.0, so every session starts by authenticating the user and obtaining an access token. You register an app with Google, supply its credentials on the Authentication object, and call Connect to run the consent flow; enabling PersistTokens lets the same call reuse or silently refresh a previous session instead of prompting the browser every time. This chapter covers the credential setup, the connect flow, and persisting tokens.

App registration credentials

Enable the Gmail API and register OAuth credentials in the Google Cloud Console to get a client ID and client secret, and register a redirect URI. Set the matching values on Authentication before connecting:

  • Authentication.ClientID — the app's client ID.
  • Authentication.Secret — the app's client secret.
  • Authentication.CallBackURL — a redirect URI registered on the app (a local address such as http://127.0.0.1:8000 is typical for desktop apps).

Connecting

Connect opens the Google consent page in the browser, then exchanges the returned code for tokens, including a refresh token. Handle OnConnected to know when the component is ready to make requests.

procedure TForm1.FormCreate(Sender: TObject);
begin
  // Credentials from your app registration (https://console.cloud.google.com).
  TMSFNCCloudGoogleGmail1.Authentication.ClientID := 'your-client-id';
  TMSFNCCloudGoogleGmail1.Authentication.Secret := 'your-client-secret';
  // Must match a redirect URI registered on the app.
  TMSFNCCloudGoogleGmail1.Authentication.CallBackURL := 'http://127.0.0.1:8000';

  TMSFNCCloudGoogleGmail1.OnConnected := GmailConnected;
  // Opens the Google consent page in the browser and exchanges the code for tokens.
  TMSFNCCloudGoogleGmail1.Connect;
end;

procedure TForm1.GmailConnected(Sender: TObject);
begin
  TMSFNCCloudGoogleGmail1.GetLabels;
end;

Combining Connect with persisted and refreshed tokens

Connect already does more than run the interactive flow: it first loads any previously saved tokens, tests them, and — when the access token has expired but a refresh token is available — silently exchanges it for a new one before falling back to the browser. Setting PersistTokens.Section to a non-empty name turns this on, so a returning user with a still-valid or refreshable session never sees the browser again:

procedure TForm1.FormCreate(Sender: TObject);
begin
  TMSFNCCloudGoogleGmail1.Authentication.ClientID := 'your-client-id';
  TMSFNCCloudGoogleGmail1.Authentication.Secret := 'your-client-secret';
  TMSFNCCloudGoogleGmail1.Authentication.CallBackURL := 'http://127.0.0.1:8000';

  // A non-empty Section switches on automatic token persistence: Connect
  // loads any saved AccessToken / AccessTokenRefresh, tests them, silently
  // refreshes an expired access token, and saves the (possibly refreshed)
  // tokens again on success.
  TMSFNCCloudGoogleGmail1.PersistTokens.Section := 'MyAppGmail';

  TMSFNCCloudGoogleGmail1.OnConnected := GmailConnected;
  // Only opens the browser when there is no valid or refreshable session.
  TMSFNCCloudGoogleGmail1.Connect;
end;

procedure TForm1.GmailConnected(Sender: TObject);
begin
  TMSFNCCloudGoogleGmail1.GetLabels;
end;
Note

PersistTokens writes to local storage in cleartext by default. For a deployed app, point PersistTokens.Location at a location your own encryption or OS keychain integration controls.

Common mistakes

  • Mismatched redirect URI. Authentication.CallBackURL must exactly match a redirect URI registered on the app, or the consent flow fails.
  • Gmail API not enabled on the project. The app registration's Google Cloud project must have the Gmail API enabled, in addition to holding valid OAuth credentials.
  • Calling operations before OnConnected. Requests issued before the tokens are in place fail; start them from OnConnected.

See also