Table of Contents

Authentication

TTMSFNCCloudMicrosoftOutlookMail talks to Microsoft Graph over OAuth 2.0, so every session starts by authenticating the user and obtaining an access token. You register an app with Microsoft, 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

Register an app in the Microsoft Entra admin center to get a client ID and client secret, register a redirect URI, and grant it the Mail permissions your app needs (Mail.Read, Mail.Send, and so on). 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 Microsoft 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://portal.azure.com).
  TMSFNCCloudMicrosoftOutlookMail1.Authentication.ClientID := 'your-client-id';
  TMSFNCCloudMicrosoftOutlookMail1.Authentication.Secret := 'your-client-secret';
  // Must match a redirect URI registered on the app.
  TMSFNCCloudMicrosoftOutlookMail1.Authentication.CallBackURL := 'http://127.0.0.1:8000';

  TMSFNCCloudMicrosoftOutlookMail1.OnConnected := OutlookMailConnected;
  // Opens the Microsoft consent page in the browser and exchanges the code for tokens.
  TMSFNCCloudMicrosoftOutlookMail1.Connect;
end;

procedure TForm1.OutlookMailConnected(Sender: TObject);
begin
  TMSFNCCloudMicrosoftOutlookMail1.GetFolders;
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
  TMSFNCCloudMicrosoftOutlookMail1.Authentication.ClientID := 'your-client-id';
  TMSFNCCloudMicrosoftOutlookMail1.Authentication.Secret := 'your-client-secret';
  TMSFNCCloudMicrosoftOutlookMail1.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.
  TMSFNCCloudMicrosoftOutlookMail1.PersistTokens.Section := 'MyAppOutlookMail';

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

procedure TForm1.OutlookMailConnected(Sender: TObject);
begin
  TMSFNCCloudMicrosoftOutlookMail1.GetFolders;
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.
  • Missing Mail permissions. Reading, sending, or deleting mail fails with an authorization error if the app registration was not granted the corresponding Microsoft Graph Mail permission.
  • Calling operations before OnConnected. Requests issued before the tokens are in place fail; start them from OnConnected.

See also