@govtechsg/singpass-myinfo-oidc-helper

中文文档
9.1.0发布于 2026/07/01MITTypeScriptCommonJS近 30 天下载 7239

Helper for building a Relying Party to integrate with Singpass OIDC and MyInfo person basic API

原始使用文档
文档目录21 节
  1. Installation
  2. Testing your SingPass / MyInfo client setup and secrets
  3. MyInfo
  4. MyInfoHelper
  5. MyInfoRequest
  6. Fake
  7. Updating Myinfo domains
  8. Folder / file structure of src/types
  9. Help! The swagger file is missing <insert data item name>
  10. Help! myinfo-api-code-tables.xlsx is missing <insert code n…
  11. Help! myinfo-api-code-tables.xlsx's <insert code name> does…
  12. Singpass (Pre-NDI)
  13. Login
  14. Singpass (Post-NDI)
  15. Login (V3) deprecated
  16. Login (V4)
  17. Corppass (Pre-NDI)
  18. Login
  19. Corppass (Post-NDI)
  20. Login
  21. Key Object

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


Testing your SingPass / MyInfo client setup and secrets

  • These tests will allow you to check if your IDs / keys / certs / JWK endpoints/objects are correctly setup
  • Use singpass-helper-ndi-ext.spec.ts to test login and retrieval of tokens
  • After logging in use myinfo.ext.spec.ts to test retrieval of myinfo data

MyInfo


MyInfoHelper

Helper to get a V3 MyInfo person.

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

MyInfo.Helper

  • constructor
ParamTypeDescription
attributesstring[]Array of user attributes to retrieve from MyInfo. For full list of attributes, see here
clientIDstringYour app's client ID when you onboarded with MyInfo
personBasicURLstringThe full URL to the MyInfo person basic endpoint. Exposed for lib user to choose between staging, prod, and any mock server
singpassEserviceIDstringYour app's ID when you onboarded Singpass. Used by MyInfo to check if the NRIC you are trying to retrieve MyInfo data for has recently logged into your app via Singpass
keyToDecryptJWEstringYour private key to decrypt MyInfo's JWE payload. The public key has been given to MyInfo during onboarding, for them to encrypt the JWE containing Person Data
certToVerifyJWSstringThe public cert from MyInfo as MyInfo payloads are both encrypted with JWE, and signed with JWS
privateKeyToSignRequeststringUsed for signing the request to MyInfo server. Needs to be an encrypted PKCS8 private key
privateKeyPasswordstringthe password that you used to encrypt privateKeyToSignRequest
  • 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
ParamTypeDescription
appIdstringYour app's client ID when you onboarded with MyInfo
privateKeyToSignRequeststringUsed for signing the request to MyInfo server. Needs to be an encrypted PKCS8 private key
privateKeyPasswordstringthe password that you used to encrypt privateKeyToSignRequest
  • 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
ParamTypeDescription
attributesstring[]?List of MyInfo attributes that this helper will return
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

Folder / file structure of src/types

PathWhat is does
custom/enumsCustom defined enums in json
custom/person-commonAdditional swagger definitions to go into the PersonCommon object
generatedAuto generated enums from generate-myinfo-typings script, do not add files here!

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
ParamTypeDescription
authorizationUrlstringThe URL for Singpass /authorize endpoint
logoutUrlstringThe URL for Singpass /logout endpoint
tokenUrlstringThe URL for Singpass /token endpoint
clientIDstringYour app's ID when you onboarded Singpass.
clientSecretstringThe client secret. To be sent together with client ID to token endpoint
redirectUristringthe redirect URL for Singpass to redirect to after user login. Must be whitelisted by SP during onboarding
jweDecryptKeystringPrivate key for decrypting the JWT that wraps the token
jwsVerifyKeystringPublic key for verifying the JWT that wraps the token

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
ParamTypeDescription
oidcConfigUrlstringThe URL for Singpass OIDC configuration details endpoint
clientIDstringYour app's ID when you onboarded Singpass.
redirectUristringthe redirect URL for Singpass to redirect to after user login. Must be whitelisted by SP during onboarding
jweDecryptKeykey objectObject conatining private key for decrypting the JWT that wraps the token
clientAssertionSignKeykey objectObject conatining private key for signing the client assertion provided in the token endpoint request

Login (V3) deprecated

  • constructAuthorizationUrl = (params: { state: string; userInfoScope: string[]; nonce?: string; codeVerifier?: 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

Login (V4)

  • constructAuthorizationUrlV2 = (params: { state: string; userInfoScope: string[]; nonce?: string; codeVerifier?: 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)
    • scope (determines the attributes/user data to be fetched from MyInfo)
  • getTokens (authCode: string, axiosRequestConfig?: AxiosRequestConfig) => Promise<TokenResponse> - get back the tokens from SP token endpoint. Outputs TokenResponse, which is the input for getIdTokenPayload

  • getUserInfo (token: string) => Promise<string> - using the access_token from getTokens, retrieve user data, with the response being a JWE token

  • verifyUserInfo (jwe: string) => Promise<object> - decrypts the userInfo JWE to return user data


Corppass (Pre-NDI)

Helper for integrating with Pre-NDI Corppass OIDC

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

Corppass.OidcHelper

  • constructor
ParamTypeDescription
authorizationUrlstringThe URL for Corppass /authorize endpoint
tokenUrlstringThe URL for Corppass /token endpoint
clientIDstringYour app's ID when you onboarded Corppass.
clientSecretstringThe client secret. To be sent together with client ID to token endpoint
redirectUristringthe redirect URL for Corppass to redirect to after user login. Must be whitelisted by SP during onboarding
jweDecryptKeystringPrivate key for decrypting the JWT that wraps the token
jwsVerifyKeystringPublic key for verifying the JWT that wraps the token

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
ParamTypeDescription
oidcConfigUrlstringThe URL for Corppass OIDC configuration details endpoint
clientIDstringYour app's ID when you onboarded Corppass.
redirectUristringthe redirect URL for Corppass to redirect to after user login. Must be whitelisted by SP during onboarding
jweDecryptKeykey objectObject conatining private key for decrypting the JWT that wraps the token
clientAssertionSignKeykey objectObject conatining private key for signing the client assertion provided in the token endpoint request

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

ParamTypeDescription
keystringcontents of key
formatstringformat of key provided
algstringkey algorithm

版本与发布记录

@govtechsg/singpass-myinfo-oidc-helper 共发布 70 个版本,首次发布于 2020/04/08;过去 12 个月发布了 5 个版本。

版本发布日期距今
9.1.0latest2026/07/014 个月前
9.0.62026/04/157 个月前
9.0.52026/04/147 个月前
9.0.42026/04/107 个月前
9.0.32026/03/098 个月前
9.0.22025/10/081.1 年前

关于 @govtechsg/singpass-myinfo-oidc-helper 的常见问题

@govtechsg/singpass-myinfo-oidc-helper 是什么?

Helper for building a Relying Party to integrate with Singpass OIDC and MyInfo person basic API

如何安装 @govtechsg/singpass-myinfo-oidc-helper?

在项目目录运行 npm install @govtechsg/singpass-myinfo-oidc-helper,或使用 pnpm add / yarn add / bun add。

@govtechsg/singpass-myinfo-oidc-helper 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@govtechsg/singpass-myinfo-oidc-helper 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@govtechsg/singpass-myinfo-oidc-helper 可以商用吗?

@govtechsg/singpass-myinfo-oidc-helper 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@govtechsg/singpass-myinfo-oidc-helper 的下载量有多少?

根据 npm 官方下载统计,@govtechsg/singpass-myinfo-oidc-helper 在 2026/10/17 – 2026/11/15 这 30 天内被下载 7,239 次,日均约 241 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@govtechsg/singpass-myinfo-oidc-helper 还在维护吗?

最新版本 9.1.0 发布于 2026/07/01(4 个月前);至今共发布 70 个版本,其中过去 12 个月发布了 5 个;首次发布于 2020/04/08。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。