16 Implementing OTP Anywhere

This chapter explains how to implement OTP Anywhere. OTP Anywhere allows end users to authenticate themselves by entering a server generated one-time-password (OTP). When the OTP is sent through SMS, the user's cell phone serves as a physical second factor that the user has in their possession. As well, the authentication is being sent out-of-band to increase the level of assurance that only the valid user has access to the one-time password.

This chapter contains the following sections:

16.1 About the OTP Implementation

One-Time Password (OTP) is a form of secondary authentication, which is used in addition to standard user name and password credentials to strengthen the existing authentication and authorization process, thereby providing additional security for users. The application sends a one-time password that is only valid for the current session to the user. The system uses this password to challenge the user to verify identity.

Oracle Adaptive Access Manager 11g provides the framework to support One Time Password (OTP) authentication using Oracle User Messaging Service (UMS). This implementation enables an application to use OTP to challenge users with Oracle User Messaging Service (UMS) used as the method to deliver the password.

Benefits of OTP Anywhere are:

  • It is built on 11g Challenge Processor framework

  • Out of the box integration with Oracle User Messaging Service

  • Customizable registration user interface

  • Optional Opt-Out functionality

  • Email and SMS supported delivery channels

16.2 Concepts and Terms

This section provides key definitions, acronyms, and abbreviations that are related to OTP Anywhere Implementation.

Table 16-1 OTP Anywhere Terms

Term Description

One Time Password (OTP)

One Time Password (OTP) is used to authenticate an individual based on a single-use alphanumeric credential. The OTP is delivered to the user's configured delivery method. The user then provides the OTP credential as the response to proceed with the operation. The following are major benefits of using out-of-band OTP:

  • If the end user's browser/internet is compromised, the authentication can safely take place in another band of communication separate from the browser

  • The user does not require any proprietary hardware or client software of any kind.

Oracle User Messaging Service (UMS)

The Oracle User Messaging Service is a facility installed in the SOA Domain during installation of the SOA Suite. The Oracle User Messaging Service enables two-way communication between users and deployed applications. The communication can be through various channels, including email, instant messaging (IM or Chat), and SMS. OAAM uses Oracle User Messaging Service as a means of communicating with the user.

Challenge Processor

A challenge processor is java code that implements the ChallengeProcessorIntf interface or extends the AbstractChallengeProcessor class. Custom challenge processors can be created to generate a challenge, validate the challenge answer from the user, and check service delivery and availability statuses. By default OAAM has support (or challenge processor implementations) for KBA question challenges and OTP challenges through SMS and email through Oracle User Messaging Service delivery.

Challenge Type

"Channel" refers to the delivery channel used to send an OTP to the user (Email, SMS, or IM). The challenge type is the channel that OTP is using to challenge the user. You can configure a challenge type for any differences in handling for a challenge that is required. Handling of challenge types could be any specifics for that challenge type, from generating the "secret" used for the challenge to delivering the "secret" to the user and finally validating the users input. For each type of challenge these primary processes (Generation, Sending, and Validating) could require slightly different code.


16.3 Prerequisites

Ensure that the following prerequisites are met before configuring OTP for your application.

Note:

Ensure you are familiar with deploying custom OAAM extensions.

Oracle Adaptive Access Manager is customized through adding customized JAR files and other files to an extensions shared library.

For information on adding customized JAR files and other files, see Chapter 7, "Using the OAAM Extensions Shared Library to Customize OAAM."

16.3.1 Install SOA Suite

Before you can configure the Oracle User Messaging Service (UMS) driver and OTP, you must have installed the SOA Suite 11g, configured the SOA Domain and have the Admin Server and the SOA Server running. You also need access to the Oracle Enterprise Manager Fusion Middleware Control Console.

For information on installing the SOA Suite 11g, see Oracle Fusion Middleware Installation Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

16.3.2 Configure the Oracle User Messaging Service Driver

The User Messaging Service comes with some drivers that each handle traffic for a specific channel. The drivers control the channels and need to be configured with the properties of the appropriate delivery server, protocol, and so on from which messages are sent. The OAAM Server will be set up for the channels.

Drivers can be deployed or undeployed independently of one another depending on what messaging channels are available in a given installation.

Go to the Oracle Enterprise Manager Fusion Middleware Control Console (typically http://host:7001/em) and open the User Messaging Service node. From the drop down menu in the right panel, select the option for the driver properties. For example, choose Email Driver Properties. The form that is shown enables you to set various properties on the driver, including the details about the server (or protocol, and so on) to be used by the driver for the operations. For example, you might enter details about the email server to be used by the driver for email operations.

16.3.2.1 Email Driver

Configure the Email driver to a SMTP server. For information on configuring the Email driver, see Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

Table 16-2 Connecting to the SMTP Server

Parameter Description

OutgoingMailServer

Mandatory if email sending is required. For example, smtp.name.com for name.

OutgoingMailServerPort

Port number of SMTP server.

OutgoingMailServerSecurity

Possible values are TLS and SSL.

OutgoingDefaultFromAddress (optional)

The email address that is indicated as the sender of the email message.

OutgoingUsername

The user account from which the email is sent.

OutgoingPassword

The account's password (stored in encrypted format).


Press Apply. To have these settings take effect, the driver has to be restarted.

16.3.2.2 SMPP Driver

Short Message Peer-to-Peer (SMPP) is one of the most popular GSM SMS protocols. User Messaging Service includes a prebuilt implementation of the SMPP protocol as a driver that is capable of both sending and receiving short messages.

Note:

For SMS, unlike the Email driver that is deployed out-of-the-box, you must deploy the SMPP driver first before modifying the configurations.

Configure the SMPP driver as described in the "Configuring the SMPP Driver" section of the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite. You will need to provide parameter values for connecting to the driver gateway vendor.

Table 16-3 Connecting to the Vendor

Parameter Description

SmsAccountId

The Account Identifier on the SMS-C. This is your vendor account ID which you must get from the vendor.

SmsServerHost

The name (or IP address) of the SMS-C server. TransmitterSystemId

TransmitterSystemPassword

The password of the transmitter system. This includes Type of Password (choose from Indirect Password/Create New User, Indirect Password/Use Existing User, and Use Cleartext Password) and Password. This is the password corresponding to your vendor account ID

TransmitterSystemType

The type of transmitter system. The default is Logica.

ReceiverSystemId

The account ID used to receive messages. ReceiverSystemPassword

ReceiverSystemType

The type of receiver system. The default is Logica.

ServerTransmitterPort

The TCP port number of the transmitter server.

ServerReceiverPort

The TCP port number of the receiver server.

DefaultEncoding

The default encoding of the SMPP driver. The default is IA5. Choose from the drop-down list: IA5, UCS2, and GSM_DEFAULT.

DefaultSenderAddress

Default sender address


After providing the parameter values, press Apply. To have these settings take effect, the driver has to be restarted.

16.4 OTP Setup

OTP using Oracle User Messaging Service (UMS) as a delivery method is a standard feature of the OAAM Server. This section contains an overview of the steps required to implement the feature.

Follow the instructions for customizing the OAAM server interface through adding customized JAR files and other files to an extensions shared library. For information on customizing the OAAM server interface, see Chapter 7, "Using the OAAM Extensions Shared Library to Customize OAAM."

The Oracle User Messaging Service (UMS) and OTP implementation is integrated into the OAAM Server login, challenge, and registration flows using the OAAM Server challenge processor framework. For information on the login, challenge, and registration flows, see Chapter 2, "Natively Integrating Oracle Adaptive Access Manager."

16.5 Configure OTP

This section contains the following topics:

16.5.1 Integrate Oracle User Messaging Service

The properties to set for the Oracle User Messaging Service (UMS) server URLs and credentials are listed in Table 16-5. They can be edited using the Property Editor in OAAM Admin. Note: End point is the Web Services URL that OAAM uses to send calls into Oracle User Messaging Service.

Table 16-5 Oracle User Messaging Service Server URLs and Credentials

Property Default Value Description

bharosa.uio.default.ums.integration.webservice

 

UMS Server Webservice URL

http://UMS_Server_URL:

UMS_Port/

ucs/messaging/webservice

bharosa.uio.default.ums.integration.parlayx.endpoint

 

UMS Server ParlayX Endpoint URL

http://UMS_Server_URL:UMS_Port/

sdpmessaging/parlayx/

SendMessageService

bharosa.uio.default.ums.integration.useParlayX

false

Configures the use of webservice or parlayx API. The value is false by default (Webservices recommended)

bharosa.uio.default.ums.integration.userName

 

Username for Oracle User Messaging Service server

bharosa.uio.default.ums.integration.password

 

Password for Oracle User Messaging Service server

bharosa.uio.default.ums.integtaion.policies

 

Oracle User Messaging Service authentication policies

bharosa.uio.default.ums.integration.fromAddress

demo@oracle.com

OAAM from address for OTP messages

bharosa.uio.default.ums.integration.message.status.poll.attempts

3

Number of times to attempt status poll each time the wait page is displayed

bharosa.uio.default.ums.integration.message.status.poll.delay

1000

Delay between status polls while the wait page is being displayed

bharosa.uio.default.ums.integration.sleepInterval

10000

 

bharosa.uio.default.ums.integration.deliveryPage.delay

3000

 

After you set up the Oracle User Messaging Service server properties, restart the application.

16.5.2 Enable OTP Challenge Types

Enable challenge types by setting the appropriate property to true. By setting the property to true, policies will be able to challenge using OTP through the challenge type (email, SMS, or IM). The user will see the email, SMS, or IM page in registration flow.

You use the challenge type enum to associate a Challenge Type with the Java code needed to perform any work related to that challenge type. The Challenge Type ID (ChallengeEmail) should match a rule action returned by the rules when that challenge type is going to be used.

Table 16-6 Oracle User Messaging Service OTP challenge types

Property Default Value Description

bharosa.uio.default.challenge.type.enum.ChallengeEmail.available

false

Availability flag for email challenge type

bharosa.uio.default.challenge.type.enum.ChallengeSMS.available

false

Availability flag for SMS challenge type

bharosa.uio.default.challenge.type.enum.ChallengeIM.available

false

Availability flag for instant message challenge type


16.5.3 Enable Registration and User Preferences

Enable the registration flow and user preferences by setting these properties to true:

Table 16-7 Enable OTP Profile Registration and Preference Setting

Property Description

bharosa.uio.default.register.userinfo.enabled

Setting the property to true enables the profile registration pages if the OTP channel is enabled and requires registration.

bharosa.uio.default.userpreferences.userinfo.enabled

Setting the property to true enables the user to set preferences if the OTP channel is enabled and allows preference setting.

User Preferences is a page that allows the user to change their image/phrase, challenge questions, un-register devices, and update their OTP profile.


16.6 Customize OTP

This section contains the following topics:

16.6.1 Customize Registration Fields and Validations

Mobile registration field definitions and validations for the OTP registration page are shown in Table 16-8.

Add Mobile Input Registration Field Properties to oaam_custom.properties

These properties should be added to oaam_custom.properties.

Table 16-8 Mobile Input - Properties File

Property Default Value Description

bharosa.uio.default.userinfo.inputs.enum.mobile

0

Mobile phone enum value

bharosa.uio.default.userinfo.inputs.enum.mobile.name

Mobile Phone

Name for mobile phone field

bharosa.uio.default.userinfo.inputs.enum.mobile.description

Mobile Phone

Description for mobile phone field

bharosa.uio.default.userinfo.inputs.enum.mobile.inputname

cell number

HTML input name for mobile phone field

bharosa.uio.default.userinfo.inputs.enum.mobile.inputtype

text

HTML input type for mobile phone field

bharosa.uio.default.userinfo.inputs.enum.mobile.maxlength

15

HTML input max length for mobile phone field

bharosa.uio.default.userinfo.inputs.enum.mobile.required

true

Required flag for mobile phone field during registration and user preferences

bharosa.uio.default.userinfo.inputs.enum.mobile.order

1

Order on the page for mobile phone field

bharosa.uio.default.userinfo.inputs.enum.mobile.enabled

true

Enabled flag for mobile phone enum item

bharosa.uio.default.userinfo.inputs.enum.mobile.regex

\\D?(\\d{3})

\\D?\\D?

(\\d{3})\\D?(\\d{4})

Regular expression for validation of mobile phone field

bharosa.uio.default.userinfo.inputs.enum.mobile.errorCode

otp.invalid.mobile

Error code to get error message from if validation of mobile phone entry fails

bharosa.uio.default.userinfo.inputs.enum.mobile.managerClass

com.bharosa.uio.manager.user.DefaultContactInfoManager

Java class to use to save / retrieve mobile phone from data storage


Add Mobile Input Registration Field Properties to client_resource.properties

These properties should be added to the resource bundle.

Table 16-9 Mobile Input - Resource Bundle

Property Default Value Description

bharosa.uio.default.userinfo.inputs.enum.mobile.name

Mobile Phone

Name for mobile phone field

bharosa.uio.default.userinfo.inputs.enum.mobile.description

Mobile Phone

Description for mobile phone field


16.6.2 Customize Terms and Conditions

The following examples show term and conditions definitions for the OTP registration page.

Add Terms and Conditions Definitions to oaam_custom.properties

These properties should be added to oaam_custom.properties.

Table 16-10 Terms and Conditions Checkbox

Property Default Value Description

bharosa.uio.default.userinfo.inputs.enum.terms

4

Terms and Conditions enum value

bharosa.uio.default.userinfo.inputs.enum.terms.name

Terms and Conditions

Name for Terms and Conditions checkbox

bharosa.uio.default.userinfo.inputs.enum.terms.description

Terms and Conditions

Description for Terms and Conditions checkbox

bharosa.uio.default.userinfo.inputs.enum.terms.inputname

terms

HTML input name for Terms and Conditions checkbox

bharosa.uio.default.userinfo.inputs.enum.terms.inputtype

checkbox

HTML input type for Terms and Conditions checkbox

bharosa.uio.default.userinfo.inputs.enum.terms.values

true

Required values for Term and Conditions checkbox during registration and user preferences

bharosa.uio.default.userinfo.inputs.enum.terms.maxlength

40

HTML input max length for Terms and Conditions checkbox

bharosa.uio.default.userinfo.inputs.enum.terms.required

true

Required flag for Term and Conditions checkbox during registration and user preferences

bharosa.uio.default.userinfo.inputs.enum.terms.order

5

Order on the page for Terms and Conditions checkbox

bharosa.uio.default.userinfo.inputs.enum.terms.enabled

true

Enabled flag for Terms and Conditions enum item

bharosa.uio.default.userinfo.inputs.enum.terms.regex

.+

Regular expression for validation of Terms and Conditions checkbox

bharosa.uio.default.userinfo.inputs.enum.terms.errorCode

otp.invalid.terms

Error code to get error message from if validation of Terms and Conditions fails

bharosa.uio.default.userinfo.inputs.enum.terms.managerClass

com.bharosa.uio.manager.user.DefaultContactInfoManager

Java class to use to save / retrieve Terms and Conditions from data storage


Add Terms and Conditions Definitions to client_resource.properties

Default messaging for Terms and Conditions is defined by these resource bundle values:

Table 16-11 Messaging of Terms and Conditions

Property Descriptions

bharosa.uio.default.userinfo.inputs.enum.terms.name

I agree to the [ENTER COMPANY OR SERVICE NAME HERE] terms & conditions. Click to view full <a href="javascript:infoWindow('terms');">Terms & Conditions</a> and <a href="javascript:infoWindow('privacy');">Privacy Policy</a>.

bharosa.uio.default.userinfo.inputs.enum.terms.description

Message and Data Rates May Apply. <br/>For help or information on this program send "HELP" to [ENTER SHORT/LONG CODE HERE]. <br/>To cancel your plan, send "STOP" to [ENTER SHORT/LONG CODE HERE] at anytime.<br/><br/>For additional information on this service please go to <a href="" target="_blank">[ENTER INFORMATIONAL URL HERE]</a>.<br/><br/><b>Supported Carriers:</b><br/>AT&T, Sprint, Nextel, Boost, Verizon Wireless, U.S. Cellular&reg;, T-Mobile&reg;, Cellular One Dobson, Cincinnati Bell, Alltel, Virgin Mobile USA, Cellular South, Unicel, Centennial and Ntelos


The value for bharosa.uio.default.userinfo.inputs.enum.terms.name includes placeholder links that use OAAM Server popup messaging for "Terms & Conditions" and "Privacy Policy". The property and resource keys for the contents of the popups are listed as follows.

Table 16-12 Terms & Conditions and Privacy Policy Popup Messaging

Property Descriptions

bharosa.uio.default.messages.enum.terms.name

Terms and Conditions

bharosa.uio.default.messages.enum.terms.description

PLACEHOLDER TEXT FOR TERMS AND CONDITIONS

bharosa.uio.default.messages.enum.privacy.name

Privacy Policy

bharosa.uio.default.messages.enum.privacy.description

PLACEHOLDER TEXT FOR PRIVACY POLICY


16.6.3 Customize Registration Page Messaging

Add registration properties to client_resource.properties.

Table 16-13 Registration Resource Bundle

Property Default Value

bharosa.uio.default.register.userinfo.title

OTP Anywhere Registration

bharosa.uio.default.register.userinfo.message

For your protection please enter your mobile telephone number so we may use it to verify your identity in the future. Please ensure that you have text messaging enabled on your phone.

bharosa.uio.default.register.userinfo.registerdevice.message

Check to register the device that you are currently using as a safe device:

bharosa.uio.default.register.userinfo.continue.button

Continue

bharosa.uio.default.register.userinfo.decline.message

If you decline you will not be asked to register again.

bharosa.uio.default.register.userinfo.decline.button

Decline


Decline Button

To control the presence of the Decline button on the profile registration pages, set the following properties:

bharosa.uio.default.register.userinfo.decline.enabled = true

bharosa.uio.default.userpreferences.userinfo.decline.enabled = true

Note:

Even if these are true, the button will not show if the Opt Out property is false.

When the Decline button is enabled, the user will have another option on the OTP registration page that will allow him to Opt out of OTP challenges. He will not be asked to register OTP again, and will not receive OTP challenges. However, if a Customer Care OTP Profile reset is performed (or reset all) the user will have the opportunity to register OTP again.

Also, even if the user has opted out of OTP, he can access the OTP page in User Preferences and add information and click Continue. This will remove the OTP out flag and the user will now be registered for OTP.

16.6.4 Customize Challenge Page Messaging

Add challenge type fields to client_resource.properties.

Table 16-14 Challenge Type Resource Bundle Items

Property Default Value

bharosa.uio.default.ChallengeSMS.message

For your protection please enter the code we just sent to your mobile telephone. If you did not receive a code please ensure that text messaging is enabled on your phone and click the resend link below.

bharosa.uio.default.ChallengeSMS.registerdevice.message

Check to register the device that you are currently using as a safe device:

bharosa.uio.default.ChallengeSMS.continue.button

Continue


16.6.5 Customize OTP Message Text

Add OTP message fields to client_resource.properties.

Table 16-15 Challenge Type Resource Bundle Items

Property Default Value

bharosa.uio.default.ChallengeSMS.incorrect.message

Incorrect OTP. Please try again.

bharosa.uio.default.ChallengeSMS.message.subject

Oracle OTP Code

bharosa.uio.default.ChallengeSMS.message.body

Your Oracle SMS OTP Code is: {0}


16.6.6 Enable Opt Out Functionality

This feature is disabled by default. To enable Opt Out for the user, set the property to true.

Table 16-16 OTP opt-out properties

Property Default Value

bharosa.uio.default.otp.optOut.enabled

false

bharosa.uio.default.otp.optOut.managerClass

com.bharosa.uio.manager.user.DefaultContactInfoManager


16.7 Register SMS Processor to Perform Work for Challenge Type

You use the challenge type enum to associate a Challenge Type with the Java code needed to perform any work related to that challenge type. The Challenge Type ID (ChallengeEmail) should match a rule action returned by the rules when that challenge type is going to be used. "Channel" typically refers to the delivery channel used to send an OTP to the user (Email, SMS, or IM).

Table 16-17 Challenge type enums

Property Description

available

if the challenge type is available for use (service ready and configured). To enable/disable an OTP challenge type, the available flag should be set.

processor

java class for handling challenges of this type.

requiredInfo

comma separated list of inputs from the registration input enum


The properties to register the SMS challenge processor and mark service as available (or unavailable) are listed in Table 16-18.

Table 16-18 Properties to register the SMS challenge processor

Property Default Value Description

bharosa.uio.default.challenge.type.enum.ChallengeSMS

2

SMS Challenge enum value

bharosa.uio.default.challenge.type.enum.ChallengeSMS.name

SMS Challenge

Name of SMS challenge type

bharosa.uio.default.challenge.type.enum.ChallengeSMS.description

SMS Challenge

Description of SMS challenge type

bharosa.uio.default.challenge.type.enum.ChallengeSMS.processor

com.bharosa.uio.processor.challenge.ChallengeSMSProcessor

Processor class for SMS challenge type

bharosa.uio.default.challenge.type.enum.ChallengeSMS.requiredInfo

mobile

Required fields to challenge user with SMS challenge type

bharosa.uio.default.challenge.type.enum.ChallengeSMS.available

false

Availability flag for SMS challenge type

bharosa.uio.default.challenge.type.enum.ChallengeSMS.otp

true

OTP flag for SMS challenge type


16.8 Customize One-Time Password Generation

You can configure the one-time password through properties edits. The following properties are used to generate the OTP:

# OTP pin generation config
bharosa.uio.default.otp.generate.code.length = 5
bharosa.uio.default.otp.generate.code.characters = 1234567890
 

The default OTP codes will be 5 characters made up of the numbers 0-9 (for example: 44569).

bharosa.uio.default.otp.generate.code.length designates the length of the OTP.

bharosa.uio.default.otp.generate.code.characters designates the characters to use when generating the OTP.

An example is shown below for generating a 4 character OTP code with numbers 0-9 and letters a-d (for example: 0c6a):

bharosa.uio.default.otp.generate.code.length = 4
bharosa.uio.default.otp.generate.code.characters = 1234567890abcd

16.9 Customize One Time Password Expiry Time

To set up OTP SMS password expiry time, add the following property:

bharosa.uio.default.challenge.type.enum.ChallengeSMS.otpexpirytimeMs

To set up OTP email password expiry time, add the following property:

bharosa.uio.default.challenge.type.enum.ChallengeEmail.otpexpirytimeMs to oaam_custom.properties.

The time is in milliseconds. If the value is not in milliseconds, you will have to perform a conversion. For example, to set the expiration time for OTP to be 5 minutes, then you must set the property to 300000 ms (5 minutes).

Note:

This property works for the OTP API, but now OAAM Server does not use the API. Hence, by default, OAAM Server OTP is valid for the session or until used.

16.10 Configure the Challenge Pads Used for Challenge Types

By default, challenge devices that will be used are configured through rules. The rules are under the AuthentiPad checkpoint where you can specify the type of device to use based on the purpose of the device.

To create/update policies to use the challenge type:

  1. Add a new rule action, MyChallenge, with the enum, rule.action.enum.

  2. Create policy to return newly created action, MyChallenge, to use the challenge method.

Alternatively, to configure challenge devices using properties, you can bypass the AuthentiPad checkpoint by setting bharosa.uio.default.use.authentipad.checkpoint to false.

Devices to use for the challenge type can be added.

bharosa.uio.application.challengeType.authenticator.device=<value>

The examples shown use the challenge type key, ChallengeEmail and ChallengeSMS to construct the property name.

bharosa.uio.default.ChallengeSMS.authenticator.device=DevicePinPad
bharosa.uio.default.ChallengeEmail.authenticator.device=DevicePinPad

Available challenge device values are DeviceKeyPadFull, DeviceKeyPadAlpha, DeviceTextPad, DeviceQuestionPad, DevicePinPad, and DeviceHTMLControl.

Table 16-19 Authentication Device Type

Property Description

None

No HTML page or authentication pad

DeviceKeyPadFull

Challenge user using KeyPad.

DeviceKeyPadAlpha

Challenge user with the alphanumeric KeyPad (numbers and letters only, no special characters)

DeviceTextPad

Challenge user using TextPad.

DeviceQuestionPad

Challenge user using QuestionPad.

DevicePinPad

Challenge user using PinPad.

DeviceHTMLControl

Challenge user using HTML page instead of an authentication pad.


16.11 Customize OTP Anywhere Data Storage

This section describes how to customize data storage for OTP Anywhere. You can customize OTP Anywhere by implementing the com.bharosa.uio.manager.user.UserDataManagerIntf interface.

16.11.1 com.bharosa.uio.manager.user.UserDataManagerIntf

The methods used in customizations are:

  • public String getUserData(UIOSessionData sessionData, String key);

  • public void setUserData(UIOSessionData sessionData, String key, String value);

16.11.2 Default Implementation - com.bharosa.uio.manager.user.DefaultContactInfoManager

The default implementation expands on the interface to break every get and set into two items: UserDataValue and UserDataFlag. The UserDataFlag is used by OAAM to track that a value has been set, or soft reset a value. OAAM uses rules to check if a user is registered for a given item and to check the UserDataFlag in the OAAM database. The UserDataValue is the actual data element entered by the user. In the default implementation this is also stored in the OAAM database, but by extending the DefaultContactInfoManager class and overriding the UserDataValue methods (getUserDataValue and setUserDataValue) the data can be stored in an external location if required.

Methods

public class DefaultContactInfoManager implements UserDataManagerIntf {
 
  public String getUserData(UIOSessionData sessionData, String key){
    if (getUserDataFlag(sessionData, key)){
      return getUserDataValue(sessionData, key);
     }
 
     return null;
     }
 
  public void setUserData(UIOSessionData sessionData, String key, String value){
    setUserDataValue(sessionData, key, value);
    setUserDataFlag(sessionData, key, value);
  }
 
    protected void setUserDataValue(UIOSessionData sessionData, 
       String key, String value){
    VCryptAuthUser clientUser = sessionData.getClientAuthUser();
    if (clientUser != null) {
     clientUser.setUserData(BharosaConfig.get("oaam.otp.contact.info.prefix", 
        "otpContactInfo_") + key, value);
     }
   }
 
   protected String getUserDataValue(UIOSessionData sessionData, String key) {
    VCryptAuthUser clientUser = sessionData.getClientAuthUser();
    if (clientUser != null) {
      return  
clientUser.getUserData(BharosaConfig.get("oaam.otp.contact.info.prefix",
"otpContactInfo_") + key);

     }
 
     return null;
   }
 
 
   protected void setUserDataFlag(UIOSessionData sessionData, 
        String key, String value){
     VCryptAuthUser clientUser = sessionData.getClientAuthUser();
     if (clientUser != null) {
       if (StringUtil.isEmpty(value)) {
clientUser.setUserData(BharosaConfig.get("oaam.otp.contact.info.flag.prefix", 
"otpContactInfoFlag_") + key, null);
      } else {
clientUser.setUserData(BharosaConfig.get("oaam.otp.contact.info.flag.prefix", 
"otpContactInfoFlag_") + key, "true");
       }
     }
   }
 
   protected boolean getUserDataFlag(UIOSessionData sessionData, String key) {
    VCryptAuthUser clientUser = sessionData.getClientAuthUser();
    if (clientUser != null) {
       return 
           Boolean.valueOf(clientUser.getUserData(BharosaConfig.get
              ("oaam.otp.contact.info.flag.prefix", 
                 "otpContactInfoFlag_") + key));
     }
 
     return false;
   }
 
 
}
 

16.11.3 Custom Implementation Recommendations

Extend the base implementation class DefaultContactInfoManager, and override the setUserDataValue and getUserDataValue methods to store the data values where appropriate for you implementation.

Leave the default implementation of setUserDataFlag and getUserDataFlag in place in order for OAAM to properly track which data has been set for the user.

16.11.4 Configure Properties

OTP Anywhere registration fields are defined by the user defined enum: bharosa.uio.default.userinfo.inputs.enum.

Each element has a managerClass property that designates which class will be used to store the registration data.

For example, the default mobile phone element is as follows:

bharosa.uio.default.userinfo.inputs.enum=Enum for Contact information
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=16
bharosa.uio.default.userinfo.inputs.enum.mobile.required=true
bharosa.uio.default.userinfo.inputs.enum.mobile.order=4
bharosa.uio.default.userinfo.inputs.enum.mobile.enabled=true
bharosa.uio.default.userinfo.inputs.enum.mobile.regex=
\\d{1}\\D?(\\d{3})\\D?\\D?(\\d{3})\\D?(\\d{4})
bharosa.uio.default.userinfo.inputs.enum.mobile.errorCode=otp.invalid.mobile
bharosa.uio.default.userinfo.inputs.enum.mobile.managerClass=
com.bharosa.uio.manager.user.DefaultContactInfoManager

As shown, the default mobile phone definition uses the DefaultContactInfoManager class to manage the data. If a custom implementation is desired, the value of the managerClass attribute can be updated in OAAM Admin (or through OAAM Extension shared library) to use a custom class.

16.12 Example Configurations

This section contains the following topics:

16.12.1 Additional Registration Field Definitions Examples

Additional registration field definitions are shown in Table 16-20.

Table 16-20 Contact Information Inputs

Property Description

inputname

Name used for the input field in the HTML form

inputtype

Set for text or password input

maxlength

Maximum length of user input

required

Set if the field is required on the registration page

order

The order displayed in the user interface

regex

Regular expression used to validate user input for this field

errorCode

Error code used to look up validation error message (bharosa.uio.application_ID.error.errorCode)

managerClass

java class that implements com.bharosa.uio.manager.user.UserDataManagerIntf (if data is to be stored in Oracle Adaptive Access Manager database this property should be set to com.bharosa.uio.manager.user.DefaultContactInfoManager)


16.12.1.1 Email Input

The following is an example of an enum defining email registration on the OTP registration page of an authenticator:

Table 16-21 Email Input

Property Default Value Description

bharosa.uio.default.userinfo.inputs.enum.email

1

Email address enum value

bharosa.uio.default.userinfo.inputs.enum.email.name

Email Address

Name for email address field

bharosa.uio.default.userinfo.inputs.enum.email.description

Email Address

Description for email address field

bharosa.uio.default.userinfo.inputs.enum.email.inputname

email

HTML input name for email address field

bharosa.uio.default.userinfo.inputs.enum.email.inputtype

text

HTML input type for email address field

bharosa.uio.default.userinfo.inputs.enum.email.maxlength

40

HTML input max length for email address field

bharosa.uio.default.userinfo.inputs.enum.email.required

true

Required flag for email address field during registration and user preferences

bharosa.uio.default.userinfo.inputs.enum.email.order

2

Order on the page for email address field

bharosa.uio.default.userinfo.inputs.enum.email.enabled

false

Enabled flag for email address enum item

bharosa.uio.default.userinfo.inputs.enum.email.regex

.+@[a-zA-Z_]+?\\.[a-zA-Z]{2,3}

Regular expression for validation of email address field

bharosa.uio.default.userinfo.inputs.enum.email.errorCode

otp.invalid.email

Error code to get error message from if validation of email address entry fails

bharosa.uio.default.userinfo.inputs.enum.email.managerClass

com.bharosa.uio.manager.user.DefaultContactInfoManager

Java class to use to save / retrieve email address from data storage


16.12.1.2 Phone Input

The following is an example of an enum defining phone registration on the OTP registration page of an authenticator:

Table 16-22 Phone Input

Property Default Value Description

bharosa.uio.default.userinfo.inputs.enum.phone

2

Phone number enum value

bharosa.uio.default.userinfo.inputs.enum.phone.name

Phone Number

Name for phone number field

bharosa.uio.default.userinfo.inputs.enum.phone.description

Phone Number

Description for phone number field

bharosa.uio.default.userinfo.inputs.enum.phone.inputname

phone

HTML input name for phone number field

bharosa.uio.default.userinfo.inputs.enum.phone.inputtype

text

HTML input type for phone number field

bharosa.uio.default.userinfo.inputs.enum.phone.maxlength

15

HTML input max length for phone number field

bharosa.uio.default.userinfo.inputs.enum.phone.required

true

Required flag for phone number field during registration and user preferences

bharosa.uio.default.userinfo.inputs.enum.phone.order

3

Order on the page for phone number field

bharosa.uio.default.userinfo.inputs.enum.phone.enabled

false

Enabled flag for phone number enum item

bharosa.uio.default.userinfo.inputs.enum.phone.regex

\\D?(\\d{3})\\D?\\D?(\\d{3})\\D?(\\d{4})

Regular expression for validation of phone number field

bharosa.uio.default.userinfo.inputs.enum.phone.errorCode

otp.invalid.phone

Error code to get error message from if validation of phone number entry fails

bharosa.uio.default.userinfo.inputs.enum.phone.managerClass

com.bharosa.uio.manager.user.DefaultContactInfoManager

Java class to use to save / retrieve phone number from data storage


16.12.1.3 Example - OTP Registration Page to Display Values for Entry of an Email Address Instead of a Mobile Phone

To display only entry information for email and disable entry information for mobile phone for registration, set

bharosa.uio.default.userinfo.inputs.enum.email.enabled=true

bharosa.uio.default.userinfo.inputs.enum.mobile.enabled=false
Enabling the email field will require a server restart.

16.12.1.4 IM Input

The following is an example of an enum defining IM registration on the OTP registration page of an authenticator:

Table 16-23 IM Input

Property Default Value Description

bharosa.uio.default.userinfo.inputs.enum.im

3

Instant message enum value

bharosa.uio.default.userinfo.inputs.enum.im.name

Instant Messaging

Name for instant message field

bharosa.uio.default.userinfo.inputs.enum.im.description

Instant Messaging

Description for instant message field

bharosa.uio.default.userinfo.inputs.enum.im.inputname

im

HTML input name for instant message field

bharosa.uio.default.userinfo.inputs.enum.im.inputtype

text

HTML input type for instant message field

bharosa.uio.default.userinfo.inputs.enum.im.maxlength

15

HTML input max length for instant message field

bharosa.uio.default.userinfo.inputs.enum.im.required

true

Required flag for instant message field during registration and user preferences

bharosa.uio.default.userinfo.inputs.enum.im.order

4

Order on the page for instant message field

bharosa.uio.default.userinfo.inputs.enum.im.enabled

false

Enabled flag for instant message enum item

bharosa.uio.default.userinfo.inputs.enum.im.regex

TBD

Regular expression for validation of instant message field

bharosa.uio.default.userinfo.inputs.enum.im.errorCode

otp.invalid.im

Error code to get error message from if validation of instant message entry fails

bharosa.uio.default.userinfo.inputs.enum.im.managerClass

com.bharosa.uio.manager.user.DefaultContactInfoManager

Java class to use to save / retrieve instant message from data storage


16.12.2 Additional Challenge Message Examples

Other examples of challenge message resource bundles are in the sections following. These properties must be added to client_resource.properties.

16.12.2.1 Customize OTP Email Message

OTP Email message properties are shown in Table 16-24. Customized OTP email message properties bharosa.uio.default.ChallengeEmail.message.subject and bharosa.uio.default.ChallengeEmail.message.body must be added to client_resource.properties. The property bharosa.uio.default.ChallengeEmail.message.from.address must be added to oaam_custom.properties.

Table 16-24 Customize OTP Email Message

Property Default Value Description

bharosa.uio.default.ChallengeEmail.message.from.name

Oracle ASA Test

Email message from address

bharosa.uio.default.ChallengeEmail.message.subject

Oracle OTP Code

Email message subject

bharosa.uio.default.ChallengeEmail.message.body

Your Oracle Email OTP Code is: {0}

Email message body


16.12.2.2 Customize OTP IM Message

OTP IM message properties are shown in Table 16-25.

Table 16-25 Customize OTP IM Message

Property Default Value Description

bharosa.uio.default.ChallengeIM.message.from.name

Oracle ASA Test

IM message from name

bharosa.uio.default.ChallengeIM.message.subject

Oracle OTP Code

IM message subject

bharosa.uio.default.ChallengeIM.message.body

Your Oracle IM OTP Code is: {0}

IM message body


16.12.3 Additional Processors Registration Examples

Additional processor registration properties are listed in Table 16-26.

Table 16-26 Challenge type enums

Property Description

available

if the challenge type is available for use (service ready and configured). To enable/disable an OTP challenge type, the available flag should be set.

processor

java class for handling challenges of this type.

requiredInfo

comma separated list of inputs from the registration input enum


16.12.3.1 Register Email Challenge Processor

The properties to register the email challenge processor and mark service as available (or unavailable) are listed in Table 16-27.

Table 16-27 Properties to register the email challenge processor

Property Default Value Description

bharosa.uio.default.challenge.type.enum.ChallengeEmail

1

Email Challenge enum value

bharosa.uio.default.challenge.type.enum.ChallengeEmail.name

Email Challenge

Name of email challenge type

bharosa.uio.default.challenge.type.enum.ChallengeEmail.description

Email Challenge

Description of email challenge type

bharosa.uio.default.challenge.type.enum.ChallengeEmail.processor

com.bharosa.uio.processor.challenge.ChallengeEmailProcessor

Processor class for email challenge type

bharosa.uio.default.challenge.type.enum.ChallengeEmail.requiredInfo

email

Required fields to challenge user with email challenge type

bharosa.uio.default.challenge.type.enum.ChallengeEmail.available

false

Availability flag for email challenge type

bharosa.uio.default.challenge.type.enum.ChallengeEmail.otp

true

OTP flag for email challenge type


16.12.3.2 Register IM Challenge Processor

The properties to register the IM challenge processor and mark service as available (or unavailable) are listed in Table 16-28.

Table 16-28 Properties to register the IM challenge processor

Property Default Value Description

bharosa.uio.default.challenge.type.enum.ChallengeIM

3

Instant message Challenge enum value

bharosa.uio.default.challenge.type.enum.ChallengeIM.name

IM Challenge

Name of instant message challenge type

bharosa.uio.default.challenge.type.enum.ChallengeIM.description

Instant Message Challenge

Description of instant message challenge type

bharosa.uio.default.challenge.type.enum.ChallengeIM.processor

com.bharosa.uio.processor.challenge.ChallengeIMProcessor

Processor class for instant message challenge type

bharosa.uio.default.challenge.type.enum.ChallengeIM.requiredInfo

mobile

Required fields to challenge user with instant message challenge type

bharosa.uio.default.challenge.type.enum.ChallengeIM.available

false

Availability flag for instant message challenge type

bharosa.uio.default.challenge.type.enum.ChallengeIM.otp

true

OTP flag for instant message challenge type


16.13 Challenge Use Case

An example challenge scenario is as follows:

  1. Oracle Adaptive Access Manager Server presents the user with the user name page.

  2. The user submits his user name on the user name page.

  3. Oracle Adaptive Access Manager fingerprints the user device and runs pre-authentication rules to determine if the user should be allowed to proceed to the password page.

  4. The user is allowed to proceed to the password page and he enters his password.

  5. The OAAM policies indicate that the user should be challenged.

  6. The challenge checkpoint is run to determine the type of challenge to use (KBA, Email, SMS, and so on). If SMS challenge is returned, the SMS Challenge Processor is loaded and used to generate and deliver an OTP to the user through SMS.

  7. Once the SMS has been sent, the user is presented with a challenge page indicating that his OTP has been sent to him in an SMS.

  8. User submits correct OTP to continue into application and complete the login flow.

The OTP generated and sent to the user is only valid for one correct submission within a single HTTP session. If the user's HTTP session expires and a new OTP will be generated and sent if he is challenged again in a later session.