9 OTP Anywhere

9.2.1 Create a Challenge Processor

To implement a challenge processor, you will need to extend the following class:

com.bharosa.uio.processor.challenge.AbstractChallengeProcessor 

Later, you will compile the code by adding oaam.jar from $ORACLE_IDM_HOME\oaam\cli\lib folder to the build classpath.

Methods to Implement

A few methods to implement a challenge processor is shown as follows:

protected boolean generateSecret(UIOSessionData sessionData, boolean isRetry) to generate code to send to client

protected boolean validateAnswer(UIOSessionData sessionData, String answer) to validate the user answer

public String checkDeliveryStatus(UIOSessionData sessionData, boolean userWaiting, boolean isRetry) if you want to provide wait until message is sent

public boolean isServiceAvailable(UIOSessionData sessionData) to check if external service is available

Example

An example of implementing a challenge processor is shown as follows:

package oracle.oaam.challenge.processor.challenge;
 
import com.bharosa.common.util.*;
import com.bharosa.uio.util.UIOUtil;
import com.bharosa.uio.util.UIOSessionData;
 
import com.bharosa.common.logger.Logger;
 
import java.io.Serializable;
 
/**
 * Email Challenge Processor - provides OTP Code generation, delivery and validation
 */
public class EmailChallengeProcessor extends com.bharosa.uio.processor.challenge.AbstractOTPChallengeProcessor implements Serializable{
 
  static Logger logger = Logger.getLogger(EmailChallengeProcessor.class);
 
  public EmailChallengeProcessor( ) {
  }
 
  /**
   * Generates OTP Code and stores it in sessionData
   * 
   * @param sessionData data object available for the session
   * @param isRetry boolean value if method was called as a result of a failed answer attempt
   * @return 
   */
  protected boolean generateSecret(UIOSessionData sessionData, boolean isRety) {
   String otpCode = sessionData.getOTPCode(); 
 
// If no secret code is present in session, generate one.
    if (StringUtil.isEmpty(otpCode)) {
      if (logger.isDebugEnabled())
        logger.debug("ChallengeEmail generating security code for user: " +
                     sessionData.getCustomerId());
      otpCode = generateCode(sessionData);
 
      // save the code for later reference - validate / resend
      sessionData.setOTPCode(otpCode);
    }
 
    if (logger.isDebugEnabled())
      logger.debug("OTP code for user " + sessionData.getCustomerId() + " : " + otpCode);
 
    if (StringUtil.isEmpty(otpCode)) {
      logger.error("Email Challenge pin generation returned null.");
      return false;
    }
        // isRetry flag is turned on if user fails to answer the question
    if (!isRetry) {       
      return sendCode(sessionData);
    }
    
    return true;
  }
 
  /**
   * Validate user entered answer against value in sessionData
   * 
   * @param sessionData validate code and return result.
   * @param answer answer provided by the user
   * @return
   */
  protected boolean validateAnswer(UIOSessionData sessionData, String answer){
    //need to authenticate OTP Code
    String otpCode = sessionData.getOTPCode();
    
    if (otpCode != null && otpCode.equals(answer)) {
      // Expire OTP Code
      sessionData.setOTPCode(null);
      return true;
    }
    
    return false;
  }
 
  /**
   * Private methods to send secret code to client
   * 
   * @param sessionData
   * @return
   */
  private boolean sendCode(UIOSessionData sessionData){
    String otpCode = sessionData.getOTPCode();
 
    try {
      // UIOUtil.getOTPContactInfo fetches the information registered by the user. Refer to ChallengeEmail.requiredInfo in configuration.
      String toAddr = UIOUtil.getOTPContactInfo(sessionData, "email");
      if (StringUtil.isEmpty(toAddr)) {
        logger.error("No user email in profile.");
         return false;  
      }
 
      // Send secret code to customer using your email provider
 
    } catch (Exception ex) {
        logger.error("ChallengeEmail Error sending code.", ex);
        return false;
    }
    
    return true;
  }
  
  public String checkStatus(UIOSessionData sessionData, boolean userWaiting, boolean isRetry) {
    String target = ChallengeProcessorIntf.TARGET_WAIT;
    // user already has code, trying again - send to challenge page
    if (isRetry){ 
      return ChallengeProcessorIntf.TARGET_CHALLENGE;
    }
    
    boolean sendComplete = false;
    if (userWaiting){
      // if secret code is sent set target to 
      target = ChallengeProcessorIntf.TARGET_CHALLENGE;
      // failed to send
      target = ChallengeProcessorIntf.TARGET_ERROR;
      // still processing    
      target = ChallengeProcessorIntf.TARGET_WAIT;   
    }    
    return target;
  }
}

9.2.2 Configure Custom Challenge Processor as Challenge Type with Required Profile Data

Challenge types are configured by the enum, "challenge.type.enum". The actual enum value is shown as follows:

bharosa.uio.<application>. challenge.type.enum.<challenge type>

Example for Defining an OTP Type

Configure the bharosa.uio.default.challenge.type.enum property to edit out of the box OTP challenge types or add a new challenge type.

Here is an example for defining an OTP type:

bharosa.uio.default.challenge.type.enum.MyChallenge

In the example, the "default" is the UIO application name, and "MyChallenge" is challenge Type being newly added

To enable/disable a challenge type, the available flag should be set (not the enable flag, that would remove it from list)

Attributes of the enum with example values is shown as follows:

bharosa.uio.default.challenge.type.enum.MyChallenge = 1  // unique value to identify Challenge Email in bharosa.uio.default.challenge.type.enum

bharosa.uio.default.challenge.type.enum.MyChallenge.name = MyChallenge //  unique string to identify Challenge Email in bharosa.uio.default.challenge.type.enum, no spaces

bharosa.uio.default.challenge.type.enum.MyChallenge.description = Email Challenge // descriptive name

bharosa.uio.default.challenge.type.enum.MyChallenge.processor = oracle.oaam.challenge.processor.challenge.EmailChallengeProcessor  // Processor used for sending emails instance of com.bharosa.uio.processor.challenge.ChallengeProcessorIntf

bharosa.uio.default.challenge.type.enum.MyChallenge.requiredInfo = email  // comma separated field names, User registration flow captures these data fields, check Contact information Inputs section to define this enum

bharosa.uio.default.challenge.type.enum.MyChallenge.available = false // to turn off this service

bharosa.uio.default.challenge.type.enum.MyChallenge.otp = true // indicates this challenge is used for OTP, set it to true

Email Example

bharosa.uio.default.challenge.type.enum.ChallengeEmail = 1
bharosa.uio.default.challenge.type.enum.ChallengeEmail.name = Email Challenge
bharosa.uio.default.challenge.type.enum.ChallengeEmail.description = Email Challenge
bharosa.uio.default.challenge.type.enum.ChallengeEmail.processor =
com.bharosa.uio.processor.challenge.EmailChallengeProcessor
bharosa.uio.default.challenge.type.enum.ChallengeEmail.requiredInfo = mobile
bharosa.uio.default.challenge.type.enum.ChallengeEmail.available = true
bharosa.uio.default.challenge.type.enum.ChallengeEmail.enabled = true

SMS Example

bharosa.uio.default.challenge.type.enum.ChallengeSMS = 2
bharosa.uio.default.challenge.type.enum.ChallengeSMS.name = SMS Challenge
bharosa.uio.default.challenge.type.enum.ChallengeSMS.description = SMS Challenge
bharosa.uio.default.challenge.type.enum.ChallengeSMS.processor =
com.bharosa.uio.processor.challenge.SmsChallengeProcessor
bharosa.uio.default.challenge.type.enum.ChallengeSMS.requiredInfo = mobile
bharosa.uio.default.challenge.type.enum.ChallengeSMS.available = true
bharosa.uio.default.challenge.type.enum.ChallengeSMS.enabled = true

9.4.1 Configuration Settings for Information Registration and Preferences and PIN Generation

Default configurations for settings for registration of information, preference, and PIN generation are listed as follows:

Contact information registration

bharosa.uio.default.register.userinfo.enabled=false

Contact information preferences

bharosa.uio.default.userpreferences.userinfo.enabled=false

OTP PIN Generation

# Length of the Pin
bharosa.uio.otp.generate.code.length = 5
# Characters to use when generating the Pin
bharosa.uio.otp.generate.code.characters = 1234567890

The AbstractOTPChallengeProcessor class has a default pin generation method, generateCode, that you can override to provide your pin generation logic.

9.4.2 Set Contact Information Inputs

Contact information inputs are defined in userinfo.inputs.enum. The enum element is:

bharosa.uio.<application>.userinfo.inputs.enum.<inputname>

Example

bharosa.uio.default.userinfo.inputs.enum.email=1
bharosa.uio.default.userinfo.inputs.enum.email.name=Email Address
bharosa.uio.default.userinfo.inputs.enum.email.description=Email Address
bharosa.uio.default.userinfo.inputs.enum.email.inputname=email
bharosa.uio.default.userinfo.inputs.enum.email.inputtype=text
bharosa.uio.default.userinfo.inputs.enum.email.maxlength=40
bharosa.uio.default.userinfo.inputs.enum.email.required=true
bharosa.uio.default.userinfo.inputs.enum.email.order=2
bharosa.uio.default.userinfo.inputs.enum.email.enabled=true
bharosa.uio.default.userinfo.inputs.enum.email.regex=.+@[a-zA-Z_]+?\\.[a-zA-Z]{2,3}
bharosa.uio.default.userinfo.inputs.enum.email.errorCode=otp.invalid.email
bharosa.uio.default.userinfo.inputs.enum.email.managerClass=com.bharosa.uio.manager.user.DefaultContactInfoManager

9.4.3 SMS Configuration to Receive OTP via SMS

For OTP to be receive via SMS, you must:

• Enable Registration and Preference Setting

• Set Input Information

bharosa.uio.default.userinfo.inputs.enum

bharosa.uio.default.userinfo.inputs.enum.mobile=0
bharosa.uio.default.userinfo.inputs.enum.mobile.name=Mobile Phone
bharosa.uio.default.userinfo.inputs.enum.mobile.description=Mobile Phone
bharosa.uio.default.userinfo.inputs.enum.mobile.inputname=cellnumber
bharosa.uio.default.userinfo.inputs.enum.mobile.inputtype=text
bharosa.uio.default.userinfo.inputs.enum.mobile.maxlength=15
bharosa.uio.default.userinfo.inputs.enum.mobile.required=true
bharosa.uio.default.userinfo.inputs.enum.mobile.order=1
bharosa.uio.default.userinfo.inputs.enum.mobile.enabled=true