Show nav
Heroku Dev Center
  • Get Started
  • Docs
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Dynos (app containers)
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Command Line
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery
    • Continuous Integration
  • Language Support
    • Node.js
    • Ruby
      • Rails Support
      • Working with Bundler
    • Python
      • Background Jobs in Python
      • Working with Django
    • Java
      • Working with Maven
      • Java Database Operations
      • Working with the Play Framework
      • Java Advanced Topics
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku Redis
    • Apache Kafka on Heroku
    • Other Data Stores
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
    • Compliance
  • Heroku Enterprise
    • Private Spaces
      • Infrastructure Networking
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
    • Single Sign-on (SSO)
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Add-ons
  • ›
  • All Add-ons
  • ›
  • Secure Key
Secure Key

This add-on is operated by Will

Automatic and Graceful Secure Key Rotation

Secure Key

Last updated 17 February 2016

Table of Contents

  • Provisioning the add-on
  • Attaching to other apps
  • Removing the add-on
  • Support
  • Additional resources

Secure Key is an add-on for providing automatic and graceful key rotation.

Adding automatic key rotation to an application ensures your app always has fresh, unguessable secrets. They can be used anywhere in your application where some sort of entropy is needed. Secure Key promotes best practices by keeping these secrets in your environment (rather than checked into source control) and by rotating them periodically.

This is especially perfect for cookie signing. In this case, you will want to sign all new cookies with the new key, but accept cookies signed with both the new and the old key. This ensures that there is not a discontinuity upon key rotation that causes all users to be logged out.

Secure Key is accessible directly via your applications environment.

Provisioning the add-on

Secure Key can be attached to a Heroku application via the CLI:

$ heroku addons:create securekey --app sushi
Creating securekey-clear-6489... done, (free)
Adding securekey-clear-6489 to sushi... done
Setting SECURE_KEY and restarting sushi... done, v3
Use `heroku addons:docs securekey` to view documentation.

Once Secure Key has been added, SECURE_KEY will be available in the app configuration and will contain the current securely generated keys. This can be confirmed using the heroku config command.

$ heroku config | grep SECUREKEY
SECUREKEY_CHARCOAL_KEY: 2fi9ugflsiscwcdv3g2aq2v2c2nwam2elripnkjbn1s6n5m6c4,6c7r6pz375bhltbvt57slj5waqj3fw1t7hc0u8bqwda0sqdth5

The keys are formatted like <CURRENT_KEY>,<OLD_KEY>. After the appropriate amount of time, CURRENT_KEY will move after the comma becoming the old key, and a fresh key will be put before the comma.

$ heroku config | grep SECUREKEY
SECUREKEY_CHARCOAL_KEY: 3bxllgq4u28ogxr6yug8hhiuqse3lgzg1zixu7cxrs0prdpw5d,2fi9ugflsiscwcdv3g2aq2v2c2nwam2elripnkjbn1s6n5m6c4

Attaching to other apps

You can attach the same key to several apps. In this situation, when the key is rotated, every app will get the new credentials.

Before attaching, we need to know the add-on name. In the above example the add-on name is securekey-clear-6489, given at provisioning time. It can also be found later by using heroku addons.

~ ➤ h addons -a sushi
=== Resources for sushi
Plan                   Name                  Price
---------------------  --------------------  -----
securekey:fortnightly  securekey-clear-6489  free

=== Attachments for sushi
Name    Add-on                Billing App
------  --------------------  -----------
SECURE  securekey-clear-6489  sushi

This add-on can be shared to and attached on other apps with heroku addons:attach

~ ➤ h addons:attach securekey-clear-6489 -a sushi2
Attaching securekey-clear-6489 to sushi2... done
Setting SECURE vars and restarting sushi2... done, v3

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it’s also possible to set local environment variables using export SECURE_KEYS=value1,value2.

Use the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env file. To view all of your app’s config vars, type heroku config. Use the following command to add the ADDON_CONFIG_NAME values retrieved from heroku config to your .env file.

$ heroku config -s | grep SECURE_KEY >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

For more information, see the Heroku Local article.

Removing the add-on

Secure Key can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:destroy SECUREKEY_CHARCOAL
-----> Removing securekey from sushi... done, v20 (free)

Support

All Secure Key support and runtime issues should be logged with Heroku Support at https://support.heroku.com. Secure Key is an open source add-on. Any non-support related issues or product feedback is welcome at https://github.com/will/securekey.

Additional resources

Additional resources are available at:

  • Secure Key Site
  • Source

Keep reading

  • All Add-ons
  • The Procfile
  • Running Apps Locally

Feedback

Log in to submit feedback.

SearchifySemaphore

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Heroku Podcasts
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
Heroku is acompany

 © Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies