.. _voiceprovider:

===============================
Voice Provider
===============================

Starting with version 2.10 LinOTP supports Voice Tokens. 

.. note:: KeyIdentity's voice challenge service is required additionally to
          LinOTP to utilize Voice Tokens.

Configuration
~~~~~~~~~~~~~~

For using Voice Tokens at least one "Voice Token Provider" must be
configured.

The Voice Token Provider configuration can be found at the token management GUI
(`https://LINOTPSERVER/manage`) "LinOTP Config" --> "Provider Config" --> "Voice
Provider Config" where the Providers can be created, edited and deleted.

|

.. figure:: images/menu_voiceprovider.png
 :width: 50%

 Access Push Provider Configuration

|

.. figure:: images/webui_popup_voiceprovider.png
 :width: 60%

 Create a new Push Provider

|

Set up as many Push Providers as required. Which one will be used can be
configured by policies. If no policy exists or no existing policy applies the
Push Provider marked as "(Default)" will be used.

.. _Choose Voice Provider:

Policy to choose Voice Provider
```````````````````````````````

Different Voice Provider can be used depending on username, realm or client.

 * Policy name: this is a unique name of the policy.
 * Scope: You need to set this to **authentication**.
 * Action: **voice_provider=<NAME_OF_ONE_OF_THE_DESIRED_PROVIDER>**
 * User: This is a comma separated list of usernames or resolver names. Please see :ref:`users_in_policies`.
 * Realm: Enter the name of the realm.
 * Client: This is a list of IP addresses or subnets this policy is valid for.

.. index::
	VoiceProvider,  VoiceProviderConfig

Configure Voice Provider
``````````````````````````

A Voice Provider is a LinOTP module, that defines how the push messages are
transmitted to the user's phone.

These four values can be configured in the server configuration:

``Name``
 Name of the Voice Provider as to be used in the policies.

``Class``
 The Voice Provider module to be used for sending messages. At the moment LinOTP comes
 with one Voice Provider class: ``CustomVoiceProvider``


``Config``
 The configuration parameter for the Voice Provider Class.

``Timeout``
 This configuration key holds the time that an OTP value that was transmitted 
 is valid. The number is interpreted in seconds. The default value is 120 e.g.
 2 minutes. That means that after a user requested a Voice OTP he will be able to
 use this OTP value within the next 2 minutes. If the Voice arrives later or the 
 user will not use this OTP value within 2 minutes, it will not be valid
 anymore.  


Configuration details of the Voice Token Provider
--------------------------------------------------

.. index::
   CustomVoiceProvider

.. note:: At the moment the LinOTP Voice Provider in conjunction with the voice
        provider service supports only Twilio as voice provider. More provider will be
        added.

Here is a complete example configuration. Details are explained below.

.. code::

 {
 "server_url": "https://stretchvc.example.net/v1/twilio/call",
 "access_certificate":"/etc/linotp2/client-certfificate.pem",
 "server_certificate": "/etc/linotp2/root_ca.crt",
 "twilioConfig": {
     "authToken": "1234678901234567891234567891234",
     "accountSid": "AC7d3c6f34462c7c0aa84576db6a26fe28",
     "voice": "alice",
     "callerNumber": "+49123456789"}
 }

The Voice Provider configuration itself contains the configuration for the
voice challenge service:

.. code::

 {
 "server_url": "https://FQDN_VOICE_CHALLENGE_SERVER>/v1/twilio/call"
 "access_certificate": "FULLPATH_TO_CLIENT_CERTIFICATE",
 "server_certificate": "FULLPATH_TO_PNPSERVER_CERTIFICATE"
 }


``server_url``  
 holds the link to the API of KeyIdentity's voice challenge server.

**Example:**

.. code::

 "server_url": "https://voicechallenge.exampe.net/v1/twilio/call" 


``access_certificate`` 
 points to the client certificate used to authenticate against the voice
 challenge server. This is required to make sure only authenticated parties can
 trigger challenges.

**Example:**

.. code::

 "access_certificate": "/etc/linotp2/client-certfificate.pem"

``server_certificate``
 points to the server certificate (or certificate chain) of the voice challenge
 server to ensure to communicate with the correct server. 

**Example:**

.. code::

 "server_certificate": "/etc/linotp2/root_ca.crt"

.. note:: Please make sure all certificates are correct and the trusted as required. 

Additionally to the voice challenge server configuration the provider must
contain details about the actual Voice Provider used. At the moment only
`Twilio <https://www.twilio.com/voice>`_ is supported.

These are the available actions:

``accountSid``
 This is the account used to communicate with Twilio.

**Example:**

.. code::

 "accountSid": "AC7d3c6f34462c7c0aa84576db6a26fe28",

``authToken``
 This is the password for the account.

**Example:**

.. code::

 "authToken": "1234678901234567891234567891234",

``voice``
 This is an optional parameter which chose the voice used to read the OTP to
 the user.

**Example:**

.. code::

 "voice": "alice",

``callerNumber``
 This is the number the user will receive the call from. It must be registered
 at Twilio.

**Example:**

.. code::

 "callerNumber": "+49123456789",


Testing of the Voice Token
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting with version 2.10 LinOTP offers a test page for challenge response tokens:

https://LINOTP/auth/challenge-response

Enter username and OTP PIN (the PIN depends on the otppin policy) and press
`trigger`. If everything is set up correctly a call is received. Enter the OTP
in the "Submit response" section. Then press `submit`.  A pop up appears which
tells whether the authenication has been successful or not.

.. image:: images/challenge_response_test.png
   :width: 80%