Telephone Authentication
Contents
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.
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.
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 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
