Integrating Singpass Login API with Laravel Socialite Provider — Part 1 Onboarding Setup

As you saw this post you might struggle about integrating SingPass Login API as part of the Laravel application, due to the cryptographic terms and tons of pages of documentation you need to go through. Don’t worry I will cover everything in this post, including the onboarding process.

Onboarding process todos

• RP JWKS Endpoint
• Request Singpass Test App
• Fill up onboarding form

RP JWKS Endpoint
A JWKS Endpoint which is an API that expose your public keys in JSON Web Key format known as JWK, Singpass API server will retrieve those public keys to perform signature checking and token encryption purpose to ensure the security and integrity of network data transmission within your Laravel application and Singpass Login API server.

Step 1 — Generate the private and public key-pairs for JWKS endpoint.
You are required to generate TWO key-pairs for token encryption and signature checking. In addition based on the requirement of SingPass Login API you need to generate an EC type Key and NOT RSA key!

Generate a key is quite simple all you need is a openssl command in Linux or macOS

Due to the key-pairs that is generated isn’t password protected, right now let’s encrypt those signing key and decryption key using AES-256 encryption algorithm, you must run the command below one by one due to it will prompt you to enter a passphrase that use to encrypt these keys.

Step 2 — Prepare a JWKS endpoint in Laravel

Before proceed to next step we will be using a PHP JWT framework package known as web-token/jwt-framework this is due to SingPass Login API is using OpenID connect protocol known as OIDC which sits on top the OAuth 2.0 and JWT architecture to perform secure token exchange. So this package which provide an easy way to import our decryption key or signing key to decrypt JWE and verify JWS.

Terms

JWE — An encrypted token which contains a JWT

JWS — A JWT which contains a signature that allow anyone to validate the authenticity of this token.

composer require web-token/jwt-framework

For this demo I will register my JWKS endpoint in the existing Laravel api.php routes files.

Step 3 — Setting up singpass configuration in config/services.php
By default Laravel provide services.php to mapped / store our configuration for third party service add these configuration below to the config/services.php file

Due to for security best practices, we stored all our configuration in .env file due to it is not under version controlled

The redirect URI which is the callback url once the Singpass Login account is authenticated which will contains a state and code query parameters attach. Please ensure that the callback url must be same as you fill in into the onboarding form, due to Singpass Login API is quite secure they will do a validation check on redirect callback url!

Step 4 — Import verification and encryption key-pairs to JWK

In your Laravel project app directory create a Singpass Helper class which consists of the generateJWKS static methods

Sourced from Singpass {api}

Based on the diagram we have completed the RP JWKS Endpoint (Relying party means your Laravel application). Right now make sure to fill in the correct JWKS in your onboarding form that will be sent out by Singpass / Corpass authority.

Test out the JWKS verifier
If you unsure your JWKS is supported by Singpass Login API you can use the official provided JWKS Verifier to verify your JWKS by just copy the entire JWKS json into the JWKS verifier input fields.

JWKS verifier

Request Singpass Test App and Test Account
If you are an iOS user please inform the Singpass authority to invite you to the staging version of the Singpass App via Testflight, If you have an existing Singpass Production App on your iPhone please remove it before you install the staging version staging Singpass App.

Onboarding Form
Before submit the onboarding form ensure the callback url, domain and JWKS endpoint make sure that the information is provided correctly, due to it might take few days for them to update your configuration if your wish to update those information again.

And that’s all about the onboarding process, for next part we will going to write a Singpass Login Adapter for Laravel Socialite provider.

Thanks for Reading ~

Portal To Next Part

Integrating Singpass Login API with Laravel Socialite Provider — Part 2 Writing Socialite Provider