HOWTO dev Goggles_credentials

HOWTO: Goggles projects credentials: management and creation

References:

• Rails Edge guides: environmental security
• Encrypted Secrets(Credentials) in Rails 6, Rails 5.1/5.2, older versions and non-Rails applications: How to manage encrypted keys for different environments

Background:

Applications after Rails 5.2 automatically have a basic credentials file generated that just contains the secret_key_base used by MessageVerifiers/MessageEncryptors, like the ones signing and encrypting cookies. (Sessions based on cookies will be invalidated whenever you change this secret value.)

For applications created prior to Rails 5.2, the first time you run rails credentials:edit a new credentials file is generated as config/credentials.yml.enc. If you didn't have a master key saved in config/master.key, that'll be created too.

Rails also looks for the master key value as an environment variable in ENV["RAILS_MASTER_KEY"] if the master.key file is not found.

Run rails credentials:help for additional information.

Don't lose the master key and exclude it from the source control system you're using. Without the master key you'll be forced to re-create the credentials from scratch, and the new services built with these credentials won't be compatible with the existing versions.

This is most important especially if the master.key is used to decrypt keys and values for deploying the service to a swarm of containers; but it doesn't matter so much if you just need to rebuild a local container image used for testing or debugging.

In the latter case, you'll just need a cloned copy of the source repository, override the credentials with your own version and, then, rebuild each customized container you want from scratch using direct docker commands.

See also the dedicated How-To for more.

Goggles build-flow and credentials:

Rails 6 supports different encrypted credentials for each running environment, stored under /config/credentials.

Currently, the build flow of all Goggles sub-projects uses a single common credentials file (config/credentials.yml.enc), which can be decrypted using its associated master key (config/master.key - which is not public - ask Steve about it).

• For localhost usage (server or console) the master.key file must be present. Alternatively, set the RAILS_MASTER_KEY with its correct value before issuing any rails command:

  $> RAILS_MASTER_KEY=MY_SUPER_SECRET_MASTER_KEY rails s -e staging

• For container usage, the way to go is to set the master key as an environment variable when building a custom image from scratch.

Credentials details:

The needed credentials keys are:

• secret_key_base: used as the base Rails secret value, including the one protecting cookies;
• api_static_key: the actual API token value that is needed to create a new API session request.

Edit or show the existing credentials for the current environment with:

$> rails credentials:edit

To create or edit environment-wise credentials, just add the environment at the end (i.e.: -e development).