How to configure two factor authentication - pegasystems/uplus-wss GitHub Wiki

Introduction

To provide support for two-factor authentication, we rely on the Pega Platform to generate a One Time Password (OTP) that will be requested through the DX API v1 using the authenticate/ODP endpoint. This endpoint supports two options to send the OTP to the user, through email or SMS. Once the user enters the OTP in the Uplus application, the OTP is validated using the 2nd endpoint. image

Configuring 2-factor authentication

Two factor authentication can be configured for the Uplus application through the 'General' category under the settings tab. set the server based URL - make sure that it does not contain other path like '/prweb'. The server base url will be used to generate the url of the rest endpoint used for the OTP

Set the sendmode as email or sms. Note that sms requires some additional customization on the Pega Platform and is harder to setup than email notification. image

To use email notification, create a new email account under integration-resources - in the screenshot above, the email account is called TestOTP. Make sure that the account is configured for outbound emails. The ruleset of the email account needs to be accessible to the user that will be authenticated. Make sure to store the instance in the same ruleset as the application used by the user.

To send the email to your account, you will need to set the OTP send to field - this field is configured under the Users category and will accept an email (if the sendmode is set to email) or a phone number (if the sendmode is set to sms). The OTP send to field is configured for each user. image

If the DX API for the authenticate/ODP endpoint fails, it is likely that the pega username and pega password is incorrect. When calling this api, these 2 parameters are sent using basic authentication.

After turning on this feature and entering the username password, the login overlay will ask for the OTP image

This feature is also implemented on the phone version of the Uplus app either through the overlay or in the full login page. image

Sending one-time password using Twilio SMS

There is unfortunately no extension point when using the sendMode to 'sms' to hook up with other SMS provider - the only provider supported in the Amazon SNS when creating an SMS account. If you have an account on Twilio, you can override the pxSendSMS activity to use the SMS through Twilio. There is a RAP in the wiki folder on github that you can import into your application - see Twilio RAP. The RAP contains the pxSendSMS activity and a starting point o the REST service connector to connect to Twilio - you will need to create an auth profile in your application (see REST Connect rule and the auth profile TwilioAuth) as well as set the originator phone number in one of the post parameter (set to 1111111) - To test, you can run the pxSendSMS and provide the To phone number and the message.

Note: Special thanks to Piotr Koszela for implementing the two-factor authentication feature and providing a detailed branch with the changes.