Proteja seu aplicativo Rails com credenciais do Rails: um guia prático

Armazene chaves de API com segurança no Rails usando o Rails Credentials e, em seguida, envie mensagens RCS com o Vonage neste guia passo a passo para aplicativos em Rails.

Introdução

Ao compilar qualquer aplicativo Rails que utilize serviços externos, surge a questão de onde armazenar configurações confidenciais acaba surgindo. Chaves de API, tokens privados, identificadores para integrações de terceiros — todos esses pequenos, mas essenciais elementos que não devem constar no seu código-fonte. Em nosso artigo anterior, Trabalhando com variáveis de ambiente em Ruby, analisamos o panorama mais amplo das variáveis de ambiente e por que os desenvolvedores dependem tanto delas.

O Rails oferece outra opção: Credenciais do Rails, uma maneira criptografada e nativa do aplicativo de gerenciar segredos. Elas foram projetadas para oferecer um local seguro para armazenar dados confidenciais, ao mesmo tempo em que permitem que esses dados circulem pelo seu fluxo de trabalho de desenvolvimento e implantação sem atritos. Depois que você entender como elas funcionam, elas se tornarão uma parte natural da criação de um aplicativo Rails, especialmente ao integrar APIs como as fornecidas pela Vonage.

Neste artigo, vamos explicar como as credenciais do Rails se encaixam nesse contexto, em que diferem das variáveis de ambiente e como você pode usá-las para carregar com segurança as chaves da API da Vonage em uma aplicação Rails. Ao final, você terá um exemplo funcional integrado a um aplicativo Rails simples para enviar mensagens de texto RCS.

Vamos começar.

O que são credenciais do Rails?

As Credenciais do Rails são o mecanismo de armazenamento criptografado integrado ao Rails para informações confidenciais, como chaves de API, tokens de serviço, certificados privados e outras configurações que não devem ser mantidas em texto simples. Elas foram introduzidas no Rails 5.2 para resolver um desafio comum no desenvolvimento de aplicativos: as equipes precisam de uma maneira confiável de gerenciar segredos juntamente seu código, mas sem expor esses valores no controle de versão.

É nesse ponto que as credenciais do Rails diferem fundamentalmente das variáveis de ambiente. As variáveis de ambiente nunca são armazenadas no seu repositório. Cada desenvolvedor, servidor ou ambiente de implantação precisa de sua própria cópia, geralmente configurada por meio de perfis de shell, painéis de hospedagem ou sistemas de CI. Essa abordagem funciona, mas acarreta uma sobrecarga. Quando um valor muda, ele precisa ser redistribuído em todos os lugares onde é usado, e cabe à equipe manter esses valores sincronizados.

O Rails Credentials adota uma abordagem diferente. Os segredos são armazenados em um arquivo criptografado que fica fica no repositório. O arquivo em si pode ser enviado com segurança, pois só pode ser descriptografado com a chave mestra correspondente. O acesso aos segredos é controlado pelo acesso a essa chave, e não pelo compartilhamento manual de valores individuais.

Na prática, isso simplifica os fluxos de trabalho das equipes. Imagine que você precise alternar um segredo da API da Vonage ou regenerar uma chave privada. Com variáveis de ambiente, seria necessário distribuir esse novo valor de forma segura a todos os desenvolvedores e a todos os ambientes que dependem dele. Com o Rails Credentials, basta atualizar o arquivo de credenciais criptografadas uma única vez, confirmar a alteração e enviá-la. Qualquer pessoa que já tenha a chave mestra pode baixar a atualização e continuar trabalhando sem nenhuma configuração adicional.

A ideia principal é que o Rails Credentials centraliza as credenciais secretas alterações , mantendo o acesso restrito restrito. Você controla as versões dos dados criptografados, e não dos valores em texto simples, o que facilita o gerenciamento de atualizações ao longo do tempo, sem espalhar a configuração por máquinas, terminais ou caixas de entrada.

Quando você entende o que o Rails está tentando fazer, o fluxo de trabalho começa a fazer mais sentido. Ao executar:

rails credentials:edit

Você não recebe um arquivo YAML comum. O Rails abre uma cópia descriptografada das suas credenciais na memória dentro do seu editor de texto. No disco, o arquivo real permanece totalmente criptografado. Quando você salva e fecha o editor, o Rails criptografa novamente o conteúdo atualizado automaticamente. É um pequeno ciclo seguro: descriptografar temporariamente, editar com segurança, criptografar novamente.

O resultado é um cofre integrado diretamente ao Rails. É previsível, versionado, criptografado por padrão e pronto para armazenar qualquer coisa que você prefira não deixar vazar nos logs ou colar acidentalmente no Slack com a pergunta “isso funciona para mais alguém?” anexada. Ele mantém seus segredos protegidos e sua configuração organizada, o que é especialmente útil ao fazer a implantação a partir de um fluxo de trabalho baseado em repositório (Heroku, Render, Fly.io, etc.), onde seu código e sua infraestrutura funcionam em conjunto.

Como funcionam as credenciais no Rails

Depois que você entender o conceito por trás das credenciais do Rails, a mecânica se encaixa rapidamente. Tudo gira em torno de um arquivo criptografado: config/credentials.yml.enc. Se ele ainda não existir, o Rails o gera na primeira vez que você editar as credenciais. Ele permanece criptografado no disco até que você adicione valores a ele.

Junto com esse arquivo está a chave mestra, normalmente armazenada em config/master.key. O Rails usa essa chave para descriptografar credenciais quando você as edita e para lê-las durante a execução. Ela é intencionalmente ignorada pelo Git, já que o acesso à chave mestra efetivamente concede acesso a todos os segredos armazenados. O Rails presume que você fornecerá essa chave por meio do seu ambiente de implantação ou de outro canal seguro.

Ao executar:

EDITOR="code --wait" rails credentials:edit

O Rails descriptografa o arquivo de credenciais usando a chave mestra, abre uma cópia temporária descriptografada no seu editor e criptografa novamente o conteúdo assim que você salvar e fechar o arquivo. Essa versão descriptografada existe apenas na memória, sem nunca ser gravada no disco, o que torna o processo seguro e fácil de usar para os desenvolvedores.

>>Observação: Ao usar bin/rails garante que o comando seja executado com a versão exata do Rails do seu projeto, e o sinalizador é necessária no VS Code para que o Rails não volte a criptografar o arquivo de credenciais antes de você terminar a edição.

A regra principal a ser lembrada é simples: o arquivo criptografado pode ser enviado para o seu repositório, mas a chave mestra não. O sistema depende da separação desses dois elementos.

O Rails também oferece suporte a credenciais específicas para cada ambiente. É possível manter arquivos e chaves criptografados totalmente separados executando:

rails credentials:edit --environment production

Isso abre config/credentials/production.yml.enc em vez do arquivo padrão. Cada ambiente mantém sua própria chave e seu próprio conjunto de segredos, o que é importante porque as credenciais de produção devem permanecer isoladas de tudo o que é usado localmente.

No dia a dia do desenvolvimento, grande parte disso fica em segundo plano. Você escreve o YAML, o Rails o criptografa e sua aplicação o lê em tempo de execução sem complicações. É uma abordagem simples: um arquivo criptografado, uma chave. E, por se tratar do Rails, a maior parte da complexidade é resolvida para você com um único comando.

Adicionando as credenciais do aplicativo Vonage às credenciais do Rails

Para mostrar como o Rails Credentials é fácil e poderoso, vamos criar uma aplicação simples em Rails para enviar uma mensagem de texto RCS.

Se você não tiver o RCS ativado na sua conta da Vonage ou não tiver um celular compatível com RCS para fazer o teste, pode substituir o RCS por SMS ou WhatsApp, seguindo fluxos praticamente idênticos.

Pré-requisitos

• Ruby (recomenda-se a versão 3.x)

• Rails 7 ou superior

• Um account da API da Vonage

• Um número de telefone compatível com RCS e uma conta compatível com RCS (ou alternativa para SMS/WhatsApp)

Criar uma aplicação da Vonage

Antes de podermos usar o Rails Credentials para armazenar qualquer coisa, precisamos dos próprios valores. Para mensagens via RCS, isso significa criar um aplicativo da Vonage usando a Messages API. 

Crie seu aplicativo no Painel da Vonage. Dê um nome ao aplicativo e ative o recurso “Mensagens”.

Requisitos para o seu aplicativo RCS 

• Defina as URLs de entrada e de status como um endpoint provisório

• Gere uma chave pública e uma chave privada clicando no botão

• Salvar as alterações 

Em seguida, vincule seu RCS Agent clicando na guia “Vincular contas externas”.

Neste momento, você já deve ter três valores definidos para o seu projeto Rails:

1. ID do aplicativo

2. Arquivo de chave privada

3. ID do remetente RCS

Vonage Dashboard showing an application configured for RCS messaging, including linked external RCS accounts and application credentials.

Utilização das credenciais do Rails para mensagens RCS

Com o aplicativo Vonage configurado e suas chaves em mãos, podemos passar para a parte do tutorial dedicada ao Rails. O objetivo aqui é mostrar como as credenciais do Rails se encaixam naturalmente no fluxo de trabalho de um aplicativo real. Para simplificar, vamos criar um aplicativo Rails minimalista com um único endpoint que envia uma mensagem de texto RCS para um número de telefone que você passa em uma solicitação POST.

Comece criando uma nova aplicação Rails e adicionando o SDK da Vonage:

rails new rails_credentials_rcs_demo --api

cd rails_credentials_rcs_demobundle add vonage

(Usando a sinalizador --api mantém o projeto leve, mas é opcional caso você prefira um ambiente Rails full-stack.)

A seguir, vamos carregar as credenciais do Vonage no Rails. Abra seu arquivo de credenciais criptografadas:

EDITOR="code --wait" bin/rails credentials:edit

Atualize o arquivo YAML com os valores das Applications do seu aplicativo Vonage, obtidos no painel de controle:

vonage:
  application_id: "<YOUR_APPLICATION_ID>"
  private_key: |
    -----BEGIN PRIVATE KEY-----
    <contents of private_<app-id>.key here>
    -----END PRIVATE KEY-----
  rcs_sender_id: "<YOUR_RCS_SENDER_ID>"

Salve e feche o editor. O Rails irá criptografar tudo novamente automaticamente, e suas credenciais agora estarão disponíveis por meio de Rails.application.credentials.

>>Observação: Ao adicionar a chave privada às credenciais, certifique-se de que cada linha da chave esteja recuada de maneira consistente abaixo de private_key: — um recuo incorreto causará erros de análise do YAML.

Com os segredos configurados, podemos criar uma única rota e um único controlador para enviar mensagens RCS.

Adicione uma rota para o endpoint:

# config/routes.rb
post "/rcs_messages", to: "rcs_messages#create"

Agora, gere o controlador:

rails generate controller RcsMessages --no-helper --no-assets --skip-routes

E atualize-o com a lógica para enviar uma mensagem RCS usando o SDK Ruby da Vonage:

# app/controllers/rcs_messages_controller.rb

class RcsMessagesController < ApplicationController
  def create
    to   = params[:to]
    text = params[:text] || "Hello from Rails + RCS"

    client = Vonage::Client.new(
      application_id: Rails.application.credentials.dig(:vonage, :application_id),
      private_key:    Rails.application.credentials.dig(:vonage, :private_key)
    )

    client.messaging.send(
        message_type: "text",
        channel:      "rcs",
        to:           to,
        from:         Rails.application.credentials.dig(:vonage, :rcs_sender_id),
        text:         text
    )

    head :ok
  end
end

>>Observação: Para o RCS, o rcs_sender_id é geralmente um nome de marca (como “Vonage”), em vez de um número de telefone.

Este controlador foi mantido intencionalmente minimalista para que o foco permaneça no fluxo de trabalho de credenciais, em vez de na estrutura do Rails ou na persistência de mensagens. Você passa um número de telefone e uma sequência de texto opcional em uma solicitação POST, e o endpoint envia uma mensagem RCS autenticada usando os valores que você criptografou no Rails Credentials. O método `dig` é muito útil aqui para acessar dados aninhados.

Inicie sua aplicação Rails:

rails s

Para testar, no seu terminal, abra uma nova aba. Em seguida, execute o comando com um simples solicitação para um número de telefone compatível com RCS:

curl -X POST http://localhost:3000/rcs_messages \
  -d 'to=447700900000' \
  -d 'text=Hello from Rails!'

Nos bastidores, o Rails descriptografa suas credenciais na inicialização; o SDK Ruby da Vonage usa o ID do seu aplicativo e a chave privada para criar um JWT; e a Messages API envia a mensagem RCS para o número que você forneceu.

Este pequeno exemplo ilustra todo o ciclo de vida: armazenar segredos com segurança, carregá-los em um ambiente Rails e utilizá-los em uma integração real, sem expor valores confidenciais no código-fonte ou nos arquivos de configuração.

Melhores práticas para credenciais em aplicações reais

Uso de credenciais em ambiente de produção

Mais cedo ou mais tarde, todo desenvolvedor Rails chega ao ponto em que a configuração local não é mais suficiente e o aplicativo precisa ser executado em um ambiente real. É geralmente nesse momento que o Rails Credentials volta à tona, pois o ambiente de produção exige seu próprio arquivo criptografado e sua própria chave mestra.

Para editar as credenciais de produção, execute:

rails credentials:edit --environment production

O Rails criará (ou abrirá) um arquivo criptografado em: config/credentials/production.yml.enc

e ele esperará a chave mestra correspondente em:

config/credentials/production.key

No ambiente de desenvolvimento, o Rails consegue ler essa chave automaticamente do sistema de arquivos. No ambiente de produção, no entanto, é necessário fornecer a chave mestra por meio do seu ambiente de hospedagem para que o aplicativo possa descriptografar as credenciais na inicialização.

O método exato depende da sua plataforma:

• Render: definir RAILS_MASTER_KEY no painel

• Fly.io: fly secrets set RAILS_MASTER_KEY=...

• Heroku: adicione isso às variáveis de configuração do aplicativo

• VPS ou servidor personalizado: exporte-o no ambiente ou na sua unidade do systemd

O Rails não inicia sem a chave correta; por isso, é importante garantir que ela esteja presente onde quer que sua aplicação seja executada.

Vale a pena destacar uma orientação: cada ambiente precisa de sua própria chave mestra. Os ambientes de desenvolvimento, teste e produção devem permanecer isolados uns dos outros, tanto por segurança quanto por clareza. Manter essas chaves separadas garante que a configuração permaneça restrita ao ambiente ao qual pertence e evita o acesso acidental a valores confidenciais entre ambientes.

Depois que a chave mestra de produção for definida, o Rails cuida do resto; ele descriptografa as credenciais na inicialização e as disponibiliza para sua aplicação da mesma forma que estavam disponíveis no ambiente de desenvolvimento.

Armadilhas comuns e como resolvê-las

O Rails Credentials cuida da maior parte da complexidade para você, mas há alguns problemas com os quais os desenvolvedores se deparam de vez em quando. Estes são os mais comuns e como resolvê-los.

Confirmar acidentalmente a chave mestra

Se a chave mestra vier a ser exposta no Git, considere-a comprometida. Faça a rotação dos segredos afetados, gere uma nova chave e certifique-se de que a original seja removida do histórico do controle de versão. O arquivo criptografado só estará seguro se a chave mestra permanecer privada.

Resolver conflitos de mesclagem no arquivo criptografado

Como os arquivos criptografados não contêm uma estrutura significativa, o Git não consegue resolver conflitos dentro deles. Se várias pessoas precisarem editar credenciais, coordenem essas alterações ou utilizem credenciais específicas para cada ambiente ou um gerenciador externo de segredos para evitar colisões.

As credenciais não estão sendo carregadas no ambiente de produção

Isso geralmente indica que o variável de ambiente RAILS_MASTER_KEY está ausente ou não corresponde à chave usada para criptografar o arquivo de credenciais. Verifique se a chave correta foi definida em seu ambiente de hospedagem e se ela corresponde ao arquivo criptografado correto.

Um arquivo criptografado corrompido

Embora seja raro, um arquivo de credenciais criptografado pode se tornar ilegível. Você pode regenerá-lo usando:

rm config/credentials.yml.enc

rails credentials:edit

Certifique-se de inserir novamente seus valores após regenerar o arquivo, pois o conteúdo anterior não poderá ser recuperado sem os dados originais e a chave.

Quando você deve usar variáveis de ambiente

As credenciais do Rails são uma ótima opção para muitas aplicações, mas não são a solução universal para o gerenciamento de segredos. Em alguns ambientes, as variáveis de ambiente tradicionais continuam sendo a escolha mais adequada.

As variáveis de ambiente funcionam bem ao fazer a implantação em arquiteturas baseadas em contêineres ou multisserviços, nas quais a configuração precisa ser injetada em tempo de execução, em vez de ser armazenada no repositório. Elas também são a opção padrão ao trabalhar com sistemas de orquestração, como Kubernetes, ECS ou Nomad, ou ao executar pipelines de CI/CD que precisam acessar segredos durante compilações ou execuções de teste. E se vários serviços que não são do Rails compartilham os mesmos valores de configuração, o uso de variáveis de ambiente mantém essa configuração consistente em toda a pilha.

Já o Rails Credentials se encaixa naturalmente em applications que permanecem dentro do ecossistema do Rails. Ele oferece armazenamento criptografado e com controle de versão para dados confidenciais, sem a sobrecarga de gerenciar vários arquivos arquivos .env ou armazenamentos externos de segredos. Elas também se integram perfeitamente a plataformas que fazem a implantação diretamente a partir de um repositório Git e esperam que a aplicação forneça sua própria configuração.

Muitas configurações de produção combinam ambas as abordagens — utilizando variáveis de ambiente para questões relacionadas à infraestrutura e o Rails Credentials para segredos específicos da aplicação. A escolha certa depende de como seu sistema está estruturado e de onde a configuração deve ser armazenada.

Conclusão

O Rails Credentials oferece uma maneira simples de lidar com configurações confidenciais, sem deixar de lado a segurança e a facilidade de manutenção. Ao armazenar valores criptografados junto com sua aplicação e utilizar chaves específicas para cada ambiente, você conta com um padrão confiável para gerenciar segredos, sem precisar espalhar a configuração por vários arquivos ou sistemas.

Em combinação com o SDK Ruby da Vonage, essa abordagem se encaixa perfeitamente nos fluxos de trabalho reais do Rails. Seu aplicativo pode realizar autenticações com segurança, enviar mensagens RCS e interagir com a Messages API sem expor chaves de API ou chaves privadas no código-fonte ou em ambientes de shell. O resultado é uma configuração que é ao mesmo tempo prática e segura, e que se adapta bem à medida que seu aplicativo cresce.