Uso de chaves privadas em variáveis de ambiente

Este artigo foi atualizado em março de 2025

Muitas de nossas APIs mais recentes utilizam JWTs (JSON Web Tokens) para autenticação, o que é ótimo. No entanto, como nossos JWTs são assinados com chaves privadas e contêm caracteres de nova linha, isso às vezes pode atrapalhar algumas de nossas abordagens habituais para lidar com credenciais!

Esta publicação mostrará como você pode usar uma chave privada em uma variável de ambiente e apresentará um exemplo prático disso com a Voice API da Vonage e uma função do Netlify.

Então vá em frente e crie um aplicativo com recursos de Voice; você precisará do ID do aplicativo e do arquivo da chave privada para a próxima etapa.

Você pode usar o painel da sua conta de Account para essa parte ou usar a CLI da seguinte maneira:

vonage apps create private

O comando exibirá o ID do aplicativo e gravará a chave privada no arquivo com o nome bastante criativo private.key . Ambos os itens são usados na próxima etapa.

Por que não basta simplesmente enviar o arquivo?

Os dados estão aqui private.key, certo? Por que não podemos simplesmente usar esse arquivo que temos no disco?

No caso de uma aplicação local, isso é perfeitamente possível, e você verá que muitos das nossas aplicações de exemplo fazem exatamente isso.

No entanto, para um aplicativo “real”, o private.key arquivo não faz parte do aplicativo e não pode ser tratado da mesma forma que os outros arquivos.

Um private.key arquivo nunca deve ser adicionado ao controle de versão; ele é uma credencial secreta, assim como a senha da sua conta. Também é provável que diferentes conjuntos de credenciais sejam usados com esse aplicativo em diferentes plataformas, como sua plataforma de desenvolvimento local ou quando o aplicativo for implantado em uma plataforma de teste ou de produção.

Pensando nisso, preciso encontrar outra maneira segura de lidar com essa chave privada como uma string.

Criar um aplicativo básico de chamadas de voz

Uma ótima maneira de ver isso em ação é criar um aplicativo que utilize a Voice API. Acho que nunca vou me cansar de fazer meu celular tocar por meio de programação!

O exemplo de hoje usa o Node.js e faz uma ligação telefônica com um anúncio simples gerado por conversão de texto em fala.

Antes de escrever o código, vou instalar o dependência do Vonage Node SDK :

Agora é hora do código! Para um aplicativo tão simples, geralmente coloco tudo em index.js, mais ou menos assim:

const Vonage = require('@vonage/server-sdk');

const vonage = new Vonage({
  applicationId: process.env.VONAGE_APPLICATION_ID,
  privateKey: Buffer.from(process.env.VONAGE_APPLICATION_PRIVATE_KEY64, 'base64')
})

vonage.calls.create({
  to: [{
    type: 'phone',
    number: process.env.TO_NUMBER
  }],
  from: {
    type: 'phone',
    number: process.env.VONAGE_NUMBER
  },
  ncco: [{
    "action": "talk",
    "text": "Safely handling environment variables makes coding even more fun."
  }]
}, (error, response) => {
  if (error) console.error(error)
  if (response) console.log(response)
})

Dê uma olhada no exemplo de código e você perceberá que há vários pontos em que ele faz referência a variáveis de ambiente com process.env.*.

O uso de variáveis de ambiente é uma ótima maneira de criar um código que funcione perfeitamente em mais de um lugar, pois, em cada cenário, ele simplesmente verificará os valores disponíveis e os utilizará.

Em particular, prefiro o ambiente em vez de arquivos de configuração para plataformas em nuvem, nas quais posso fazer a implantação a partir do controle de código-fonte, mas nunca incluiria credenciais nesse local.

Para plataformas locais, eu uso o dotenv para carregar variáveis de ambiente a partir de um arquivo de configuração. Ao usar o dotenv, ou em algumas plataformas de nuvem como o Netlify e o Glitch, não é possível usar valores com várias linhas para uma variável de ambiente. Para contornar isso, uso valores codificados em base64 para minhas variáveis de ambiente e faço com que meu aplicativo decodifique os valores antes de usá-los.

Preparação das variáveis de ambiente

Para uso local do dotenv, ou para uma plataforma que não suporta variáveis de ambiente com várias linhas, eu preparo um .env arquivo assim:

TO_NUMBER=44777000777
VONAGE_NUMBER=44777000888
VONAGE_APPLICATION_ID=abcd1234-aaaa-bbbb-cccc-0987654321ef
VONAGE_APPLICATION_PRIVATE_KEY64=LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2UUlCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktjd2dnU2pBZ0VBQW9JQkFRQ25VaFp3N214cTljZHUKU21oL1UrekovdGRZSUxRVDF5VExjWnFETk11OW44WUVHMmMyR1JUbmR2a2cxeXlBVCtqTk45Zmp5eTg1Zi9EOG9zTzhPdnhRS0Y0aWpoblJlVTVDQStnU0o3UEhLa3U5YjJsMzZ2TmN5WFFCdWRJVk8KV2tBOERraTlFVHpqaG8rRnh0SGJuWGZHa3o3emtzUTJvMjVMemorblFkendCQlc3aXVrNVNqdkdYSkFEK0xQRUIveHhUVEhSRFZJRjNxYWM2dmM5L3NPUStYa0MvVzB4MzgKUDg0T3JpdjhNdytCdktOZlMwMU94Y05PWU9yMENvYWM4Z1VxazljQ2dZRUFtYmFMYjROeEE3ckdkc1B1YU9UOEpSSjN6L2J0VzdnMXF4NUxvCkZ0b1c2Qm9vSnhmb2lhV1YrTURtcEFsL2FJZzRqMGJ1cXFwajU3UjlZWlhTK0xhdU1HUWl0azRPWi9ZS1lZSDUKK3psWTJ0VjhHUTdqM29CWURDd2puWWc9Ci0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0K

Se você estiver definindo variáveis de ambiente por outro meio, como por meio de uma interface web, também poderá reutilizar esses valores nesse local.

Os valores devem ser:

• TO_NUMBER o número para ligar; usei o número do meu celular

• VONAGE_NUMBER um número que tenho na plataforma da Vonage

• VONAGE_APPLICATION_ID o ID do aplicativo que criei na primeira seção

• VONAGE_APPLICATION_PRIVATE_KEY64 o conteúdo do meu private.key arquivo, codificado em base64

O comando que uso para obter o valor em base64 é:

Junte tudo isso

Ao codificar as variáveis de ambiente com caracteres de nova linha, podemos transferi-las com segurança como strings. Usando a configuração acima com o index.js arquivo que trouxemos anteriormente, posso executar meu código localmente (adicionando-o dotenv ao meu aplicativo) ou em qualquer outra plataforma.

É uma coisinha, mas sempre me deparo com isso em lugares inesperados ao lidar com os arquivos de chave privada; por isso, tenho certeza de que eu mesmo voltarei a consultar este post.