credentials.adoc

Credentials

Deploying secret API keys or other secret configuration to a production environment can become quite a hassle. You normally don’t want to commit them unencrypted to your repository. And you also want to share them with other developers. Rails 5.1 introduced the concept of secrets. Rails 5.2 deprecated them and introduced the concept of credentials.

You still have to store one central encryption key on your server and on all development systems, but that’s it. All other secrets/credentials are encrypted with that key and can be stored safely in your code repository.

Credentials are identical in all environments. There is no difference between development and production.

We start with a new rails application:

$ rails new shop
$ cd shop

Setup

In a new Rails 5.2 application you’ll find the master key which is used to encrypt all credentials in the file config/master.key. Save this in your team password manager so that your team can access it.

Warning

If you lose the key, no one, including you, can access any encrypted credentials.

It is very important to keep this key securely. Anyone who has it can decrypt your credentials and if you lose it you can not decrypt your credentials any more.

Editing Credentials

The encrypted credentials are stored in config/credentials.yml.enc. But because they are encrypted you can not edit them in that file with an editor. You have to use rails credentials:edit. In case you are using the bash shell and don’t have the env variable EDITOR already set you can edit your credentials with this command:

$ EDITOR=vim rails credentials:edit

Credentials are saved in the YAML format.

# aws:
#  access_key_id: 123
#  secret_access_key: 345

# Used as the base secret for all MessageVerifiers in Rails, including the one protecting cookies.
secret_key_base: 9846dad34a3168...68d634f
test: foobar

Accessing a key

You can access a credential with the format AppName::Application.credentials.name_of_the_credential. Here is an example for the above configuration:

$ rails console
Running via Spring preloader in process 19662
Loading production environment (Rails 5.2.0)
>> Shop::Application.credentials.test
=> "foobar"
>> exit

Using the credentials on the production web server

To use the credentials in the production web server system you have to copy the file config/master.key to that system.