@govtechsg/singpass-myinfo-oidc-helper v8.3.9

Singpass MyInfo OIDC helper

Use this module to build client applications that can:

• Authenticate users via the Singpass/Corppass OIDC provider
• Retrieve user's MyInfo data via the MyInfo Person-Basic API and Person API

Installation

npm i @govtechsg/singpass-myinfo-oidc-helper

MyInfo

MyInfoHelper

Helper to get a V3 MyInfo person.

import { MyInfo } from "singpass-myinfo-oidc-helper"

MyInfo.Helper

• constructor

• getPersonBasic(uinfin: string, attributes: string[]) => MyInfoComponents.Schemas.PersonBasic - get basic profile data which excludes CPF and IRAS data in the shape of MyInfoComponents.Schemas.PersonBasic
• constructAuthorizationUrl(state: string, purpose: string, attributes: string[]) => string - constructs the authorization url with the necessary params for authorising the user to retrieve full person data
• getToken(authCode: string, state?: string): => TokenResponse - get access token when presented with a valid authcode obtained from the Authorise API
• getPerson(accessToken: string, attributes: string[]) => MyInfoComponents.Schemas.Person - get full person data in the shape of MyInfoComponents.Schemas.Person, requires a valid access token obtained from getToken

MyInfoRequest

Usually not needed, for making any other custom requests to MyInfo not covered in our MyInfo helper.

• constructor

• get(uri: string, queryParams?: { [key: string]: any }, accessToken?: string) - make get request to the defined myinfo gov endpoint

  • queryParams refer to the query params for the get request
  • accessToken will be prefixed with 'Bearer ' and included in the Authorization header, meant for getPerson api which requires an access token obtained from the Token API

• post(uri: string, params: { [key: string]: any }) - make post request to the defined myinfo gov endpoint

Fake

MyInfo.Fake.FakeMyInfoHelper

Use getPersonBasic to get a fake MyInfo basic profile. Use getPerson if you want the full profile which includes the financial data from CPF and IRAS.

• constructor

getPersonBasic({
  archetype: ProfileArchetype;
  userdisplayname?: string;
  race?: MyInfoRaceCode:
  marital?: MyInfoMaritalStatusCode;
  marriagedate?: string;
  divorcedate?: string;
  marriagecertno?: string;
  countryofmarriage?: MyInfoCountryPlaceCode;
  childrenbirthrecords?: ChildrenBirthRecord[];
  childrenoverridemode?: ChildrenOverrideMode;
  residentialstatus?: MyinfoResidentialCode;
  occupationfreeform?: string;
  dob?: string;
  gstvyear?: number;
  gvs?: GVS;
  merdekageneligible?: boolean;
  merdekagenquantum?: number;
  merdekagenmessagecode?: MyinfoMerdekaGenerationMessageCode;
  hdbtype?: MyinfoHDBTypeCode;
  housingtype?: MyinfoHousingTypeCode;
  drivingqdlvalidity?: MyinfoDrivingLicenceValidityCode;
  vehicles?: VehicleDetails[];
  employment?: string;
}) => MyInfoComponents.Schemas.PersonBasic

getPerson({
  archetype: ProfileArchetype;
  userdisplayname?: string;
  race?: MyInfoRaceCode:
  marital?: MyInfoMaritalStatusCode;
  marriagedate?: string;
  divorcedate?: string;
  marriagecertno?: string;
  countryofmarriage?: MyInfoCountryPlaceCode;
  childrenbirthrecords?: ChildrenBirthRecord[];
  childrenoverridemode?: ChildrenOverrideMode;
  residentialstatus?: MyinfoResidentialCode;
  occupationfreeform?: string;
  dob?: string;
  gstvyear?: number;
  gvs?: GVS;
  merdekageneligible?: boolean;
  merdekagenquantum?: number;
  merdekagenmessagecode?: MyinfoMerdekaGenerationMessageCode;
  hdbtype?: MyinfoHDBTypeCode;
  housingtype?: MyinfoHousingTypeCode;
  drivingqdlvalidity?: MyinfoDrivingLicenceValidityCode;
  vehicles?: VehicleDetails[];
  employment?: string;
  cpfcontributionhistoryoverridemode?: OverrideMode;
  cpfcontributions?: CpfContributionHistory[];
  cpfbalances?: CpfBalance;
  noabasic?: NoaBasic;
}) => MyInfoComponents.Schemas.Person

• get a fake person data.

• enum MyInfo.Fake.ProfileArchetype suitably named profile archetypes to generate different types of fake MyInfo person

Updating Myinfo domains

• Myinfo domains including MyinfoComponents and various enums are auto generated via npm run generate-myinfo-typings '<swagger file>'
• Swagger file needs to be downloaded from https://public.cloud.myinfo.gov.sg/myinfo/tuo/myinfo-tuo-specs.html
  • Note: there are different variants, this is for Government Digital Services which has the person-basic api
• The script will also fetch and generate enums from https://api.singpass.gov.sg/assets/api-lib/myinfo/downloads/myinfo-api-code-tables.xlsx

Folder / file structure of src/myinfo/domain

Help! The swagger file is missing <insert data item name>

• Myinfo REST API does not publish every data item
• You will need to manually add its OpenAPI specification in custom/person-common then run npm run generate-myinfo-typings '<swagger file>'
• An interface will be created and the corresponding data item will be added to the PersonCommon object

Help! myinfo-api-code-tables.xlsx is missing <insert code name>

• myinfo-api-code-tables.xlsx lists general codes only
• More detailed lists can be found at https://www.singstat.gov.sg/standards/standards-and-classifications
• If the missing code list can be found in SingStat, update generate-myinfo-typings script to import accordingly
• Otherwise
  1. Manually add the enum definition (json) to custom/enums folder
     • Hint: Refer to existing files for format
  2. Run npm run generate-myinfo-typings '<swagger file>'

Help! myinfo-api-code-tables.xlsx's <insert code name> does not match the swagger definition

• Follow the solution above to add enum definition manually
• That enum will overwrite the auto generated enum

Singpass (Pre-NDI)

Helper for integrating with Pre-NDI Singpass OIDC

import { Singpass } from "singpass-myinfo-oidc-helper"

Singpass.OidcHelper

• constructor

Login

• constructAuthorizationUrl = (state: string, nonce?: string) => string - constructs the authorization url with the necessary params, including the:

• state (later returned in redirectUri)

• nonce (later returned inside the JWT from token endpoint)

• getTokens (authCode: string, axiosRequestConfig?: AxiosRequestConfig) => Promise<TokenResponse> - get back the tokens from SP token endpoint. Outputs TokenResponse, which is the input for getIdTokenPayload

• refreshTokens (refreshToken: string, axiosRequestConfig?: AxiosRequestConfig) => Promise<TokenResponse> - get fresh tokens from SP token endpoint. Outputs TokenResponse, which is the input for getIdTokenPayload
• getIdTokenPayload(tokens: TokenResponse) => Promise<TokenPayload> - decrypt and verify the JWT. Outputs TokenPayload, which is the input for extractNricAndUuidFromPayload
• extractNricAndUuidFromPayload(payload: TokenPayload) => { nric: string, uuid: string } - finally, get the nric and WOG (Whole-of-government) UUID of the user from the ID Token TokenPayload

Logout Singpass SSO session

• logoutOfSession(sessionId: string) => Promise<SessionLogoutResult>- Log user out of Singpass session, using a valid session id (that is retrieved from Singpass domain cookie)

Singpass (Post-NDI)

Helper for integrating with Post-NDI Singpass OIDC

import { Singpass } from "singpass-myinfo-oidc-helper"

Singpass.NdiOidcHelper

• constructor

Login

• constructAuthorizationUrl = (state: string, nonce?: string) => Promise<string> - constructs the authorization url with the necessary params, including the:

• state (later returned in redirectUri)

• nonce (later returned inside the JWT from token endpoint)

• getTokens (authCode: string, axiosRequestConfig?: AxiosRequestConfig) => Promise<TokenResponse> - get back the tokens from SP token endpoint. Outputs TokenResponse, which is the input for getIdTokenPayload

• getIdTokenPayload(tokens: TokenResponse, overrideDecryptKey?: Key) => Promise<TokenPayload> - decrypt and verify the JWT. Outputs TokenPayload, which is the input for extractNricAndUuidFromPayload
• extractNricAndUuidFromPayload(payload: TokenPayload) => { nric: string, uuid: string } - finally, get the nric and WOG (Whole-of-government) UUID of the user from the ID Token TokenPayload

Corppass (Pre-NDI)

Helper for integrating with Pre-NDI Corppass OIDC

import { Corppass } from "singpass-myinfo-oidc-helper"

Corppass.OidcHelper

• constructor

Login

• constructAuthorizationUrl = (state: string, nonce?: string) => string - constructs the authorization url with the necessary params, including the:

• state (later returned in redirectUri)

• nonce (later returned inside the JWT from token endpoint)

• getTokens (authCode: string, axiosRequestConfig?: AxiosRequestConfig) => Promise<TokenResponse> - get back the tokens from token endpoint. Outputs TokenResponse, which is the input for getIdTokenPayload

• refreshTokens (refreshToken: string, axiosRequestConfig?: AxiosRequestConfig) => Promise<TokenResponse> - get fresh tokens from SP token endpoint. Outputs TokenResponse, which is the input for getIdTokenPayload
• getAccessTokenPayload(tokens: TokenResponse) => Promise<AccessTokenPayload> - decode and verify the JWT. Outputs AccessTokenPayload, which contains the EntityInfo, AuthInfo and TPAccessInfo claims
• getIdTokenPayload(tokens: TokenResponse, overrideDecryptKey?: Key) => Promise<IdTokenPayload> - decrypt and verify the JWT. Outputs IdTokenPayload, which is the input for extractInfoFromIdTokenSubject
• extractInfoFromIdTokenSubject(payload: TokenPayload) => { nric: string, uuid: string, countryCode: string } - finally, get the nric, system defined UUID and country code of the user from the ID Token TokenPayload

Corppass (Post-NDI)

Helper for integrating with Post-NDI Corppass OIDC

import { Corppass } from "singpass-myinfo-oidc-helper"

Corppass.NdiOidcHelper

• constructor

Login

• constructAuthorizationUrl = (state: string, nonce?: string) => Promise<string> - constructs the authorization url with the necessary params, including the:

• state (later returned in redirectUri)

• nonce (later returned inside the JWT from token endpoint)

• getTokens (authCode: string, axiosRequestConfig?: AxiosRequestConfig) => Promise<TokenResponse> - get back the tokens from token endpoint. Outputs TokenResponse, which is the input for getIdTokenPayload

• getAccessTokenPayload(tokens: TokenResponse) => Promise<AccessTokenPayload> - decode and verify the JWT. Outputs AccessTokenPayload, which contains the EntityInfo, AuthInfo and TPAccessInfo claims
• getIdTokenPayload(tokens: TokenResponse) => Promise<IdTokenPayload> - decrypt and verify the JWT. Outputs IdTokenPayload, which is the input for extractInfoFromIdTokenSubject
• extractInfoFromIdTokenSubject(payload: TokenPayload) => { nric: string, uuid: string, countryCode: string } - finally, get the nric, system defined UUID and country code of the user from the ID Token TokenPayload
• getAuthorisationInfoTokenPayload(tokens: TokenResponse) => Promise<AuthInfoTokenPayload> - get authorisation info JWT from authorisation info endpoint. Outputs AuthInfoTokenPayload, which contain roles and params information of user
• extractActiveAuthResultFromAuthInfoToken(authInfoToken: AuthInfoTokenPayload): Record<string, EserviceAuthResultRow[]> - get the currently active authorisation information of the user from the authorisation information token payload

Key Object