Sichern Sie Ihre Rails-App mit Rails Credentials: Ein praktischer Leitfaden

Speichern Sie API-Schlüssel sicher in Rails mit Rails Credentials und senden Sie dann RCS-Nachrichten mit Vonage in dieser Schritt-für-Schritt-Anleitung für Rails-Anwendungen.

Einführung

Wenn Sie eine beliebige Rails-Anwendung die mit externen Diensten in Verbindung steht, stellt sich die Frage wo sensible Konfigurationen gespeichert werden sollen, stellt sich irgendwann. API-Schlüssel, private Token, Identifikatoren für Integrationen von Drittanbietern - all die kleinen, aber kritischen Teile, die nicht in Ihren Quellcode gehören. In unserem vorherigen Artikel, Arbeiten mit Umgebungsvariablen in Rubyhaben wir uns mit den Umgebungsvariablen im Allgemeinen befasst und erklärt, warum Entwickler sich so sehr auf sie verlassen.

Rails bietet eine weitere Möglichkeit: Rails Credentialsist eine verschlüsselte, anwendungsspezifische Methode zur Verwaltung von Geheimnissen. Sie wurden entwickelt, um Ihnen einen sicheren Ort für die Speicherung sensibler Daten zu bieten und gleichzeitig zu ermöglichen, dass diese Daten ohne Reibungsverluste durch Ihren Entwicklungs- und Bereitstellungsworkflow laufen. Wenn Sie erst einmal verstanden haben, wie sie funktionieren, werden sie ein natürlicher Bestandteil der Entwicklung einer Rails-Anwendung, insbesondere bei der Integration von APIs wie denen von Vonage.

In diesem Artikel gehen wir darauf ein, wie Rails Credentials ins Bild passen, wie sie sich von Umgebungsvariablen unterscheiden und wie Sie sie verwenden können, um Vonage API-Schlüssel sicher in eine Rails-Anwendung zu laden. Am Ende werden Sie ein funktionierendes Beispiel haben, das in eine einfache Rails-Anwendung integriert ist, um RCS-Textnachrichten zu versenden.

Fangen wir an.

Was sind Rails Credentials?

Rails Credentials sind der in Rails eingebaute, verschlüsselte Speichermechanismus für sensible Dinge wie API-Schlüssel, Service-Tokens, private Zertifikate und andere Konfigurationen, die nicht im Klartext vorliegen sollten. Sie wurden in Rails 5.2 eingeführt, um ein häufiges Problem bei der Anwendungsentwicklung zu lösen: Teams brauchen eine zuverlässige Möglichkeit, Geheimnisse zu verwalten neben Code zu verwalten, aber ohne diese Werte in der Versionskontrolle offenzulegen.

In diesem Punkt unterscheiden sich Rails Credentials grundlegend von Umgebungsvariablen. Umgebungsvariablen werden niemals in Ihrem Repository gespeichert. Jeder Entwickler, Server oder jede Einsatzumgebung benötigt seine eigene Kopie, die normalerweise über Shell-Profile, Hosting-Dashboards oder CI-Systeme konfiguriert wird. Dieser Ansatz funktioniert, ist aber mit einem gewissen Aufwand verbunden. Wenn sich ein Wert ändert, muss er überall, wo er verwendet wird, neu verteilt werden, und es obliegt dem Team, diese Werte auf dem gleichen Stand zu halten.

Rails Credentials verfolgen einen anderen Ansatz. Geheimnisse werden in einer verschlüsselten Datei gespeichert, die nicht im Repository vorhanden ist. Die Datei selbst ist bei der Übertragung sicher, da sie nur mit dem passenden Hauptschlüssel entschlüsselt werden kann. Der Zugriff auf die Geheimnisse wird durch den Zugriff auf diesen Schlüssel kontrolliert, nicht durch die manuelle Freigabe einzelner Werte.

In der Praxis vereinfacht dies die Arbeitsabläufe im Team. Stellen Sie sich vor, Sie müssen ein Vonage-API-Geheimnis ändern oder einen privaten Schlüssel neu generieren. Mit Umgebungsvariablen müssten Sie diesen neuen Wert sicher an jeden Entwickler und jede Umgebung, die davon abhängt, verteilen. Mit Rails Credentials aktualisieren Sie die verschlüsselte Datei mit den Anmeldeinformationen einmal, übertragen die Änderung und geben sie weiter. Jeder, der bereits über den Hauptschlüssel verfügt, kann das Update übernehmen und ohne zusätzliche Einstellungen weiterarbeiten.

Die Schlüsselidee ist, dass Rails Credentials geheime Änderungen und gleichzeitig geheim halten Zugang beschränkt. Sie versionieren die verschlüsselten Daten, nicht die Klartextwerte, was es einfacher macht, Aktualisierungen im Laufe der Zeit zu verwalten, ohne die Konfiguration über Maschinen, Shells oder Posteingänge zu verstreuen.

Sobald Sie wissen, was Rails erreichen will, ergibt der Arbeitsablauf mehr Sinn. Wenn Sie ausführen:

rails credentials:edit

Sie erhalten keine normale YAML-Datei. Rails öffnet eine entschlüsselte Kopie Ihrer Anmeldedaten im Speicher in Ihrem Texteditor. Auf der Festplatte bleibt die echte Datei vollständig verschlüsselt. Wenn Sie den Editor speichern und schließen, verschlüsselt Rails den aktualisierten Inhalt automatisch erneut. Es ist eine sichere kleine Schleife: vorübergehend entschlüsseln, sicher bearbeiten, wieder verschlüsseln.

Das Ergebnis ist eine Lockbox, die direkt in Rails integriert ist. Sie ist vorhersehbar, versioniert, standardmäßig verschlüsselt und bereit, alles zu speichern, was Sie lieber nicht in die Logs lecken oder versehentlich in Slack einfügen möchten, mit dem Anhang "Funktioniert das auch für andere?". So bleiben Ihre Geheimnisse verlässlich und Ihre Konfiguration ordentlich, was besonders nützlich ist, wenn Sie von einem Repository-basierten Workflow aus deployen (Heroku, Render, Fly.iousw.), bei denen sich Ihr Code und Ihre Infrastruktur gemeinsam bewegen.

Wie Rails Credentials funktionieren

Sobald Sie die Idee hinter Rails Credentials verstanden haben, werden Sie die Mechanismen schnell begreifen. Alles dreht sich um eine verschlüsselte Datei: config/credentials.yml.enc. Falls sie noch nicht existiert, wird sie von Rails beim ersten Bearbeiten der Credentials generiert. Sie bleibt auf der Festplatte verschlüsselt, bis Sie ihr Werte hinzufügen.

Mit dieser Datei ist der Hauptschlüssel gepaart, der normalerweise unter config/master.key. Rails verwendet diesen Schlüssel, um Anmeldedaten zu entschlüsseln, wenn Sie sie bearbeiten, und um sie zur Laufzeit zu lesen. Er wird von Git absichtlich ignoriert, da der Zugriff auf den Hauptschlüssel den Zugriff auf alle von Ihnen gespeicherten Geheimnisse ermöglicht. Rails geht davon aus, dass Sie diesen Schlüssel über Ihre Bereitstellungsumgebung oder einen anderen sicheren Kanal bereitstellen.

Wenn Sie laufen:

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

Rails entschlüsselt die Anmeldedatei mithilfe des Hauptschlüssels, öffnet eine temporäre entschlüsselte Kopie in Ihrem Editor und verschlüsselt den Inhalt erneut, sobald Sie speichern und schließen. Diese entschlüsselte Version existiert nur im Speicher und kommt nie mit der Festplatte in Berührung, wodurch der Prozess sicher und entwicklerfreundlich bleibt.

>>Hinweis: Mit bin/rails stellt sicher, dass der Befehl mit der exakten Rails-Version Ihres Projekts ausgeführt wird, und die Option --warte Flagge ist für VS Code erforderlich, damit Rails die Credentials-Datei nicht erneut verschlüsselt, bevor Sie die Bearbeitung beendet haben.

Die wichtigste Regel, die Sie sich merken sollten, ist einfach: Die verschlüsselte Datei kann in Ihr Repository übertragen werden, der Hauptschlüssel jedoch nicht. Das System ist darauf angewiesen, diese beiden Teile getrennt zu halten.

Rails unterstützt auch umgebungsspezifische Anmeldeinformationen. Sie können vollständig getrennte verschlüsselte Dateien und Schlüssel verwalten, indem Sie diese ausführen:

rails credentials:edit --environment production

Dies öffnet config/credentials/production.yml.enc anstelle der Standarddatei. Jede Umgebung behält ihren eigenen Schlüssel und ihren eigenen Satz von Geheimnissen, was wichtig ist, da die Produktionsanmeldeinformationen von allen lokal verwendeten Daten isoliert bleiben sollten.

Im Entwicklungsalltag tritt vieles davon in den Hintergrund. Sie schreiben YAML, Rails verschlüsselt es, und Ihre Anwendung liest es zur Laufzeit ohne zusätzliche Zeremonie. Es ist ein einfacher Ansatz: eine verschlüsselte Datei, ein Schlüssel. Und da es sich um Rails handelt, wird der größte Teil der Komplexität mit einem einzigen Befehl für Sie erledigt.

Hinzufügen von Vonage Application Credentials zu Rails Credentials

Um zu zeigen, wie einfach und leistungsfähig Rails Credentials sind, werden wir eine einfache Rails-Anwendung erstellen, um eine RCS-Textnachricht zu senden.

Wenn Sie RCS in Ihrem Vonage Account nicht aktiviert haben oder kein RCS-fähiges Telefon zum Testen haben, können Sie RCS durch SMS oder WhatsApp mit fast identischem Ablauf ersetzen.

Voraussetzungen

• Ruby (3.x empfohlen)

• Rails 7+

• Ein Vonage API-Konto

• Eine RCS-fähige Rufnummer und RCS-fähiger Account (oder Rückgriff auf SMS/WhatsApp)

Vonage API-Konto

Um dieses Tutorial durchzuführen, benötigen Sie ein Vonage API-Konto. Wenn Sie noch keines haben, können Sie sich noch heute anmelden und mit einem kostenlosen Guthaben beginnen. Sobald Sie ein Konto haben, finden Sie Ihren API-Schlüssel und Ihr API-Geheimnis oben auf dem Vonage-API-Dashboard.

Sind Sie bereit, mit dem Bau zu beginnen?

Erleben Sie nahtlose Konnektivität, Echtzeit-Messaging und kristallklare Sprach- und Videoanrufe - alles auf Knopfdruck.

Erstellen einer Vonage-Anwendung

Bevor wir Rails Credentials verwenden können, um etwas zu speichern, benötigen wir die Werte selbst. Für RCS Messaging bedeutet das, dass wir eine Vonage Application mit der Messages API erstellen müssen.

Erstellen Sie Ihre App im Vonage Dashboard. Geben Sie der App einen Namen und aktivieren Sie die Nachrichtenfunktion.

Anforderungen für Ihre RCS-App

• Setzen Sie die Eingangs- und Status-URLs auf einen Platzhalter-Endpunkt

• Erzeugen Sie einen öffentlichen und einen privaten Schlüssel, indem Sie auf die Schaltfläche

• Speichern Sie die Änderungen

Verknüpfen Sie dann Ihren RCS-Agenten, indem Sie auf die Registerkarte "Externe Konten verknüpfen" klicken.

Zu diesem Zeitpunkt sollten Sie drei Werte für Ihr Rails-Projekt bereit haben:

1. ID der Anwendung

2. Datei mit privatem Schlüssel

3. RCS-Sender-ID

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

Verwendung von Rails Credentials für RCS Messaging

Wenn Sie Ihre Vonage-Anwendung eingerichtet und Ihre Schlüssel in der Hand haben, können wir zum Rails-Teil des Tutorials übergehen. Ziel ist es, zu zeigen, wie sich Rails Credentials auf natürliche Weise in einen echten Anwendungsworkflow einfügen. Um die Dinge einfach zu halten, werden wir eine minimale Rails-Anwendung mit einem einzigen Endpunkt erstellen, der eine RCS-Textnachricht an eine Telefonnummer sendet, die Sie in einer POST-Anfrage übergeben.

Beginnen Sie mit der Erstellung einer neuen Rails-Anwendung und fügen Sie das Vonage SDK hinzu:

rails new rails_credentials_rcs_demo --api

cd rails_credentials_rcs_demobundle add vonage

(Mit der Option --api Flagge hält das Projekt schlank, aber es ist optional, wenn Sie eine vollständige Rails-Umgebung bevorzugen).

Als nächstes laden wir die Vonage-Anmeldedaten in Rails. Öffnen Sie Ihre verschlüsselte Anmeldedaten-Datei:

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

Aktualisieren Sie die YAML mit den Werten Ihrer Vonage-Anwendung über das Dashboard:

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

Speichern und schließen Sie den Editor. Rails wird alles automatisch neu verschlüsseln, und Ihre Anmeldedaten sind nun über Rails.application.credentials.

>>Anmerkung: Achten Sie beim Hinzufügen des privaten Schlüssels zu den Anmeldeinformationen darauf, dass jede Zeile des Schlüssels einheitlich eingerückt ist private_key: Eine falsche Einrückung führt zu YAML-Parsing-Fehlern.

Mit den bestehenden Geheimnissen können wir eine einzige Route und einen einzigen Controller zum Senden von RCS-Nachrichten erstellen.

Fügen Sie eine Route für den Endpunkt hinzu:

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

Erzeugen Sie nun den Controller:

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

Und aktualisieren Sie sie mit der Logik für das Senden einer RCS-Nachricht mit dem Vonage Ruby SDK:

# 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

>>Anmerkung: Bei RCS ist die rcs_sender_id normalerweise ein Markenname (z.B. "Vonage") und nicht eine Telefonnummer.

Dieser Controller ist absichtlich minimal gehalten, damit der Schwerpunkt auf dem Credentials-Workflow und nicht auf der Rails-Struktur oder der Nachrichtenpersistenz liegt. Sie übergeben eine Telefonnummer und einen optionalen Textstring in einer POST-Anfrage, und der Endpunkt sendet eine authentifizierte RCS-Nachricht mit den Werten, die Sie in Rails Credentials verschlüsselt haben. Die dig-Methode ist hier sehr nützlich für den Zugriff auf verschachtelte Daten.

Starten Sie Ihre Rails-Anwendung:

rails s

Zum Testen öffnen Sie in Ihrem Terminal eine neue Registerkarte. Dann lösen Sie es mit einem einfachen curl Anfrage an eine RCS-fähige Telefonnummer aus:

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

Hinter den Kulissen entschlüsselt Rails Ihre Anmeldedaten beim Start, das Vonage Ruby SDK verwendet Ihre Anwendungs-ID und Ihren privaten Schlüssel, um ein JWT zu erstellen, und die Messages API sendet die RCS-Nachricht an die von Ihnen angegebene Nummer.

Dieses kleine Beispiel zeigt den gesamten Lebenszyklus: sicheres Speichern von Geheimnissen, Laden in eine Rails-Umgebung und Verwendung in einer echten Integration, ohne sensible Werte im Quellcode oder in Konfigurationsdateien preiszugeben.

Bewährte Praktiken für Berechtigungsnachweise in realen Anwendungen

Verwendung von Berechtigungsnachweisen in der Produktion

Irgendwann erreicht jeder Rails-Entwickler den Punkt, an dem die lokale Konfiguration nicht mehr ausreicht und die Anwendung in einer realen Umgebung laufen muss. Dies ist in der Regel der Zeitpunkt, an dem Rails Credentials wieder auftaucht, da die Produktion ihre eigene verschlüsselte Datei und ihren eigenen Hauptschlüssel benötigt.

Führen Sie zum Bearbeiten der Produktionsanmeldeinformationen den Befehl aus:

rails credentials:edit --environment production

Rails erstellt (oder öffnet) eine verschlüsselte Datei unter: config/credentials/production.yml.enc

und es erwartet den entsprechenden Hauptschlüssel bei:

config/credentials/production.key

In der Entwicklung kann Rails diesen Schlüssel automatisch aus dem Dateisystem lesen. In der Produktion müssen Sie jedoch den Hauptschlüssel über Ihre Hosting-Umgebung bereitstellen, damit die Anwendung die Anmeldeinformationen beim Booten entschlüsseln kann.

Die genaue Methode hängt von Ihrer Plattform ab:

• Rendern: setzen RAILS_MASTER_KEY im Dashboard

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

• Heroku: zu den Konfigurationsvariablen der Anwendung hinzufügen

• VPS oder benutzerdefinierter Server: exportieren Sie ihn in die Umgebung oder Ihre systemd-Einheit

Rails startet nicht ohne den richtigen Schlüssel, daher ist es wichtig, dass er überall dort vorhanden ist, wo Ihre Anwendung läuft.

Eine Leitlinie ist besonders hervorzuheben: Jede Umgebung braucht ihren eigenen Hauptschlüssel. Entwicklung, Staging und Produktion sollten voneinander isoliert bleiben, sowohl aus Sicherheitsgründen als auch aus Gründen der Übersichtlichkeit. Durch die Trennung dieser Schlüssel wird sichergestellt, dass die Konfiguration auf die Umgebung beschränkt bleibt, zu der sie gehört, und ein versehentlicher umgebungsübergreifender Zugriff auf sensible Werte verhindert.

Sobald der Produktionshauptschlüssel festgelegt ist, kümmert sich Rails um den Rest; es entschlüsselt die Anmeldeinformationen beim Booten und stellt sie Ihrer Anwendung auf dieselbe Weise zur Verfügung wie in der Entwicklungsphase.

Häufige Fallstricke und wie man sie löst

Rails Credentials übernimmt den größten Teil der Komplexität für Sie, aber es gibt ein paar Probleme, auf die Entwickler von Zeit zu Zeit stoßen. Dies sind die häufigsten und wie man sie lösen kann.

Versehentliches Übertragen des Hauptschlüssels

Wenn der Hauptschlüssel seinen Weg in Git findet, behandeln Sie ihn als offen. Drehen Sie die betroffenen Geheimnisse, erzeugen Sie einen neuen Schlüssel und stellen Sie sicher, dass das Original aus dem Versionskontrollverlauf entfernt wird. Die verschlüsselte Datei ist nur sicher, wenn der Hauptschlüssel geheim bleibt.

Zusammenführen von Konflikten in der verschlüsselten Datei

Da verschlüsselte Dateien keine sinnvolle Struktur enthalten, kann Git keine Konflikte in ihnen auflösen. Wenn mehrere Personen Anmeldeinformationen bearbeiten müssen, sollten Sie diese Änderungen koordinieren oder auf umgebungsspezifische Anmeldeinformationen oder einen externen Geheimhaltungsmanager zurückgreifen, um Kollisionen zu vermeiden.

Berechtigungsnachweise werden in der Produktion nicht geladen

Dies zeigt normalerweise an, dass der RAILS_MASTER_KEY Umgebungsvariable fehlt oder nicht mit dem Schlüssel übereinstimmt, der für die Verschlüsselung der Anmeldeinformationsdatei verwendet wird. Vergewissern Sie sich, dass der richtige Schlüssel in Ihrer Hosting-Umgebung festgelegt wurde und dass er der richtigen verschlüsselten Datei entspricht.

Eine beschädigte verschlüsselte Datei

Es kommt zwar selten vor, aber eine verschlüsselte Anmeldedatei kann unlesbar werden. Sie können sie mit regenerieren:

rm config/credentials.yml.enc

rails credentials:edit

Achten Sie darauf, dass Sie Ihre Werte nach der Neugenerierung der Datei erneut eingeben, da der vorherige Inhalt ohne die ursprünglichen Daten und den Schlüssel nicht wiederhergestellt werden kann.

Wann Sie ENV-Variablen verwenden sollten

Rails Credentials sind eine gute Lösung für viele Applications, aber sie sind nicht die universelle Lösung für die Verwaltung von Geheimnissen. In einigen Umgebungen bleiben traditionelle Umgebungsvariablen die bessere Wahl.

Umgebungsvariablen eignen sich gut für die Bereitstellung in Container-basierten oder Multi-Service-Architekturen, bei denen die Konfiguration zur Laufzeit injiziert und nicht im Repository gespeichert werden muss. Sie sind auch die Standardoption bei der Arbeit mit Orchestrierungssystemen wie Kubernetes, ECS oder Nomad oder bei der Ausführung von CI/CD-Pipelines, die während der Builds oder Testläufe Zugriff auf Geheimnisse benötigen. Und wenn mehrere Nicht-Rails-Dienste die gleichen Konfigurationswerte verwenden, sorgt die Verwendung von Umgebungsvariablen dafür, dass die Einrichtung im gesamten Stack konsistent bleibt.

Rails Credentials hingegen passen ganz natürlich in Applications, die innerhalb des Rails-Ökosystems bleiben. Sie bieten eine verschlüsselte, versionierte Speicherung von sensiblen Daten ohne den Overhead der Verwaltung mehrerer .env Dateien oder externen geheimen Speichern. Sie lassen sich auch problemlos in Plattformen integrieren, die direkt aus einem Git-Repository bereitstellen und erwarten, dass die Anwendung ihre eigene Konfiguration bereitstellt.

Viele Produktivsysteme kombinieren beide Ansätze - die Verwendung von Umgebungsvariablen für Belange auf Infrastrukturebene und Rails Credentials für anwendungsspezifische Geheimnisse. Die richtige Wahl hängt davon ab, wie Ihr System strukturiert ist und wo die Konfiguration gespeichert werden muss.

Einpacken

Rails Credentials bieten eine unkomplizierte Möglichkeit, sensible Konfigurationen zu verwalten und dabei die Sicherheit und Wartbarkeit im Auge zu behalten. Indem Sie verschlüsselte Werte neben Ihrer Anwendung speichern und sich auf umgebungsspezifische Schlüssel verlassen, erhalten Sie ein zuverlässiges Muster für die Verwaltung von Geheimnissen, ohne die Konfiguration über mehrere Dateien oder Systeme zu verstreuen.

In Kombination mit dem Vonage Ruby SDK fügt sich dieser Ansatz nahtlos in reale Rails-Workflows ein. Ihre Anwendung kann sich sicher authentifizieren, RCS-Nachrichten senden und mit der Messages API interagieren, ohne API-Schlüssel oder private Schlüssel im Quellcode oder in Shell-Umgebungen preiszugeben. Das Ergebnis ist ein Setup, das sowohl praktisch als auch sicher ist, und das sich gut skalieren lässt, wenn Ihre Anwendung wächst.