Proteja su aplicación Rails con credenciales Rails: Guía práctica

Almacena de forma segura las claves API en Rails utilizando Rails Credentials y luego envía mensajes RCS con Vonage en esta guía paso a paso de aplicaciones Rails.

Introducción

Cuando se crea una aplicación aplicación Rails que toca servicios externos, la cuestión de dónde almacenar la configuración sensible. Claves API, tokens privados, identificadores para integraciones de terceros... todas esas piezas pequeñas pero críticas que no deben estar en el código fuente. En nuestro artículo anterior, Trabajando con Variables de Entorno en Rubyvimos el panorama más amplio de las variables de entorno y por qué los desarrolladores dependen tanto de ellas.

Rails ofrece otra opción: Credenciales Railsuna forma encriptada y nativa de la aplicación de gestionar secretos. Están diseñadas para ofrecer un lugar seguro en el que almacenar datos confidenciales al tiempo que permiten que esos datos se muevan por el flujo de trabajo de desarrollo y despliegue sin fricciones. Una vez que entiendes cómo funcionan, se convierten en una parte natural de la construcción de una aplicación Rails, sobre todo cuando se integran APIs como las proporcionadas por Vonage.

En este artículo, veremos cómo encajan las credenciales de Rails, en qué se diferencian de las variables de entorno y cómo puedes usarlas para cargar de forma segura las claves de la API de Vonage dentro de una aplicación Rails. Al final, tendrás un ejemplo funcional conectado a una sencilla aplicación Rails para enviar mensajes de texto RCS.

Empecemos.

¿Qué son las credenciales Rails?

Las credenciales Rails son el mecanismo de almacenamiento cifrado integrado en Rails para datos confidenciales como claves API, tokens de servicio, certificados privados y otras configuraciones que no deberían estar en texto plano. Se introdujeron en Rails 5.2 para resolver una tensión común en el desarrollo de aplicaciones: los equipos necesitan una forma fiable de gestionar secretos junto con su código, pero sin exponer esos valores en el control de versiones.

Aquí es donde las credenciales Rails difieren fundamentalmente de las variables de entorno. Las variables de entorno nunca se almacenan en el repositorio. Cada desarrollador, servidor o entorno de despliegue necesita su propia copia, normalmente configurada a través de perfiles de shell, paneles de control de alojamiento o sistemas CI. Este enfoque funciona, pero conlleva una sobrecarga. Cuando un valor cambia, tiene que ser redistribuido dondequiera que se utilice, y depende del equipo mantener esos valores sincronizados.

Las credenciales Rails tienen un enfoque diferente. Los secretos se almacenan en un archivo cifrado que no en el repositorio. El archivo en sí es seguro porque sólo puede ser descifrado con la clave maestra correspondiente. El acceso a los secretos se controla mediante el acceso a esa clave, no compartiendo manualmente valores individuales.

En la práctica, esto simplifica los flujos de trabajo del equipo. Imagina que necesitas rotar un secreto de la API de Vonage o regenerar una clave privada. Con variables de entorno, tendrías que distribuir de forma segura ese nuevo valor a cada desarrollador y a cada entorno que dependa de él. Con Credenciales Rails, actualizas el archivo cifrado de credenciales una vez, confirmas el cambio y lo envías. Cualquiera que ya tenga la clave maestra puede obtener la actualización y continuar trabajando sin ninguna configuración adicional.

La idea clave es que las credenciales Rails centralizan los secretos cambios manteniendo en secreto acceso restringido. Tú versionas los datos encriptados, no los valores en texto plano, lo que facilita la gestión de las actualizaciones a lo largo del tiempo sin dispersar la configuración entre máquinas, shells o bandejas de entrada.

Una vez que sabes lo que Rails intenta conseguir, el flujo de trabajo empieza a tener más sentido. Cuando se ejecuta:

rails credentials:edit

No obtienes un archivo YAML normal. Rails abre una copia descifrada de tus credenciales en memoria dentro de tu editor de texto. En el disco, el archivo real permanece completamente encriptado. Cuando guardas y cierras el editor, Rails vuelve a encriptar los contenidos actualizados automáticamente. Es un pequeño bucle seguro: desencriptar temporalmente, editar con seguridad, encriptar de nuevo.

El resultado es una caja de seguridad integrada directamente en Rails. Es predecible, versionado, encriptado por defecto, y listo para contener cualquier cosa que preferirías que no se filtrara en los logs o que accidentalmente pegaras en Slack con un "¿esto funciona para alguien más?" adjunto. Mantiene tus secretos fiables y tu configuración ordenada, lo que es especialmente útil cuando se despliega desde un flujo de trabajo basado en repositorios (Heroku, Render, Fly.ioetc.) donde su código y su infraestructura se mueven juntos.

Cómo funcionan las credenciales Rails

Una vez que se entiende la idea que hay detrás de Rails Credentials, la mecánica encaja rápidamente. Todo se centra alrededor de un archivo encriptado config/credentials.yml.enc. Si aún no existe, Rails lo genera la primera vez que se editan las credenciales. Permanece encriptado en el disco hasta que le añades valores.

Junto con ese archivo se encuentra la clave maestra, normalmente almacenada en config/master.key. Rails utiliza esta clave para descifrar las credenciales cuando las editas y para leerlas en tiempo de ejecución. Git la ignora intencionadamente, ya que el acceso a la clave maestra permite acceder a todos los secretos almacenados. Rails asume que proporcionarás esa clave a través de tu entorno de despliegue u otro canal seguro.

Cuando corras:

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

Rails descifra el archivo de credenciales utilizando la clave maestra, abre una copia temporal descifrada en tu editor y vuelve a cifrar el contenido en cuanto guardas y cierras. Esa versión descifrada sólo existe en la memoria, nunca toca el disco, lo que mantiene el proceso seguro y amigable para el desarrollador.

>>Nota: Utilizando bin/rails asegura que el comando se ejecuta con la versión exacta de Rails de tu proyecto, y el parámetro --wait es necesario en VS Code para que Rails no vuelva a cifrar el archivo de credenciales antes de que terminemos de editarlo.

La regla principal a recordar es simple: el archivo encriptado puede ser enviado a tu repositorio, pero la llave maestra no. El sistema se basa en mantener esas dos piezas separadas.

Rails también admite credenciales específicas del entorno. Puedes mantener archivos y claves encriptados completamente separados ejecutando:

rails credentials:edit --environment production

Esto abre config/credenciales/produccion.yml.enc en lugar del archivo predeterminado. Cada entorno mantiene su propia clave y su propio conjunto de secretos, lo cual es importante porque las credenciales de producción deben permanecer aisladas de cualquier cosa que se utilice localmente.

En el desarrollo del día a día, mucho de esto pasa a un segundo plano. Escribes YAML, Rails lo cifra y tu aplicación lo lee en tiempo de ejecución sin ceremonias adicionales. Es un enfoque sencillo: un archivo cifrado, una clave. Y como se trata de Rails, la mayor parte de la complejidad se gestiona con un único comando.

Cómo añadir credenciales de aplicaciones de Vonage a credenciales de Rails

Para mostrar lo fácil y potente que es Rails Credentials, vamos a crear una sencilla aplicación Rails para enviar un mensaje de texto RCS.

Si no tienes RCS habilitado en tu cuenta de Vonage o no tienes un teléfono habilitado para RCS para probar, puedes sustituir RCS por SMS o WhatsApp con flujos casi idénticos.

Requisitos previos

• Ruby (se recomienda la versión 3.x)

• Rails 7+

• Una cuenta API de Vonage

• Un número de teléfono habilitado para RCS y Account habilitado para RCS (o SMS/WhatsApp)

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Crear una aplicación de Vonage

Antes de que podamos utilizar las Credenciales Rails para almacenar cualquier cosa, necesitamos los propios valores. Para la mensajería RCS, eso significa crear una Aplicación Vonage con el Messages API.

Crea tu aplicación en el panel de Vonage. Dale un nombre a la aplicación y activa la función Mensajes.

Requisitos para su aplicación RCS

• Establezca las URL de entrada y de estado en un punto final de marcador de posición

• Genere una clave pública y privada pulsando el botón

• Guardar los cambios

A continuación, vincule su Agente RCS haciendo clic en la pestaña "Vincular cuentas externas".

Llegados a este punto, deberías tener listos tres valores para tu proyecto Rails:

1. ID de aplicación

2. Archivo de clave privada

3. ID de remitente RCS

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

Uso de credenciales Rails para mensajería RCS

Con tu aplicación de Vonage configurada y tus claves en la mano, podemos pasar a la parte de Rails del tutorial. El objetivo aquí es mostrar cómo las Credenciales Rails encajan de forma natural en el flujo de trabajo de una aplicación real. Para simplificar las cosas, crearemos una aplicación Rails mínima con un único punto final que envía un mensaje de texto RCS a un número de teléfono que pasas en una solicitud POST.

Empieza generando una nueva aplicación Rails y añadiendo el SDK de Vonage:

rails new rails_credentials_rcs_demo --api

cd rails_credentials_rcs_demobundle add vonage

(Usando el comando --api mantiene el proyecto ligero, pero es opcional si prefieres un entorno Rails completo).

A continuación, cargaremos las credenciales de Vonage en Rails. Abre tu archivo de credenciales encriptadas:

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

Actualiza el YAML con los valores de tu aplicación de Vonage desde el panel:

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>"

Guarda y cierra el editor. Rails volverá a cifrar todo automáticamente, y tus credenciales estarán ahora disponibles a través de Rails.application.credentials.

>>Nota: Cuando añada la clave privada a las credenciales, asegúrese de que cada línea de la clave está sangrada de forma consistente debajo de clave_privada: -una sangría incorrecta causará errores de análisis de YAML.

Con los secretos en su lugar, podemos crear una única ruta y controlador para enviar mensajes RCS.

Añade una ruta para el punto final:

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

Ahora genera el controlador:

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

Y actualízalo con la lógica para enviar un mensaje RCS usando el SDK Ruby de 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

>>Nota: Para RCS, el rcs_sender_id suele ser un nombre de marca (como "Vonage") en lugar de un número de teléfono.

Este controlador se mantiene intencionadamente mínimo para que el foco permanezca en el flujo de trabajo de las credenciales más que en la estructura de Rails o la persistencia de mensajes. Pasamos un número de teléfono y una cadena de texto opcional en una petición POST, y el endpoint envía un mensaje RCS autenticado utilizando los valores que hemos cifrado dentro de Rails Credentials. El método método dig es muy útil para acceder a datos anidados.

Inicie su aplicación Rails:

rails s

Para probarlo, en tu terminal, abre una nueva pestaña. A continuación, actívalo con un simple curl a un número de teléfono habilitado para RCS:

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

Entre bastidores, Rails descifra tus credenciales al inicio, el SDK Ruby de Vonage utiliza tu ID de aplicación y clave privada para crear un JWT, y la Messages API envía el mensaje RCS al número que proporcionaste.

Este pequeño ejemplo captura todo el ciclo de vida: almacenar secretos de forma segura, cargarlos en un entorno Rails y utilizarlos en una integración real sin exponer valores sensibles en código fuente o archivos de configuración.

Mejores prácticas para credenciales en aplicaciones reales

Uso de credenciales en producción

Con el tiempo, todo desarrollador Rails llega a un punto en el que la configuración local no es suficiente y la aplicación necesita ejecutarse en un entorno real. Suele ser entonces cuando resurgen las credenciales Rails porque producción requiere su propio archivo cifrado y su propia clave maestra.

Para editar las credenciales de producción, ejecute:

rails credentials:edit --environment production

Rails creará (o abrirá) un archivo cifrado en: config/credentials/production.yml.enc

y esperará la llave maestra correspondiente en:

config/credentials/production.key

En desarrollo, Rails puede leer esta clave automáticamente desde el sistema de archivos. En producción, sin embargo, debes proporcionar la clave maestra a través de tu entorno de alojamiento para que la aplicación pueda descifrar las credenciales en el arranque.

El método exacto depende de su plataforma:

• Render: set RAILS_CLAVE_MAESTRO en el panel de control

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

• Heroku: añádelo a las variables de configuración de la aplicación

• VPS o servidor personalizado: expórtelo en el entorno o en su unidad systemd

Rails no se iniciará sin la clave correcta, por lo que es importante asegurarse de que está presente dondequiera que se ejecute la aplicación.

Merece la pena insistir en una directriz: cada entorno necesita su propia llave maestra. Desarrollo, puesta en escena y producción deben permanecer aislados unos de otros, tanto por seguridad como por claridad. Mantener estas claves separadas asegura que la configuración se mantiene en el entorno al que pertenece, y evita el acceso accidental a valores sensibles entre entornos.

Una vez establecida la clave maestra de producción, Rails se encarga del resto; descifra las credenciales en el arranque y las pone a disposición de tu aplicación de la misma forma que estaban disponibles en desarrollo.

Errores comunes y cómo resolverlos

Las credenciales de Rails se encargan de la mayor parte de la complejidad por ti, pero hay algunos problemas que los desarrolladores se encuentran de vez en cuando. Estos son los más comunes y cómo solucionarlos.

Confirmar accidentalmente la llave maestra

Si la clave maestra llega a Git, trátala como expuesta. Rota los secretos afectados, genera una nueva clave y asegúrate de que la original se elimina del historial del control de versiones. El archivo cifrado sólo es seguro si la clave maestra sigue siendo privada.

Fusionar conflictos en el archivo encriptado

Dado que los archivos encriptados no contienen una estructura significativa, Git no puede resolver conflictos dentro de ellos. Si varias personas necesitan editar credenciales, coordina esos cambios o confía en credenciales específicas del entorno o en un gestor de secretos externo para evitar colisiones.

Las credenciales no se cargan en producción

Esto suele indicar que la RAILS_CLAVE_MAESTRA falta o no coincide con la clave utilizada para cifrar el archivo de credenciales. Confirma que se ha establecido la clave correcta en tu entorno de alojamiento y que corresponde al archivo cifrado correcto.

Un archivo cifrado dañado

Aunque es poco frecuente, un archivo de credenciales cifrado puede volverse ilegible. Puedes regenerarlo utilizando:

rm config/credentials.yml.enc

rails credentials:edit

Asegúrese de volver a introducir sus valores después de regenerar el archivo, ya que el contenido anterior no puede recuperarse sin los datos y la clave originales.

Cuándo debe utilizar variables ENV

Las credenciales Rails se adaptan bien a muchas Applications, pero no son la respuesta universal a la gestión de secretos. En algunos entornos, las variables de entorno tradicionales siguen siendo la opción más adecuada.

Las variables de entorno funcionan bien cuando se despliega en arquitecturas basadas en contenedores o multiservicio, en las que la configuración debe inyectarse en tiempo de ejecución en lugar de almacenarse en el repositorio. También son la opción estándar cuando se trabaja con sistemas de orquestación como Kubernetes, ECS o Nomad, o cuando se ejecutan canalizaciones CI/CD que necesitan acceso a secretos durante las compilaciones o las ejecuciones de prueba. Y si varios servicios que no son Rails comparten los mismos valores de configuración, el uso de variables de entorno mantiene la coherencia en toda la pila.

Las credenciales Rails, por otro lado, encajan de forma natural en las Applications que permanecen dentro del ecosistema Rails. Proporcionan almacenamiento cifrado y versionado para datos confidenciales sin la sobrecarga de gestionar múltiples archivos .env o almacenes secretos externos. También se integran sin problemas con plataformas que se despliegan directamente desde un repositorio Git y esperan que la aplicación proporcione su propia configuración.

Muchas configuraciones de producción combinan ambos enfoques: el uso de variables de entorno para cuestiones relacionadas con la infraestructura y el uso de credenciales Rails para secretos específicos de la aplicación. La elección correcta depende de cómo esté estructurado el sistema y de dónde tenga que residir la configuración.

Conclusión

Las credenciales de Rails ofrecen una forma sencilla de gestionar la configuración confidencial sin perder de vista la seguridad y la facilidad de mantenimiento. Al almacenar valores cifrados junto con la aplicación y depender de claves específicas del entorno, se obtiene un patrón fiable para gestionar secretos sin dispersar la configuración en varios archivos o sistemas.

En combinación con el SDK Ruby de Vonage, este enfoque se adapta perfectamente a los flujos de trabajo Rails del mundo real. Tu aplicación puede autenticarse de forma segura, enviar mensajes RCS e interactuar con Messages API sin exponer claves API o claves privadas en entornos de código fuente o shell. El resultado es una configuración práctica y segura que se adapta al crecimiento de la aplicación.