SG FAPI Connect Mobile – Singpass & Corppass (FAPI 2.0)

Overview

SG FAPI Connect Mobile adds Singpass and Corppass login to OutSystems 11 Mobile apps. It is a thin client library on top of the SG FAPI Connect web component, which does all FAPI 2.0 work on the server (PAR, DPoP, PKCE, private_key_jwt, encrypted ID token).

No keys or tokens are stored on the device. The login runs in the phone's system browser (Custom Tabs / SFSafariViewController), and the app receives only a short-lived, single-use ticket through a deep link.

How it works

1. The app calls SGFapi_StartLogin. It creates a random secret on the device and sends only its SHA-256 hash to the server.
2. The server starts the FAPI 2.0 login (PAR) and the system browser opens the Singpass / Corppass page.
3. After login, Singpass / Corppass redirects to the SG FAPI Connect callback. The server exchanges the code, validates the ID token and creates a one-time ticket (valid 60 seconds, single use, only its hash is stored).
4. The server redirects to your app's deep link: AppReturnURL?ticket=… (or ?error=…&error_description=…).
5. Your callback screen calls SGFapi_CompleteLogin. It closes the browser and redeems the ticket together with the device secret. Only the device that started the login can complete it. The user is then logged in to OutSystems on the device.

Requirements

• SG FAPI Connect (web component) installed and a login app configured in its admin console (Singpass or Corppass). See that component's documentation.
• OutSystems 11 Mobile app, built with MABS (the login needs the native app – it does not work in the browser preview).
• Plugins: Common Plugin and InAppBrowser Plugin (Forge, supported by OutSystems).

Installation

1. Install SG FAPI Connect first, then SG FAPI Connect Mobile. It contains the module SGFAPIConnect_Mobile.
2. In your mobile module, open Manage Dependencies and select from SGFAPIConnect_Mobile: SGFapi_StartLogin, SGFapi_CompleteLogin, SGFapi_Logout.
3. For claims and tokens, also select from SGFapiConnect: Mobile_Get_UserClaims (and optionally Mobile_Get_IdToken, Mobile_Get_AuthorizationToken, Corppass_GetAuthInfo).

Step 1 – Create the callback screen

• Add a screen, e.g. LoginCallback, with Anonymous access.
• Add three optional Text input parameters named exactly ticket, error and error_description (these are the URL parameters the server sends).
• In its OnReady (or OnInitialize), call SGFapi_CompleteLogin(Ticket: ticket, Error: error, ErrorDescription: error_description).
  • Success = True: navigate to your home screen.
  • Success = False: show ErrorMessage and a button back to the login screen.

Step 2 – Build the deep link (AppReturnURL)

OutSystems mobile deep links have the form:

<url-scheme>://<ModuleName>/<ScreenName>

Example: myapp://MyAppModule/LoginCallback. The URL scheme is set in the app's Native Platforms settings in Service Studio (by default derived from the app name). Use exactly the same value in the next step and in every build.

Step 3 – Add the login button

1. On the login screen, call SGFapi_StartLogin(AppName: "<AppName>", AppReturnURL: "myapp://MyAppModule/LoginCallback").
2. If Success is False, show ErrorMessage (e.g. the app name is not configured, or no network).
3. If Success is True, the system browser is open – nothing else to do; the callback screen takes over.

Step 4 – Logout

Call SGFapi_Logout, then navigate to the login screen. It ends the OutSystems session on the device and clears any pending login.

Public API (SGFAPIConnect_Mobile)

SGFapi_StartLogin (client action)

Inputs: AppName, AppReturnURL, AdditionalScopes (optional). Outputs: Success, ErrorMessage.
Creates the device secret, starts the FAPI 2.0 login on the server and opens the system browser.

SGFapi_CompleteLogin (client action)

Inputs: Ticket, Error, ErrorDescription, PersistentLogin (default True). Outputs: Success, ErrorMessage, UserId, AppName.
Closes the browser, redeems the ticket and logs the user in. Provider errors arrive in Error / ErrorDescription and are returned in ErrorMessage.

SGFapi_Logout (client action)

Logs the user out on this device and clears any pending login.

Server actions from SGFapiConnect (mobile)

• Mobile_Get_UserClaims – ID token claims of this device's session (same keys as the web Get_UserClaims).
• Mobile_Get_IdToken – raw ID token.
• Mobile_Get_AuthorizationToken – DPoP-bound access token while valid (no refresh tokens).
• Corppass_GetAuthInfo – Corppass roles captured at login.

Security notes

• Login runs in the system browser, not a WebView, as recommended for OAuth on mobile (RFC 8252).
• All FAPI keys, DPoP keys and tokens stay on the server. The device holds only a one-time secret until the callback.
• The ticket is valid for 60 seconds, can be used once, and only works together with the device secret and device id that started the login.

Troubleshooting

• "Could not start the login: …" in the browser preview
  Expected – the device plugins only work in the native app. Test with a MABS build.
• "Login app '…' was not found in SGFapiConnect"
  AppName does not match an app in the SG FAPI Connect admin console.
• Browser stays open / app does not return after login
  AppReturnURL is wrong: check the URL scheme, module name and screen name, and that the build uses the same scheme.
• "No pending login on this device"
  The app was reinstalled or its data cleared during the login. Start the login again.
• "No login ticket received" or ticket expired
  More than 60 seconds passed, or the callback screen was opened twice. Start the login again.
• Provider errors (invalid_client, invalid_scope …)
  Same causes as on the web – see the SG FAPI Connect documentation.

Demo

See SingpassDemoMobile for a working example (login, callback, home with claims, logout). It can be tested with MockPass (Singpass FAPI only).

Credits & license

Companion to SG FAPI Connect, which is based on the Forge OIDC Client component.

Singpass and Corppass are trademarks of the Government of Singapore. This component is not affiliated with or endorsed by GovTech Singapore or OutSystems.