UNIMAS Official Wiki » Dashboard » HOW-TO, Tutorial & User Manual » UNIMAS Identity 2FA Developer Guides

UNIMAS Identity 2FA Developer Guides

Last modified by Mohd Razif Bin Baital @ Latif Razif on 2020/06/18 13:07

UNIMAS Identity 2FA Developer Guides

Table of content

1.    UNIMAS Identity 2FA 

   1.1  Enable 2FA in application (per-application) 

   1.2  Verify OTP using endpoints (per-transaction)

   1.3  Trigger OTP via SMS (per-transaction)  

   1.4  Trigger 2FA Setup page 

 

1.    UNIMAS Identity 2FA

1.1    Enable 2FA in application 

UNIMAS Identity 2FA can be enabled on per-application(client) basis and can be limited to only a certain role/authority.

  1. Login to UNIMAS Identity Dev Console at https://identity.unimas.my/admin 
  2. Navigate to Dev Console and click Edit on the application/client that you want to enable its 2FA 
  3. Navigate to 2FA tab and tick 'Enable 2-step verification (2FA)'. To limit the 2FA only on a certain role, fill in 'Limit 2-step verification..." field with the role/authority name separated by comma (ie: STAFF_GRP,CICTS_GRP) 
  4. Click Save Client button to finish the process 

Make sure to test that the 2FA is working properly as intended in your application.

1.2    Verify OTP with endpoint (per-transaction)

We can verify OTP via our OTP’s verification endpoints. This would be useful for per-transaction verification. You can prompt the user to key in the OTP and verify the OTP first via verify-tx endpoint before performing any secured transaction. The verify-tx endpoint will return a json with property ‘valid’ = true if the OTP is valid.

POST https://identity.unimas.my/2fa/verify-tx
Parameters

otp

(parameter)

6-digits OTP number to be verified

Example Value | number
 123456
Response
200OK

Value:
 {
    "valid":boolean,
    "user": "string",
    "timestamp": "string"
 
}
401Unauthorized

Implementation Example:

function doTransaction(){

 var otp = window.prompt("Enter OTP:", "");
    if (otp != null && otp != "") {
         $http.post("https://identity.unimas.my/2fa/verify-tx?otp="+otp,{})
         .then(function(res){
             if (res.data.valid){ // check the result
                  // perform secured transaction
              }else{
                  alert(res.data.message);
              }
          });
     }
 }

The endpoint required secured http request (with access token).

Example response (valid OTP):

{

 "valid": true,
    "user": "blmrazif",
    "timestamp": "2020-06-09T05:58:02.314+0000",
   "user": "blmrazif",
   "hasSetup": true,
   "message": "OTP code valid"

}

If the user has not done any 2FA Setup yet:

{
    "valid": false,
    "user": "blmrazif",
    "timestamp": "2020-06-09T05:58:02.314+0000",
   "user": "blmrazif",

 "hasSetup": false,

 "message_html": "User has yet done 2FA setup. 2FA setup can be done at <a   
                 href=\”https://identity.unimas.my/setup2fa\”
                target=\”_blank\”>https://identity.unimas.my/setup2fa</a>"
,
   "message": "User has yet done 2FA setup. 2FA setup can be done at 

                      https://identity.unimas.my/setup2fa",

}

1.3    Trigger OTP via SMS (for per-transaction 2FA)

Since the per-transaction 2FA requires implementation by the system developer, we also provide endpoints to request OTP via SMS.

POST https://identity.unimas.my/2fa/sms-otp
Parameters
<none>
Response
200OK

Value:
 {
    "otpSent": boolean,
    "success": boolean,
    "timestamp": "string"
 
}
401Unauthorized

The endpoint required secured http request (with access token).

Example response:

{
    "otpSent": true,
    "success": true,
    "timestamp": "2020-06-09T05:58:02.314+0000",
    "hasSetup": true,
   "message": "OTP sent via SMS"

}

Example of per-transaction 2FA implementation can be seen on ‘Reset 2FA’ features in UNIMAS Identity admin page. Basic implementation should have

  • One text input to receive OTP code. It is highly recommended to include clear instruction on what to do and where to get the code.
  • Options for user to receive OTP code in another way (ie: SMS). The endpoint to trigger sms-otp was mentioned above.
  • A button to perform the action. For popup, it is highly recommended to include button to close the dialog.
1.4    Trigger 2FA setup page

Unlike normal 2FA, per-transaction 2FA happen in stateless environment and doesn’t require dispatching to login page and 2FA setup page.

To trigger 2FA setup page, you may redirect your user to the following page:

https://identity.unimas.my/setup2fa

It is a 2FA-protected static page which will trigger 2FA setup if the user has not yet setup their 2FA

Tags:
Created by Mohd Razif Bin Baital @ Latif Razif on 2020/06/18 13:01

Start Here

Welcome to the UNIMAS WIKI.
To start, use search function by entering keywords in the search box below :
 

Quick Navigation

About UNIMAS

HOW-TO, Tutorial & User Manual

HOW-TO, Tutorial &amp; User Manual

Macros

Pekeliling

STB2242 - PLANT BIOTECHNOLOGY

Semester Registration

signatureattach

Recently Created

Recently Modified

My Recent Modifications


This wiki is licensed under a Creative Commons 2.0 license
XWiki Enterprise 5.0.3 - Documentation