Table of Contents

Authorizing mobile applications

This chapter explains how to configure Sphinx and authenticate users from mobile applications (iOS and Android) built with Delphi.

Before proceeding, make sure you have followed the Quickstart chapter thoroughly. It describes the common procedures to setup Sphinx. This chapter extends what is explained there, with information that targets mobile platforms specifically.

Registering a client application

Registering a mobile client application in Sphinx follows the same steps as registering a native desktop application. Mobile applications are also public clients, so they do not use a client secret.

The key difference is in the redirect URI. Desktop applications can use http://127.0.0.1 (loopback) because they can open a local HTTP server. Some mobile platforms might restrict this, like iOS, so sometimes mobile applications need to register a custom URL scheme redirect URI instead — for example, myapp://auth/callback.

The following example registers a mobile client application with both a loopback and a custom URL scheme redirect URI, so it can work on all platforms:

  Client := SphinxConfig1.Clients.Add;
  Client.ClientId := 'mobile';
  Client.DisplayName := 'My mobile app';
  Client.RedirectUris.Add('myapp://auth/callback');
  Client.RedirectUris.Add('http://127.0.0.1');
  Client.RequireClientSecret := False;
  Client.AllowedGrantTypes := [TGrantType.gtAuthorizationCode, TGrantType.gtRefreshToken];
  Client.ValidScopes.Add('openid');
  Client.ValidScopes.Add('email');
  Client.ValidScopes.Add('offline_access');

The redirect URI myapp://auth/callback must be registered as a custom URL scheme in your mobile application project (see Handling the callback URL).

The gtRefreshToken grant type is included to enable refresh token support, so users do not need to log in again when the access token expires. The offline_access scope is required for the server to issue refresh tokens.

Authenticating from Delphi mobile applications

TMS Sphinx provides the TSphinxLogin component that handles the full OAuth 2.0 Authorization Code Flow with PKCE on your behalf. It works on desktop and mobile, but requires a small difference in configuration when running on mobile platforms.

How the desktop approach works

On desktop platforms, TSphinxLogin starts an internal local HTTP server to receive the authorization callback from the browser. When login completes, the browser redirects to http://127.0.0.1:<port>/oauth2redirect, the component captures the callback, and fires TSphinxLogin.​OnUser​LoggedIn automatically. No extra code is needed.

Why mobile platforms require a different approach

iOS does not allow applications to open a local HTTP server for this purpose, so the internal server approach does not work reliably on that platform. The recommended approach for iOS is to use a custom URL scheme: the authorization server redirects the browser to a URI like myapp://auth/callback, and the OS delivers that URL to your application via a platform-specific callback.

On Android, the internal HTTP server currently works fine, so the custom URL scheme approach is optional. It is still recommended for a more robust and future-proof implementation, but you can use the default TSphinxLogin configuration (without setting TSphinxLogin.​RedirectUri) and authentication will work without any additional platform integration.

Note

For desktop applications, the internal server approach works seamlessly and is the easiest option. Use the custom URL scheme approach only when targeting iOS, or when you want a consistent setup across all platforms.

Configuring TSphinxLogin for mobile

Drop the TSphinxLogin component in any form or data module in your application so that it is accessible when the application starts.

Configure the following key properties:

  • TSphinxLogin.​Authority: The base URL of the Sphinx server. For example, https://myserver.example.com/tms/sphinx.
  • TSphinxLogin.​ClientId: The id of the client you registered above. For example, mobile.
  • TSphinxLogin.Scope: Space-separated list of scope tokens. Include at least openid email. Add offline_access to enable refresh tokens.
  • TSphinxLogin.​RedirectUri: Set this to the custom URL scheme redirect URI registered in the server, for example myapp://auth/callback. Setting this property activates the custom URL scheme mode: TSphinxLogin will launch the browser without starting a local server, and will wait for you to call TSphinxLogin.​Handle​Callback from the platform URL handler.

Initiating login

Call TSphinxLogin.Login to start the authentication flow. The device default browser will open the Sphinx login page. After the user authenticates, the browser will redirect to the custom URL scheme URI. Your application receives this URL via the platform URL handler, and you must pass it to TSphinxLogin.​Handle​Callback to complete the flow.

Use TSphinxLogin.​IsLoggedIn to check whether the user is already authenticated before calling TSphinxLogin.Login.

Handling the callback URL

After the user authenticates in the browser, the OS delivers the callback URL to your application. You must forward this URL to TSphinxLogin.​Handle​Callback, which validates the response, exchanges the authorization code for tokens, saves the credentials, and fires TSphinxLogin.​OnUser​LoggedIn on the main thread.

The specifics of how the OS delivers the URL to your application, and how to register the custom URL scheme in the project, depend on the platform and are outside the scope of this documentation. As a general reference for Delphi FMX iOS applications, the URL is typically delivered through the IFMXApplicationEventService platform service. The following example illustrates the pattern — adapt it to your project structure as needed:

uses
  FMX.Platform, iOSapi.UIKit;

procedure TForm1.FormCreate(Sender: TObject);
var
  AppEventSvc: IFMXApplicationEventService;
begin
  // ... other initialization ...
  {$IFDEF IOS}
  if TPlatformServices.Current.SupportsPlatformService(IFMXApplicationEventService, AppEventSvc) then
    AppEventSvc.SetApplicationEventHandler(HandleAppEvent);
  {$ENDIF}
end;

function TForm1.HandleAppEvent(AEvent: TApplicationEvent; AContext: TObject): Boolean;
var
  URL: string;
begin
  Result := False;
  if AEvent = TApplicationEvent.OpenURL then
  begin
    {$IFDEF IOS}
    URL := TiOSOpenApplicationContext(AContext).URL;
    Result := SphinxLogin.HandleCallback(URL);
    {$ENDIF}
  end;
end;

TSphinxLogin.​Handle​Callback returns True if the URL was a recognized authentication callback and tokens were obtained successfully, or False if the URL was unrelated to authentication or the login failed. The return value of HandleAppEvent tells the OS whether your application consumed the URL.

Note

Registering the custom URL scheme in the iOS project (info.plist.TemplatiOS.xml) and wiring up the platform URL handler are standard Delphi FMX tasks not specific to Sphinx. Refer to the Delphi and Apple documentation for your target platform and IDE version.

Once TSphinxLogin.​OnUser​LoggedIn fires, you can access TSphinxLogin.​Auth​Result to retrieve information about the logged user, such as email and display name.

Logout

Call TSphinxLogin.Logout to clear the stored credentials and log the user out of the application. This only clears the local session; the SSO session at the identity provider remains active.

To also terminate the SSO session at the identity provider, call TSphinxLogin.​Logout​AndEnd​Session instead. This opens the system browser to the provider's end-session endpoint, ensuring other applications sharing the same SSO session will also require the user to log in again.