Click2Call
El microservicio Click2Call expone una pequeña API HTTP/JSON que origina llamadas click-to-call sin necesidad de un JWT del portal. Está pensado para ser consumido por una extensión de navegador que detecta números de teléfono en las páginas web y, al hacer clic, solicita al servicio que realice la llamada.
A diferencia de las APIs REST basadas en roles, este servicio no utiliza autenticación JWT: el llamante demuestra la propiedad de un terminal con las propias credenciales SIP del terminal mediante HTTP Digest, de modo que la contraseña nunca viaja por la red.
Si tiene éxito, el servicio lanza, a través de AMI, un Originate que reutiliza el dialplan click2dial ya existente:
Pata 1: suena el propio terminal del usuario.
Pata 2: cuando el usuario contesta, se genera la llamada hacia el
destinationsolicitado.
Nota
Este servicio se distribuye como el paquete ivozprovider-click2call y sirve HTTPS directamente en su propio puerto (9090 por defecto, ver Cortafuegos). Es independiente de las APIs REST /api/platform, /api/brand y /api/provider.
Endpoints
El flujo siempre tiene dos pasos: primero solicitar un desafío (challenge) y después realizar la llamada firmando el destino con dicho desafío.
1) POST /challenge
Solicita un nonce de un solo uso para un Address of Record (AoR).
Cuerpo de la petición:
{ "aor": "username@domain" }
Respuesta (200):
{ "nonce": "<server-issued nonce>", "realm": "domain" }
aor: elusername@domaindel terminal.realm(devuelto): la parte de dominio del AoR, a utilizar en el digest.
El nonce está firmado con HMAC, tiene una caducidad configurable (nonce_ttl) y es de un solo uso, por lo que no hay reenvío (replay). En este paso no se accede a la base de datos.
2) POST /call
Realiza la llamada. El destino debe firmarse con un digest calculado a partir de la contraseña del terminal y del nonce obtenido anteriormente.
Cuerpo de la petición:
{
"aor": "username@domain",
"nonce": "<nonce from /challenge>",
"response": "<digest response>",
"destination": "+34900000000",
"iden": "optional-call-id",
"maxDuration": 10800000,
"dialTimeout": 30,
"optimize": false
}
Respuesta (200):
{ "iden": "<call iden>" }
destination: número de destino (^[+*0-9]+$).iden(opcional): identificador proporcionado por el llamante (^[A-Za-z0-9_-]{1,32}$); si se omite, el servicio genera uno (base62 de 16 caracteres) y lo devuelve en la respuesta.maxDuration(ms, por defecto10800000),dialTimeout(s, por defecto30),optimize(booleano, por defectofalse).
El iden devuelto identifica la llamada generada: se usa como ChannelId de AMI y se propaga en la pata 2 (la llamada hacia el destino) hacia el proxy como la cabecera SIP X-Info-Click2Dial-iden. El proxy lo publica como IDEN en los eventos de tiempo real de la pata 2, de modo que la llamada puede correlacionarse con la petición /call que la originó. No se guarda en los CDRs.
Un 200 significa que Asterisk ha encolado el Originate (la acción es asíncrona), no que la llamada se haya establecido. La llamada todavía puede fallar después (el terminal no contesta, falla el destino…) y no hay forma de consultar su estado: usa el iden para seguirla en los datos de tiempo real.
Advertencia
La pata 1 se envía al terminal del usuario con la cabecera Call-Info: <...>;answer-after=0. Los terminales que la respetan descuelgan automáticamente, así que la llamada hacia el destino empieza sin que el usuario toque el teléfono.
Cálculo del digest
El digest se calcula en el lado del cliente, basado en MD5, y solo viaja response (la contraseña nunca sale del cliente):
HA1 = MD5(username : realm : password)
HA2 = MD5(destination)
response = MD5(HA1 : nonce : HA2)
El servidor lo recalcula y lo compara en tiempo constante.
Nota
En el navegador crypto.subtle no proporciona MD5; utiliza una librería como blueimp-md5 / crypto-js. El CORS se resuelve declarando el origen del servicio en los host_permissions de la extensión; el servicio devuelve los orígenes permitidos a partir de su configuración.
Códigos de error
Código |
Motivo |
|---|---|
|
JSON / AoR / destino / iden no válidos |
|
nonce no válido, caducado o reutilizado |
|
AoR no elegible (sin terminal+endpoint+usuario+extensión) o digest incorrecto |
|
no se pudo resolver el Application Server (Kamailio) ni originar la llamada (AMI) |
Por seguridad, no se revela el motivo exacto entre «el AoR no existe» y «contraseña incorrecta»: ambos devuelven 403. Solo el log del servicio los distingue.
El servicio no limita el número de peticiones: las llamadas que origina están sujetas a los límites de llamadas simultáneas de la plataforma.
Fallos de autenticación
Cada 401 y 403 de /call escribe una línea warning en el log del servicio (journalctl -u ivozprovider-click2call), con el mensaje fijo click2call auth failed y estos campos:
status:401o403.reason:invalid_nonce(401: nonce inválido, caducado, reutilizado o emitido para otro AoR),not_eligible(403: el AoR no es elegible) obad_response(403: digest incorrecto).aor: el AoR solicitado.dst: el destino solicitado.ip: la dirección IP de la conexión TCP.
level=warning msg="click2call auth failed" aor=101@example.com dst=600123123 ip=203.0.113.7 reason=bad_response status=403
El formato es estable, así que puede usarse para alertas o fail2ban. Nunca se registran el response, el nonce, la contraseña del terminal ni el iden. Se ignoran X-Forwarded-For y cabeceras similares, porque un cliente podría falsificarlas: la IP registrada es siempre la de la conexión.
Configuración
El fichero de configuración es /opt/irontec/ivozprovider/microservices/click2call/configs/config.yml, un conffile del paquete ivozprovider-click2call. Al instalarse, el paquete fija la contraseña de la base de datos y genera un digest.secret aleatorio.
TLS: el servicio usa el certificado de portals (
/etc/ssl/certs/ivozprovider-portals.pemy/etc/ssl/private/ivozprovider-portals.key). Sitls_certytls_keyestán vacíos sirve HTTP sin cifrar, solo pensado para pruebas: detrás de un proxy, el log de fallos de autenticación mostraría la dirección IP del proxy.Una sola instancia: los nonces usados se guardan en memoria, así que solo puede haber una instancia activa del servicio. En un clúster, pacemaker lo ejecuta en el nodo portals activo. En un cambio de nodo, los nonces emitidos en los últimos
nonce_ttlsegundos (30 por defecto) dejan de valer y el cliente tiene que pedir uno nuevo. Todos los nodos deben compartir el mismodigest.secret: como cada instalación genera uno aleatorio, hay que poner el mismo valor en todos los nodos portals.
Caso de uso
Un intercambio típico desde la extensión de navegador:
POST /challengecon elaordel terminal con sesión iniciada → obtenernonceyrealm.Calcular
responsea partir deusername,realm,password,noncey eldestinationsobre el que se ha hecho clic.POST /callconaor,nonce,responseydestination→ suena el terminal del usuario y, al contestar, se marca el destino. Conserva elidendevuelto para correlacionar la llamada más adelante.