Lançamento do Nexmo Ruby v7.2.0

O SDK do Nexmo para Ruby lançou recentemente uma nova versão, a v7.2.0. Nessa nova versão, o recurso de geração de JSON Web Tokens foi reescrito para utilizar a nova nexmo-jwt gem do Ruby para gerar tokens.

A gem nexmo-jwt oferece aos usuários mais flexibilidade na criação de um token que atenda exatamente às suas necessidades específicas e, como parte desta versão, essa funcionalidade agora está disponível para todos os usuários do próprio SDK.

Qual é a finalidade dos tokens JSON da Web (JWTs)?

Os JWTs são utilizados em muitos dos nossos serviços de API para fins de autenticação. Um JWT é um mecanismo autônomo para o compartilhamento seguro de informações entre máquinas.

Cada JWT da Vonage é assinado com um par de chaves pública e privada utilizando o algoritmo RSA256 . O processo de codificação e decodificação de um token por meio desse par de chaves permite que se estabeleça confiança entre o cliente e o servidor.

Conforme mencionado, algumas das APIs mais recentes e repletas de recursos da Vonage utilizam JSON Web Tokens para autenticar e se comunicar com segurança. Essas APIs incluem Voice, Mensagens, Dispatch e Conversation.

O Guia de Autenticação no portal do desenvolvedor traz uma lista completa de cada API e quais modos de autenticação ela suporta.

A geração manual de um JWT totalmente autenticado para uso com as APIs da Vonage envolve uma grande complexidade. É possível fazer isso, e temos um guia também no portal do desenvolvedor que explica o processo passo a passo.

No entanto, devido a todos os parâmetros interligados e complexos que isso exige, recomendamos o uso de um de nossos SDKs para que ele faça o trabalho por você.

Geração de JWT pelas APIs da Vonage em Ruby: o que mudou?

Desde que a autenticação JWT foi introduzida no SDK do Nexmo para Ruby, ela utilizou o gem , que é uma biblioteca em conformidade com os padrões para a criação de JWTs em Ruby. Isso significava que grande parte da validação dos requisitos específicos da Vonage ficava a cargo do usuário.

Isso também significava que a geração assistida de JWT para desenvolvedores Ruby que trabalhavam com as APIs da Vonage só era possível no SDK; mesmo que não precisassem de todas as funcionalidades do SDK, eles ainda precisavam instalá-lo em seus aplicativos.

Essas razões nos levaram a criar uma biblioteca separada, específica para a geração de JWT, nexmo-jwt. Essa gem Ruby da Vonage para JWT pode ser usada dentro do SDK do Ruby e, o que é igualmente importante, fora do SDK, de forma independente.

Como recurso adicional, nos empenhamos em simplificar também o que você precisa saber para gerar JWTs para as APIs da Vonage. Além disso, oferecemos orientações sobre o tratamento personalizado de exceções quando seus parâmetros precisarem ser aprimorados.

Geração de um JWT

O nexmo-jwt gem pode ser usada dentro do SDK do Nexmo para Ruby e de forma independente, conforme mencionado. Dentro do SDK, mantivemos o mesmo nome e a mesma estrutura dos métodos para garantir a compatibilidade com versões anteriores:

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

Se você já utilizou o SDK do Nexmo para Ruby para gerar um JWT anteriormente, provavelmente está acostumado a fornecer o private_key como um parâmetro separado para o método. Embora você possa fazer isso, não é mais necessário. Você pode incluir o private_key dentro do claims hash, conforme mostrado acima.

Outro detalhe que você notará é que não estamos mais fornecendo um parâmetro de validade explícito com uma exp chave e um valor inteiro representando o tempo da máquina no sistema Unix.

Em vez disso, calculamos esses dados para você com base nos requisitos das APIs da Vonage. Você pode modificar o resultado final fornecendo um valor personalizado ttl ou um valor de “time to live” (TTL) como um número inteiro que represente um número de segundos.

No entanto, isso também não é necessário. Por padrão, são adicionados 900 segundos (15 minutos) a partir do momento em que o JWT é gerado para calcular o tempo até sua expiração.

O processo de geração de um JWT usando nexmo-jwt fora do SDK é semelhante, mas com algumas pequenas diferenças:

require 'nexmo-jwt'

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

Personalização de um JWT

Você também pode adicionar qualquer um desses parâmetros personalizados, além de ttl como mencionamos acima, na instanciação da Nexmo::JWTBuilder classe:

• nbf: Carimbo de data/hora do Unix (UTC+0), em segundos, a partir do qual o JWT passa a ser válido

• paths: Informações de caminho em um hash para controle de acesso às rotas da API

• sub: “Assunto” ou string criada pelo usuário e associada ao aplicativo Nexmo

Por exemplo, se você quisesse criar um token com paths, subject e ttl informações, você faria o seguinte:

@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 saber mais sobre o SDK do Nexmo para Ruby e as APIs da Vonage, você pode ler a documentação em RubyDoc e encontrar trechos de código, guias, tutoriais e muito mais em nosso portal do desenvolvedor.