9 Setting Up OTP Anywhere

OTP Anywhere is a secondary risk-based challenge solution consisting of a server generated one time password delivered to an end user via a configured out of band channel. Supported OTP delivery channels include short message service (SMS), email, and instant messaging.

This chapter focuses on setting up Oracle Adaptive Access Manager to use OTP for secondary, risk-based user challenges. Out of the box, OAAM provides User Messaging Service (UMS) as the delivery method. For other custom methods, refer to the Oracle Fusion Middleware Developer's Guide for Oracle Adaptive Access Manager.

This chapter contains the following sections:

Introduction and Concepts
Quick Start
Setup Roadmap
Prerequisites for Configuring OTP
UMS Integration
Enabling OTP Challenge
Enabling Registration and Preferences
Configuring Policies and Rules to Use OTP Challenge
Setting Up the Registration Page
Configuring OTP Presentation
Configuring Failure Counter
Customizing OTP Registration and Messaging

9.1 Introduction and Concepts

This section introduces you to the concept of One Time Password (OTP) and how it is used in Oracle Adaptive Access Manager.

Topics in this section are as follows:

What is a One Time Password
About Out-of-Band OTP Delivery
How Does OTP Work?
OTP Failure Counters
Challenge Type
KBA vs. OTP

9.1.1 What is a One Time Password

A one-time password is a randomly generated, single-use authentication credential. OTP is a form of secondary authentication that 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. When the user is OTP-challenged, a one-time password is generated and delivered to the user through one of the configured channels. The user must retrieve the one-time password and enter it when prompted, before the one-time password expires.

The one-time password may be either numeric or alphanumeric and any configured length and the randomization algorithm is pluggable.

The following are major benefits of using out-of-band OTP:

The OTP is delivered to the valid user through one of the configured channels. These can include SMS, Instant Messaging (IM), and e-mail.
The user does not require any proprietary hardware or client software of any kind.

9.1.2 About Out-of-Band OTP Delivery

Oracle Adaptive Access Manager 11g contains OTP authentication capabilities that support delivery of the OTP via the following three out-of-band channels:

e-mail
Short Message Service (SMS)
instant messaging

By default, only cell phone registration is displayed on the OTP Registration page.

9.1.3 How Does OTP Work?

During the Registration process in OAAM, the user is asked to register for questions, image, phrase and OTP (e-mail, phone, and so on) if the deployment supports OTP. Once successfully registered, OTP can be used as a secondary authentication to challenge the user.

The administrator can enable the OTP if the deployment supports OTP. The login process begins with entering standard user name and password credentials. During a session, for example, when the user is making a large transaction, if the user is OTP-challenged, the password is delivered to the user through the configured delivery channel. The user retrieves the one-time password, then enters it.

If the correct answer is provided, the user is directed to continue with the operation. If the user answers incorrectly, he is allowed other attempts until he either answers correctly or is locked out of his account after a certain number of failures. By default, the user is allowed three attempts to provide the correct answer.

9.1.4 OTP Failure Counters

The failure counter is incremented when the user supplies an incorrect answer during an OTP-challenge. OTP failures are counted across sessions.

Whether the user is locked out after a number of successive OTP failures or needs to try providing the OTP again depends on the failure counter value, the maximum number for OTP challenges set by the administrator. When the failure counter exceeds this value, the user is "OTP Locked" with no further opportunity for another attempt to answer. If the user is OTP-locked, he can call the Customer Service Representative to become unlocked.

When the correct OTP is provided by the user, the failure counter is reset to 0 and the user is allowed to proceed with the operation.

9.1.5 Challenge Type

The challenge type is the delivery channel used to send an OTP to the user. For example, policies can challenge using OTP via the challenge type (email, SMS, or IM).

Table 9-1 OTP Challenge Types

Challenge Type	Description
ChallengeEmail	OTP challenge via email
ChallengeSMS	OTP challenge via SMS
ChallengeIM	OTP challenge via instant messaging

An integrator can create or configure a challenge type to handle a challenge that is required, such as generating the "secret" used for the challenge to delivering the "secret" to the user and finally validating the user's input.

The challenge type properties are used to associate a challenge type with a Challenge Processor, the java code needed to perform any work for challenges.

9.1.6 KBA vs. OTP

Oracle Adaptive Access Manager deployments may choose to use both KBA and OTP or each separately or no challenge mechanisms at all. If both KBA and OTP are being used in a deployment, the security team may choose to use OTP first for high risk situations and then KBA.

For example, a user logging in from a new IP addresses in a city he often logs in from is relatively low risk on its own, so a KBA challenge is a good option to gain additional verification that this is the valid user. If, however, a user is attempting a funds transfer of more than $1000 using a device and location he has never accessed from previously and the user has never performed a transfer, a stronger measure such as OTP Anywhere would be warranted.

If a customer has both KBA and OTP enabled, the priority is configurable through properties. The default is to OTP challenge first and then KBA challenge for high risk situations.

For information on KBA and OTP Anywhere priority, see Table 11-22, "OAAM Challenge Trigger Combinations".

9.2 Quick Start

The first step in starting to use OTP Anywhere is to enable it using the Properties Editor in OAAM Admin.

This checklist provides you with the basic steps for enabling OTP Anywhere out of the box. Included are links to pertinent documentation and prerequisites.

Table 9-2 Quick Start for Enabling OTP Out of the Box

# Task Details

#	Task	Details
1	Enable OTP Anywhere Registration	OTP Challenge is not enabled by default. It has to be enabled by setting the following properties to true: `bharosa.uio.default.register.userinfo.enabled` Setting this property to true enables OTP profile in the registration flow `bharosa.uio.default.userpreferences.userinfo.enabled` Setting this property to true enables the OTP profile in User Preferences
2	Make SMS Challenge Type Available.	Enable the SMS Challenge Type by setting the following property to true: `bharosa.uio.default.challenge.type.enum.ChallengeSMS.available` This makes it possible for the policies to challenge using OTP via SMS.
3	Configure UMS URLs and Credentials.	Set the following properties: `bharosa.uio.default.ums.integration.webservice` - UMS Web service URL `bharosa.uio.default.ums.integration.parlayx.endpoint` - UMS ParlayX URL `bharosa.uio.default.ums.integration.useParlayX=false` - Configures use of Web service or parlayx API. Value is false by default (preferred). `bharosa.uio.default.ums.integration.userName` - UMS integration user name `bharosa.uio.default.ums.integration.password` - UMS integration password

Enable OTP Anywhere Registration

OTP Challenge is not enabled by default. It has to be enabled by setting the following properties to true:

bharosa.uio.default.register.userinfo.enabled

Setting this property to true enables OTP profile in the registration flow
bharosa.uio.default.userpreferences.userinfo.enabled

Setting this property to true enables the OTP profile in User Preferences

Make SMS Challenge Type Available.

Enable the SMS Challenge Type by setting the following property to true:

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

This makes it possible for the policies to challenge using OTP via SMS.

Configure UMS URLs and Credentials.

Set the following properties:

bharosa.uio.default.ums.integration.webservice - UMS Web service URL
bharosa.uio.default.ums.integration.parlayx.endpoint - UMS ParlayX URL
bharosa.uio.default.ums.integration.useParlayX=false - Configures use of Web service or parlayx API. Value is false by default (preferred).
bharosa.uio.default.ums.integration.userName - UMS integration user name
bharosa.uio.default.ums.integration.password - UMS integration password

9.3 Setup Roadmap

Table 9-3 lists the high-level tasks for configuring OTP for use with OAAM.

Table 9-3 OTP Setup Tasks

Number	Task	Information
1	Enable and configure User Messaging Service (UMS) for SMS delivery gateways on the SOA that the OAAM Server is configured to send messages through and the SMS delivery channel. UMS comes with a number of drivers that handle traffic for a specific channel. Configure UMS to use SMS for sending the one-time password.	Section 9.4, "Prerequisites for Configuring OTP."
2	Set up UMS URLs and credentials so that OAAM can communicate with the UMS server via web services APIs to send the OTP code to the user via the challenge type.	Section 9.5, "UMS Integration."
3	Enable the SMS challenge type so that it can be used to challenge the user if secondary authentication is required.	Section 9.6, "Enabling OTP Challenge."
4	Enable registration and user preferences. The user can use the pages for profile registration and resetting OTP profile.	Section 9.7, "Enabling Registration and Preferences."
5	Make sure out-of-the-box policies are available and active.	Section 9.8, "Configuring Policies and Rules to Use OTP Challenge."
6	Set up the registration and preferences page input fields for the user. Input properties includes maximum length for the email address the user can enter, validation for the email address field (expression), and so on. Note: Any user facing strings need to be duplicated into resource bundle.	Section 9.9, "Setting Up the Registration Page."
7	Define type of device for the specific type of challenge.	Section 9.10, "Configuring OTP Presentation."
8	Customize the registration page using the resource bundle (client_resource_<locale>.properties file). Also, the challenge type message subject, the body of the message, and the message itself could be fully customized by specifying the custom values in resource bundle files and deploying the changes via OAAM extension shared libraries	Section 9.12, "Customizing OTP Registration and Messaging."
9	Customize OTP generation.	Section 9.13, "Customizing One-Time Password Generation."

9.4 Prerequisites for Configuring OTP

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

Install SOA Suite
Configure the Delivery Channels

Figure 9-1 shows an OTP implementation.

Figure 9-1 An OTP Implementation

9.4.1 Install SOA Suite

The Oracle SOA Suite contains the User Messaging Service (UMS). 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, refer to the Oracle Fusion Middleware Installation Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

9.4.2 Configure the Delivery Channels

In addition to the components that comprise the User Messaging Service (UMS) itself, the other key entities in a messaging environment are the external gateways required for each messaging channel. These gateways are not a part of the User Messaging Service (UMS) or Oracle WebLogic Server. Since UMS drivers support widely-adopted messaging protocols, UMS can be integrated with existing infrastructures such as an e-mail servers or XMPP servers. Alternatively, UMS can connect to outside providers of SMS service that support SMPP.

UMS must be configured for appropriate delivery gateways on the SOA that the OAAM Server is configured to send messages through.

Figure 9-2 Messaging Service

UMS Drivers connect UMS to the messaging gateways. The drivers handle traffic for a specific channel. They 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. To configure drivers, follow the steps in "Configuring User Messaging Service Drivers" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

9.4.2.1 Email Driver

Configure the Email driver to a SMTP server as described in "Configuring the Email Driver" in 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 remote gateway.

Table 9-4 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.

9.4.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 need to 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. You will need to provide parameter values for connecting to the driver gateway vendor.

Table 9-5 Connecting to the Vendor

Parameter	Description
SmsAccountId	The Account Identifier on the SMS-C. This is your vendor account ID which you need to 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 that is 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

9.5 UMS Integration

Set up OAAM to use the UMS server by modifying the following properties using the Properties Editor. The properties to set for the UMS server URLs and credentials are shown in Table 9-6. After you set up the UMS server properties, restart the application.

Note: End point is the Web Services URL that OAAM uses to send calls into UMS.

Table 9-6 UMS Server URLs and Credentials

Property	Default Value	Description
bharosa.uio.default.ums.integration.webservice		UMS Server Web service 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 web service or parlayx API. The value is false by default (Web services recommended)
bharosa.uio.default.ums.integration.userName		User name for UMS server
bharosa.uio.default.ums.integration.password		Password for UMS server
bharosa.uio.default.ums.integtaion.policies		UMS authentication policies
bharosa.uio.default.ums.integration.fromAddress	demo@company.example.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 UMS server properties, restart the application.

9.6 Enabling OTP Challenge

The challenge type is the channel that OTP can use to challenge the user, such as Email, SMS, IM, and so on. The challenge type properties are used to associate a Challenge Type with a Challenge Processor, the java code needed to perform any work for challenges.

Enable the OTP challenge type you want to use to challenge the user if secondary authentication is required by setting the available flag. Set bharosa.uio.default.challenge.type.enum.ChallengeSMS.available to true.

Then, you can define the properties for the OTP challenge type, such as the required field for registration, and register the challenge processor that is handling the challenge processing.

To enable and define a challenge type, such as ChallengeEmail, ChallengeSMS, ChallengeQuestion, and so on, perform the following steps:

Log in to OAAM Admin.
In the Navigation tree, double-click Properties under the Environment node. The Properties Search page is displayed.
Search for bharosa.uio.default.challenge.type.enum and edit the properties for the out-of-the-box OTP challenge type:

SMS Challenge Type

The following is an example of an enum defining SMS challenge for OTP:

Table 9-7 Properties for SMS Challenge Type

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 Specifies the java class for handling challenges of this type. The challenge mechanism is customizable through Java classes. See the Oracle Fusion Middleware Developer's Guide for Oracle Adaptive Access Manager for information.
bharosa.uio.default.challenge.type.enum.ChallengeSMS.requiredInfo	mobile	Required fields to challenge user with SMS challenge type A comma separated list of inputs from registration input enum
bharosa.uio.default.challenge.type.enum.ChallengeSMS.available	false	Availability flag for SMS challenge type Specifies 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.
bharosa.uio.default.challenge.type.enum.ChallengeSMS.otp	true	OTP flag for SMS challenge type

Email Challenge Type

The following is an example of the enum defining the challenge type, email challenge, for OTP:

Table 9-8 Properties for Email Channel Type

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 Specifies the java class for handling challenges of this type. The challenge mechanism is customizable through Java classes. See the Oracle Fusion Middleware Developer's Guide for Oracle Adaptive Access Manager for information.
bharosa.uio.default.challenge.type.enum.ChallengeEmail.requiredInfo	email	Required fields to challenge user with email challenge type A comma separated list of inputs from registration input enum
bharosa.uio.default.challenge.type.enum.ChallengeEmail.available	false	Availability flag for email challenge type Specifies 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.
bharosa.uio.default.challenge.type.enum.ChallengeEmail.otp	true	OTP flag for email challenge type

9.7 Enabling Registration and Preferences

For the end user to be able to enter his profile and reset phases at a later time, the following properties must be enabled so that the fields that are set up for the pages can be used.

Ensure that the OTP Challenge types are enabled.

Use the Properties Editor in the OAAM Admin to enable OTP profile registration and preference setting. The properties are listed below.

Table 9-9 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.

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.

9.8 Configuring Policies and Rules to Use OTP Challenge

Policies in the Challenge checkpoint determine the type of challenge to present the user. For more information, refer to Section 11.5.9, "OAAM Challenge."

To configure a policy with a rule that OTP-challenge users for specific scenarios, perform the following steps:

Log in to the OAAM Administration Console.
Double-click Policies in the Navigation pane.

The Policies Search page displays.
In the Policies Search page, click the New Policy button.

The New Policy page appears. In the Summary tab, create a post-authentication security policy:
1. For Policy Name, enter OTP Challenge for Many Failures.
2. For Description, enter a description for the policy.
3. For Checkpoint, select Post-Authentication.
4. Modify the policy status, scoring engine, and weight according to your requirements.
5. Click Apply.
6. Click OK to dismiss the confirmation dialog.
Click the Rules tab to select it.
1. Add general summary information about the rule.
2. On the conditions tab, add User: Check OTP failures condition or other OTP-related conditions.
On the Results tab, specify OAAM challenge as the Action group.
Link the policy to all users.

9.9 Setting Up the Registration Page

Setting up the registration page involves the following tasks:

Enabling the Opt-Out Feature
Customizing Terms and Conditions
Configuring Text and Fields on Registration and Preference Pages
Customizing Registration Page Messaging

9.9.1 Enabling the Opt-Out Feature

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

Table 9-10 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

If you want the user to be able to opt-out of registering an OTP profile, you must enable a Decline button on the OTP registration page by setting the following properties using the Properties Editor:

Table 9-11 Enabling Opt-Out for OTP Registration and Challenge

Property	Value
bharosa.uio.default.register.userinfo.decline.enabled	true
bharosa.uio.default.userpreferences.userinfo.decline.enabled	true

Note:

The property to opt-out must be set to true for the Decline button to be available. If the other two properties are true and opt-out is false, the button will not be displayed.

If a customer chooses to decline registration of an OTP profile, he will not be asked again to register OTP, and he will not receive OTP challenges. However if a customer representative resets a user's OTP profile through a reset all, the user will have an opportunity to register OTP again. Even if the user has opted out of OTP registration and challenge, he can still access the OTP page in User Preferences and register for OTP.

9.9.2 Customizing Terms and Conditions

To configure terms and conditions check boxes and fields in the OTP registration page, add the properties in the sections following.

To configure check boxes and fields, follow these steps:

Create a work folder called oaam_extensions. (The folder can be created anywhere as long as it is outside the installation folder.)
Locate oracle.oaam.extensions.war, which is located in the IAM_Home/oaam/oaam_extensions/generic directory.
Explode oracle.oaam.extensions.war into the oaam_extensions folder.
Open the oaam_custom.properties file in the WEB-INF/classes/bharosa_properties directory of the oracle.oaam.extensions.war file.
Add properties from Section 9.9.2, "Customizing Terms and Conditions" and Section 9.9.3, "Configuring Text and Fields on Registration and Preference Pages."
Repackage oracle.oaam.extensions.war from the parent folder of oaam_extensions using the command:

jar -cvfm oracle.oaam.extensions.war oaam_extensions\META-INF\MANIFEST.MF -C oaam_extensions/ .
Shut down the OAAM Admin and OAAM Server managed servers.
Start the WebLogic Server where Oracle Adaptive Access Manager is deployed and log in to the WebLogic Administration Console.
Navigate to Domain Environment, and select Deployments and lock the console.
Click Install.
Browse to the location of the oracle.oaam.extensions.war file and select it by clicking the radio button next to the WAR file and clicking Next.
Ensure Install this deployment as a library is selected and click Next.
Select deployment targets, OAAM Admin and OAAM Server.
Click Next again to accept the defaults in this next page and then click Finish.
Click Save and then Activate Changes.
Start the OAAM Admin and OAAM managed servers.

9.9.2.1 Term and Condition Definitions

To configure terms and conditions check boxes and fields in the OTP registration page, add the properties in the sections following.

Table 9-12 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

9.9.3 Configuring Text and Fields on Registration and Preference Pages

Set up text and fields on registration and preference pages. Input properties includes maximum length for the email address the user can enter, validation for the email address field (expression), and so on.

Mobile Input Registration Fields

Mobile registration field definitions and validations for the OTP registration page are shown below.

These properties should be added to oaam_custom.properties.

Table 9-13 Mobile Input Registration Fields

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

Second Mobile Device Input Registration Field Properties Example

The following properties illustrate how to configure registration fields for a second mobile device on the OTP registration page.

Table 9-14 Mobile Input

Property	Default Value	Description
bharosa.uio.default.userinfo.inputs.enum.mobile2	2	Mobile phone enum value
bharosa.uio.default.userinfo.inputs.enum.mobile2.name	Mobile Phone 2	Name for mobile phone field
bharosa.uio.default.userinfo.inputs.enum.mobile2.description	Mobile Phone 2	Description for mobile phone field
bharosa.uio.default.userinfo.inputs.enum.mobile2.inputname	cell number 2	HTML input name for mobile phone field
bharosa.uio.default.userinfo.inputs.enum.mobile2.inputtype	text	HTML input type for mobile phone field
bharosa.uio.default.userinfo.inputs.enum.mobile2.maxlength	15	HTML input max length for mobile phone field
bharosa.uio.default.userinfo.inputs.enum.mobile2.required	true	Required flag for mobile phone field during registration and user preferences
bharosa.uio.default.userinfo.inputs.enum.mobile2.order	2	Order on the page for mobile phone field
bharosa.uio.default.userinfo.inputs.enum.mobile2.enabled	true	Enabled flag for mobile phone enum item
bharosa.uio.default.userinfo.inputs.enum.mobile2.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.mobile2.errorCode	otp.invalid.mobile	Error code to get error message from if validation of mobile phone entry fails
bharosa.uio.default.userinfo.inputs.enum.mobile2.managerClass	com.bharosa.uio.manager.user.DefaultContactInfoManager	Java class to use to save / retrieve mobile phone from data storage

Email Address Input Registration Field Properties

Add these properties to configure the email address registration fields on the OTP registration page.

Table 9-15 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

Second Email Address Input Registration Field Properties Example

The following properties illustrate how to configure registration fields for a second email address on the OTP registration page.

Table 9-16 Email Input

Property	Default Value	Description
bharosa.uio.default.userinfo.inputs.enum.email2	2	Email address enum value
bharosa.uio.default.userinfo.inputs.enum.email2.name	Email Address 2	Name for email address field
bharosa.uio.default.userinfo.inputs.enum.email2.description	Email Address 2	Description for email address field
bharosa.uio.default.userinfo.inputs.enum.email2.inputname	email2	HTML input name for email address field
bharosa.uio.default.userinfo.inputs.enum.email2.inputtype	text	HTML input type for email address field
bharosa.uio.default.userinfo.inputs.enum.email2.maxlength	40	HTML input max length for email address field
bharosa.uio.default.userinfo.inputs.enum.email2.required	true	Required flag for email address field during registration and user preferences
bharosa.uio.default.userinfo.inputs.enum.email2.order	2	Order on the page for email address field
bharosa.uio.default.userinfo.inputs.enum.email2.enabled	false	Enabled flag for email address enum item
bharosa.uio.default.userinfo.inputs.enum.email2.regex	.+@[a-zA-Z_]+?\\.[a-zA-Z]{2,3}	Regular expression for validation of email address field
bharosa.uio.default.userinfo.inputs.enum.email2.errorCode	otp.invalid.email	Error code to get error message from if validation of email address entry fails
bharosa.uio.default.userinfo.inputs.enum.email2.managerClass	com.bharosa.uio.manager.user.DefaultContactInfoManager	Java class to use to save / retrieve email address from data storage

9.10 Configuring OTP Presentation

By default, challenge devices are configured through rules. The rules are under the Authentipad checkpoint and determine the type of device to use based on the purpose of the device (ChallengeEmail, ChallengeSMS, ChallengeQuestion, and so on).

To change the OTP Device used for challenges, change the OTP challenge type for the rule's result action.

Alternatively, if you want to configure challenge devices using properties you can bypass the Authentication Pad checkpoint by following these instructions:

Log in to OAAM Admin.
In the Navigation tree, double-click Properties under the Environment node. The Properties Search page is displayed.
Set bharosa.uio.default.use.authentipad.checkpoint to false.
Edit bharosa.uio.default.<ChallengeType>.authenticator.device=<Device> with the challenge type and the property for the desired device.
```
bharosa.uio.default.ChallengeSMS.authenticator.device=DeviceTextPad
bharosa.uio.default.ChallengeEmail.authenticator.device=DeviceTextPad
```
Table 9-17 shows the property and the authentication pad that would be used. In the above example, the SMS authenticator is the Text Pad since the property, DeviceTextPad, was specified. (DeviceKeyPadAlpha would display a alphanumeric KeyPad.)

For authentication device types, refer to Table 9-17.

Table 9-17 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.

The OTP device is displayed at the next log in to the application.

9.11 Configuring Failure Counter

When a user fails the OTP challenge, a counter is updated to indicate that user has had a failure. The failure counter looks across sessions.

The failure counter is set by default in the OAAM Challenge Policy, but you can customize it by following these instructions:

Open the OAAM Challenge Policy.
Open the appropriate maximum failed OTP rule.
In the Conditions tab, select User: Check OTP failures.

Edit the appropriate properties.

Table 9-18 User: Check OTP failures Values

Property	Description
Description	Checks if user's OTP failure counter value is over a specified value.
Failures more than or equal to	The number of failed attempts allowed
If above or equal, return	True or False
OTP Challenge Type	The challenge type is the channel that OTP is using to challenge the user.

9.12 Customizing OTP Registration and Messaging

The registration page could be fully customized using the resource bundle (client_resource_<locale>.properties file). Also, the challenge type message subject, the body of the message, and the message itself could be fully customized by specifying the custom values in resource bundle files and deploying the changes via OAAM extension shared libraries.

9.12.1 Customizing Terms and Conditions

To customize the Terms and Condition text, add the following properties to the resource bundle, client_resource_<locale>.properties:

Table 9-19 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®, T-Mobile®, Cellular One Dobson, Cincinnati Bell, Alltel, Virgin Mobile USA, Cellular South, Unicel, Centennial and Ntelos

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. For help or information on this program send "HELP" to [ENTER SHORT/LONG CODE HERE]. To cancel your plan, send "STOP" to [ENTER SHORT/LONG CODE HERE] at anytime. For additional information on this service please go to <a href="" target="_blank">[ENTER INFORMATIONAL URL HERE]</a>. Supported Carriers: AT&T, Sprint, Nextel, Boost, Verizon Wireless, U.S. Cellular®, T-Mobile®, 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 9-20 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

9.12.2 Customizing Mobile Input Registration Fields

To customize mobile input fields, these properties can be added to the resource bundle, client_resource_<locale>.properties:

Table 9-21 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

9.12.3 Customizing Registration Page Messaging

To customize the registration page messaging, add the following registration properties to client_resource_<locale>.properties:

Table 9-22 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

9.12.4 Customizing Challenge Messaging

To customize the challenge type fields, add the following properties to the resource bundle, client_resource_<locale>.properties:

Table 9-23 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

9.12.5 Customizing the OTP Messaging

To customize the OTP messaging, add these properties to the resource bundle, client_resource_<locale>.properties:

Note:

User facing strings need to be duplicated into resource bundle. Resource bundle values can be customized by adding them to the client_resource_<locale>.properties and deploying the file in OAAM Extensions Shared Library.

Table 9-24 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}

9.13 Customizing 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

9.14 Customizing One Time Password Expiry Time

Note:

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

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

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

To set up OTP e-mail 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, if you want to set the expiration time for OTP to be 5 minutes, then you must set the property to 300000 ms (5 minutes).