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 via 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.
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
This chapter contains these sections:
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. This password is used to challenge the user to verify the user's 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.
The high-level integration tasks consist of:
This section provides the terms that are helpful to know as you implement OTP Anywhere.
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.
The UMS Server orchestrates message flows between applications and users. OAAM uses UMS to send email, SMS, IM, or voice message to the user.
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 via SMS and email through UMS delivery.
"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. A challenge type can be configured 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.
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 jars and files to an extensions shared library.
For information, refer to Chapter 7, "Customizing Oracle Adaptive Access Manager.".
Oracle SOA Suite must be installed outside of the OAAM domains. UMS is a part of SOA.
For information, refer to the Oracle Fusion Middleware Installation Guide for Oracle SOA Suite and Oracle Business Process Management Suite.
UMS must be configured for appropriate delivery gateways on the SOA that the OAAM Server is configured to send messages through.
UMS Drivers connect UMS to the messaging gateways, adapting content to the various protocols supported by UMS. Drivers can be deployed or undeployed independently of one another depending on what messaging channels are available in a given installation.
Configure the Email driver to a SMTP server. See the "Configuring the Email Driver" section of Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite for how to configure the Email 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 and Oracle Business Process Management Suite. You will need to provide parameter values for connecting to the driver gateway vendor.
Table 11-1 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 |
OTP using 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 jars and files to an extensions shared library. For information, refer to Chapter 7, "Customizing Oracle Adaptive Access Manager.".
Table 11-2 Tasks in the OTP Setup
| Task | Description |
|---|---|
|
Configure |
Configuration involves Tasks 1 through 3. OTP Challenge is not enabled by default. It has to be enabled by setting these properties. |
|
Task 1- Integrate UMS. |
Set up UMS URLs and credentials so that OAAM can communicate with the UMS server. |
|
Task 2 - Make Challenge Types available. |
Make it possible for the policies to challenge using OTP via the challenge type. |
|
Task 3 - Enable Registration and User Preferences. |
Enable registration and user preferences. The user will use the pages for profile registration and resetting OTP profile. |
|
Customize |
Customizations involves Tasks 4 through 7. |
|
Task 4 - Set up the user registration fields and validations. |
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 will need to be duplicated into resource bundle. |
|
Task 5 - Set up Terms and Condition fields. |
Additional fields to set up are Terms of Service, Privacy Policy, and so on. |
|
Task 6 - Set up registration and challenge page messaging |
Customize the messaging that appear on the registration and challenge pages. |
|
Task 7 - Customize OTP message text. |
Customize the message containing the One Time Password |
|
Task 8 - Register Processors |
The challenge type enum is used to associate a Challenge Type with the java code needed to perform any work related to that challenge type. |
|
Task 9 - Configure challenge pads for challenge types. |
Specify the type of device to use based on the purpose of the device. |
The UMS 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, refer to Chapter 2, "Natively Integrating with Oracle Adaptive Access Manager."
This section contains the following topics:
The properties to set for the UMS server URLs and credentials are listed below. 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 UMS.
Table 11-3 UMS 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 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@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 UMS server properties, restart the application.
Enable challenge types by setting the appropriate property to true. By setting the property to true, policies will be able to challenge using OTP via the challenge type (email, SMS, IM, or Voice). The user will see the email, SMS, IM, or Voice page in registration flow.
The challenge type enum is used 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 11-4 UMS 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 |
|
bharosa.uio.default.challenge.type.enum.ChallengeVoice.available |
false |
Availability flag for voice challenge type |
Enable the registration flow and user preferences by setting these properties to true:
Table 11-5 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. |
This section contains the following topics:
Mobile registration field definitions and validations for the OTP registration page are shown below.
Add Mobile Input Registration Field Properties to bharosa_server.properties
These properties should be added to bharosa_server.properties.
Table 11-6 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.
The following examples show term and conditions definitions for the OTP registration page.
Add Terms and Conditions Definitions to bharosa_server.properties
These properties should be added to bharosa_server.properties.
Table 11-8 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 11-9 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 |
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 pop-ups are listed as follows.
Table 11-10 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 |
Add registration properties to client_resource.properties.
Table 11-11 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 |
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.
Add challenge type fields to client_resource.properties.
Table 11-12 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 |
Add OTP message fields to client_resource.properties.
The challenge type enum is used 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" normally refers to the delivery channel used to send an OTP to the user (Email, SMS, or IM).
Table 11-15 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 below.
Table 11-16 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 |
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:
Add a new rule action, MyChallenge, with the enum, rule.action.enum.
Create policy to return newly created action, MyChallenge, to use the challenge method.
Alternatively, if you want 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 11-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. |
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.
The methods used in customization are:
public String getUserData(UIOSessionData sessionData, String key);
public void setUserData(UIOSessionData sessionData, String key, String value);
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. When rules are used to check if a user is registered for a given item, the UserDataFlag will be checked 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.
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;
}
}
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.
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.
This section contains the following topics:
Additional registration field definitions are shown below.
Table 11-18 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) |
The following is an example of an enum defining email registration on the OTP registration page of an authenticator:
| 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 |
|
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 |
The following is an example of an enum defining phone registration on the OTP registration page of an authenticator:
| 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 |
The following is an example of an enum defining IM registration on the OTP registration page of an authenticator:
| 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 |
Other examples of challenge message resource bundles are shown below.
OTP Email message properties are shown below.
Table 11-22 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 |
OTP IM message properties are shown below.
Table 11-23 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 |
Additional processor registration properties are listed below.
Table 11-25 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 email challenge processor and mark service as available (or unavailable) are listed below.
Table 11-26 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 |
|
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 |
The properties to register the IM challenge processor and mark service as available (or unavailable) are listed below.
Table 11-27 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 |
The properties to register the Voice challenge processor and mark service as available (or unavailable) are listed below.
Table 11-28 Properties to register the Voice challenge processor
| Property | Default Value | Description |
|---|---|---|
|
bharosa.uio.default.challenge.type.enum.ChallengeVoice |
4 |
Voice Challenge enum value |
|
bharosa.uio.default.challenge.type.enum.ChallengeVoice.name |
Voice Challenge |
Name of voice challenge type |
|
bharosa.uio.default.challenge.type.enum.ChallengeVoice.description |
Voice Challenge |
Description of voice challenge type |
|
bharosa.uio.default.challenge.type.enum.ChallengeVoice.processor |
com.bharosa.uio.processor.challenge.ChallengeVoiceProcessor |
Processor class for voice challenge type |
|
bharosa.uio.default.challenge.type.enum.ChallengeVoice.requiredInfo |
phone |
Required fields to challenge user with voice challenge type |
|
bharosa.uio.default.challenge.type.enum.ChallengeVoice.available |
false |
Availability flag for voice challenge type |
|
bharosa.uio.default.challenge.type.enum.ChallengeVoice.otp |
true |
OTP flag for voice challenge type |
An example challenge scenario is presented below.
Oracle Adaptive Access Manager Server presents the user with the user name page.
The user submits his user name on the user name page.
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.
The user is allowed to proceed to the password page and he enters his password.
The OAAM policies indicate that the user should be challenged.
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 via SMS.
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.
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.