How to Keep Sensitive Information Secret (Symfony Docs)

Environment variables are the best way to store configuration that depends on where the application is run - for example, some API key that might be set to one value while developing locally and another value in production.
When these values are sensitive and need to be kept private, you can safely store them by using Symfony's secrets management system - sometimes called a "vault".
The Secrets system requires the Sodium PHP extension.
In order to encrypt and decrypt secrets, Symfony needs cryptographic keys. A pair of keys can be generated by running:
This will generate a pair of asymmetric cryptographic keys. Each environment has its own set of keys. Assuming you're coding locally in the dev environment, this will create:
You can generate a pair of cryptographic keys for the prod environment by running the following command. The APP_RUNTIME_ENV env var selects the vault where the keys are stored:
This will generate config/secrets/prod/prod.encrypt.public.php and config/secrets/prod/prod.decrypt.private.php.
The prod.decrypt.private.php file is highly sensitive. Your team of developers and even Continuous Integration services don't need that key. If the decryption key has been exposed (e.g. an employee left the team), you should consider generating a new one by running: secrets:generate-keys --rotate.
Suppose you want to store your database password as a secret. By using the secrets:set command, you should add this secret to both the dev and prod vaults:
This will create a new file for the secret in config/secrets/dev and another in config/secrets/prod. You can also set the secret in a few other ways:
There's no command to rename secrets, so you'll need to create a new secret and remove the old one.
Secret values can be referenced in the same way as environment variables. Be careful that you don't accidentally define a secret and an environment variable with the same name: environment variables override secrets.
If you stored a DATABASE_PASSWORD secret, you can reference it like this:
The actual value will be resolved at runtime: container compilation and cache warmup don't need the decryption key.
Everybody is allowed to list the secret names with the command secrets:list. If you have the decryption key you can also reveal the secrets' values by passing the --reveal option:
If you have the decryption key, the secrets:reveal command allows you to reveal a single secret's value.
Symfony provides a convenient command to remove a secret:
The dev environment secrets should contain nice default values for development. But sometimes a developer still needs to override a secret value locally when developing.
Most of the secrets commands - including secrets:set - have a --local option that stores the "secret" in the .env.{env}.local file as a standard environment variable. To override the DATABASE_PASSWORD secret locally, run:
If you entered root, you will now see this in your .env.dev.local file:
This will override the DATABASE_PASSWORD secret because environment variables always take precedence over secrets.
Listing the secrets will now also display the local variable:
Symfony also provides the secrets:decrypt-to-local command which decrypts all secrets and stores them in the local vault and the secrets:encrypt-from-local command to encrypt all local secrets to the vault.
If you add a secret in the dev and prod environments, it will be missing from the test environment. You could create a "vault" for the test environment and define the secrets there. But an easier way is to set the test values via the .env.test file:
Since secrets are exposed as environment variables, you can inject them into your services with the #[Autowire] attribute. See Fixing Non-Autowireable Arguments for more details.
Due to the fact that decryption keys should never be committed, you will need to manually store this file somewhere and deploy it. There are 2 ways to do that:
(1) Uploading the file
The first option is to copy the production decryption key - config/secrets/prod/prod.decrypt.private.php to your server.
(2) Using an Environment Variable
The second way is to set the SYMFONY_DECRYPTION_SECRET environment variable to the base64 encoded value of the production decryption key. A fancy way to fetch the value of the key is:
To improve performance (i.e. avoid decrypting secrets at runtime), you can decrypt your secrets during deployment to the "local" vault:
This will write all the decrypted secrets into a %kernel.project_dir%/.env.<environment>.local file (in this example, .env.prod.local). After doing this, the decryption key does not need to remain on the server(s).
If your application stores environment files in a custom directory, override the secrets.local_vault service to point to the correct location:
When SYMFONY_DECRYPTION_SECRET is set and APP_SECRET is not defined, the kernel.secret parameter is automatically derived from the decryption secret. This means you don't need to define a separate APP_SECRET environment variable if you are already using the secrets vault.
The secrets:generate-keys command provides a --rotate option to regenerate the cryptographic keys. Symfony will decrypt existing secrets with the old key, generate new cryptographic keys and re-encrypt secrets with the new key. In order to decrypt previous secrets, the developer must have the decryption key.
The secrets system is enabled by default and some of its behavior can be configured:
Show your Symfony expertise
No stress: we've got you covered with our 141 automated quality checks of your code
Thanks Bruno Nogueira Nascimento Wowk for being a Symfony contributor
1 commit • 2 lines changed