Download the PHP package accredifysg/singpass-login without Composer

SingPass-Login

PHP Laravel Package for SingPass Login, MyInfo, and CorpPass. The authorization flow follows FAPI 2.0–style integration: Pushed Authorization Requests (PAR) with DPoP on the PAR, token, and UserInfo calls, PKCE, and private-key JWT client assertions. Your OpenID Provider metadata (discovery) must expose a pushed_authorization_request_endpoint; the package validates this when caching discovery.

Official SingPass Login Docs · Official CorpPass Docs

Architecture

The package separates shared FAPI 2.0 choreography from provider-specific logic:

• Shared layer (FapiAuthenticationService, FapiCallbackService) handles discovery, PAR, DPoP, PKCE, token exchange, and JWE/JWS processing.
• Thin controllers for each flow (SingPass Login, MyInfo, CorpPass) delegate to the shared layer and fire provider-specific events.
• A ProviderConfig DTO encapsulates per-provider configuration (client ID, redirect URI, cache key, scopes).

Installation

You can install the package via composer:

Publish the config files:

This publishes four config files:

Optionally, publish the default listener that logs in a user on SingPassSuccessfulLoginEvent:

Configuration

Shared NDI (config/ndi.php)

JWKS, signing keys, DPoP algorithm, and logging — shared across all providers.

SingPass Login (config/singpass-login.php)

MyInfo (config/myinfo.php)

CorpPass (config/corppass-login.php)

Enabling / Disabling Modules

Each flow can be independently toggled via environment variables. All are enabled by default.

The JWKS endpoint (/ndi/jwks) is always registered regardless of these flags, as it is shared across all providers.

Route URLs are also configurable:

Routes

The package registers the following routes under the web middleware group:

Each auth controller returns JSON with a redirect_url the browser should navigate to. The callback controllers handle the OAuth redirect, validate state (CSRF), exchange the code using DPoP, and fire the appropriate event.

If you prefer custom controllers, override the *_controller keys in the respective config file.

SingPass Login

Starting a Login

GET /ndi/sp/login returns 200 JSON: { "redirect_url": "..." }. The browser (or SPA) should request that URL with same-origin credentials so the session cookie is sent, then navigate to redirect_url.

Optional query parameters: authentication_context_type and authentication_context_message override config defaults for that request. See the SingPass authorization request documentation for valid values.

Listener

If you published the default listener, edit it to map your user retrieval via NRIC. Read the NRIC/FIN from the readonly nric property (populated from sub_attributes.identity_number when the user.identity scope is requested). SingPassUser::getNric() is deprecated and will be removed in a future major release; migrate listeners to $singPassUser->nric.

If you prefer a custom listener, set SINGPASS_USE_DEFAULT_LISTENER=false and replace listener_class in singpass-login.php.

MyInfo Integration

MyInfo has its own dedicated routes (/ndi/mi/initiate and /ndi/mi/callback), config file (config/myinfo.php), and separate client credentials (MYINFO_CLIENT_ID / MYINFO_REDIRECT_URI).

Starting a MyInfo Flow

How It Works

The MyInfo callback controller calls the UserInfo endpoint (with DPoP) to retrieve the requested data and emits MyInfoDataRetrievedEvent. Internally, FapiCallbackService uses shouldCallUserInfo() with the provider's loginScopes to determine the correct path: if the access token contains only login scopes, the ID token path is taken; otherwise the UserInfo endpoint is called.

Scope comparison reads the access token as an unverified JWT and expects a standard three-part compact JWT whose payload JSON includes a string scope claim (space-separated scope values, per OIDC). If the token is not a JWT, the payload cannot be decoded, or scope is missing or not a string, UserInfoRequestException is thrown instead of assuming openid only, so malformed tokens fail visibly during callback processing.

Handling MyInfo Data

Available MyInfo Scopes

For the complete list, see the MyInfo Data Catalog. The package validates requested scopes against the available_scopes in config/myinfo.php.

CorpPass Integration

CorpPass uses the same FAPI 2.0 flow as SingPass, with a hierarchical entity + actor identity model. The entity represents the company/organisation (sub), and the actor represents the individual user (act.sub).

Starting a CorpPass Login

CorpPass Scopes

Handling CorpPass Events

The CorpPass callback controller fires up to two events:

• CorpPassSuccessfulLoginEvent — Always fired when an ID token payload is present. Carries a CorpPassUser model.
• CorpPassDataRetrievedEvent — Fired when UserInfo scopes (authinfo, tpauthinfo) were requested. Carries the authorization data array.

Registering CorpPass Listeners

Configure the built-in listener via corppass-login.php:

Or register manually in your EventServiceProvider:

Event Flow Summary

Diagnostic Logging

Set NDI_LOGS_ENABLED=true in your .env to enable detailed logging of every step in the authentication flow. All log entries are prefixed with [SingPass] and sensitive values (client_assertion, code_verifier, id_token, access_token) are automatically redacted.

Logged steps include:

This is particularly useful for diagnosing session issues (mismatched session IDs between login and callback), issuer/audience mismatches, and PAR rejections.

Upgrading from pre–FAPI 2.0 versions

• The login route returns JSON with redirect_url; update clients to fetch (with credentials) then navigate.
• Ensure your app uses session-backed routes (default web middleware).
• Discovery metadata must include pushed_authorization_request_endpoint.
• Review login_scopes in singpass-login.php and available_scopes in myinfo.php.
• MyInfo now has dedicated routes (/ndi/mi/initiate and /ndi/mi/callback) and its own config file (config/myinfo.php) instead of sharing the login route and config.
• Configuration has been split into four files: ndi.php (shared), singpass-login.php, myinfo.php, and corppass-login.php. Several environment variables have been renamed (see Configuration section).
• The old SingPassLoginFacade and SingPassLoginInterface have been removed. If you were calling SingPassLogin::handleCallback() directly, the logic is now internal to the callback controllers.
• Exceptions have been renamed: SingPassGetEndpointException → AuthFlowException, SingPassAuthenticationErrorException → AuthenticationErrorException, SingPassTokenException → TokenExchangeException, SingPassJwksException → JwksException.
• Services have been renamed: SingPassJwtService → JwtService, GetSingPassTokenService → TokenExchangeService, GetSingPassJwksService → JwksService.
• SingPassUser::getNric() is deprecated; use the readonly nric property on SingPassUser instead.

Exceptions

Configuration Exceptions

• MissingConfigException: A required config value (e.g. singpass-login.client_id) is null. Thrown by ProviderConfig factory methods with a message identifying the missing key.

FAPI / PAR Exceptions

• PushedAuthorizationRequestException: The PAR endpoint returned an error or an invalid response (includes OAuth error codes when provided).
• AuthenticationErrorException: The provider returned an OAuth error to the callback (error / error_description query parameters).
• AuthFlowException: The callback request was missing required parameters, failed CSRF/session validation, or the ID token payload was invalid.

Token / JWT Exceptions

• TokenExchangeException: The token endpoint returned an error, an unparseable response, or was missing id_token.
• JwtPayloadException: The decoded ID token payload failed validation (e.g. missing sub claim).
• JweDecryptionFailedException / JwtDecodeFailedException: JWE decryption or JWS verification of the ID token failed.
• JwksException / JwksInvalidException: JWKS retrieval or parsing failed.
• OpenIdDiscoveryException: OpenID discovery endpoint returned invalid or incomplete configuration.

UserInfo Exceptions

• UserInfoRequestException: The UserInfo HTTP request failed, or the access token could not be inspected for scopes before choosing the ID token vs UserInfo path (invalid JWT shape, undecodable payload, missing or non-string scope claim). Callback handling treats these as hard failures rather than silently defaulting scopes.
• UserInfoDecryptionException: The UserInfo JWE token decryption failed.
• UserInfoVerificationException: The UserInfo JWS token verification failed.