Myinfo (v3) apps

Overview

The Myinfo (v3) integration differs significantly from the new Authentication API, as while Myinfo (v3) wes based on OAuth 2.0, the new Authentication API is based on OIDC with the FAPI 2.0 Security Profile, which contains several extensions to the OAuth 2.0 flow.

Due to these differences, we recommend that you perform a new integration from scratch using one of the certified OIDC Relying Party Libraries, instead of updating your existing integration. Doing so should simplify your integration. You can refer to our Integration Guide to understand how to perform a new integration.

Regardless of which approach you choose to take, this document will highlight all of the differences between your existing integration and the new integration.

Creating New App

Before you start on the new integration, you must first create a new Myinfo (v5) app on the Singpass Developer Portal. Your existing Myinfo (v3) app cannot be used for the new integration.

Refer to our User Guide to understand how to create your staging app (for testing purposes) and your production app.

There are two important differences between the setup for Myinfo (v3) apps and Myinfo (v5) apps:

  1. Myinfo (v5) apps should only have a single purpose. If your current Myinfo (v3) app has multiple purposes, you will need to create a new Myinfo (v5) app for each purpose.

  2. Myinfo (v5) apps perform authentication and verification using JSON Web Key Sets (JWKS) instead of using X.509 public key certificates. You will be required to configure your JWKS instead of your certificate when creating your new Myinfo (v5) apps. Your JWKS must have at least one signing key and one encryption key.

Changes Required

General

1. Implement Demonstrating of Proof of Possession (DPoP)

DPoP is a security mechanism in which the access token and authorization code is bound to a ephemeral private key that is known only to you, preventing malicious parties from using your code or token.

Read our DPoP guide for instructions on how to implement DPoP.

2. Update custom scheme URLs

The new Authentication API no longer supports the use of custom scheme URLs (i.e. URLs that do not start with https:// ) as redirect URLs or app launch URLs.

If you are currently integrating with Myinfo via an Android or iOS app, and rely on such URLs for redirection back to the mobile app, you will need to change these URLs to use app-claimed HTTPS URLs instead. App-claimed HTTPS URLs are HTTPS URLs which, when opened on a mobile device, will launch your mobile app.

Android applications support app-claimed HTTPS URLs via Android App Links, while iOS applications support them via universal links. Read the official Android documentation and the official iOS documentation to understand how to implement Android App Links and universal links respectively.

Once your applications support redirection via app-claimed HTTPS, you should update your app's configuration in the Singpass Developer Portal to add your new HTTPS URLs. Refer to our Singpass Developer Portal User Guide if you are unsure on how to do this.

You will also need to update your backend integration with us. Specifically, you will need to change these parameters in your authorization request:

  1. The redirect_uri and app_launch_url parameters must be updated to use the new HTTPS URLs that you have configured.

  2. The redirect_uri_https_type parameter in the authorization request should be added with a value of app_claimed_https , to indicate that the redirection is being done using an app-claimed HTTPS URL.

Once the backend changes are completed and deployed, you should proceed to remove the old custom scheme URLs from your app's configuration in the Singpass Developer Portal.

Authorization Request

1. Use pushed authorization request

In your existing integration, you would have sent the authorization request by redirecting the user to the authorization endpoint, with the authorization request parameters being included as query parameters.

In the new integration, you should instead send the authorization request parameters by first sending the authorization request parameters via a pushed authorization request, which will return a short-lived request_uri in the response. You should then redirect the user the user to the authorization endpoint, with the request_uri, together with your client_id, as query parameters.

For more details, you may refer to our Integration Guide.

2. Remove parameters that are no longer used

There are some parameters in the authorization request which are no longer required in the new API. These parameters should be removed from the authorization request:

  • authmode

  • purpose (this will be configured in the Singpass Developer Portal instead of being sent for every request)

  • login_type

3. Update existing parameters

There are some parameters used in the Myinfo (v3) parameters which are still used in the new API, but they have been changed, as detailed below:

Old parameter name
New parameter name
Other changes

attributes

scope

This needs to be changed from a comma-separated string to a space-separated string, and openid has to be added. For example:

  • old: name,hanyupinyinname

  • new: openid name hanyupinyinname

appLaunchURL

app_launch_url

The app launch URL you are using will need to be pre-registered in the Singpass Developer Portal

4. Add parameters for Proof of Key Code Exchange (PKCE)

You are required to implement PKCE for the authentication flow in the new API. Read our PKCE guide for instructions on how to implement PKCE.

5. Add nonce parameter

You are required to include a nonce in your authorization request for the new API. Refer to our Integration Guide to understand how the nonce should be generated and what it is used for.

Token Exchange

1. Add parameters for Proof of Key Code Exchange (PKCE)

As part of the PKCE implementation, you will need to include the code_verifier as part of the request body when making the request to the token endpoint. This must be the same code_verifier that you had used to generate the code_challenge when making the authorization request earlier.

2. Authenticate using client assertion instead of PKI Signature

In the new API, you will authenticate yourself when calling the token endpoint by generating a client assertion instead of a PKI signature. Specifically:

  • You should no longer send an Authorization header when calling the token endpoint

  • You should no longer send the client_secret in the request body

  • You will need to send client_assertion and client_assertion_type in the request body. Refer to our Integration Guide to understand what the values of these parameters should be.

3. Remove the state parameter

The new API does not support the state parameter in the request body, so it should be removed.

4. Parse the ID token

In the new API, the token request returns an encrypted ID token in addition to the access token. You should decrypt this ID token and perform verification checks to ensure that it is legitimate.

Read our Integration Guide to understand how to perform the decryption and what sort of verification checks are required.

Userinfo Request

The userinfo request replaces the Person API call used in Myinfo (v3). Refer to our Integration Guide for the full specifications of the new userinfo request.

Here's a quick comparison of the two endpoints:

Person API
Userinfo

Request

GET /userinfo HTTP/1.1
Host: id.singpass.gov.sg
Authorization: DPoP eyJ0eXAiOiJhdCtqd3QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyLWphbmUtZG9lIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vZGF0YSIsImV4cCI6MTc1NjczMDM4MCwiaWF0IjoxNzI1MTk0MzgwLCJqdGkiOiJ0eC0xMjMtYWJjIiwiY25mIjp7ImprdCI6Ik93SWlGaVl2T0NXRkpiV1hlbUdUZzRtU1NYQkNwZk9NaFhRV21XOTBVSEEifX0.dGhpcy1pcy1hLXBsYWNlaG9sZGVyLXNpZ25hdHVyZS1hcy1pdC1yZXF1aXJlcy1hLXByaXZhdGUta2V5
DPoP: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiQXNWakh4elZ4MURaNnNKcEpzUnM2ek5YYXFmcFR3UmNfcXV0bWw0aEFJQSIsInkiOiI0SkhwVVZDRE5DaXhOTW9OclIzSElodFRzTWNfMF9NcmdpMzJxR3VoUkQ4In19.eyJqdGkiOiIyZmM3Y2Q4ZC0xN2IzLTRlYTUtYTg4ZC1lZWM0NTY5M2JhZDQiLCJodG0iOiJHRVQiLCJodHUiOiJodHRwczovL2lkLnNpbmdwYXNzLmdvdi5zZy91c2VyaW5mbyIsImlhdCI6MTc1NjcwODI0N30.wBYjFQRzY2o5aG82LjR1X8qT9bZ-jK3c7hI5fE0gP9vR_7sU6tW5xV4yZ3aB2cE1dF0eG9hI8jJ7kL6mN5oP4qR
GET /com/v3/person/{sub}?attributes=name,uinfin&client_id=EXAMPLE_CLIENT HTTP/1.1
Host: api.myinfo.gov.sg
Authorization: PKI_SIGN
timestamp="1505900210349",
nonce="150590021034800",
app_id="STG2-MYINFO-SELF-TEST",
signature_method="RS256",
signature="EEm+HEcNQajb5FkVd82zjojk+daYZXxSGPCO
R2GHZeoyjZY1PK+aFMzHfWu7eJZYMa5WaEwWxdOdq5hjNbl
8kHD7bMaOks7FgEPdjE++TNomfv7
SMktDnIvZmPYAxhjb/C9POU2KT6tSlZT/Si/qMgD1cryaPw
SeMoM59UZa1GzY
mqlkveba7rma58uGwb3wZFH0n57UnouR6LYX
DOOLkqi8uMZBuvRUvSJRXETAj2N0hT+4QJiN96Ct6IEQh/w
oZh0o74K5Ol9Pp
DSM08qC7Lj6N/k694J+hbBQVVviGn7/6mDkfbwdMDuoKs4t
7NpqmAnwT+xaQS
IZcexfrAVQYA==",Bearer eyJ0eXAiOiJhdCtqd3QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyLWphbmUtZG9lIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vZGF0YSIsImV4cCI6MTc1NjczMDM4MCwiaWF0IjoxNzI1MTk0MzgwLCJqdGkiOiJ0eC0xMjMtYWJjIiwiY25mIjp7ImprdCI6Ik93SWlGaVl2T0NXRkpiV1hlbUdUZzRtU1NYQkNwZk9NaFhRV21XOTBVSEEifX0.dGhpcy1pcy1hLXBsYWNlaG9sZGVyLXNpZ25hdHVyZS1hcy1pdC1yZXF1aXJlcy1hLXByaXZhdGUta2V5

Response

{
  "person_info": {
    "uinfin": {
      "lastupdated": "2024-09-26",
      "source": "1",
      "classification": "C",
      "value": "S9000001B"
    },
    "name": {
      "lastupdated": "2024-09-26",
      "source": "1",
      "classification": "C",
      "value": "SOH HAO FENG"
    }
  },
  // above scopes are returned in the same format as the Myinfo Get Person response
  "iss": "https://id.singpass.gov.sg/fapi",
  "sub": "d45d8f21-6178-4713-b962-8635ed2a945a",
  "aud": "T5sM5a53Yaw3URyDEv2y9129CbElCN2F",
  "iat": 1746678089
}
{
  "uinfin": {
    "lastupdated": "2024-09-26",
    "source": "1",
    "classification": "C",
    "value": "S9000001B"
  },
  "name": {
    "lastupdated": "2024-09-26",
    "source": "1",
    "classification": "C",
    "value": "SOH HAO FENG"
  }
}

The exact changes required are listed below.

1. Remove sub from the path

In Myinfo (v3), you were required to pass the sub from the access token as a path parameter when calling the Person API. This is no longer required in the new API. You should no longer perform any parsing of the access token.

If you still wish to obtain the UUID of the user, you should do so by parsing the ID token instead.

2. Remove PKI Signature

PKI signature is no longer needed for the API call. Instead, authentication is done via DPoP and the access token.

Thus, you should update your Authorization header to only include the access token in the format DPoP <your_access_token> .

3. Remove all query parameters

The new API does not require any query parameters in the userinfo request. All of the user's data belonging to the scopes requested during the Authorization request will be returned.

4. Handle the new format of the userinfo response

The userinfo response has a slightly different format compared to the response of the Person API. The format of the data itself remains unchanged - the only difference is that the data is now nested inside a person_info field.

You will thus need to update your parsing logic to extract the user's data from the person_info field, instead of from the root of the response data.

5. Update access token prefix

When calling the Person API, your access token would have had a Bearer prefix:

Authorization: Bearer <your_access_token>

In the new API, you should change this prefix to DPoP:

Authorization: DPoP <your_access_token>

PreviousLogin / Myinfo (v5) appsNextMyinfo (v4) apps

Last updated

Was this helpful?