Lanzamiento de Nexmo Ruby v7.2.0

El SDK Ruby de Nexmo ha publicado recientemente una nueva versión, v7.2.0. Esta nueva versión ha reescrito la función de generación de Token Web JSON para utilizar la nueva gema de nexmo-jwt Ruby gem para generar tokens.

El sitio gema nexmo-jwt ofrece a los usuarios más flexibilidad a la hora de diseñar un token que se ajuste exactamente a sus necesidades específicas, y como parte de esta versión, esa funcionalidad está ahora disponible para todos los usuarios del propio SDK.

¿Para qué sirven los tokens web JSON (JWT)?

Los JWT se utilizan en muchos de nuestros servicios API para la autenticación. Un JWT es un mecanismo autónomo para compartir información de forma segura entre máquinas.

Cada JWT de Vonage se firma con un par de claves pública y privada utilizando el protocolo RSA256 . El proceso de codificación y descodificación de un token mediante este par de claves permite establecer la confianza entre el cliente y el servidor.

Como se mencionó, algunas de las API más nuevas y con más funciones de Vonage aprovechan los tokens web JSON para autenticarse y comunicarse de manera segura. Estas API incluyen Voice, Messages, Dispatch y Conversation.

En Guía de autenticación del portal para desarrolladores contiene una lista completa de cada API y el modo de autenticación que admite.

Generar a mano un JWT con todas las credenciales para usarlo con las API de Vonage es muy complejo. Es posible hacerlo, y tenemos una guía también en el portal para desarrolladores que explica el proceso paso a paso.

Sin embargo, debido a todos los parámetros interrelacionados y complejos que requiere, recomendamos utilizar uno de nuestros SDK para que haga el trabajo por usted.

Generación de JWT de API de Vonage en Ruby: ¿Qué ha cambiado?

Desde que se introdujo la autenticación JWT en el SDK Ruby de Nexmo, se utilizó la función jwt Ruby gem, que es una librería que cumple con los estándares para construir JWTs en Ruby. Esto significaba que gran parte de la validación de los requisitos específicos para Vonage se dejaba al usuario.

También significaba que la generación asistida de JWT para los desarrolladores de Ruby que trabajaban con las API de Vonage sólo era posible en el SDK, incluso si no requerían la funcionalidad completa del SDK, aún necesitaban instalarlo en su aplicación.

Estas razones nos llevaron a crear una librería separada específicamente para la generación de JWT, nexmo-jwt. Esta gema Vonage JWT Ruby se puede utilizar dentro del SDK de Ruby yy, lo que es igualmente importante, también fuera del SDK de manera independiente.

Como característica adicional, hemos trabajado para simplificar lo que necesitas saber para generar JWT para las API de Vonage. También te guiamos con el manejo de excepciones personalizadas cuando tus parámetros necesitan mejoras.

Generación de un JWT

La gema nexmo-jwt se puede utilizar dentro del SDK de Nexmo Ruby y de forma independiente, como se ha mencionado. Dentro del SDK, hemos mantenido el mismo nombre de método y estructura para compatibilidad con versiones anteriores:

claims = {
    application_id: application_id,
    private_key: 'path/to/private_key',
    ttl: 800,
    subject: 'My_Subject'
  }
token = Nexmo::JWT.generate(claims)

Si has utilizado el SDK Ruby de Nexmo para generar un JWT anteriormente, probablemente estés acostumbrado a proporcionar el parámetro private_key como un parámetro separado al método. Aunque puedes hacerlo, ya no es necesario. Puedes incluir el parámetro private_key dentro del hash claims como se muestra arriba.

Otro elemento que observará es que ya no proporcionamos un parámetro de caducidad explícito con una clave exp y un valor entero que representa el tiempo de máquina Unix.

En su lugar, calculamos esos datos para ti con lo que requieren las API de Vonage. Puedes modificar el resultado final proporcionando un valor personalizado ttl o valor de "tiempo de vida" de un número entero que represente una cantidad de segundos.

Sin embargo, tampoco es necesario. El valor predeterminado es añadir 900 segundos (15 minutos) desde el momento en que se genera el JWT para calcular su tiempo hasta la expiración.

El proceso para generar un JWT utilizando nexmo-jwt fuera del SDK es similar, pero con algunas ligeras diferencias:

require 'nexmo-jwt'

@builder = Nexmo::JWTBuilder.new(application_id: application_id, private_key = 'path/to/private/key')
@token = @builder.jwt.generate

Personalización de un JWT

También puede añadir cualquiera de estos parámetros personalizados, además de ttl como hemos mencionado anteriormente, en la instanciación de la clase Nexmo::JWTBuilder clase:

• nbf: Unix Timestamp (UTC+0), en segundos, cuando el JWT se convierte en válido

• paths: Información de ruta en un Hash para control de acceso a rutas API

• sub: "Asunto" o Cadena creada por el usuario y asociada a la Aplicación Nexmo

Por ejemplo, si quisieras crear un token con custom paths, subject y ttl personalizados, lo harías de la siguiente manera:

@builder = Nexmo::JWTBuilder.new(
  application_id: YOUR_APPLICATION_ID,
  private_key: YOUR_PRIVATE_KEY,
  ttl: 500,
  paths: {
    "acl": {
      "paths": {
        "/messages": {
          "methods": ["POST", "GET"],
          "filters": {
            "from": "447977271009"  
          }     
        }  
      }   
    }
  },
  subject: 'My_Custom_Subject'
)

@token = @builder.jwt.generate

Para obtener más información sobre el SDK Ruby de Nexmo y las API de Vonage, puedes leer la documentación en RubyDoc y encontrar fragmentos de código, guías, tutoriales y mucho más en nuestro portal para desarrolladores.