SG FAPI Connect – Singpass & Corppass (FAPI 2.0)

Overview

SG FAPI Connect adds Singpass and Corppass login to OutSystems 11 Reactive Web apps using the FAPI 2.0 security profile: Pushed Authorization Requests (PAR), DPoP, PKCE, private_key_jwt and encrypted ID tokens.

No client secret is used. The component generates and stores its own signing and encryption keys and publishes the public keys (JWKS) for the Singpass / Corppass developer portal.

Requirements

• OutSystems 11 with Reactive Web apps.
• An environment reachable over HTTPS from the internet (Singpass / Corppass call back into it).
• A client registered in the Singpass or Corppass developer portal (staging first). You need the Client ID.

Installation

1. Install SG FAPI Connect from Forge. It includes SGFapiConnect (core and admin screens), SGFapiConnect_UI, SGFapiConnect_Crypto (.NET extension) and OIDCCustomization.
2. Give your administrators the role OIDC_Admin. Only this role can open the admin screens.

Step 1 – Create a login app

Open https://<your-environment>/SGFapiConnect/Apps and click Add app. The screen shows a setup guide and provider-specific hints. Fill in:

• Identity provider: Singpass (FAPI 2.0) or Corppass (FAPI 2.0).
• App name: a unique name your applications use, e.g. MyPortal_Singpass.
• Discovery URL: the provider's OpenID discovery URL (.well-known/openid-configuration) for the environment you connect to (staging or production). Always take the current value from the official documentation:
  • Singpass: docs.developer.singpass.gov.sg (Technical specifications › .well-known endpoints)
  • Corppass: docs.corppass.gov.sg (Corppass Authorization API (FAPI 2.0) › OpenID Discovery Endpoint)
• Client ID: from the developer portal.
• Scopes (optional):leave empty for the defaults.
  • Singpass default: openid user.identity name email mobileno
  • Corppass default: openid entity.identity entity.basic_profile.name user.identity user.name – add authinfo and/or tpauthinfo to receive e-service roles.
• Authentication context type:
  • Singpass Login apps: required, e.g. APP_AUTHENTICATION_DEFAULT.
  • Corppass: leave empty (APP_AUTHENTICATION_DEFAULT is sent automatically).
• Level of assurance (optional):
  • Singpass: urn:singpass:authentication:loa:2 or urn:singpass:authentication:loa:3 (face verification, chargeable).
  • Corppass: only urn:singpass:authentication:loa:2.
• Auto-create users (optional): creates OutSystems users on first login.

Click Save. The discovery URL is validated and the app's keys are generated. Use separate apps for staging and production.

Step 2 – Register in the developer portal

Open the app's details page and copy (copy buttons provided):

• Redirect URI: https://<your-environment>/SGFapiConnect/rest/Callback/Redirect
• JWKS URL: https://<your-environment>/SGFapiConnect/rest/FAPI/JWKS?AppName=<AppName>

Register both in the Singpass / Corppass developer portal for your client.

Step 3 – Add login to your application

1. In your app, open Manage Dependencies and select from SGFapiConnect: Get_Authorization_URL, Get_UserClaims, Get_Logout_URL (and Corppass_GetAuthInfo for Corppass roles).
2. Create a server action that returns Get_Authorization_URL(AppName: "<AppName>", OriginalURL: <page to return to>).
3. On your Login with Singpass button, call that server action and redirect the browser to the returned URL.
4. After a successful login the user returns to OriginalURL, already logged in to OutSystems.
5. To log out, redirect to Get_Logout_URL(OriginalURL).

Public API

Get_Authorization_URL

Inputs: AppName, OriginalURL, AdditionalScopes (optional), ErrorURL (optional). Output: URL.
Starts the FAPI 2.0 login (PAR) and returns the URL to redirect to.

Get_UserClaims

Outputs: JWT_Claim (list), Success, ErrorMessage, Subject.
Claims of the logged-in user. Useful keys: preferred_username, name, email, phone_number, sub, sub_type, sub_attributes.*, act.*, entity_id, entity_name.

Get_IdToken

Output: IdToken. Raw ID token (decrypted JWT) of the session.

Get_AuthorizationToken

Outputs: AuthToken, AutorizationHeader.
DPoP-bound access token while valid. Singpass / Corppass do not issue refresh tokens; when it expires the user must sign in again.

Get_Logout_URL

Input: OriginalURL. Output: URL. Ends the session and returns to OriginalURL.

Corppass_GetAuthInfo

Inputs: AppName, UserId (optional – empty = logged-in user). Outputs: Found, AuthInfoJson, TpAuthInfoJson, CapturedOn.
Corppass e-service roles captured at login (requires the authinfo / tpauthinfo scopes).

IdentityProviderError (exception)

Raised when Singpass / Corppass returns HTTP 400 or above. The message contains the provider's error and error_description.

OIDCCustomization.Custom_User_Check (optional)

Implement your own user mapping and enable Custom user mapping on the app.

How users are mapped

• Singpass: username = the person's Singpass UUID (sub).
• Corppass: username = the Corppass user (act.sub). The company UEN and name are available as entity_id and entity_name. A person acting for several companies is one OutSystems user – read entity_id per login.
• With auto-create enabled, name, email and mobile are filled from the claims when available. Empty claims never overwrite existing values (Corppass does not send email or mobile).

Security notes

• The Callback and FAPI (JWKS) REST endpoints are anonymous by design (the identity provider calls them) and SSL/TLS only. JWKS exposes public keys only.
• Private keys are stored encrypted in the database.
• The callback validates state, nonce, PKCE and, when present, the iss parameter (RFC 9207).

Troubleshooting

• "Identity provider returned HTTP 400: invalid_client" or "No matching key found for kid"
  The portal's JWKS URL points to another app or old keys. Register this app's JWKS URL.
• "Failed to parse response of the method Get_OpenId_Configuration"
  The Discovery URL is wrong or not reachable (returns HTML).
• "invalid_scope"
  A requested scope is not enabled for your client.
• "Invalid IdToken"
  Wrong Client ID, key mismatch or clock skew.
• "Issuer mismatch in authorization response (iss)"
  The app's Discovery URL does not match the provider that answered.
• Login returns to the login page
  The Redirect URI registered in the portal must match exactly (HTTPS and path).

Go-live checklist

• Separate production app with the production Discovery URL and Client ID.
• Production Redirect URI and JWKS URL registered in the production portal.
• HTTPS only; a full login tested in production.
• State and session purge timers active.

Demo

See the SG FAPI Connect Demo asset (SingpassDemo) for a working example. It can be tested with MockPass.

Credits & license

Based on the Forge OIDC Client component by OutSystems (BSD-3-Clause). Released under BSD-3-Clause.

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