Telephone Authentication

Overview

Voice authentication allows a telephone number (Mobile or landline) to be called by the Swivel server to let the user authenticate by:

• Pressing # or other defined characters on phone keypad
• Enter OTC on phone keypad. The OTC may be from a security string or PINless

For other forms of authentication see: Transports How To Guide

Technical explanation

Login page starts a session and retrieves a session ID.

The login page then displays the TURing image for that sessionid using a TCImage request, for example https://hostname:8443/TCImage?username=test.

This causes the core platform to initiate the call.

The user answers the call and types the OTC.

The telephony provider posts the OTC to the Swivel core.

The Swivel Core works out who the user is from the phone number, updates the session by injecting the OTC into it.

The login page polls the core platform to see if the session has been updated. When it has the login page is submitted.

The login page actually submits the username and the session ID (if the mode is match, this means the OTC submitted by the form must match that type on the phone, in this mode the OTC is submitted not the sessionID).

The Swivel Core looks up the session id, reads the OTC from the session and processes the authentication as usual.

Prerequisites

Swivel 3.10 onwards

Nexmo Account

Swivel configuration

Add an Agent

On the Swivel Administration console select Server/Agents, and ensure that an Agent exists to allow communication to the Swivel server. On Swivel virtual and hardware appliances a local agent will exist by default.

See Agents How to Guide

Configure 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

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]):

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 Telephony Users

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

Define a Telephone Transport

On the Swivel Administration console, select or create a voice Transport such as NexmoVoice

Identifier: NexmoVoice

Class: com.swiveltechnologies.pinsafe.server.transport.NexmoVoiceTransport

Strings per message: 1

Copy to alert transport: Yes No

Destination attribute: None

Strings Repository Group: NONE

Alert repository group: NONE

[transport_general_classes_twowaygroup]: The Telephony group defined above e.g. PINsafeUsers

Configure a Telephone Transport

On the Swivel Administration console select the created Transport then enter the configuration details (note the default URL has changed from rest to api):

[transport_nexmo_timeout]: 180000

[transport_nexmo_prompt]: Enter your one-time code:bye

[transport_nexmo_nexmomessageurl]: https://api.nexmo.com/tts/xml

[transport_nexmo_nexmoprompturl]: https://api.nexmo.com/tts-prompt/xml

[transport_nexmo_nexmocallback]: http://83.105.30.10:8080/pinsafe/nexmoinbound

[transport_nexmo_nexmoapikey]: Your Nexmo account key

[transport_nexmo_nexmoapisecret]: Your Nexmo account password/secret

[transport_nexmo_nexmodigits]: 4 (to match the OTC length)

Testing

The Swivel Telephony can be configured to work with a an authentication portal. For testing it is possible to use the User Portal.

Configuring the User Portal

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.

Testing with the User Portal

Browse to https://IP_Hostname:8443/userportal/telephonylogin this will present the user with a Username and OTC field. Enter the Username then click Go. The user should be displayed a TURING image and receive a call. The User can enter on the Telephone using the keypad, and then also in the OTC field on screen, if they are set to match. If both are correct the authentication succeeds.

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 Mesages

LOG_HTTP_TRANSPORT_ERROR, https://rest.nexmo.com/tts-prompt/xml

LOG_HTTP_TRANSPORT_ERROR, 404 Not Found

The Nexmo transport has changed, use https://api.nexmo.com/tts-prompt/xml