Hiding Your Secrets in Rails 5 Using Credentials

While there are a number of blog posts that address the new Rails’ way of handling secrets, there was still a bit of piecing together I had to do in order to figure out exactly how to use the new Credentials file correctly. It was also a bit unclear how to tie this in with Heroku so I wanted to walk through the whole process.

First off, there’s only two files to deal with:

config/credentials.yml.enc

and…

config/master.key

All your secrets are encrypted and stored in the credentials file (Do not edit this file directly!!). And the master.key file will hold the key to decrypt the credentials file.

What this is means is you CAN check your credentials file into version control but you SHOULD NOT upload your master.key file.

Changing Credentials

In order to change/update your credentials you’ll need to use the rails credentials edit command in the terminal. In your terminal, type:

// ♥ EDITOR="atom --wait" rails credentials:edit

You can swap out atom for whichever editor you prefer. Note that two things should happen:

1. A file should open with a name that ends in “.credentials.yml”. This file will hold all your current credentials (in may be blank if you have none).
2. Your terminal should hang. The “wait” flag we added is telling the terminal that we haven’t finished editing our credentials file and so the file isn’t ready to be encrypted. While the Atom window is open, the terminal should be waiting. Once you save and close the window you should get this message:

New credentials encrypted and saved.

Formatting Your Credentials

Your credentials should be written as key-value pairs in plain text. In other words, no quotations needed for strings. For example:

github_secret: 1241212

You can also nest your credentials if you’d like:

github:
  secret: 1241212

Lastly, if you’d like to create Environment specific variables, you can do that, as well:

development:
  github:
    secret: 1241212
production:
  github:
    secret: 1241212

But whatever you do, don’t touch the “secrete_key_base” line at the bottom of the file. That is generated automatically. Remember it, because you’ll need it later.

Reading Your Credentials

You can access your credentials in your code like so

// One Key-Value pair
Rails.application.credentials.github_secret
// Nested Key-Value pair
Rails.application.credentials.github[:secret]
// Environment Variables
Rails.application.credentials[Rails.env.to_sym][:github][:secret]

Deploying Master.key to Heroku

This system is pretty straightforward in development but what happens when you deploy your project, leaving your Master.key file behind?

Heroku.config to the rescue.

Heroku provides a fast and easy way to upload secret keys and information you may not want in your code but which is necessary for your program to work. There’s two keys we’ll need to set to Heroku.config in order to make our credentials accessible in production:

1. Our Master Key
2. Our Secret Key base

From the config/master.key file in your Rails project, copy the line of jumbled numbers and letters. Then, in your terminal, run:

heroku config:set RAILS_MASTER_KEY=<your_master_key_here>

To see if that worked, type:

heroku config:get RAILS_MASTER_KEY

Next, you’ll want to use the same command to set your Secret Key base:

heroku config:set SECRET_KEY_BASE=<your_secret_key_base_here>

Check to make sure that stuck.

And that’s it! Your credentials are now hidden but accessible when they’re needed both in production and development.

Resources:

Rails 5.2 credentials

Configuration and Config Vars | Heroku Dev Center