Table of Contents

Article

Configuring two-factor authentication with a one-time password

Pega Platform™ supports two-factor authentication by sending a one-time password (OTP) to a user through email. The user must enter this one-time password in your Pega Platform application for verification.

Two-factor authentication is supported for the following use cases:

  • In custom authentication services
  • In case flows, to authenticate a user before critical transactions (such as a funds transfer in excess of a certain amount)

You can configure your Pega Platform application to use two-factor authentication by completing the following steps:

Configuring multifactor authentication policies

To control the behavior of two-factor authentication, configure the following settings on the Security Policies landing page.

  1. In the Designer Studio header, click Designer Studio > Org & Security > Authentication > Security Policies.
  2. In the Multi-factor authentication policies (using one-time password) section, configure the following required fields:
    1. In the Maximum one-time password failure attempts list, select a value between 1 and 3 to set the number of failed login attempts that your application allows before the one-time password becomes invalid and another one-time password must be generated. Setting a lower value helps prevent brute force attacks.
    2. In the Maximum age of one-time password token in seconds field, enter the length of time from when the token is generated to when the user must verify it with your application. The maximum age of the one-time password token must be less than the shortlived requestor timeout period, which is defined in minutes in the prconfig setting timeout/requestor/shortlived, and which defaults to 1 minute. If you set the maximum age to be greater than one minute, you must increase the timeout/requestor/shortlived setting.
    3. In the Validity of one-time password confirmation in minutes field, enter how long a user can work in a single session before being logged out.
    4. In the Email account from which one-time password needs to be sent field, press the Down Arrow key, and then select the name of an email account.
  3. Click Submit.

Generating a one-time password

The pxSendOTP activity generates a one-time password (a fixed-length, eight-digit number), sends it to pyEmailSettings.pyEmailAccount, and stores it in memory until it expires. It returns a Reference ID value that identifies a specific one-time password during later verification of a user entry by the pxVerifyOTP activity. Input parameters for this activity must be supplied in an instance of the Embed-OTPInputs class, which issupplied as the OTPInputs parameterin the activity.

You can generate a one-time password in the following ways:

  • By calling an activity – Choose this method to use a one-time password in an application that is running on Pega 7.3 or later.
  • By using APIs – Choose this method to use a one-time password from an external system or if your application is running on a Pega Platform version earlier than 7.3.

Generating a one-time password by calling an activity

  1. Create an activity. For more information about how to create an activity, see Creating an activity, Authentication Service form – Completing the Custom tab.
  2. On the Pages & Classes tab of the Activity form, define the page that passes the parameters to the pxSendOTP activity and an OperatorID page to access the Operator instance.
    1. In the Page name field, enter the name of the page that passes parameters to the activity (for example, OTPInputs).
    2. In the Class field, enter Embed-OTPInputs.
    3. Click the Plus icon to add a new parameter.
    4. In the Page name field, enter OperatorID.
    5. In the Class field, enter Data-Admin-Operator-ID.
  3. On the Steps tab, in the first step, create a page.
    1. In the Method list, press the Down Arrow key, and select Page-New.
    2. In the Step page field, enter the name of the previously defined page that passes the parameters (for example, OTPInputs).
  4. Add a second step to the activity to configure the page properties.
    1. In the Method field, click the Down Arrow key, and select Property-Set.
    2. In the Step page field, enter the name of the page that passes parameters to the activity (for example, OTPInputs).
    3. Click the Expand icon, and then provide the following name-value pairs in the PropertiesName and PropertiesValue field:
    • pyContext – Enter a description of the business context for which the one-time password is being generated.
    • pySendMode – Enter EMAIL. This method is to send the one-time password to the user.
    • pyEmailSettings.pyEmailAccount – Enter the email account that is used for outbound email messages.
    • pyEmailSettings.pyCorrName – Enter the correspondence name for the email message. The .pyOTP property must be inserted in the correspondence content. If no value is provided for this parameter, the default pyDefaultOTPCorr correspondence name that is in Work- class is used.
    • pyEmailSettings.pyToAddress – Enter the email address to which the one-time password should be sent.
    • pyEmailSettings.pySubject – Enter a subject line for the generated email message.
    • pyInputClass – Enter your application level work class so that you are able to refer to a correspondence rule that exists in your application level work class.
  5. Add a third step to the activity that calls the pxSendOTP activity.
    1. In the Method field, enter Call pxSendOTP.
    2. In the Step page field, enter OperatorID.
  6. Add a fourth step to the activity that reads the Reference ID.
    1. In the Method field, click the Down Arrow key, and select Property-Set.
    2. In the Step page field, enter the name of the OTPInputs page (for example, OTPInputs).
    3. Click the Expand icon, and then provide the following name-value pairs in the PropertiesName and PropertiesValue field:
      1. In the PropertiesName field, enter the name of the property that stores the Reference ID on the Primary page (for example, Primary.OTPRefID).
      2. In the PropertiesValue field, enter .pyReferenceID.
  7. Click Save.

Generating a one-time password by calling an API

  1. Create a REST Connector by using the REST integration wizard. For more information about how to configure the connector, see Creating REST integration.
  2. In the Endpoint URL field, enter the authenticate/one-time password web service on your server instance, for example, https://localhost:9090/prweb/PRRestService/api/v1/authenticate/otp/email
  3. Select the POST method to invoke the external REST service.
  4. In the Add a REST response dialog box, in the Content type list, select JSON.
  5. For the response, enter the following text:

    {

    "Context": "Test 126",

    "EmailSettings": {

    "CorrespondenceName": "pyDefaultOTPCorr",

    "EmailAccount": "Default",

    "Subject": "OTP New",

    "ToAddress": "userid@sampledomain.com"

    }

    }

  6. Click Save.

Verifying a one-time password

The pxVerifyOTP activity takes as inputs a reference to a previously generated one-time password and a user entry, and verifies that the previously generated one-time password has not expired and matches the user entry.

Input parameters for this activity must be supplied in an instance of the Embed-OTPInputs class, which is supplied as the OTPInputs parameter in the activity

You can verify a one-time password in the following ways:​

  • By calling an activity – Choose this method to verify a one-time password in an application that is running on Pega 7.3 or later.
  • By using APIs – Choose this method to verify a one-time password from an external system or if your application is running on a Pega Platform version earlier than 7.3.

Verifying a one-time password by calling an activity

  1. Create an activity. For more information about how to create an activity, see Creating an activityAuthentication Service form – Completing the Custom tab.
  2. On the Pages & Classes tab of the Activity form, define a page that passes the parameters to the pxVerifyOTP activity and an OperatorID page that accesses the Operator instance.
    1. In the Page name field, enter the name of the page that passes the parameters to the activity (for example, OTPInputs).
    2. In the Class field, enter Embed-OTPInputs.
    3. Click the Plus icon to add a new parameter.
    4. In the Page name field, enter OperatorID.
    5. In the Class field, enter Data-Admin-Operator-ID.
  3. On the Steps tab, in the first step, create a page.
    1. In the Method list, press the Down Arrow key, and select Page-New.
    2. In the Step page field, enter the name of the page that passes parameters to the activity (for example, OTPInputs).
  4. Add a second step to the activity to configures the properties of the page.
    1. In the Method field, press the Down Arrow key, and select Property-Set.
    2. In the Step page field, enter the name of the page that passes parameters to the activity (for example, OTPInputs).
    3. Click the Expand icon, and then provide the following name-value pairs in the PropertiesName and PropertiesValue field:
    • pyReferenceID – Enter the Reference ID returned by the pxSendOTP activity when it generated the one-time password.
    • pyOTPValue – Enter the one-time password value entered by the user.
  5. Add a third step to the activity that calls the pxVerifyOTP activity.
    1. In the Method field, enter Call pxVerifyOTP.
    2. In the Step page field, enter OperatorID.
  6. Add a fourth step to the activity that reads the Reference ID.
    1. In the Method field, press the Down Arrow key, and select Property-Set.
    2. In the Step page field, enter the name of the OTPInputs page (for example, OTPInputs).
    3. Click the Expand icon, and then provide the following name-value pairs in the PropertiesName and PropertiesValue field:
      1. In the PropertiesName field, enter Primary.OTPStatus.
      2. In the PropertiesValue field, enter .pyOTPStatus.
      3. Click the Add item icon to add another parameter.
      4. Enter the parameter, in the PropertiesName field, enter Primary.OTPStatusMessage.
      5. In the PropertiesValue field, enter .pyOTPStatusMessage.
    4. Click Save.

Verifying a one-time password by calling a REST API

  1. Create a REST Connector by using the REST integration wizard. For more information about how to configure the connector, see Creating REST integration.
  2. In the Endpoint URL field, enter the authenticate/one-time password web service on your server instance, for example, https://localhost:9090/prweb/PRRestService/api/v1/authenticate/otp/verify
  3. Select the GET method to invoke the external REST service.
  4. Click Override to add query parameters.
  5. Enter the Reference ID and OTPValue parameters. The Reference ID is returned by the pxSendOTP activity, while the OTPValue is the one-time password entered by the user.
  6. Add a REST service, and enter query string parameter values for the Reference ID and OTPValue parameters.
  7. Click Submit.

Published October 26, 2017 — Updated March 22, 2019


50% found this useful

Related Content

Have a question? Get answers now.

Visit the Pega Support Community to ask questions, engage in discussions, and help others.