Managing Secrets in Laravel with AWS Parameter Store

Published on by

Managing Secrets in Laravel with AWS Parameter Store image

Secrets are values you don't want to be exposed publicly, such as API credentials or private keys.

In Laravel, these are typically values added to your .env file. Sometimes they are private keys, perhaps generated for Laravel Passport, or downloaded for a GitHub app.

How you manage these secrets depends a lot on your deployment process. Forge allows you to load and edit the .env file directly from the server. For more custom hosting solutions, you might save the .env file in an S3 bucket, and download them during deployments.

A more secure solution (but still easy to use!) for managing secrets is AWS Parameter Store.

There is also an AWS service appropriately named Secrets Manager.

Secrets Manager has a lot more features, but you may not necessarily need or want them for this use case. It's also more expensive. Parameter Store pricing is here. Secrets Manager pricing is here.

Using Parameter Store

Parameter store is a key-value store. It's part of the larger AWS Systems Manager (SSM) service.

It's got a bunch of features! We'll cover what we need to manage secrets for Laravel apps, including:

  1. Storing encrypted values
  2. Storing large values
  3. Creating a parameter
  4. Retrieving parameters
  5. Security (IAM permissions)

Storing Encrypted Values

The following are the types of values you can store:

  • String
  • String List (essentially an array of strings)
  • Secure String

We'll be using SecureString, which is appropriate for storing secrets. Using this type will encrypt the parameter value. Values requiring encryption use the KMS service (Key Management Service) to provide a the key pair used for encryption.

You can create and manage your own keys within KMS, or you can use the default key, which is managed for you.

Creating your own key gives you more fine-grained control over who has access to data encrypted with the key. KMS is used EVERYTHING in AWS where things are encrypted - such as encrypted EBS drives, Parameter Store, and Secrets Manager.

I'm using the default KMS key in this example. Whether or not you should depends on your team size and who should be able to access these secrets within your organization.

Storing Large Values

Parameters are priced on the number of parameters and how often you access them via API calls. There are two tiers - "standard" and "advanced".

Standard tiers are limited to 10,000 parameters, each no larger than 4 KB. These parameters are free (altho there's still a charge for API usage).

Advanced parameters are limitd to 100,000 parameters, but have a limit of 8 KB along with extra security features. Each parameter has a cost per month.

Since we'll be saving our entire .env file into a parameter, it's possible to go over the 4 KB limit. You may then need to use an Advanced Parameter or save individual secrets (key/values) into separate parameters.

Create a Parameter

To store a secret into Parameter Store, we'll use the AWS CLI command ssm put-parameter.

Here we store the entire .env file:

aws ssm put-parameter \
--name /cloudcasts/staging/env \
--type SecureString \
--value file://.env

There's a few things to note:

  1. The name of the parameter uses parameter hierarchies, useful for categorizing parameters and for enforcing security policies.
    • For example, our env parameter is in the cloudcasts "namespace" for the staging environment
  2. We use the type of SecureString, but we don't define a KMS key via the --key-id flag. This will use the default KMS key within the region we're working in
  3. We use the handy file://path/to/file.ext method to tell the AWS CLI to find the content of the parameter in a local file

This will encrypt and store our secret into Parameter Store!

Generating Your .env File

I like to grab a fresh copy of the secrets (rebuilding the .env file) on every deployment.

If you'd like to see how to create a fully automated, auto-scaled infrastructure on AWS, checkout the Simple Auto Scaling course on CloudCasts! Within it, we use Parameter Store during deployments to retrieve secrets.

If your secrets change dynamically (outside of deployments), you may need something more dynamic. In any case, one thing I would avoid is saving parameters into a "build artifact" (e.g. a .zip archive of your application). If these build artifacts are stored somewhere publicly (for example, an S3 bucket with pulic access enabled), you can leak important secrets.

To build a new .env file (perhaps during a deployment), we can use the ssm get-parameter command:

aws ssm get-parameter \
--with-decryption \
--name /cloudcasts/staging/env \
--output text \
--query 'Parameter.Value' > .env

Things to note:

  1. We use the --with-decryption flag so the value we receive is decrypted
    • If not using the default KMS key, the user calling this command needs to have permission to get the KMS key
  2. We output the result as text via --output text
  3. We use the --query flag to retreieve just the decrypted value (rather than all the meta data you'd otherwise get)
  4. We redirect the output to the .env file in the current directory, just as if we ran echo "foo" > .env

The --output and --query flags are available on all AWS CLI commands. You can find more info on those flags, and other tricks, here.

Handling large .env Files

If you have a large .env file and have separated individual secrets into their own parameters, you may want to append to your .env file rather than overwrite it.

For example, perhaps your base .env file is in one parameter, but then a few longer secrets are in others. You can do the following:

# Create the initial .env file
aws ssm get-parameter \
--with-decryption \
--name /cloudcasts/staging/base-env \
--output text \
--query 'Parameter.Value' > .env
 
# Append a long secret to .env for each
# additional secret
SOME_LONG_SECRET_VALUE=$(aws ssm get-parameter \
--with-decryption \
--name /cloudcasts/staging/SOME_LONG_SECRET \
--output text \
--query 'Parameter.Value')
 
echo "SOME_LONG_SECRET=\"$SOME_LONG_SECRET_VALUE\"" >> .env

Nothing fancy there! Just keep appending to the .env file for each secret.

IAM Permissions

The IAM User or Role used to call get-parameter can be locked down using a variety of methods. Using the hierarchical name (e.g. /cloudcasts/staging/env) helps us lock down secrets related to specific apps and environments.

For example, I may have an IAM Role for automations related to deploying the cloudcasts app within the staging environment. I can set the Role's IAM Policy like so:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetParameter"
],
"Resource": "arn:aws:ssm:us-east-2:012345678910:parameter/cloudcasts/staging/*"
}
]
}

So, within us-east-2, on account ID 012345678910, this Role with the above IAM Policy can run GetParameter on parameters that start with /cloudcasts/staging (note the use of the wildcard).

Chris Fidao photo

Teaching coding and servers at CloudCasts and Servers for Hackers. Co-founder of Chipper CI.

Cube

Laravel Newsletter

Join 40k+ other developers and never miss out on new tips, tutorials, and more.

image
Paragraph

Manage your Laravel app as if it was a CMS – edit any text on any page or in any email without touching Blade or language files.

Visit Paragraph
Laravel Forge logo

Laravel Forge

Easily create and manage your servers and deploy your Laravel applications in seconds.

Laravel Forge
Tinkerwell logo

Tinkerwell

The must-have code runner for Laravel developers. Tinker with AI, autocompletion and instant feedback on local and production environments.

Tinkerwell
No Compromises logo

No Compromises

Joel and Aaron, the two seasoned devs from the No Compromises podcast, are now available to hire for your Laravel project. ⬧ Flat rate of $7500/mo. ⬧ No lengthy sales process. ⬧ No contracts. ⬧ 100% money back guarantee.

No Compromises
Kirschbaum logo

Kirschbaum

Providing innovation and stability to ensure your web application succeeds.

Kirschbaum
Shift logo

Shift

Running an old Laravel version? Instant, automated Laravel upgrades and code modernization to keep your applications fresh.

Shift
Bacancy logo

Bacancy

Supercharge your project with a seasoned Laravel developer with 4-6 years of experience for just $2500/month. Get 160 hours of dedicated expertise & a risk-free 15-day trial. Schedule a call now!

Bacancy
LoadForge logo

LoadForge

Easy, affordable load testing and stress tests for websites, APIs and databases.

LoadForge
Paragraph logo

Paragraph

Manage your Laravel app as if it was a CMS – edit any text on any page or in any email without touching Blade or language files.

Paragraph
Lucky Media logo

Lucky Media

Bespoke software solutions built for your business. We ♥ Laravel

Lucky Media
Lunar: Laravel E-Commerce logo

Lunar: Laravel E-Commerce

E-Commerce for Laravel. An open-source package that brings the power of modern headless e-commerce functionality to Laravel.

Lunar: Laravel E-Commerce
DocuWriter.ai logo

DocuWriter.ai

Save hours of manually writing Code Documentation, Comments & DocBlocks, Test suites and Refactoring.

DocuWriter.ai
Rector logo

Rector

Your partner for seamless Laravel upgrades, cutting costs, and accelerating innovation for successful companies

Rector

The latest

View all →
Launch your Startup Fast with LaraFast image

Launch your Startup Fast with LaraFast

Read article
Embed Livewire Components on Any Website image

Embed Livewire Components on Any Website

Read article
Statamic announces next Flat Camp retreat (EU edition) image

Statamic announces next Flat Camp retreat (EU edition)

Read article
Laravel Herd releases v1.5.0 with new services. No more Docker, DBNGIN, or even homebrew! image

Laravel Herd releases v1.5.0 with new services. No more Docker, DBNGIN, or even homebrew!

Read article
Resources for Getting Up To Speed with Laravel 11 image

Resources for Getting Up To Speed with Laravel 11

Read article
Laravel 11 is now released! image

Laravel 11 is now released!

Read article