Myinfo Connector NodeJS

Myinfo Connector NodeJS aims to simplify consumer's integration effort with MyInfo by providing an easy to use Javascript library to integrate into your application.

Contents

• Myinfo Connector NodeJS
  • Contents
  • 1. Installation
    • 1.1. Using npm:
  • 2. Usage
    • 2.1. Sample Code
    • 2.2. Process Environment file
  • 3. Individual Method
    • 3.1. Get Myinfo Person Data
    • 3.2. Generate Code Verifier and Code Challenge
    • 3.3. Get Access Token
    • 3.4. Get Person Data
  • Reporting Issue

1. Installation

1.1. Using npm:

$ npm install myinfo-connector-v4-nodejs 

2. Usage

2.1. Sample Code

var MyInfoConnector = require('myinfo-connector-v4-nodejs'); //Call constructor to initialize library and pass in the configurations.

let connector = new MyInfoConnector(config.MYINFO_CONNECTOR_CONFIG); // MYINFO_CONNECTOR_CONFIG is the Process Environment file (in JSON format), please refer to Process Environment file in 2.2


  /**
   * Get Myinfo Person Data (Myinfo Token + Person API)
   *
   * This method takes in all the required variables, invoke the following APIs.
   * - Get Access Token (Token API) - to get Access Token by using the Auth Code
   * - Get Person Data (Person API) - to get Person Data by using the Access Token
   *
   * @param {string} authCode - Authorization Code from Authorize API
   * @param {string} codeVerifier - Code verifier that corresponds to the code challenge used to retrieve authcode
   * @param {string} privateSigningKey -  Your application private signing key in .pem format
   * @param {Array} privateEncryptionKeys -  Your application private encryption keys in .pem format, pass in a list of private keys that corresponds to JWKS encryption public keys
   *
   * @returns {Promise} - Returns the Person Data (Payload decrypted + Signature validated)
   */

try{
  let personData = await connector.getMyInfoPersonData(authCode, codeVerifier, privateSigningKey, privateEncryptionKeys);

  return personData;
} catch (error) {
  throw error;
}

2.2. Process Environment file

You are required to create an environment file (in JSON format) with the following process environments for this library. You may look at the sample Process Environment file HERE.

| Required Properties | Description | | -------- | ----------- | | CLIENT_ID | Client id provided during onboarding (e.g. STG2-MYINFO-SELF-TEST)| | REDIRECT_URL | The callback URL specified when invoking the authorize call. For our sample application, it is http://localhost:3001/callback | | SCOPE | Space separated list of attributes to be retrieved from Myinfo. | | AUTHORIZE_JWKS_URL | The callback URL specified when invoking the authorize call. For our sample application, it is http://localhost:3001/callback | | SCOPE | Comma separated list of attributes requested. Possible attributes are listed in the Person object definition in the API specifications. (e.g. name,mobileno) | | AUTHORIZE_JWKS_URL | The URL to retrieve the JWKS public key from Authorize. The URL is available in two environments: TEST: https://test.authorise.singpass.gov.sg/.well-known/keys.jsonPRD: https://authorise.singpass.gov.sg/.well-known/keys.json| | MYINFO_JWKS_URL | The URL to retrieve Myinfo JWKS public key. The URL is available in two environments: TEST: https://test.myinfo.singpass.gov.sg/.well-known/keys.jsonPRD: https://myinfo.singpass.gov.sg/.well-known/keys.json| | TOKEN_URL | Specify the TOKEN API URL for MyInfo. The API is available in two environments:TEST: https://test.api.myinfo.gov.sg/com/v4/tokenPROD: https://api.myinfo.gov.sg/com/v4/token | | PERSON_URL | Specify the PERSON API URL for MyInfo. The API is available in two environments: TEST: https://test.api.myinfo.gov.sg/com/v4/personPROD: https://api.myinfo.gov.sg/com/v4/person| | CLIENT_ASSERTION_SIGNING_KID (OPTIONAL) | kid that will be appended to client_assertion header to match JWKS kid. | | SUBENTITY_ID (OPTIONAL) | for platform applications only to specify subentity | | USE_PROXY (OPTIONAL) | Indicate the use of proxy url. It can be either Y or N.| | PROXY_TOKEN_URL (OPTIONAL) | (REQUIRED if USE_PROXY is Y) If you are using a proxy url, specify the proxy URL for TOKEN API here. | | PROXY_PERSON_URL (OPTIONAL) | (REQUIRED if USE_PROXY is Y) If you are using a proxy url, specify the proxy URL for PERSON API here.| | DEBUG_LEVEL (OPTIONAL) | (OPTIONAL: if empty will be defaulted to no logs) Configuration to set logging level for debugging within the library. ModeDescriptionerrorLog out all the errors returned from the libraryinfoLog urls called, authorization headers and errors from the librarydebugFull logs from the library, i.e (errors, urls, authorization headers, API response) IMPORTANT NOTE: debug mode should never be turned on in production

3. Individual Method

Under the hood, MyInfo Connector NodeJS makes use of SecurityHelper and you may use the class as util methods to meet your application needs.

3.1. Get MyInfo Person Data

This method takes in all the required parameters to get MyInfo Person Data.

var MyInfoConnector = require('myinfo-connector-nodejs'); //Call constructor to initialize library and pass in the configurations.

let connector = new MyInfoConnector(config.MYINFO_CONNECTOR_CONFIG); // MYINFO_CONNECTOR_CONFIG is the Process Environment file (in JSON format), please refer to Process Environment file in 2.2

  /**
   * Get MyInfo Person Data (MyInfo Token + Person API)
   *
   * This method takes in all the required variables, invoke the following APIs.
   * - Get Access Token (Token API) - to get Access Token by using the Auth Code
   * - Get Person Data (Person API) - to get Person Data by using the Access Token
   *
   * @param {string} authCode - Authorization Code from Authorize API
   * @param {string} codeVerifier - Code verifier that corresponds to the code challenge used to retrieve authcode
   * @param {string} privateSigningKey -  Your application private signing key in .pem format
   * @param {Array} privateEncryptionKeys -  Your application private encryption keys in .pem format, pass in a list of private keys that corresponds to JWKS encryption public keys
   *
   * @returns {Promise} - Returns the Person Data (Payload decrypted + Signature validated)
   */
  getMyInfoPersonData = function (authCode, codeVerifier, privateSigningKey, privateEncryptionKeys)

3.2. Generate Code Verifier and Code Challenge

This method generates the code verifier and the code challenge for the PKCE flow.

  /**
   * This method generates the code verifier and code challenge for the PKCE flow.
   * 
   * @returns {Object} - Returns an object consisting of the code verifier and the code challenge
   */
  generatePKCECodePair = function ()

3.3. Get Access Token

This method takes in the authCode obtained from Authorize API and returns the access token.

  /**
   * Get Access Token from MyInfo Token API
   *
   * This method calls the Token API and obtain an "access token",
   * which can be used to call the Person API for the actual data.
   * Your application needs to provide a valid "authorisation code"
   * from the authorize API in exchange for the "access token".
   *
   * @param {string} authCode - Authorization Code from authorize API
   * @param {string} codeVerifier - Code verifier that corresponds to the code challenge used to retrieve authcode
   * @param {object} sessionEphemeralKeyPair - Session EphemeralKeyPair used to sign DPoP
   * @param {string} privateSigningKey -  Your application private signing key in .pem format
   * @returns {Promise} - Returns the Access Token
   */
  getAccessToken = function (authCode,codeVerifier,sessionEphemeralKeyPair,privateSigningKey)

3.4. Get Person Data

This method takes in the accessToken and returns the person data.

  /**
   * Get Person Data from MyInfo Person API
   *
   * This method calls the Person API and returns a JSON response with the
   * personal data that was requested. Your application needs to provide a
   * valid "access token" in exchange for the JSON data. Once your application
   * receives this JSON data, you can use this data to populate the online
   * form on your application.
   *
   * @param {string} accessToken - Access token from Token API
   * @param {object} sessionEphemeralKeyPair - Session EphemeralKeyPair used to sign DPoP
   * @param {Array} privateEncryptionKeys -  Your application private encryption keys in .pem format, pass in a list of private keys that corresponds to JWKS encryption public keys
   * @returns {Promise} Returns the Person Data (Payload decrypted + Signature validated)
   */
  getPersonData = function (accessToken, sessionPopKeyPair, privateEncryptionKeys)

Reporting Issue

You may contact our support for any other technical issues, and we will respond to you within 5 working days.