Nexmo Ruby v7.2.0 Release

Le Nexmo Ruby SDK a récemment publié une nouvelle version, v7.2.0. Cette nouvelle version a réécrit la fonction de génération de jetons Web JSON afin d'utiliser la nouvelle gemme nexmo-jwt Ruby pour générer des tokens.

La gemme nexmo-jwt gem offre aux utilisateurs une plus grande flexibilité dans la conception d'un jeton répondant exactement à leurs besoins spécifiques, et dans le cadre de cette version, cette fonctionnalité est désormais disponible pour tous les utilisateurs du SDK lui-même.

À quoi servent les jetons Web JSON (JWT) ?

Les JWT sont utilisés pour un grand nombre de nos services API à des fins d'authentification. Un JWT est un mécanisme autonome permettant de partager des informations en toute sécurité entre des machines.

Chaque JWT de Vonage est signé à l'aide d'une paire de clés publique et privée utilisant le protocole RSA256 algorithme RSA256. Le processus d'encodage et de décodage d'un jeton à l'aide de cette paire de clés permet d'établir la confiance entre le client et le serveur.

Comme nous l'avons mentionné, certaines des API les plus récentes et les plus riches en fonctionnalités de Vonage tirent parti des jetons Web JSON pour s'authentifier et communiquer en toute sécurité. Ces API comprennent Voice, Messages, Dispatch et Conversation.

Guide d'authentification Guide d'authentification sur le portail des développeurs contient une liste complète de chaque API et du mode d'authentification qu'elle prend en charge.

La génération manuelle d'un JWT entièrement authentifié pour l'utiliser avec les API de Vonage est très complexe. Il est possible de le faire, et nous avons un un guide également sur le portail des développeurs qui explique le processus étape par étape.

Cependant, en raison de tous les paramètres complexes et interdépendants qu'il requiert, nous vous recommandons d'utiliser l'un de nos kits de développement logiciel (SDK) pour faire le travail à votre place.

Vonage APIs JWT Generation in Ruby : Qu'est-ce qui a changé ?

Depuis que l'authentification JWT a été introduite dans le SDK Nexmo Ruby, elle s'appuie sur la fonction jwt qui est une bibliothèque conforme aux normes pour construire des JWT en Ruby. Cela signifie qu'une grande partie de la validation des exigences spécifiques à Vonage a été laissée à l'utilisateur.

Cela signifiait également que la génération assistée de JWT pour les développeurs Ruby travaillant avec les API de Vonage n'était possible que dans le SDK, même s'ils n'avaient pas besoin de toutes les fonctionnalités du SDK, ils devaient toujours l'installer dans leur application.

Ces raisons nous ont amenés à créer une bibliothèque séparée spécifiquement pour la génération de JWT, nexmo-jwt. Cette gemme Ruby JWT de Vonage peut être utilisée à l'intérieur du SDK Ruby etet, ce qui est tout aussi important, en dehors du SDK de manière autonome.

Nous avons également simplifié ce que vous devez savoir pour générer des JWT pour les API de Vonage. Nous vous aidons également à gérer les exceptions personnalisées lorsque vos paramètres ont besoin d'être améliorés.

Générer un JWT

La gem nexmo-jwt peut être utilisée dans le SDK Ruby de Nexmo et de manière autonome, comme indiqué. Dans le SDK, nous avons conservé le même nom de méthode et la même structure pour des raisons de compatibilité ascendante :

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

Si vous avez utilisé le SDK Nexmo Ruby pour générer un JWT précédemment, vous avez probablement l'habitude de fournir le paramètre private_key en tant que paramètre séparé de la méthode. Bien que vous puissiez le faire, ce n'est plus nécessaire. Vous pouvez inclure le paramètre private_key à l'intérieur du hash claims comme indiqué ci-dessus.

Vous remarquerez également que nous ne fournissons plus de paramètre d'expiration explicite avec une clé exp et une valeur entière représentant le temps machine Unix.

Au lieu de cela, nous calculons ces données pour vous avec ce que les API de Vonage exigent. Vous pouvez modifier le résultat final en fournissant une valeur personnalisée de ttl ou une valeur "time to live" personnalisée d'un nombre entier représentant un nombre de secondes.

Toutefois, cela n'est pas nécessaire non plus. Par défaut, 900 secondes (15 minutes) sont ajoutées à partir du moment où le JWT est généré pour calculer son délai d'expiration.

Le processus de génération d'un JWT à l'aide de nexmo-jwt en dehors du SDK est similaire, mais avec quelques légères différences :

require 'nexmo-jwt'

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

Personnaliser un JWT

Vous pouvez également ajouter n'importe lequel de ces paramètres personnalisés, en plus de ttl comme nous l'avons mentionné ci-dessus, dans l'instanciation de la Nexmo::JWTBuilder dans l'instanciation de la classe

• nbf: Horodatage Unix (UTC+0), en secondes, lorsque le JWT devient valide

• paths: Informations sur le chemin d'accès dans un hachage pour le contrôle d'accès aux itinéraires de l'API

• sub: "Sujet" ou Chaîne créée par l'utilisateur et associée à l'application Nexmo.

Par exemple, si vous souhaitez créer un jeton avec un nom de domaine personnalisé paths, subject et ttl vous devez procéder comme suit :

@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

Pour en savoir plus sur le SDK Nexmo Ruby et les API de Vonage, vous pouvez lire la documentation sur RubyDoc et trouver des extraits de code, des guides, des tutoriels et plus encore sur notre portail des développeurs.