Configure OTP Provider

OTP Provider Configuration

To enable different delivery types of OTP Codes you will need to define SMS, Voice or Email OTP Provider. For version 4.2.1 and above, The OTP Provider configuration can be done via the _Webconsole portal

There are following providers types are available by default:

The following providers exist as predefined OTP providers in default OpenIAM Installation:

OTP Provider NameOTP Provider TypeDescription
Text OTP by TwilioTwilio SMS ProviderSend SMS with Twilio
Text OTP by SMS GlobalSMSGlobal SMS ProviderSend SMS with SMS Global
Email CodeEmail OTP ProviderTo use Configured Mailbox to Send OTP. The Email template with name 'OTP_CODE' is used by default
Call OTP by TwilioTwilio Voice Call ProviderUse Twilio to call using Programmable Voice

It is possible to configure an existing OTP Providers either using your credentials or by creating a new OTP Provider.

Let's check common OTP provider configuration options.

Common OTP Provider Configuration Options

Mailbox configuration menu

Name

Choose a user-friendly name of OTP Provider. For example: "Text OTP by Twilio"

Type

The type of the OTP Provider, you can check the list above for possible types. For example: "Text OTP by Twilio"

Failover OTP Provider

The name of another OTP Provider which will be used in case of current Provider will fail sending the OTP code. Current configuration and Failover Configuration MUST have compatible OTP Provider types. It means that the phone related to OTP Provider Types can be failed over only by OTP Provider. See OTP Provider Types compatibility matrix below. For example: "Text OTP by Twilio"

Attributes

The table of the OTP Provider type related configurations. Each attribute has the following properties:

  • Attribute Name - the NAME of the attribute. This is HARDCODED name of required Attribute which is used to identify the property
  • Stored in Secret - the flag which controls show the value of the attribute stored in secret place (make sense for passwords, usernames and etc...)
  • Value of the Attribute

Based on the type of OTP Provider Attributes can be different. Below will be described attributes based on the OTP Provider Type.

Twilio SMS Provider

Attribute NameDescriptionValue
Message format (internal: TEXT_MESSAGE_FORMAT)The format of the message that will be sent to user with OTP code. Message must contain %s literal, where OTP code will be placed.This SMS is generated by the OpenIAM Test SMS OTP Module. Your code is: %s
From Number (internal: FROM_ACCOUNT)Verified Sender Phone Number, related to the Twilio Configuration.+1234567890
Account Password (internal: ACCOUNT_PASSWORD)Service account passwordqwerty
Account Id (internal: ACCOUNT_ID)Service account nameAC12312312
Length of the OTP code (internal: TOKEN_LEN)The length of the OTP Code. If the length is less then 3 digits, the system will automatically use 3 characters. If value is set at more that 8, system will cut the length of the code to 8 characters6
Path to the groovy script (internal: GROOVY_PATH)Attach a groovy script to a custom OTP provider. You can provide the script path inside your OTP provider: go to Access Control > OTP Provider./AM/otp/TwilioSMSOTPModule.groovy

The groovy script example is given below.

import org.apache.http.HttpResponse
import org.apache.http.client.methods.HttpPost
import org.apache.http.entity.StringEntity
import org.openiam.esb.core.auth.module.AbstractOTPModule;
import org.openiam.idm.srvc.auth.domain.LoginEntity;
import org.openiam.exception.BasicDataServiceException;
import org.apache.http.client.HttpClient;
import org.apache.http.impl.client.HttpClientBuilder;
public class TwillioSMSOTPModule extends AbstractOTPModule {
public TwillioSMSOTPModule() {
super();
}
@Override
protected void validate(String sendTo, LoginEntity login) throws BasicDataServiceException {
}
@Override
protected void send(String sendTo, LoginEntity login, String text) throws BasicDataServiceException {
String accountSid = "accountid";
String authToken = "token";
String toNumber = sendTo;
String fromNumber = "number";
String messageBody = text;
String url = "https://api.twilio.com/2010-04-01/Accounts/" + accountSid + "/Messages.json";
String auth = accountSid + ":" + authToken;
String encodedAuth = Base64.getEncoder().encodeToString(auth.getBytes());
HttpClient httpClient = HttpClientBuilder.create().build();
HttpPost httpPost = new HttpPost(url);
httpPost.setHeader("Authorization", "Basic " + encodedAuth);
httpPost.setHeader("Content-Type", "application/x-www-form-urlencoded");
String body = "To=" + toNumber + "&From=" + fromNumber + "&Body=" + messageBody;
httpPost.setEntity(new StringEntity(body, "UTF-8"));
try {
HttpResponse response = httpClient.execute(httpPost)
int statusCode = response.getStatusLine().getStatusCode()
println("response "+response)
if (statusCode == 200) {
println("OTP sent");
}
} catch (Exception e) {
e.printStackTrace();
}
}
@Override
protected String getText(String sendTo, LoginEntity login, String token) {
return "This SMS is generated by the OpenIAM Test SMS OTP Module. Your token is: " + token;
}
}

SMSGlobal SMS Provider

Attribute NameDescriptionValue
Message format (internal: TEXT_MESSAGE_FORMAT)The format of the message that will be sent to user with OTP code. Message must contain %s literal, where OTP code will be placed.This SMS is generated by the OpenIAM Test SMS OTP Module. Your code is: %s
From Number (internal: FROM_ACCOUNT)Verified Sender Phone Number, related to the SMS Global Configuration.+1234567890
Account Password (internal: ACCOUNT_PASSWORD)Service account passwordqwerty
Account Id (internal: ACCOUNT_ID)Service account nameAC12312312
Length of the OTP code (internal: TOKEN_LEN)The length of the OTP Code. If value is less then 3 letters system will use 3 characters. If value is more that 8, system will use 8 characters6

Email OTP Provider

Attribute NameDescriptionValue
Length of the OTP code (internal: TOKEN_LEN)The length of the OTP Code. If value is less then 3 letters system will use 3 characters. If value is more that 8, system will use 8 characters6

Twilio Voice Call Provider

Attribute NameDescriptionValue
Message format (internal: TEXT_MESSAGE_FORMAT)The format of the message that will be sent to user with OTP code. Message must contain %s literal, where OTP code will be placed.This SMS is generated by the OpenIAM Test SMS OTP Module. Your code is: %s
From Number (internal: FROM_ACCOUNT)Verified Sender Phone Number, related to the Twilio Configuration.+1234567890
Account Password (internal: ACCOUNT_PASSWORD)Service account passwordqwerty
Account Id (internal: ACCOUNT_ID)Service account nameAC12312312
Length of the OTP code (internal: TOKEN_LEN)The length of the OTP Code. If value is less then 3 letters system will use 3 characters. If value is more that 8, system will use 8 characters6
Pronunciation Language (internal: LANGUAGE)There are following Languages are possibleen-US

OTP Provider Types compatibility matrix

#/#Twilio SMS ProviderTwilio Voice Call ProviderSMSGlobal SMS ProviderEmail OTP ProviderCustom OTP Provider
Twilio SMS ProviderXXXX
Twilio Voice Call ProviderXXXX
SMSGlobal SMS ProviderXXXX
Email OTP ProviderX
Custom OTP ProviderXXXX

Authentication Provider Configuration

To apply OTP provider to real usage it should be registered in Authentication Providers. Each Authentication provider may have unique set of OTP providers. The registered OTP Providers will be used to send OTP to the User.

The set of selected OTP Providers will be displayed during "OTP Authentication" authn step.

For instance: a "Supported OTP Providers:" for "Authentication Providers" are selected 'Text OTP by Twilio' and 'Call OTp by Twilio'

auth_provider

The 'Def. OTP Auth Rule' is selected as a 'Supported Authentication Levels' for URI pattern (for example /webconsole/about)

auth_provider

In this case when user hits /webconsole/about URL in the browser the OTP Selector page will be displayed with combobox which contains two options:

  • Call to +1****
  • Test to +1****

auth_provider

In case only the one OTP provider was select at "Authentication Providers" screen the drop-down will not be displayed and OTP will be sent directly using the single selected OTP Provider.