A better way to manage the Rails secret token

Updated January 2015
—
Originally written
May 2013

tl;dr Don't store secrets in your source control.

Update — Rails 4.1

Rails 4.1 introduces the config/secrets.yml file. It provides a standard, environment-aware place to load and define secret keys and tokens. Although some of the details below may be slightly out of date, the same principal applies: don’t store real secrets in this file if you’re checking it in to source control! Load them from the environment like so:1

production:
secret_key_base: <%= ENV["SECRET_KEY_BASE"] %>

Insecure defaults

Until recently, one of the files created in a new Rails project was config/initializers/secret_token.rb. This file looked something like this:

# config/initializers/secret_token.rb# Be sure to restart your server when you modify this file.# Your secret key for verifying the integrity of signed cookies.# If you change this key, all old signed cookies will become invalid!# Make sure the secret is at least 30 characters and all random,# no regular words or you'll be exposed to dictionary attacks.MyApp::Application.config.secret_token='3eb6db5a9026c547c72708438d496d942e976b252138db7e4e0ee5edd7539457d3ed0fa02ee5e7179420ce5290462018591adaf5f42adcf855da04877827def2'

This token is used to sign cookies that the application sets. Without this, it’s impossible to trust cookies that the browser sends, and hence difficult to rely on session based authentication.

Why this is bad

Firstly, hard-coding configuration conflates config and code. Although this may not cause much pain in a very simple context, as the application and infrastructure grow this anti-pattern will make configuration increasingly complex and error prone.

An app’s config is everything that is likely to vary between deploys (staging, production, developer environments, etc). … Apps sometimes store config as constants in the code. This is a violation of twelve-factor, which requires strict separation of config from code. Config varies substantially across deploys, code does not.

Security risk

More importantly though is the security implication. Knowing the secret token allows an attacker to trivially impersonate any user in the application.

The only system that needs to know the production secret token is the production infrastructure. In this case, the attack vector is limited to the production infrastructure, which is likely to be the most secure part of the infrastructure anyway.

By hardcoding the production secret token in the code base, the following attack vectors are opened:

Every developer that has had access to the code base

Every development workstation that has a local copy of the code

The source control repository (whether private or 3rd-party e.g. Github)

Loading Rails configuration from the environment

In order to set the secret token securely, we want to load it from the application’s environment. The simplest method is to replace the hardcoded token with a reference to Ruby’s ENV:

# config/initializers/secret_token.rb# Be sure to restart your server when you modify this file.# Your secret key for verifying the integrity of signed cookies.# If you change this key, all old signed cookies will become invalid!# Make sure the secret is at least 30 characters and all random,# no regular words or you'll be exposed to dictionary attacks.MyApp::Application.config.secret_token=ENV['SECRET_TOKEN']

While this has the advantage of maintaining development/production parity, it can be inconvenient for simple apps. If ENV['SECRET_TOKEN'] isn’t set locally — for example in the development or testing workflow — ActionDispatch will raise an exception like:

One solution to this is managing a full set of environment variables within the development and test workflows. See below for more details on this.

Alternatively, a token could be hard-coded for the development and test environments, and loaded from the ENV in production.

# config/initializers/secret_token.rb# Be sure to restart your server when you modify this file.# Your secret key for verifying the integrity of signed cookies.# If you change this key, all old signed cookies will become invalid!# Make sure the secret is at least 30 characters and all random,# no regular words or you'll be exposed to dictionary attacks.MyApp::Application.config.secret_token=ifRails.env.development?orRails.env.test?('x'*30)# meets minimum requirement of 30 chars longelseENV['SECRET_TOKEN']end

However, if ENV['SECRET_TOKEN'] isn’t set in production, this will use the insecure token with no warning.

Managing an Application’s ENV

Dotenv is an excellent gem for managing an application’s environment. Heroku’s foreman uses this behind the scenes. Install it with:

gem 'dotenv-rails'

By default, it loads environment variables from the .env file. Simply create this file in the RAILS_ROOT on the production web server.

# .env should NOT be checked in to source control
SECRET_TOKEN=3eb6db5a9026c547c72708438d496d942e976b252138db7e4e0ee5edd7539457d3ed0fa02ee5e7179420ce5290462018591adaf5f42adcf855da04877827def2

As the application configuration and infrastructure grows more complex, the gem also provides a consistent method to manage configuration across multiple developers, CI, staging and production servers. Brandon Keepers wrote more on the rationale for the gem.

Heroku

On Heroku, the application’s environment variables are managed from the heroku CLI:

$ heroku config:set SECRET_TOKEN=...

or from the web dashboard at https://dashboard.heroku.com/apps/my-app/settings

Although an order of magnitude better than storing secrets in source control, the environment has its risks too. Michael Reinsch has a very insightful write up worth reading. ↩