Sécurisez votre application Rails avec Rails Credentials : Un guide pratique

Stockez en toute sécurité les clés API dans Rails à l'aide de Rails Credentials, puis envoyez des messages RCS avec Vonage dans ce guide d'application Rails étape par étape.

Introduction

Lorsque vous créez une application Rails qui fait appel à des services externes, la question de savoir où où stocker la configuration sensible se pose un jour ou l'autre. Clés d'API, jetons privés, identifiants pour les intégrations tierces - tous les éléments petits mais critiques qui n'ont pas leur place dans votre code source. Dans notre article précédent, Travailler avec des variables d'environnement en Rubynous avons examiné le paysage plus large des variables d'environnement et les raisons pour lesquelles les développeurs s'y fient tant.

Rails offre une autre option : Rails CredentialsRails Credentials est un moyen crypté et natif pour l'application de gérer les secrets. Ils sont conçus pour vous donner un endroit sûr pour stocker des données sensibles tout en permettant à ces données de circuler dans votre flux de travail de développement et de déploiement sans friction. Une fois que vous avez compris comment ils fonctionnent, ils deviennent une partie naturelle de la construction d'une application Rails, en particulier lors de l'intégration d'API telles que celles fournies par Vonage.

Dans cet article, nous verrons comment les Rails Credentials s'intègrent dans le tableau, en quoi ils diffèrent des variables d'environnement et comment vous pouvez les utiliser pour charger en toute sécurité les clés API de Vonage à l'intérieur d'une application Rails. À la fin de l'article, vous aurez un exemple fonctionnel intégré à une application Rails simple pour envoyer des messages texte RCS.

Commençons.

Que sont les informations d'identification Rails ?

Les Rails Credentials sont le mécanisme de stockage crypté intégré à Rails pour les éléments sensibles tels que les clés API, les jetons de service, les certificats privés et d'autres configurations qui ne devraient pas être en texte clair. Ils ont été introduits dans Rails 5.2 pour répondre à une tension commune dans le développement d'applications : les équipes ont besoin d'un moyen fiable de gérer les secrets en même temps que leur code, mais sans exposer ces valeurs dans le contrôle de version.

C'est ici que les Rails Credentials diffèrent fondamentalement des variables d'environnement. Les variables d'environnement ne sont jamais stockées dans votre référentiel. Chaque développeur, serveur ou environnement de déploiement a besoin de sa propre copie, généralement configurée par le biais de profils shell, de tableaux de bord d'hébergement ou de systèmes CI. Cette approche fonctionne, mais elle s'accompagne d'une surcharge. Lorsqu'une valeur change, elle doit être redistribuée partout où elle est utilisée, et c'est à l'équipe de maintenir ces valeurs synchronisées.

Les informations d'identification Rails adoptent une approche différente. Les secrets sont stockés dans un fichier crypté qui ne dans le référentiel. Le fichier lui-même est sûr à livrer parce qu'il ne peut être décrypté qu'avec la clé principale correspondante. L'accès aux secrets est contrôlé par l'accès à cette clé, et non par le partage manuel des valeurs individuelles.

En pratique, cela simplifie les flux de travail de l'équipe. Imaginez que vous deviez changer le secret de l'API de Vonage ou régénérer une clé privée. Avec les variables d'environnement, vous devriez distribuer en toute sécurité cette nouvelle valeur à chaque développeur et à chaque environnement qui en dépend. Avec Rails Credentials, vous mettez à jour le fichier d'informations d'identification crypté une seule fois, vous validez le changement et vous l'envoyez. Toute personne possédant déjà la clé principale peut extraire la mise à jour et continuer à travailler sans aucune configuration supplémentaire.

L'idée principale est que Rails Credentials centralise les changements de secret secrètes tout en gardant secret l secret restreint. Vous versionnez les données chiffrées, et non les valeurs en clair, ce qui facilite la gestion des mises à jour dans le temps sans disperser la configuration sur les machines, les shells ou les boîtes de réception.

Une fois que vous savez ce que Rails essaie de réaliser, le flux de travail commence à avoir plus de sens. Lorsque vous exécutez :

rails credentials:edit

Vous n'obtenez pas un fichier YAML normal. Rails ouvre une copie décryptée de vos informations d'identification en mémoire dans votre éditeur de texte. Sur le disque, le fichier réel reste entièrement crypté. Lorsque vous enregistrez et fermez l'éditeur, Rails recrypte automatiquement le contenu mis à jour. Il s'agit d'une petite boucle sécurisée : déchiffrer temporairement, modifier en toute sécurité, chiffrer à nouveau.

Le résultat est un coffre-fort intégré directement dans Rails. Il est prévisible, versionné, crypté par défaut et prêt à contenir tout ce que vous préférez ne pas divulguer dans les journaux ou coller accidentellement dans Slack avec "est-ce que ça marche pour quelqu'un d'autre ?" en pièce jointe. Il garde vos secrets fiables et votre configuration ordonnée, ce qui est particulièrement utile lorsque vous déployez à partir d'un flux de travail basé sur un référentiel (Heroku, Render, Fly.ioetc.) où votre code et votre infrastructure se déplacent ensemble.

Comment fonctionnent les informations d'identification Rails

Une fois que vous avez compris l'idée derrière Rails Credentials, les mécanismes se mettent en place rapidement. Tout est centré sur un fichier crypté : config/credentials.yml.enc. S'il n'existe pas encore, Rails le génère la première fois que vous modifiez les informations d'identification. Il reste crypté sur le disque jusqu'à ce que vous y ajoutiez des valeurs.

Ce fichier est accompagné de la clé principale, généralement stockée à l'adresse suivante config/master.key. Rails utilise cette clé pour déchiffrer les informations d'identification lorsque vous les modifiez et pour les lire au moment de l'exécution. Elle est intentionnellement ignorée par Git, puisque l'accès à la clé principale donne accès à tous les secrets que vous stockez. Rails suppose que vous fournirez cette clé à travers votre environnement de déploiement ou un autre canal sécurisé.

Lorsque vous courez :

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

Rails déchiffre le fichier d'informations d'identification à l'aide de la clé principale, ouvre une copie temporaire déchiffrée dans votre éditeur, et déchiffre à nouveau le contenu dès que vous l'enregistrez et le fermez. Cette version décryptée n'existe qu'en mémoire, sans jamais toucher le disque, ce qui rend le processus sûr et convivial pour les développeurs.

>>Note : L'utilisation de bin/rails permet de s'assurer que la commande s'exécute avec la version exacte de Rails de votre projet, et l'option --wait est nécessaire pour VS Code afin que Rails ne recrypte pas le fichier d'informations d'identification avant que vous n'ayez fini de le modifier.

La règle principale à retenir est simple : le fichier chiffré peut être transféré dans votre référentiel, mais pas la clé principale. Le système repose sur la séparation de ces deux éléments.

Rails prend également en charge les informations d'identification spécifiques à l'environnement. Vous pouvez maintenir des fichiers et des clés cryptés entièrement séparés en exécutant :

rails credentials:edit --environment production

Cela ouvre config/credentials/production.yml.enc au lieu du fichier par défaut. Chaque environnement conserve sa propre clé et son propre ensemble de secrets, ce qui est important car les identifiants de production doivent rester isolés de tout ce qui est utilisé localement.

Dans le développement quotidien, la plupart de ces éléments sont relégués au second plan. Vous écrivez YAML, Rails le chiffre et votre application le lit au moment de l'exécution sans cérémonie supplémentaire. C'est une approche simple : un fichier chiffré, une clé. Et comme il s'agit de Rails, la plus grande partie de la complexité est gérée pour vous avec une seule commande.

Ajouter les informations d'identification de l'application Vonage aux informations d'identification de Rails

Pour montrer la facilité et la puissance de Rails Credentials, nous allons créer une simple application Rails pour envoyer un message texte RCS.

Si le RCS n'est pas activé dans votre Account Vonage ou si vous ne disposez pas d'un téléphone compatible RCS pour le tester, vous pouvez remplacer le SMS ou WhatsApp par le RCS avec des flux presque identiques.

Conditions préalables

• Ruby (3.x recommandé)

• Rails 7+

• Un compte API Vonage

• Un numéro de téléphone compatible avec le RCS et un compte compatible avec le RCS (ou une solution de repli vers 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.

Créer une application Vonage

Avant de pouvoir utiliser Rails Credentials pour stocker quoi que ce soit, nous avons besoin des valeurs elles-mêmes. Pour la messagerie RCS, cela signifie créer une application Vonage avec l'API Messages.

Créez votre application dans le tableau de bord de Vonage. Donnez-lui un nom et activez la fonction Messages.

Exigences pour votre application RCS

• Définir les URL d'entrée et de statut à un point de terminaison de type "placeholder".

• Générez une clé publique et une clé privée en cliquant sur le bouton

• Enregistrer les modifications

Ensuite, reliez votre RCS Agent en cliquant sur l'onglet "Link external accounts".

À ce stade, vous devriez avoir trois valeurs prêtes pour votre projet Rails :

1. ID de l'application

2. Fichier de clés privées

3. RCS ID de l'expéditeur

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

Utilisation des identifiants Rails pour la messagerie RCS

Une fois votre Applications Vonage configurée et vos clés en main, nous pouvons passer à la partie Rails du tutoriel. L'objectif est ici de montrer comment les identifiants Rails s'intègrent naturellement dans le flux de travail d'une application réelle. Pour simplifier les choses, nous allons créer une application Rails minimale avec un seul point de terminaison qui envoie un message texte RCS à un numéro de téléphone que vous transmettez dans une requête POST.

Commencez par générer une nouvelle application Rails et ajoutez le SDK de Vonage :

rails new rails_credentials_rcs_demo --api

cd rails_credentials_rcs_demobundle add vonage

(En utilisant l'option --api permet de conserver un projet léger, mais il est facultatif si vous préférez un environnement Rails complet).

Ensuite, nous allons charger les informations d'identification de Vonage dans Rails. Ouvrez votre fichier d'identification crypté :

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

Mettez à jour le YAML avec les valeurs de votre Applications Vonage à partir du tableau de bord :

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

Sauvegardez et fermez l'éditeur. Rails va tout recrypter automatiquement, et vos informations d'identification seront désormais disponibles par l'intermédiaire de Rails.application.credentials.

>>Remarque : Lorsque vous ajoutez la clé privée aux informations d'identification, assurez-vous que chaque ligne de la clé est indentée de manière cohérente en dessous. private_key : -une indentation incorrecte provoquera des erreurs d'analyse YAML.

Avec les secrets en place, nous pouvons créer une route et un contrôleur uniques pour envoyer des messages RCS.

Ajouter une route pour le point d'extrémité :

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

Créez maintenant le contrôleur :

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

Et mettez-le à jour avec la logique d'envoi d'un message RCS à l'aide du 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

>>Note : Pour le RCS, l'élément rcs_sender_id est généralement un nom de marque (tel que "Vonage") plutôt qu'un numéro de téléphone.

Ce contrôleur reste intentionnellement minimal afin que l'accent soit mis sur le flux de travail des informations d'identification plutôt que sur la structure de Rails ou la persistance des messages. Vous passez un numéro de téléphone et une chaîne de texte optionnelle dans une requête POST, et le point de terminaison envoie un message RCS authentifié en utilisant les valeurs que vous avez cryptées dans Rails Credentials. La méthode méthode dig est très utile ici pour accéder aux données imbriquées.

Démarrez votre application Rails :

rails s

Pour tester, dans votre terminal, ouvrez un nouvel onglet. Puis déclenchez-le avec une simple commande curl à un numéro de téléphone compatible RCS :

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

En coulisses, Rails déchiffre vos informations d'identification au démarrage, le SDK Ruby de Vonage utilise votre ID d'application et votre clé privée pour créer un JWT, et l'API Messages envoie le message RCS au numéro que vous avez fourni.

Ce petit exemple illustre l'ensemble du cycle de vie : stockage sécurisé des secrets, chargement dans un environnement Rails et utilisation dans une intégration réelle sans exposition de valeurs sensibles dans le code source ou les fichiers de configuration.

Meilleures pratiques pour les informations d'identification dans les applications réelles

Utilisation des informations d'identification en production

Un jour ou l'autre, tout développeur Rails arrive au point où la configuration locale ne suffit plus et où l'application doit fonctionner dans un environnement réel. C'est généralement à ce moment-là que Rails Credentials refait surface, car la production nécessite son propre fichier crypté et sa propre clé principale.

Pour modifier les informations d'identification de la production, exécutez :

rails credentials:edit --environment production

Rails créera (ou ouvrira) un fichier crypté à l'adresse : config/credentials/production.yml.enc

et il attendra la clé maîtresse correspondante à :

config/credentials/production.key

En développement, Rails peut lire cette clé automatiquement à partir du système de fichiers. En production, cependant, vous devez fournir la clé principale par l'intermédiaire de votre environnement d'hébergement afin que l'application puisse déchiffrer les informations d'identification au démarrage.

La méthode exacte dépend de votre plateforme :

• Rendu : définir RAILS_MASTER_KEY dans le tableau de bord

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

• Heroku : l'ajouter aux vars de configuration de l'application

• VPS ou serveur personnalisé : exportez-le dans l'environnement ou dans votre unité systemd.

Rails ne démarre pas sans la bonne clé, il est donc important de s'assurer qu'elle est présente partout où votre application s'exécute.

Une ligne de conduite mérite d'être soulignée : chaque environnement a besoin de son propre passe-partout. Le développement, la mise à l'essai et la production doivent rester isolés l'un de l'autre, à la fois pour des raisons de sécurité et de clarté. Le fait de garder ces clés séparées garantit que la configuration reste limitée à l'environnement auquel elle appartient et empêche l'accès accidentel à des valeurs sensibles d'un environnement à l'autre.

Une fois la clé maîtresse de production définie, Rails s'occupe du reste ; il déchiffre les informations d'identification au démarrage et les met à la disposition de votre application de la même manière qu'elles étaient disponibles lors du développement.

Les pièges les plus courants et la façon de les résoudre

Rails Credentials prend en charge la plus grande partie de la complexité pour vous, mais il y a quelques problèmes que les développeurs rencontrent de temps en temps. Voici les plus courants et comment les résoudre.

Commettre accidentellement le passe-partout

Si la clé principale se retrouve dans Git, traitez-la comme si elle était exposée. Faites tourner les secrets concernés, générez une nouvelle clé et assurez-vous que l'original est supprimé de l'historique de contrôle des versions. Le fichier chiffré n'est sûr que si la clé principale reste privée.

Fusionner les conflits dans le fichier crypté

Comme les fichiers chiffrés ne contiennent pas de structure significative, Git ne peut pas résoudre les conflits qu'ils contiennent. Si plusieurs personnes doivent modifier des informations d'identification, coordonnez ces changements ou utilisez des informations d'identification spécifiques à l'environnement ou un gestionnaire de secrets externe pour éviter les collisions.

Les informations d'identification ne se chargent pas en production

Cela indique généralement que la clé RAILS_MASTER_KEY est manquante ou ne correspond pas à la clé utilisée pour crypter le fichier d'identifiants. Confirmez que la clé correcte a été définie dans votre environnement d'hébergement et qu'elle correspond au bon fichier crypté.

Un fichier crypté corrompu

Bien que cela soit rare, un fichier d'identification crypté peut devenir illisible. Vous pouvez le régénérer en utilisant :

rm config/credentials.yml.enc

rails credentials:edit

Veillez à réintroduire vos valeurs après avoir régénéré le fichier, car le contenu précédent ne peut être récupéré sans les données et la clé d'origine.

Quand utiliser les variables ENV

Les Rails Credentials conviennent parfaitement à de nombreuses applications, mais ils ne constituent pas la réponse universelle à la gestion des secrets. Dans certains environnements, les variables d'environnement traditionnelles restent le choix le plus approprié.

Les variables d'environnement fonctionnent bien lorsque vous déployez des architectures basées sur des conteneurs ou multiservices, où la configuration doit être injectée au moment de l'exécution plutôt que stockée dans le référentiel. Elles sont également l'option standard lorsque vous travaillez avec des systèmes d'orchestration tels que Kubernetes, ECS ou Nomad, ou lorsque vous exécutez des pipelines CI/CD qui ont besoin d'accéder à des secrets pendant les builds ou les exécutions de test. Et si plusieurs services non-Rails partagent les mêmes valeurs de configuration, l'utilisation de variables d'environnement permet de conserver une configuration cohérente dans l'ensemble de la pile.

Les Rails Credentials, en revanche, s'intègrent naturellement dans les applications qui restent dans l'écosystème Rails. Ils fournissent un stockage chiffré et versionné pour les données sensibles sans avoir à gérer de multiples fichiers .env ou de magasins de secrets externes. Ils s'intègrent également sans problème aux plateformes qui se déploient directement à partir d'un dépôt Git et attendent de l'application qu'elle fournisse sa propre configuration.

De nombreuses configurations de production combinent les deux approches - en utilisant des variables d'environnement pour les préoccupations au niveau de l'infrastructure et Rails Credentials pour les secrets spécifiques à l'application. Le bon choix dépend de la structure de votre système et de l'endroit où la configuration doit se trouver.

Conclusion

Les Rails Credentials offrent un moyen simple de gérer la configuration sensible tout en gardant à l'esprit la sécurité et la facilité de maintenance. En stockant des valeurs cryptées avec votre application et en vous appuyant sur des clés spécifiques à l'environnement, vous bénéficiez d'un modèle fiable pour gérer les secrets sans disperser la configuration dans plusieurs fichiers ou systèmes.

Associée au SDK Ruby de Vonage, cette approche s'intègre parfaitement dans les flux de travail Rails du monde réel. Votre application peut s'authentifier en toute sécurité, envoyer des messages RCS et interagir avec l'API Messages sans exposer les clés API ou les clés privées dans le code source ou les environnements shell. Il en résulte une configuration à la fois pratique et sécurisée, qui s'adapte bien à la croissance de votre application.