Autenticación

Las API de Vonage admiten diferentes métodos de autenticación según el producto que estés usando:

1 Mensajes soporta tanto autenticación JWT como Básica, sin embargo la autenticación básica no soporta webhooks o características avanzadas como ACLs. Para la mayoría de los casos de uso recomendamos la autenticación JWT. Consulte Autenticación de la API de Messages

2 Verify soporta autenticación JWT y Básica, sin embargo la autenticación básica no soporta webhooks o características avanzadas como ACLs.

3 SIP Trunking utiliza Autenticación Digest con la clave de la API como usuario y el secreto de la API como contraseña.

Contenido

En este documento puedes aprender sobre la autenticación a través de los siguientes medios:

Clave y secreto de la API

Cuando creas una Account de Vonage, se crearán una clave API y un secreto para ti. Estas se encuentran en tu configuración de la Account en el Panel de Vonage. Siempre debes mantenerlos seguros y nunca comparta estos datos: tenga cuidado al añadirlo a su código base para asegurarse de que no se comparte con nadie que pueda utilizarlo de forma malintencionada. Si utiliza firmas de mensajesse generan mediante la función SIGNATURE_SECRET en lugar del API_SECRETambos valores se encuentran en su configuración de la Account.

Nota: El secreto debe mantenerse siempre seguro y nunca compartirse. Ten cuidado al añadirlo a tu código base para asegurarte de que no se comparte con nadie que pueda utilizarlo de forma malintencionada. Más información sobre Mejores prácticas de seguridad para tu Account de Vonage.

Las API de Vonage pueden requerir tu clave y secreto de API de diferentes maneras.

Autenticación básica

Algunas de las API de Vonage más recientes requieren que la autenticación se realice mediante una clave y un secreto de API enviados codificados en Base64 en el archivo Authorization de cabeza.

Para estas API, envíe su clave API y su secreto de la siguiente manera:

Authorization: Basic base64(API_KEY:API_SECRET)

Si su clave API fuera aaa012 y su secreto API eran abc123456789concatenarías la clave y el secreto con un : (dos puntos) y luego codificarlos utilizando la codificación Base64 para producir un valor como éste:

Authorization: Basic YWFhMDEyOmFiYzEyMzQ1Njc4OQ==

Aquí encontrará un sitio web para generar cadenas codificadas en Base64:

En los siguientes sitios web encontrará información detallada sobre cómo codificar cadenas Base64 en diversos lenguajes de programación:

Rotación secreta

Es posible tener dos secretos de API para ser utilizados contra una clave de API al mismo tiempo. De este modo, puede crear un segundo secreto de API y probarlo antes de revocar el secreto de API existente en su red de producción. El procedimiento de rotación del secreto de API consta de los siguientes pasos:

  1. Cree un segundo secreto de API en su configuración de la Account o utilizando la función API de rotación secreta.
  2. Actualiza uno o más de tus servidores para que utilicen el nuevo secreto de API creado para realizar llamadas a las API de Vonage
  3. Compruebe que no hay problemas de conectividad y despliegue la actualización del secreto de la API en el resto de servidores.
  4. Borrar el secreto de API reemplazado

Tokens web JSON

Tokens web JSON (JWT) son un medio compacto y seguro de URL para representar declaraciones que deben transferirse entre dos partes. Para obtener una lista completa de las API que utilizan JWT, consulte la tabla sobre.

Cabecera y carga útil

Los JWT constan de un encabezado y una carga útil. Los valores de la cabecera son:

Nombre Descripción Requerido
alg El algoritmo de cifrado utilizado para generar el JWT. RS256 es compatible.
typ La estructura de fichas. Establecida en JWT.

Los valores para la demanda de carga útil son:

Nombre Descripción Requerido
application_id El ID único asignado a tu aplicación por Vonage.
iat La marca de tiempo UNIX en UTC + 0 que indica el momento en que se solicitó el JWT.
jti Un identificador de cadena único del JWT.
nbf La marca de tiempo UNIX en UTC + 0 que indica el momento en que el JWT se hizo válido.
exp La marca de tiempo UNIX en UTC + 0 que indica el momento en que el JWT deja de ser válido. Un valor mínimo de 30 segundos desde el momento en que se genera el JWT. Un valor máximo de 24 horas desde el momento en que se genera el JWT. Un valor por defecto de 15 minutos desde el momento en que se genera el JWT.

Generación de JWT

Uso de la CLI de Vonage para generar JWT

En CLI de Vonage proporciona un comando para generar un JWT.

Un ejemplo de generación de un JWT para una aplicación es el siguiente:

# A command with parameters
vonage jwt create `
--app-id='00000000-0000-0000-0000-000000000000' `
--private-key=./private.key

# Will produce a token
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzYyODE5NDYsImp0aSI6IjBmZjcwZDNmLTAzN2EtNGY4MC04ODZjLWI3MmM3MmQyMWNmMiIsImlhdCI6MTczNjI4MTA0NiwiYXBwbGljYXRpb25faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ.gA7jClpqaZ2OoS0iri-zGCbda4jO7C0M8mka0EnSyjlds1EeY8fNoBEx3FTXHfkkzzrj0TskrWc_dcs1wuM8Kx55c5rLQ7taVpDAYopKSc_CeeOaad8S6aWnRkTUTNeduO4aIn-0CbyRTluBYsH1RBqYBQvobuQIDEwbFw8xBgx0UfREMMN6DAWknR57eiVXN9x_oD6CGQJ1yV3025nGboeMsP9YgX4Nwc-rE2r8c1ZGwCLO81x8i19Qil3Nwu5q1nzouyavQjIw00B_TZkushnI1ufdi_GNqk-h5q2HvGkg7Pj9bVkZHFdVTO8im03JYNyJmcV83vnpjOLuCFRzxQ

La clave privada en cuestión se genera desde el cuadro de mandos de la aplicación o desde vonage apps create. Puede guardar esta información para la CLI ejecutando vonage auth set. El contenido de la clave privada se guardará en el sitio .vonagerc archivo o $HOME/.vonage/config.json.

Puedes encontrar más información sobre la CLI de Vonage en su en GitHub.

Se pueden encontrar ejemplos de uso de las bibliotecas de Vonage para generar JWTs debajo de. Si no utiliza una biblioteca de Vonage, consulte RFC 7519 para implementar JWTs.

SDK de cliente de Vonage

Vonage Cliente y Vídeo Los SDK utilizan JWT para la autenticación cuando un cliente se conecta a Vonage. Estos JWT se generan utilizando el ID de la aplicación y la clave privada que se proporciona cuando se crea una nueva aplicación.

Reclamaciones

Utilizando ese private.key y el ID de la aplicación, puedes acuñar un nuevo JWT. Para registrar a un usuario en un cliente de Vonage, el JWT necesitará las siguientes afirmaciones:

Vonage Client SDK
Reclamación Descripción
sub El "asunto". El asunto, en este caso, será el nombre del usuario creado y asociado con tu aplicación de Vonage.
acl Lista de control de acceso. El Client SDK la utiliza como sistema de permisos para los usuarios. Más información en Visión general de ACL.
application_id Este es el ID de la aplicación de Vonage que creaste.
iat "Issued at time" Es la hora a la que se emitió el JWT, en tiempo de época unix.
jti "ID JWT". Se trata de un identificador de cadena único para este JWT.
exp "Expiration time" Esta es la hora en el futuro en la que expirará el JWT, en tiempo de época unix.

En exp es opcional. Si no se proporciona el claim, el JWT expirará por defecto en 15 minutos. El tiempo máximo de expiración de un JWT es de 24 horas. Normalmente, los JWT deberían durar poco, ya que es trivial crear un nuevo JWT y algunos JWT pueden tener múltiples permisos de gran alcance.

Ejemplo de carga útil JWT de Client SDK

Una vez que se hayan proporcionado todas las reclamaciones, las reclamaciones resultantes deberían aparecer así:

{
  "iat": 1532093588,
  "jti": "705b6f50-8c21-11e8-9bcb-595326422d60",
  "sub": "alice",
  "exp": "1532179987",
  "acl": {
    "paths": {
      ...
    }
  },
  "application_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

( ... fragmento truncado)

SDK de cliente de vídeo de Vonage
Reclamación Descripción
sub El "asunto". El asunto, en este caso, debe ser la cadena video.
acl Lista de control de acceso. El Client SDK la utiliza como sistema de permisos para los usuarios. Más información en Visión general de ACL.
application_id Este es el ID de la aplicación de Vonage que creaste.
session_id Este es el ID del Sesión que has creado.
scope Es el ámbito del token. Debe ser la cadena session.connect.
role Es la función del token. Puede ser un rango de cadena valores dependiendo de los permisos que quieras conceder a este token.
data Estos metadatos personalizados se pueden añadir opcionalmente para describir el token. Se trata de una cadena limitada a 1000 caracteres.
initial_layout_class_list Esto le permite, opcionalmente, al emitir, especificar la inicial lista de clases de diseño para los flujos publicados por el cliente.
iat "Issued at time" Es la hora a la que se emitió el JWT, en tiempo de época unix.
jti "ID JWT". Se trata de un identificador de cadena único para este JWT.
exp "Expiration time" Esta es la hora en el futuro en la que expirará el JWT, en tiempo de época unix.

En exp es opcional. Si no se proporciona el claim, el JWT caducará por defecto en 24 horas. El tiempo máximo de expiración para un JWT de Video SDK es de 30 días. Por lo general, los JWT deben ser de corta duración, ya que es trivial crear un nuevo JWT y algunos JWT pueden tener múltiples permisos de gran alcance. Asegúrese siempre de intentar establecer un exp al menor tiempo posible para su aplicación.

Ejemplo de carga útil JWT del Client SDK de vídeo
{
  "scope": "session.connect",
  "session_id": "1_MX44YjY4NTFmZS01NjdjLTRlODYtYWRmOC0zYmVhODM2MzNjNjB-fjE3NDIzMDY0ODY0NjZ-WS9FOHhybUdHV0JtTGZYTEV2aVlwV1N4fn5-",
  "role": "moderator",
  "initial_layout_class_list": "",
  "sub": "video",
  "acl": {
    "paths": {
      "/session/**": {}
    }
  },
  "jti": "c04c96ba-3229-4fd4-9f55-406b6a6eb485",
  "iat": 1742306486,
  "exp": 1742307386,
  "application_id": "8b6851fe-567c-4e86-adf8-3bea83633c60"
}

Lista de control de acceso (ACL)

En el ejemplo de carga útil de solicitud JWT anterior, observe cómo el acl reclamación tiene un paths objeto. El objeto path contiene una lista de endpoints que corresponden a ciertos permisos que tiene un usuario cuando utiliza el Client SDK.

A continuación se muestra la lista de puntos finales a los que puede conceder acceso a un usuario:

Punto final Descripción Necesario para
/*/rtc/** Crear sesión de señalización para recibir eventos y enviar métricas Llamadas/mensajes dentro de la aplicación
/*/sessions/** Iniciar sesión como usuario de voz o chat dentro de la aplicación Llamadas/mensajes dentro de la aplicación
/*/users/** Obtención de conversaciones de usuario, sesiones de usuario y objeto de usuario Llamadas/mensajes dentro de la aplicación
/*/conversations/** Crear y gestionar conversaciones y enviar/recibir mensajes Llamadas/mensajes dentro de la aplicación
/*/knocking/** Iniciar llamadas telefónicas Llamadas dentro de la aplicación
/*/devices/** Registrar el dispositivo para recibir notificaciones push Llamadas/mensajes dentro de la aplicación
/*/legs/** Crear y gestionar tramos en una conversación Llamadas dentro de la aplicación
/*/session/** Conectarse a una sesión de vídeo Vídeo

Debe proporcionar al usuario que está generando permisos para acceder sólo a las rutas relevantes. Por ejemplo, si el usuario del Voice Client SDK no va a necesitar obtener información sobre su objeto Usuario u otros Usuarios, debe omitir la ruta users camino. Para ilustrarlo mejor, si se añade la /*/conversations/** a la ACL de un JWT, el usuario podrá crear y gestionar conversaciones. Además, si este es el sólo ACL, el usuario sólo tendrá acceso a la carpeta /conversations punto final.

Nota: El uso de comodines en sus rutas ACL (por ejemplo. /*/conversations/**) permitirá al token JWT acceder a todas las operaciones para ese endpoint. Se recomienda encarecidamente que utilice un control más granular de sus rutas ACL como se ilustra a continuación.

Rutas ACL granulares

Arriba vimos cómo conceder a los usuarios acceso a los endpoints. También puede limitar o conceder acceso basado en sub-rutas y métodos HTTP. Esto le permite definir de forma muy granular qué permisos debe tener un token. Por ejemplo, en tu aplicación Voice Client SDK quieres que los usuarios puedan obtener información sobre una conversación:

{
  "acl": {
    "paths": {
      "/*/conversations/**": {}
    }
  }
}

Las rutas ACL anteriores permiten cualquiera con este token para realizar peticiones a cualquier Punto final de Conversation API vinculado a tu aplicación de Vonage. Esto permitirá a quien tenga este token obtener una lista de las conversaciones en curso en tu aplicación, crear nuevas conversaciones o más. Para mitigar esto, puedes especificar qué rutas específicamente deben ser accesibles y qué métodos HTTP se permiten usar en esas rutas.

{
  "acl": {
    "paths": {
      "/*/conversations/*": {
        "methods": [
          "GET"
        ]
      }
    }
  }
}

Estas nuevas rutas ACL permiten a cualquier persona con este token sólo hacer un GET a una conversación específica y no a otras sub-rutas u operaciones. Lo cual es mucho más restrictivo que antes.

Rutas ACL mínimas para SDK de cliente

A continuación se detallan las rutas ACL mínimas necesarias para realizar varias acciones en los SDK del cliente de Vonage. Para agregar compatibilidad con más terminales según tu caso de uso, consulta la sección Tabla ACL anteriores y añadirlos de la forma más restrictiva posible.

Esto soporta el caso de uso básico de crear una sesión, utilizando serverCall, reconnectCally poder responder, rechazar o colgar una llamada.

{
  "acl": {
    "paths": {
      "/*/sessions/**": { "methods": ["POST"] },
      "/*/conversations/*": { "methods": ["GET"] },
      "/*/conversations/*/rtc/*/answer": { "methods": ["POST"] },
      "/*/conversations/*/rtc/*/offer/*": { "methods": ["POST"]},
      "/*/conversations/*/members/*": { "methods": ["PUT", "DELETE"] },
      "/*/knocking/**": { "methods": ["POST", "DELETE"] },
      "/*/legs/**": { "methods": ["POST", "GET"] },
      "/*/v2/rtc/**": { "methods": ["POST", "GET"] }
    }
  }
}

Generación de JWT mediante la CLI de Vonage

En SDK de servidor contienen métodos para generar tokens JWT. Sin embargo, puede utilizar el método CLI de Vonage para hacer esto también. Esto es especialmente útil durante las pruebas.

# A command with parameters
vonage jwt create `
--app-id='00000000-0000-0000-0000-000000000000' `
--private-key=./private.key `
--sub='Alice' `
--acl='{\"paths\":{\"\/*\/users\/**\":{},\"\/*\/conversations\/**\":{},\"\/*\/sessions\/**\":{},\"\/*\/devices\/**\":{},\"\/*\/push\/**\":{},\"\/*\/knocking\/**\":{},\"\/*\/legs\/**\":{}}}'

# Will produce a token
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2wiOnsicGF0aHMiOnsiLyovcnRjLyoqIjp7fSwiLyovdXNlcnMvKioiOnt9LCIvKi9jb252ZXJzYXRpb25zLyoqIjp7fSwiLyovc2Vzc2lvbnMvKioiOnt9LCIvKi9kZXZpY2VzLyoqIjp7fSwiLyovcHVzaC8qKiI6e30sIi8qL2tub2NraW5nLyoqIjp7fSwiLyovbGVncy8qKiI6e319fSwiZXhwIjoxNzQxMTgyMzA3LCJzdWIiOiJBbGljZSIsImp0aSI6Ijg1MTViNzk2LTA1YjktNGFkMS04MTRkLTE1NWZjZTQzZWM1YiIsImlhdCI6MTc0MTE4MTQwNywiYXBwbGljYXRpb25faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ.BscMdDXZ1-nuLtKyPJvw9tE8E8ZjJvTPJPMT9y0TjPz4Q7qqNaqxcjglc5QPtYEjh2YpZH6btSKbUF4XTClI026Hl5_QOBlnayYo7jXwhba16fa5PeyzSf30QFGFrHbANwrQJFVCjd329SZUpwK4GxgB1gf230NhbfmkhegKezqicru2WTGCKm8kQncYliFwIEYUlcRAb2c8xcaVrn_6QNNahyeJRwGFfWpIkX0Oe-S4RDlPjoq47_gYWac9MmaetB4Dd3Yp531AuniGV5JiIShkaEwuY4Zyov4Hcmajm4Lm_UFY119la7vzHis0P7cT9pPUDe5cyPj7eT8-VhitfQ

Uso de los SDK de servidor

Se espera que el servidor que acompaña a tu aplicación de Vonage genere JWT para los SDK de cliente. Estos son algunos ejemplos que utilizan los SDK de servidor de Vonage:

Versión 3 del SDK de servidor de nodo de Vonage incluye un paquete para generar tokens JWT. También puede generar un JWT utilizando las reclamaciones adecuadas.

const { tokenGenerate } = require('@vonage/jwt');

const privateKey = readFileSync('path/to/private.key');

const aclPaths = {
  "paths": {
    ...
  }
}

const token = tokenGenerate("aaaaaaaa-bbbb-cccc-dddd-0123456789ab", privateKey, {
      //expire in 24 hours
      exp: Math.round(new Date().getTime()/1000)+86400,
      sub: "Alice",
      acl: aclPaths,
    });

( ... fragmento truncado)

Si no utilizas una biblioteca de Vonage, consulta RFC 7519 para implementar JWT. JWT.io dispone de una selección de bibliotecas para generar JWT en varios idiomas.