Rails Credentials: Secrets Beheren in Productie Zonder Gek te Worden

Rails heeft een ingebouwd versleuteld credentials-systeem waarmee je secrets beheert zonder externe tools. Draai bin/rails credentials:edit om je versleutelde kluis te openen, sla API-keys en databasewachtwoorden op, en benader ze overal met Rails.application.credentials. Geen wildgroei aan ENV-variabelen, geen .env-bestanden die per ongeluk gecommit worden, geen externe secrets manager nodig voor de meeste apps.

Dat is het verkooppraatje. In de praktijk lopen teams tegen echte wrijving aan: multi-omgeving setups, key-distributie voor CI/CD, credential-rotatie zonder downtime, en het gevreesde “we zijn de master key kwijt”-scenario. Deze gids behandelt de praktische kant van Rails credentials in productie, getest met Rails 7.1 en 8.0.

Hoe Rails Credentials Echt Werken

Rails credentials gebruiken AES-256-GCM-encryptie. Je secrets staan in config/credentials.yml.enc — één versleuteld bestand dat in versiebeheer staat. De ontsleutelingskey staat in config/master.key (of de RAILS_MASTER_KEY omgevingsvariabele), die standaard in .gitignore staat.

Wanneer je draait:

EDITOR=vim bin/rails credentials:edit

Ontsleutelt Rails het bestand naar een tijdelijk plaintext YAML-bestand, opent je editor, en versleutelt opnieuw wanneer je opslaat en afsluit. De plaintext raakt nooit permanent de schijf.

Het credentials-object is overal beschikbaar in je app:

# config/credentials.yml.enc (ontsleuteld)
aws:
  access_key_id: AKIAIOSFODNN7EXAMPLE
  secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

stripe:
  secret_key: sk_live_4eC39HqLyjWDarjtT1zdp7dc

database:
  password: productie_db_wachtwoord_hier

# Overal in je app
Rails.application.credentials.aws.access_key_id
# => "AKIAIOSFODNN7EXAMPLE"

Rails.application.credentials.dig(:stripe, :secret_key)
# => "sk_live_4eC39HqLyjWDarjtT1zdp7dc"

De dig-methode is veiliger voor geneste keys — het retourneert nil in plaats van een NoMethodError wanneer een key ontbreekt.

Per-Omgeving Credentials (Gebruik Ze)

De grootste verbetering die je kunt maken is credentials splitsen per omgeving. Sinds Rails 7.1 wordt dit goed ondersteund:

bin/rails credentials:edit --environment production
bin/rails credentials:edit --environment staging

Dit maakt aparte bestanden aan:

config/credentials/production.yml.enc
config/credentials/production.key
config/credentials/staging.yml.enc
config/credentials/staging.key

Rails laadt automatisch het juiste bestand op basis van RAILS_ENV. Omgevingsspecifieke credentials hebben voorrang op het basis config/credentials.yml.enc.

Waarom dit in de praktijk uitmaakt:

1. Staging kan niet per ongeluk productie API-keys gebruiken. Ik heb dit twee keer zien gebeuren bij verschillende bedrijven. Beide keren veroorzaakte het echte factureringsproblemen.
2. Verschillende teamleden kunnen verschillende toegangsniveaus hebben. Je junior developers krijgen de staging key. De productie key blijft bij ops.
3. Key-rotatie wordt onafhankelijk. Het roteren van de staging key vereist geen aanpassing aan productie.

Instellen

# Maak productie credentials
EDITOR=vim bin/rails credentials:edit --environment production

# Maak staging credentials
EDITOR=vim bin/rails credentials:edit --environment staging

# Houd basis credentials voor gedeelde, niet-gevoelige standaardwaarden
EDITOR=vim bin/rails credentials:edit

Stel in je productieomgeving RAILS_MASTER_KEY in op de inhoud van config/credentials/production.key:

# Op je server of in je deployment-configuratie
export RAILS_MASTER_KEY="a1b2c3d4e5f6..."

Keys Distribueren naar CI/CD

Je CI-pipeline heeft de master key nodig om tests te draaien die credentials raken. Zo pak je dit aan bij veelgebruikte platforms.

GitHub Actions

Sla de key op als repository secret:

# .github/workflows/test.yml
env:
  RAILS_MASTER_KEY: $

Kamal 2

Kamal leest uit .kamal/secrets, dat omgevingsvariabelen inlaadt. De schoonste aanpak:

# .kamal/secrets
RAILS_MASTER_KEY=$(cat config/credentials/production.key)

Of verwijs naar een secrets manager:

# .kamal/secrets (met 1Password CLI)
RAILS_MASTER_KEY=$(op read "op://Vault/Rails/master_key")

Docker

Geef de key mee at runtime, bak hem nooit in de image:

docker run -e RAILS_MASTER_KEY="a1b2c3d4..." myapp

Credentials Roteren Zonder Downtime

Credential-rotatie is een van die dingen waar niemand voor plant totdat een medewerker vertrekt of een key lekt. Hier is een proces dat werkt:

Stap 1: Ontsleutel huidige credentials en sla de plaintext op:

bin/rails credentials:show --environment production > /tmp/creds_backup.yml

Stap 2: Verwijder het oude versleutelde bestand:

rm config/credentials/production.yml.enc
rm config/credentials/production.key

Stap 3: Maak opnieuw aan met een nieuwe key:

EDITOR=vim bin/rails credentials:edit --environment production

Rails genereert een verse key. Plak je secrets terug (en werk bij wat nodig is).

Stap 4: Distribueer de nieuwe key naar alle servers en CI-systemen.

Stap 5: Deploy. Aangezien het versleutelde bestand en de key samen veranderen in één deploy, is er geen window waarin ze niet matchen.

Stap 6: Verwijder de plaintext backup veilig:

shred -u /tmp/creds_backup.yml  # Linux

De hele rotatie duurt ongeveer 10 minuten voor een typische app. De deploy zelf heeft nul downtime omdat het nieuwe versleutelde bestand en de nieuwe key samen aankomen.

Het “We Zijn de Master Key Kwijt”-Scenario

Als je config/credentials/production.key kwijtraakt en niemand RAILS_MASTER_KEY ergens heeft opgeslagen, zijn die credentials weg. AES-256-GCM brute-force je niet.

Preventie:

• Sla keys op in een team password manager (1Password, Bitwarden)
• Minimaal twee personen moeten toegang hebben tot productie keys
• Documenteer waar keys zijn opgeslagen in je team runbook (niet in de repo)

Herstel wanneer de key echt kwijt is:

1. Je moet alle secrets opnieuw genereren (nieuwe API-keys, nieuwe databasewachtwoorden, alles)
2. Verwijder het oude .yml.enc-bestand
3. Maak verse credentials met bin/rails credentials:edit --environment production
4. Voer alle nieuwe secrets in
5. Werk elke externe service bij met de nieuwe keys

Het is pijnlijk. Daarom sla je de key op in een password manager.

Credentials Veilig Benaderen in Code

Een paar patronen die ik nuttig heb gevonden in productie Rails-apps:

Verplichte credentials met duidelijke fouten

# config/initializers/stripe.rb
Stripe.api_key = Rails.application.credentials.stripe&.secret_key ||
  raise("Missing credentials: stripe.secret_key")

Dit faalt snel bij het opstarten in plaats van mysterieuze nil-fouten in productie om 2 uur ‘s nachts.

Credential wrapper voor complexe configuraties

# app/lib/app_credentials.rb
module AppCredentials
  def self.stripe_key
    Rails.application.credentials.dig(:stripe, :secret_key) ||
      ENV["STRIPE_SECRET_KEY"] ||
      raise("No Stripe key configured")
  end

  def self.database_url
    Rails.application.credentials.dig(:database, :url) ||
      ENV["DATABASE_URL"]
  end
end

Dit geeft je één plek om credential-bronnen te checken, en een fallback-keten (versleutelde credentials → ENV → fout). Handig tijdens migratie van ENV-gebaseerde configs.

Wanneer Rails Credentials NIET Gebruiken

Rails credentials zijn niet voor elke situatie het juiste gereedschap:

• Vaak veranderende waarden (feature flags, runtime config): Gebruik database-backed config of iets als Flipper. Opnieuw versleutelen en deployen voor elke toggle-wijziging is verspilling.
• Grote teams met granulaire toegangscontrole: Als je audit logs nodig hebt van wie welk secret heeft benaderd, gebruik HashiCorp Vault of AWS Secrets Manager.
• Secrets gedeeld met niet-Rails services: Als je Python-microservice dezelfde API-key nodig heeft, is een gecentraliseerde secrets manager logischer dan keys dupliceren.
• Kortstondige of auto-roterende secrets: AWS IAM-rollen, kortlevende tokens — die horen niet in een statisch versleuteld bestand.

Voor een typische Rails-monoliet met een klein tot middelgroot team, dekken ingebouwde credentials 90% van de use cases netjes af.

Als je credentials combineert met een deployment-pipeline, bekijk dan Rails 8 deployen met Kamal 2 voor de volledige productie-setup. Voor het versleutelen van data op applicatieniveau in plaats van configuratieniveau, zie ActiveRecord Encryption in Rails. En als je feature toggles bouwt naast je credentials-setup, behandelt feature flags in Rails productie een complementair patroon.

FAQ

Wat gebeurt er als RAILS_MASTER_KEY verkeerd is?

Rails gooit een ActiveSupport::MessageEncryptor::InvalidMessage bij het opstarten. Je app start niet, wat het correcte gedrag is — beter luid falen dan draaien met ontbrekende secrets. Controleer of de key overeenkomt met het versleutelde bestand voor je huidige RAILS_ENV.

Kan ik zowel ENV-variabelen als Rails credentials gebruiken?

Ja, en veel teams doen dit tijdens migratie. Het wrapper-patroon hierboven laat je eerst credentials checken, met fallback naar ENV. Verplaats na verloop van tijd alles naar credentials en verwijder de ENV-fallback. Sla niet permanent hetzelfde secret op beide plekken op — dat verdubbelt je rotatie-oppervlak.

Hoe verhouden Rails credentials zich tot dotenv of Figaro?

Dotenv (.env-bestanden) en Figaro (application.yml) slaan secrets op in plaintext bestanden die je .gitignore‘t. Het risico: iemand commit ze per ongeluk, en ze belanden voor altijd in de git-geschiedenis. Rails credentials zijn versleuteld en veilig om te committen. De trade-off is dat credentials de master key nodig hebben voor elke bewerking, terwijl .env-bestanden plain text zijn die je met elk hulpmiddel kunt bewerken. Voor productie-apps is de encryptie de kleine onhandigheid waard.

Is het veilig om credentials.yml.enc naar een publieke repo te committen?

Technisch wel — het bestand is AES-256-GCM versleuteld en nutteloos zonder de key. In de praktijk geven beveiligingsbewuste teams toch de voorkeur aan privé-repo’s. De encryptie is sterk, maar “defense in depth” betekent niet leunen op één enkele laag.

Hoe deel ik credentials met een nieuw teamlid?

Stuur ze de juiste master key via een beveiligd kanaal — je team password manager, een versleuteld bericht, of persoonlijk. Stuur keys nooit via Slack, e-mail, of een kanaal dat berichtgeschiedenis permanent opslaat. Voor per-omgeving setups, deel alleen de keys die ze daadwerkelijk nodig hebben.