Latest revision as of 12:52, 11 May 2017

Overview

OneTouch Voice authentication allows a mobile device to be called by the Swivel server to let the user authenticate by:

• Entering the OTC on the same on the telephone keypad and in the login
• Entering the OTC comes only on the phone
• Pressing the Confirm key(s) example: if # is entered then confirm by entering # on the telephone keypad.

For other forms of authentication see: Transports How To Guide and OneTouch Mobile uing the Swivel Mobile Phone Client

Prerequisites

Swivel 3.10.4 onwards

Nexmo Account (or other Telephony provider) for OneTouch Voice telephone-based solution.

Swivel configuration

In order for a user to receive the OneTouch Voice telephone call they must be allocated the right to use the OneTouch mode of operation. This is done by ensuring that they are a member of a group that has this right. In addition they must be in a group associated with an OneTouch transport.

The transport must be a suitable telephony based transport (eg Nexmo) for the the telephone call based approach.

Configuring Dual Channel settings

On the Swivel Administration console select Server/Dual Channel and ensure the below settings are configured:

Set On-Demand Delivery: to Yes

Set Allow message request by Username: to Yes

In Bound OTC Rule:

• None - No inbound
• Match - Must be the same on the telephone keypad as in the login
• Message - OTC comes from phone only
• Confirm key - enter the digits defined under Confirm Key to authenticate, example: if 1234 is entered then confirm by entering 1234 on the telephone keypad.

Confirmation key: (may be shown as [server_dualchannel_inboundconfirmkey]): The key(s) to be pressed to confirm authentication

Call/Notification gap(s) (may be shown as [server_dualchannel_inboundcallgap]):

Domain Allowed to get OTC: Indicates the domain (e.g. http://localhost:8080, http://domain) authorized to get OTC. That is used by 2 way transport like OneTouch Voice telephone or OneTouch Mobile PNA (push notification authentication). The domain will correspond with the domain client (e.g. Userportal, Juniper, ...). If the value is * it will allow all the domains.

NOTE: The Server -> Voice Channel page is not required any more. The options on this page are replaced by the Dual Channel and NexmoVoice options.

Define a group of OneTouch Users

On the Swivel Administration console, select a group of users that will be using OneTouch authentication and ensure that the OneTouch box is ticked then click Apply.

OneTouch Voice Users

Define a OneTouch Transport

On the Swivel Administration console, select or create a OneTouch Transport

For OneTouch Voice this will be a telephopny proivder such as NexmoVoice

One Touch Voice Transport

Configure OneTouch Transports

Configure a One Touch Voice Transport

HTTP Timeout (ms): default: 180000

Enter a prompt: default: Enter your one-time code:bye

Message URL: set to: https://api.nexmo.com/tts/xml

Prompt URL: set to: https://api.nexmo.com/tts-prompt/xml

Call back URL: set to: https://your_url:8443/proxy/nexmoinbound

API key: Your Nexmo account API key

Secret: Your Nexmo account secret

Confirm Code: default: 4

Testing

The Swivel OneTouch can be configured to work with a test authentication page available for download.

Configuring the Test Page

Edit the userportal/js/ajax.js file and make sure the top line has the serverContext variable set

var serverContext = https://localhost:8080/pinsafe

If it is installed on a different server then a Hostname or IP address will need to be specified. If HTTP is used instead of HTTPS then this may need to be changed.

Integrating OneTouch

The OneTouch Voice telephone call can be initiated in much the same way as the sending of an SMS message.

The login page needs to start an authentication session then include a GET request to TCImageCall servlet passing in the session ID. This generates the call.

The login page can also include logic to detect when the core platform has received the user’s response.

Once the user response has been received the form can be submitted, using the sessionID as the users’ one-time code.

An example OneTouch login page is available for Juniper.

VPN Integration

As it may not be possible to perform some of the stages of the integration within the constraints of a VPN login page, we have developed a different approach for OneTouch integration with VPNs.

Rather than creating a login page that handles the authentication we have created a custom VPN login page that redirects the user to a different server that hosts the OneTouch login page.

The user enters their username and password on this page and this page requests the push-message/call. When this page detects that the user has responded it redirects the user back to the VPN login page, complete with username, password and session ID. The modified login page automatically submits the form and the authentication then proceeds.

Known Issues

Troubleshooting

Check the Swivel logs for error messages

Try with the country code

If a phone number is not receving calls, check the Swivel logs

Nexmo have a number of error Codes on their website which may be returned: What are Nexmo delivery error codes?

Error Messages

Calling or sending notification to user "onetouch" failed, error: The transport destination is empty.

This error can be seen where the user is authenticationg with the PNA and if the Mobile device has not been provisioned.

NEXMO_ERROR <?xml version="1.0" encoding="UTF-8"?> <response> <call_id /> <to /> <status>17</status> <error_text>Cannot route the call</error_text> </response>

The telephone number may be in the wrong format such as no country code etc.

More than one user was found with the attribute "phone" = "1234567890123"

Ensure that the telephone number is unique.