{"id":19107129,"url":"https://github.com/govtechsg/singpass-myinfo-oidc-helper","last_synced_at":"2025-04-05T03:07:14.039Z","repository":{"id":42191721,"uuid":"177287107","full_name":"GovTechSG/singpass-myinfo-oidc-helper","owner":"GovTechSG","description":"Helper for building Relying Party to integrate with Singpass OIDC and MyInfo person basic API","archived":false,"fork":false,"pushed_at":"2025-03-26T10:36:14.000Z","size":4133,"stargazers_count":29,"open_issues_count":13,"forks_count":21,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-03-29T02:06:17.083Z","etag":null,"topics":["myinfo","oidc-client","singpass"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GovTechSG.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-23T12:38:38.000Z","updated_at":"2025-02-04T06:12:18.000Z","dependencies_parsed_at":"2023-12-06T08:26:03.248Z","dependency_job_id":"45371454-df69-4994-a89e-19ac07a123c9","html_url":"https://github.com/GovTechSG/singpass-myinfo-oidc-helper","commit_stats":{"total_commits":474,"total_committers":48,"mean_commits":9.875,"dds":0.8945147679324894,"last_synced_commit":"231afff8da1314a15f7ce85c122c57bd35ae9e9e"},"previous_names":[],"tags_count":197,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GovTechSG%2Fsingpass-myinfo-oidc-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GovTechSG%2Fsingpass-myinfo-oidc-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GovTechSG%2Fsingpass-myinfo-oidc-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GovTechSG%2Fsingpass-myinfo-oidc-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GovTechSG","download_url":"https://codeload.github.com/GovTechSG/singpass-myinfo-oidc-helper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280263,"owners_count":20912967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["myinfo","oidc-client","singpass"],"created_at":"2024-11-09T04:11:23.462Z","updated_at":"2025-04-05T03:07:14.018Z","avatar_url":"https://github.com/GovTechSG.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Singpass MyInfo OIDC helper\n\nUse this module to build client applications that can:\n\n- Authenticate users via the Singpass/Corppass OIDC provider\n- Retrieve user's MyInfo data via the MyInfo Person-Basic API and Person API\n\n---\n\n## Installation\n\n`npm i @govtechsg/singpass-myinfo-oidc-helper`\n\n---\n\n## MyInfo\n\n---\n\n### MyInfoHelper\n\nHelper to get a V3 MyInfo person.\n\n`import { MyInfo } from \"singpass-myinfo-oidc-helper\"`\n\nMyInfo.Helper\n\n- `constructor`\n\n| Param                   | Type     | Description                                                                                                                                                              |\n| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| attributes              | string[] | Array of user attributes to retrieve from MyInfo. For full list of attributes, see [here](https://public.cloud.myinfo.gov.sg/myinfo/tuo/myinfo-tuo-specs.html)           |\n| clientID                | string   | Your app's client ID when you onboarded with MyInfo                                                                                                                      |\n| personBasicURL          | string   | The full URL to the MyInfo person basic endpoint. Exposed for lib user to choose between staging, prod, and any mock server                                              |\n| singpassEserviceID      | string   | Your 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 |\n| keyToDecryptJWE         | string   | Your 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          |\n| certToVerifyJWS         | string   | The public cert from MyInfo as MyInfo payloads are both encrypted with JWE, and signed with JWS                                                                          |\n| privateKeyToSignRequest | string   | Used for signing the request to MyInfo server. Needs to be an encrypted PKCS8 private key                                                                                |\n| privateKeyPassword      | string   | the password that you used to encrypt privateKeyToSignRequest                                                                                                            |\n\n- `getPersonBasic(uinfin: string, attributes: string[]) =\u003e MyInfoComponents.Schemas.PersonBasic` - get basic profile data which excludes CPF and IRAS data in the shape of `MyInfoComponents.Schemas.PersonBasic`\n- `constructAuthorizationUrl(state: string, purpose: string, attributes: string[]) =\u003e string` - constructs the authorization url with the necessary params for authorising the user to retrieve full person data\n- `getToken(authCode: string, state?: string): =\u003e TokenResponse` - get access token when presented with a valid authcode obtained from the Authorise API\n- `getPerson(accessToken: string, attributes: string[]) =\u003e MyInfoComponents.Schemas.Person` - get full person data in the shape of `MyInfoComponents.Schemas.Person`, requires a valid access token obtained from getToken\n\n---\n\n### MyInfoRequest\n\nUsually not needed, for making any other custom requests to MyInfo not covered in our MyInfo helper.\n\n- `constructor`\n\n| Param                   | Type   | Description                                                                               |\n| ----------------------- | ------ | ----------------------------------------------------------------------------------------- |\n| appId                   | string | Your app's client ID when you onboarded with MyInfo                                       |\n| privateKeyToSignRequest | string | Used for signing the request to MyInfo server. Needs to be an encrypted PKCS8 private key |\n| privateKeyPassword      | string | the password that you used to encrypt privateKeyToSignRequest                             |\n\n- `get(uri: string, queryParams?: { [key: string]: any }, accessToken?: string)` - make get request to the defined myinfo gov endpoint\n\n  - `queryParams` refer to the query params for the get request\n  - `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\n\n- `post(uri: string, params: { [key: string]: any })` - make post request to the defined myinfo gov endpoint\n\n---\n\n### Fake\n\nMyInfo.Fake.FakeMyInfoHelper\n\nUse `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.\n\n- `constructor`\n\n| Param      | Type      | Description                                            |\n| ---------- | --------- | ------------------------------------------------------ |\n| attributes | string[]? | List of MyInfo attributes that this helper will return |\n\n```ts\ngetPersonBasic({\n  archetype: ProfileArchetype;\n  userdisplayname?: string;\n  race?: MyInfoRaceCode:\n  marital?: MyInfoMaritalStatusCode;\n  marriagedate?: string;\n  divorcedate?: string;\n  marriagecertno?: string;\n  countryofmarriage?: MyInfoCountryPlaceCode;\n  childrenbirthrecords?: ChildrenBirthRecord[];\n  childrenoverridemode?: ChildrenOverrideMode;\n  residentialstatus?: MyinfoResidentialCode;\n  occupationfreeform?: string;\n  dob?: string;\n  gstvyear?: number;\n  gvs?: GVS;\n  merdekageneligible?: boolean;\n  merdekagenquantum?: number;\n  merdekagenmessagecode?: MyinfoMerdekaGenerationMessageCode;\n  hdbtype?: MyinfoHDBTypeCode;\n  housingtype?: MyinfoHousingTypeCode;\n  drivingqdlvalidity?: MyinfoDrivingLicenceValidityCode;\n  vehicles?: VehicleDetails[];\n  employment?: string;\n}) =\u003e MyInfoComponents.Schemas.PersonBasic\n\ngetPerson({\n  archetype: ProfileArchetype;\n  userdisplayname?: string;\n  race?: MyInfoRaceCode:\n  marital?: MyInfoMaritalStatusCode;\n  marriagedate?: string;\n  divorcedate?: string;\n  marriagecertno?: string;\n  countryofmarriage?: MyInfoCountryPlaceCode;\n  childrenbirthrecords?: ChildrenBirthRecord[];\n  childrenoverridemode?: ChildrenOverrideMode;\n  residentialstatus?: MyinfoResidentialCode;\n  occupationfreeform?: string;\n  dob?: string;\n  gstvyear?: number;\n  gvs?: GVS;\n  merdekageneligible?: boolean;\n  merdekagenquantum?: number;\n  merdekagenmessagecode?: MyinfoMerdekaGenerationMessageCode;\n  hdbtype?: MyinfoHDBTypeCode;\n  housingtype?: MyinfoHousingTypeCode;\n  drivingqdlvalidity?: MyinfoDrivingLicenceValidityCode;\n  vehicles?: VehicleDetails[];\n  employment?: string;\n  cpfcontributionhistoryoverridemode?: OverrideMode;\n  cpfcontributions?: CpfContributionHistory[];\n  cpfbalances?: CpfBalance;\n  noabasic?: NoaBasic;\n}) =\u003e MyInfoComponents.Schemas.Person\n```\n\n- get a fake person data.\n\n- enum MyInfo.Fake.ProfileArchetype\n  suitably named profile archetypes to generate different types of fake MyInfo person\n\n---\n\n## Updating Myinfo domains\n\n- Myinfo domains including `MyinfoComponents` and various enums are auto generated via `npm run generate-myinfo-typings '\u003cswagger file\u003e'`\n- Swagger file needs to be downloaded from \u003chttps://public.cloud.myinfo.gov.sg/myinfo/tuo/myinfo-tuo-specs.html\u003e\n  - Note: there are different variants, this is for Government Digital Services which has the person-basic api\n- The script will also fetch and generate enums from \u003chttps://api.singpass.gov.sg/assets/api-lib/myinfo/downloads/myinfo-api-code-tables.xlsx\u003e\n\n### Folder / file structure of `src/myinfo/domain`\n\n| Path                 | What is does                                                                       |\n| -------------------- | ---------------------------------------------------------------------------------- |\n| custom/enums         | Custom defined enums in json                                                       |\n| custom/person-common | Additional swagger definitions to go into the `PersonCommon` object                |\n| generated            | Auto generated enums from `generate-myinfo-typings` script, do not add files here! |\n\n### Help! The swagger file is missing `\u003cinsert data item name\u003e`\n\n- Myinfo REST API does not publish every data item\n- You will need to manually add its OpenAPI specification in `custom/person-common` then run `npm run generate-myinfo-typings '\u003cswagger file\u003e'`\n- An interface will be created and the corresponding data item will be added to the `PersonCommon` object\n\n### Help! `myinfo-api-code-tables.xlsx` is missing `\u003cinsert code name\u003e`\n\n- `myinfo-api-code-tables.xlsx` lists general codes only\n- More detailed lists can be found at \u003chttps://www.singstat.gov.sg/standards/standards-and-classifications\u003e\n- If the missing code list can be found in SingStat, update `generate-myinfo-typings` script to import accordingly\n- Otherwise\n  1. Manually add the enum definition (json) to `custom/enums` folder\n     - _Hint: Refer to existing files for format_\n  2. Run `npm run generate-myinfo-typings '\u003cswagger file\u003e'`\n\n### Help! `myinfo-api-code-tables.xlsx's \u003cinsert code name\u003e` does not match the swagger definition\n\n- Follow the solution above to add enum definition manually\n- That enum will overwrite the auto generated enum\n\n---\n\n## Singpass (Pre-NDI)\n\nHelper for integrating with Pre-NDI Singpass OIDC\n\n`import { Singpass } from \"singpass-myinfo-oidc-helper\"`\n\nSingpass.OidcHelper\n\n- `constructor`\n\n| Param            | Type   | Description                                                                                                |\n| ---------------- | ------ | ---------------------------------------------------------------------------------------------------------- |\n| authorizationUrl | string | The URL for Singpass /authorize endpoint                                                                   |\n| logoutUrl        | string | The URL for Singpass /logout endpoint                                                                      |\n| tokenUrl         | string | The URL for Singpass /token endpoint                                                                       |\n| clientID         | string | Your app's ID when you onboarded Singpass.                                                                 |\n| clientSecret     | string | The client secret. To be sent together with client ID to token endpoint                                    |\n| redirectUri      | string | the redirect URL for Singpass to redirect to after user login. Must be whitelisted by SP during onboarding |\n| jweDecryptKey    | string | Private key for decrypting the JWT that wraps the token                                                    |\n| jwsVerifyKey     | string | Public key for verifying the JWT that wraps the token                                                      |\n\n### Login\n\n- `constructAuthorizationUrl = (state: string, nonce?: string) =\u003e string` - constructs the authorization url with the necessary params, including the:\n\n- state (later returned in redirectUri)\n- nonce (later returned inside the JWT from token endpoint)\n\n- `getTokens (authCode: string, axiosRequestConfig?: AxiosRequestConfig) =\u003e Promise\u003cTokenResponse\u003e` - get back the tokens from SP token endpoint. Outputs TokenResponse, which is the input for getIdTokenPayload\n- `refreshTokens (refreshToken: string, axiosRequestConfig?: AxiosRequestConfig) =\u003e Promise\u003cTokenResponse\u003e` - get fresh tokens from SP token endpoint. Outputs TokenResponse, which is the input for getIdTokenPayload\n- `getIdTokenPayload(tokens: TokenResponse) =\u003e Promise\u003cTokenPayload\u003e` - decrypt and verify the JWT. Outputs TokenPayload, which is the input for extractNricAndUuidFromPayload\n- `extractNricAndUuidFromPayload(payload: TokenPayload) =\u003e { nric: string, uuid: string }` - finally, get the nric and WOG (Whole-of-government) UUID of the user from the ID Token TokenPayload\n\n#### Logout Singpass SSO session\n\n- `logoutOfSession(sessionId: string) =\u003e Promise\u003cSessionLogoutResult\u003e`- Log user out of Singpass session, using a valid session id (that is retrieved from Singpass domain cookie)\n\n---\n\n## Singpass (Post-NDI)\n\nHelper for integrating with Post-NDI Singpass OIDC\n\n`import { Singpass } from \"singpass-myinfo-oidc-helper\"`\n\nSingpass.NdiOidcHelper\n\n- `constructor`\n\n| Param                  | Type                      | Description                                                                                                |\n| ---------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------- |\n| oidcConfigUrl          | string                    | The URL for Singpass OIDC configuration details endpoint                                                   |\n| clientID               | string                    | Your app's ID when you onboarded Singpass.                                                                 |\n| redirectUri            | string                    | the redirect URL for Singpass to redirect to after user login. Must be whitelisted by SP during onboarding |\n| jweDecryptKey          | [key object](#key-object) | Object conatining private key for decrypting the JWT that wraps the token                                  |\n| clientAssertionSignKey | [key object](#key-object) | Object conatining private key for signing the client assertion provided in the token endpoint request      |\n\n### Login\n\n- `constructAuthorizationUrl = (state: string, nonce?: string) =\u003e Promise\u003cstring\u003e` - constructs the authorization url with the necessary params, including the:\n\n- state (later returned in redirectUri)\n- nonce (later returned inside the JWT from token endpoint)\n\n- `getTokens (authCode: string, axiosRequestConfig?: AxiosRequestConfig) =\u003e Promise\u003cTokenResponse\u003e` - get back the tokens from SP token endpoint. Outputs TokenResponse, which is the input for getIdTokenPayload\n- `getIdTokenPayload(tokens: TokenResponse, overrideDecryptKey?: Key) =\u003e Promise\u003cTokenPayload\u003e` - decrypt and verify the JWT. Outputs TokenPayload, which is the input for extractNricAndUuidFromPayload\n- `extractNricAndUuidFromPayload(payload: TokenPayload) =\u003e { nric: string, uuid: string }` - finally, get the nric and WOG (Whole-of-government) UUID of the user from the ID Token TokenPayload\n\n---\n\n## Corppass (Pre-NDI)\n\nHelper for integrating with Pre-NDI Corppass OIDC\n\n`import { Corppass } from \"singpass-myinfo-oidc-helper\"`\n\nCorppass.OidcHelper\n\n- `constructor`\n\n| Param            | Type   | Description                                                                                                |\n| ---------------- | ------ | ---------------------------------------------------------------------------------------------------------- |\n| authorizationUrl | string | The URL for Corppass /authorize endpoint                                                                   |\n| tokenUrl         | string | The URL for Corppass /token endpoint                                                                       |\n| clientID         | string | Your app's ID when you onboarded Corppass.                                                                 |\n| clientSecret     | string | The client secret. To be sent together with client ID to token endpoint                                    |\n| redirectUri      | string | the redirect URL for Corppass to redirect to after user login. Must be whitelisted by SP during onboarding |\n| jweDecryptKey    | string | Private key for decrypting the JWT that wraps the token                                                    |\n| jwsVerifyKey     | string | Public key for verifying the JWT that wraps the token                                                      |\n\n### Login\n\n- `constructAuthorizationUrl = (state: string, nonce?: string) =\u003e string` - constructs the authorization url with the necessary params, including the:\n\n- state (later returned in redirectUri)\n- nonce (later returned inside the JWT from token endpoint)\n\n- `getTokens (authCode: string, axiosRequestConfig?: AxiosRequestConfig) =\u003e Promise\u003cTokenResponse\u003e` - get back the tokens from token endpoint. Outputs TokenResponse, which is the input for getIdTokenPayload\n- `refreshTokens (refreshToken: string, axiosRequestConfig?: AxiosRequestConfig) =\u003e Promise\u003cTokenResponse\u003e` - get fresh tokens from SP token endpoint. Outputs TokenResponse, which is the input for getIdTokenPayload\n- `getAccessTokenPayload(tokens: TokenResponse) =\u003e Promise\u003cAccessTokenPayload\u003e` - decode and verify the JWT. Outputs AccessTokenPayload, which contains the `EntityInfo`, `AuthInfo` and `TPAccessInfo` claims\n- `getIdTokenPayload(tokens: TokenResponse, overrideDecryptKey?: Key) =\u003e Promise\u003cIdTokenPayload\u003e` - decrypt and verify the JWT. Outputs IdTokenPayload, which is the input for extractInfoFromIdTokenSubject\n- `extractInfoFromIdTokenSubject(payload: TokenPayload) =\u003e { nric: string, uuid: string, countryCode: string }` - finally, get the nric, system defined UUID and country code of the user from the ID Token TokenPayload\n\n---\n\n## Corppass (Post-NDI)\n\nHelper for integrating with Post-NDI Corppass OIDC\n\n`import { Corppass } from \"singpass-myinfo-oidc-helper\"`\n\nCorppass.NdiOidcHelper\n\n- `constructor`\n\n| Param                  | Type                      | Description                                                                                                |\n| ---------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------- |\n| oidcConfigUrl          | string                    | The URL for Corppass OIDC configuration details endpoint                                                   |\n| clientID               | string                    | Your app's ID when you onboarded Corppass.                                                                 |\n| redirectUri            | string                    | the redirect URL for Corppass to redirect to after user login. Must be whitelisted by SP during onboarding |\n| jweDecryptKey          | [key object](#key-object) | Object conatining private key for decrypting the JWT that wraps the token                                  |\n| clientAssertionSignKey | [key object](#key-object) | Object conatining private key for signing the client assertion provided in the token endpoint request      |\n\n### Login\n\n- `constructAuthorizationUrl = (state: string, nonce?: string) =\u003e Promise\u003cstring\u003e` - constructs the authorization url with the necessary params, including the:\n\n- state (later returned in redirectUri)\n- nonce (later returned inside the JWT from token endpoint)\n\n- `getTokens (authCode: string, axiosRequestConfig?: AxiosRequestConfig) =\u003e Promise\u003cTokenResponse\u003e` - get back the tokens from token endpoint. Outputs TokenResponse, which is the input for getIdTokenPayload\n- `getAccessTokenPayload(tokens: TokenResponse) =\u003e Promise\u003cAccessTokenPayload\u003e` - decode and verify the JWT. Outputs AccessTokenPayload, which contains the `EntityInfo`, `AuthInfo` and `TPAccessInfo` claims\n- `getIdTokenPayload(tokens: TokenResponse) =\u003e Promise\u003cIdTokenPayload\u003e` - decrypt and verify the JWT. Outputs IdTokenPayload, which is the input for extractInfoFromIdTokenSubject\n- `extractInfoFromIdTokenSubject(payload: TokenPayload) =\u003e { nric: string, uuid: string, countryCode: string }` - finally, get the nric, system defined UUID and country code of the user from the ID Token TokenPayload\n- `getAuthorisationInfoTokenPayload(tokens: TokenResponse) =\u003e Promise\u003cAuthInfoTokenPayload\u003e` - get authorisation info JWT from authorisation info endpoint. Outputs AuthInfoTokenPayload, which contain roles and params information of user\n- `extractActiveAuthResultFromAuthInfoToken(authInfoToken: AuthInfoTokenPayload): Record\u003cstring, EserviceAuthResultRow[]\u003e` - get the currently active authorisation information of the user from the authorisation information token payload\n\n---\n\n## Key Object\n\n| Param  | Type   | Description            |\n| ------ | ------ | ---------------------- |\n| key    | string | contents of key        |\n| format | string | format of key provided |\n| alg    | string | key algorithm          |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgovtechsg%2Fsingpass-myinfo-oidc-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgovtechsg%2Fsingpass-myinfo-oidc-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgovtechsg%2Fsingpass-myinfo-oidc-helper/lists"}