Sviluppo

Autenticazione

Lo scopo della fase d’autenticazione è creare un token che sarà usato per le operazioni future, quali l’invocazione delle REST API o per creare una connessione permanente (WebSocket o TCP).

Eseguire il login

  1. Il client invia una richiesta HTTP (POST) alla seguente rest api:
https://<SERVER>/webrest/authentication/login

specificando lo _username_ e _password_ in formato JSON:

{ "username": "my_user", "password": "my_password" }
  1. Il client riceve una risposta standard HTTP 401. Se l’autenticazione ha avuto successo la risposta contiene un nonce (una stringa) nello header HTTP, altrimenti l’autenticazione è fallita. Un esempio di header è (il nonce è 06d15944d8ece69bdc97742b37c507970e2f6651):
www-authenticate: Digest 06d15944d8ece69bdc97742b37c507970e2f6651
  1. Il client calcola il token:
tohash = username + ':' + password + ':' + nonce
token  = HMAC-SHA1(tohash, password)
  1. Il client memorizza il token per usi futuri.

Se il token d’autenticazione non viene mai usato, scade dopo un certo periodo di tempo (il default è mezz’ora). Una nuova fase d’autenticazione è necessaria.

Eseguire il logout

  1. Il client invia una richiesta HTTP (POST) alla seguente rest api:
https://<SERVER>/webrest/authentication/logout
  1. Il token viene rimosso dal server.

REST API

Le REST API sono dei Web Services che consentono l’interazione con il server NethCTI. È uno strumento molto utile per l’integrazione e lo sviluppo ed è la miglior soluzione da utilizzare con applicazioni mobile.

Nota

Questo documento assume che il lettore possegga già una certa familiarità con le più comuni tecniche di programmazione e Web Services.

Come usare una API

Di seguito vengono elencate le caratteristiche comuni a tutte le REST API:

  • una API viene invocata tramite l’invio di una richiesta HTTP[S] al server NethCTI che risponde fornendo i dati richiesti o tramite un codice di stato o entrambi.
  • I codici di stato delle risposte HTTP sono quelli standard.
  • Il formato utilizzato per lo scambio dati è JSON.
  • Tutte le risorse sono raggiungibili tramite l’urli base:
http[s]://<SERVER>/webrest/
  • Per richiedere una API è necessario aggiungere un patì al baseurl che specifica la risorsa da richiedere. Per esempio:
http[s]://<SERVER>/webrest/phonebook/search
  • Ogni richiesta deve contenere i parametri d’autenticazione per il controllo d’accesso, specificando lo header HTTP Authorization:
Authorization: username:token
  • Ogni richiesta viene autenticata e autorizzata del server NethCTI.

Autenticazione

  1. L’autenticazione di una richiesta REST viene eseguita dal server controllando la validità del token passato. Quindi, come fase preliminare, Il client deve eseguire il login e deve creare un token d’autenticazione come descritto qui.
  2. Ogni richiesta deve contenere lo header HTTP Authorization:
Authorization: username:token

La validità del token d’autenticazione viene aggiornato ad ogni richiesta, altrimenti scade dopo un certo intervallo temporale (di default pari a un’ora). Dopo la scadenza è necessaria una nuova fase d’autenticazione.

Autorizzazione

Ogni richiesta REST API viene autorizzata dal server che controlla i permessi utente configurati dall’amministratore attraverso l’interfaccia di NethVoice.

Esempio d’uso con cURL

L’esempio seguente mostra come eseguire una richiesta rest tramite cURL. Lo strumento si può rivelare utile per eseguire dei test e per comprendere il meccanismo delle chiamate con maggior dettaglio.

  1. Supponiamo di volere effettuare la ricerca in rubrica del contatto nethesis per estrarre il numero telefonico. La prima operazione da eseguire è l’autenticazione (è necessaria solamente la prima volta per la costruzione del token).
curl --insecure -i -X POST -d "username=my_user&password=my_password" https://192.168.5.226/webrest/authentication/login

L’autenticazione ha successo e il server risponde con:

HTTP/1.1 401 Unauthorized
Date: Thu, 12 Jun 2014 13:01:43 GMT
www-authenticate: Digest f4700adb35ad29ee16afe6c03c0196dfc74ec3b1
Content-Length: 0
Content-Type: text/plain
  1. Estraiamo il nonce dall’header www-authenticate:
f4700adb35ad29ee16afe6c03c0196dfc74ec3b1
  1. Costruiamo il token d’autenticazione:
tohash = "my_user:my_password:f4700adb35ad29ee16afe6c03c0196dfc74ec3b1"
token  = HMAC-SHA1("my_user:my_password:f4700adb35ad29ee16afe6c03c0196dfc74ec3b1", "my_password") = "1d8062d1c85a8fe6983745a1ee318d1cd9b8bde1"

$ echo -n "my_user:my_password:f4700adb35ad29ee16afe6c03c0196dfc74ec3b1" | openssl dgst -sha1 -hmac "my_password"
(stdin)= 1d8062d1c85a8fe6983745a1ee318d1cd9b8bde1
  1. Chiamiamo la rest api phonebook/search:
curl --insecure -i -H "Authorization: my_user:1d8062d1c85a8fe6983745a1ee318d1cd9b8bde1" https://192.168.5.226/webrest/phonebook/search/nethesis
  1. Il server invia la risposta in format JSON con i dati richiesti:
{
   "centralized": [
       {
           "id": 1916,
           "owner_id": "",
           "type": "Reseller",
           "homeemail": null,
           "workemail": "info@nethesis.it",
           "homephone": null,
           "workphone": "0721405516",
           "cellphone": "",
           "fax": "",
           "title": null,
           "company": "NETHESIS SRL ",
           "notes": "",
           "name": "",
           "homestreet": null,
           "homepob": null,
           "homecity": null,
           "homeprovince": null,
           "homepostalcode": null,
           "homecountry": null,
           "workstreet": "VIA DEGLI OLMI, 12",
           "workpob": null,
           "workcity": "PESARO",
           "workprovince": null,
           "workpostalcode": null,
           "workcountry": null,
           "url": "http://www.nethesis.it"
       }
   ],
   "nethcti": []
}

Elenco delle API NethCTI

Path Descrizione
/astproxy Interazione con il server Asterisk
/authentication Funzionalità d’autenticazione
/authorization Funzionalità per i permessi utente
/callernote Funzionalità relative alle note sulle chiamate
/histcallernote Storico delle note sulle chiamate relative al proprio utente
/all_histcallernote Storico delle note sulle chiamate di tutti gli utenti del sistema
/configmanager Funzionalità relative alla configurazione degli utenti e di NethCTI
/custcard Funzionalità relative alle schede clienti
/historycall Storico delle chiamate del proprio utente
/histcallswitch Storico delle chiamate di tutti gli utenti del sistema
/cel Consente di recuperare informazioni dettagliate sulle chiamate dal CEL di Asterisk
/phonebook Funzionalità relative alle rubriche
/postit Funzionalità relative ai POST-IT
/historypostit Storico dei POST-IT dell’utente
/all_historypostit Storico dei POST-IT di tutti gli utenti del sistema
/sms Funzionalità relative agli SMS
/historysms Storico degli SMS dell’utente
/all_historysms Storico degli SMS di tutti gli utenti del sistema
/streaming Funzionalità sulle sorgenti video
/voicemail Funzionalità relative alle voicemail

WebSocket

La connessione WebSocket viene utilizzata dal server per comunicare in tempo reale con tutti i client connessi (ad esempio per notificare gli eventi del server Asterisk). Per stabilire una connessione WebSocket col server NethCTI è necessaria una prima fase d’autenticazione.

Eseguire il login

  1. Il client esegue il login e crea un nuovo token d’autenticazione come descritto qui.
  2. Il client stabilisce una connessione websocket con il server (la porta di default sicura è la 8181).
  3. Il client invia il messaggio login al server attraverso la connessione websocket specificando username e token in formato JSON:
socket.emit('login', { accessKeyId: username, token: token.toString() });
  1. Se il login ha avuto successo il client riceve il messaggio authe_ok, altrimenti il messaggio 401 e il client viene disconnesso.

Una volta completato il login con successo, il token ha validità infinita fino al riavvio del server.

Sottoscrizione eventi

Attraverso la connessione WebSocket vengono emessi i seguenti eventi:

Evento Descrizione
extenUpdate Aggiornamento di stato di un interno telefonico
updateNewVoiceMessages Invia tutti i nuovi messaggi vocali in corrispondenza dell’arrivo di uno nuovo
newVoiceMessageCounter Invia il numero di nuovi messaggi vocali in corrispondenza dell’arrivo di uno nuovo
updateNewPostit Invia tutti i nuovi post-it dell’utente in corrispondenza dell’arrivo di uno nuovo
newPostitCounter Invia il numero di nuovi post-it, in corrispondenza dell’arrivo di uno nuovo
endpointPresenceUpdate Notifica il cambiamento della presence di un endpoint di un utente
queueMemberUpdate Aggiornamento di stato di un agente di una coda
trunkUpdate Aggiornamento di stato di un fascio
extenRinging Notifica che un interno sta squillando e riporta l’identificativo del chiamante
queueUpdate Aggiornamento di stato di una coda
parkingUpdate Aggiornamento di stato di un parcheggio
wsClientLoggedIn Un utente ha effettuato il login a NethCTI
allWsClientDisonnection Un utente non ha più nessuna connessione WebSocket attiva
401 L’autenticazione è fallita
authe_ok L’autenticazione è avvenuta con successo

Ogni evento fornisce i dati relativi in formato JSON.

È possibile sottoscrivere un ascoltare per ciascuno degli eventi. Un esempio è il seguente:

socket.on('extenUpdate', function (data) {
    // all the code here
});

Integrazione di applicazioni legacy

Per mantenere compatibilità con le applicazioni legacy che usano le API della versione 1.x, NethCTI offre la possibilità di fare telefonate invocando una particolare API senza autenticazione. Questa funzionalità è disabilitata di default per motivi di sicurezza.

Per l’attivazione eseguire:

config setprop nethcti-server UnAutheCall enabled
signal-event nethcti-server-update

Una volta attivata è possibile fare una telefonata eseguendo la richiesta HTTP GET:

https://<SERVER>/webrest/astproxy/unauthe_call/:endpoint/:number

dove :endpoint deve essere sostituito con l’interno telefonico che si vuole utilizzare e :number deve essere sostituito con il numero da chiamare.

Esempio per chiamare il numero 0721405516 tramite l’interno 214 tramite il server nethvoice.server.it:

https://nethvoice.server.it/webrest/astproxy/unauthe_call/214/0721405516

Può essere utilizzato anche il protocollo HTTP.

Avvertimento

Se la funzionalità viene abilitata, chiunque può eseguire telefonate da qualsiasi interno verso qualsiasi destinazione tramite una richiesta HTTP GET.

Per la disabilitazione eseguire:

config setprop nethcti-server UnAutheCall disabled
signal-event nethcti-server-update