Tutorial 2: Using OAuth2
For this tutorial, you will need to call the APIs from your server-based (or running from localhost) application.
Myinfo uses OAuth2.0 for our Authentication and Authorisation flow.
Please refer to our API specifications for this tutorial.
1. Download our Sample Client Application
For the purposes of the tutorial, please download our sample client application from Github.
1.1 Install Node.js and NPM
In order for the demo application to run, you will need to Install Node.js and NPM. Follow the instructions given by the links below depending on your OS.
1.2 Run NPM install
Run the following command in the folder you unzipped the application:
npm install1.3 Start the Application
For Linux/MacOS
Execute the following command to start the application:
For Windows Execute the following command to start the application:
Access the Application on Your Browser You should be able to access the sample application via the following URL:
2. Trigger MockPass Login and Consent (authorise API)
The authorise endpoint triggers the MockPass login and shows the consent page after successful login. Click on the "Retrieve Myinfo" button on the sample application. This calls the URL below (with some additional parameters):
This calls the URL below (with some additional parameters):
client_id
unique ID for your application. For our sample application, this is STG2-MYINFO-SELF-TEST
attributes
comma separated list of attributes requested. Possible attributes are listed in the Person object definition in the API specifications.
purpose
state the purpose of requesting the data. This will be shown to the Person when requesting for his consent
state
identifier to reconcile query and response. This will be sent back to you via the callback URL. Use a unique system generated number for each and every call.
redirect_uri
your callback URL for Myinfo to return with the authorisation code. For our sample application this is http://localhost:3001/callback
Look at the file views/html/index.html in the sample application and look for the following lines of code:
The index.html file is the frontend (client side) code.
This code triggers the authorise API.
2.1 Login with MockPass
Select this test ID and login using MockPass:
NRIC: S9812381D
You may also use test personas found in the Personas Page when testing Tutorial 2.
2.2 Consent Page
Once you have successfully logged into MockPass, a consent page similar to the one below will be shown:
2.3 Get the Authorisation Code
If you have followed the steps above correctly, the Consent Platform should return you an authorisation code by invoking your callback URL. You should now see something like this in your browser URL dialog:
Notice the parameter code is the authorisation code that your application will need to invoke the next API (token). In the example above, the authorisation code is e2369168-52da-421a-b70f-03f64e779c4b. We will use this authorisation code in the next token API call.
The token and person API calls will follow automatically once you have finished the consent page.
We will look at the code for these 2 APIs in the following sections.
3. Call the Token API (with the authorisation code)
Now that you have the authorisation code, you can invoke the token API to get the access token.
Look at the code in the file routes/index.js in our sample client application and search for the following:
index.js is the backend (server side) code.
The code is creating the request to call the following API:
The parameters in the POST body are as follows:
grant_type
grant type for getting token (default "authorization_code")
code
the authcode given by the authorise API.
redirect_uri
your callback URL for Myinfo to validate. For our sample application this is http://localhost:3001/callback
client_id
unique ID for your application. For our sample application, this is STG2-MYINFO-SELF-TEST
client_secret
secret key given to your application during onboarding. For our sample application, this is 44d953c796cccebcec9bdc826852857ab412fbe2
The sample application will then send the constructed request to the API Gateway, and you should see the following response from the onscreen logs:
Notice the response contains an "access_token", which is in the JWT_ _ (JSON Web Token) format.
3.1 What is the JSON Web Token structure?
JSON Web Tokens consist of three parts separated by dots (.), which are:
Header
Payload
Signature
Therefore, a JWT typically looks like the following: xxxxx.yyyyy.zzzzz
The header and the payload are Base64Url encoded. The signature is created using these two, a secret and the hashing algorithm being used (as specified in the header: HMAC, SHA256 or RSA).
3.2 How can I parse the JWT?
In order to parse the JWT you can use one of the libraries listed in the Libraries for Token Signing/Verification section of JWT.io._ _
For example, in our sample application, which is implemented with Node.js, we use the node-jsonwebtoken library, and we call the jwt.verify() method. If the parsing fails then the library will return a JsonWebTokenError error with the message jwt malformed.
Look at the code in the file lib/security/security.js and search for the following code snippet:
This calls the library to parse the JWT and return the decoded JSON object, which is the access token.
You should see the decoded access token in the onscreen logs that looks like this:
This access token is a representation of the permissions that was given by the user when he/she clicked on "I Agree" on the consent page.
Note:It is very important for your application to validate the signature of the JWT to ensure the response has not been changed in transit.
Notice the sub attribute in the JSON token. That is the identifier of the person who logged in via MockPass. We will use this identifier for the Person API call next.
4. Call the Person API (with the access token)
Now that you have the access token, you can invoke the person API to get the Person data.
Note:This API must be called from a server-side component. It cannot be called from the browser or mobile native client application due to security reasons (there is no secure place to store your private key).
This API call is essentially the same as the one you tried in Tutorial 1, except that here you will need to provide a valid access token or your API call will be rejected.
Look at the code in the file routes/index.js in our sample client application and search for the following:
index.js is the backend (server side) code.
The code is creating the request to call the following API:
Note that this API is called using HTTPS GET.
The additional query parameters are as follows:
client_id
unique ID for your application. For our sample application, this is STG2-MYINFO-SELF-TEST
attributes
comma separated list of attributes requested. Possible attributes are listed in the Person object definition in the API specifications.
4.1 Providing the Access Token in the Request Header
The access token should be provided in the header of your API call under "Bearer".
You should see something like this in the onscreen logs:
Once this is done, you should see the person JSON in the onscreen logs that looks like this:
5. Use the JSON object to Prefill Form
If you have followed the steps above correctly, you should have gotten the Person JSON object. Now you can use this JSON object to prefill the form values in your application.
Look at the code in our sample client application and you will see it is using the response JSON to prefill the values on the application form. Once this is done, the user just needs to submit the form and your application can save the values into your database for subsequent processing.
Summary
You've successfully used the OAuth2 process to get the Person data from Myinfo sandbox environment.
Last updated
Was this helpful?