Skip to main content

Securing Drupal: Storing API Tokens in Lockr

As seen in the recent Uber hack, storing secrets such as API tokens in your project repository can leave your organisation vulnerable to data breaches and extortion. This tutorial demonstrates a simple and effective way to mitigate this kind of threat by leveraging Key module to store API tokens in remote key storage.

by nick.santamaria /

Even tech giants like Uber are bitten by poor secret management in their applications. The snippet below describes how storing AWS keys in their repository resulted in a data breach, affecting 57 million customers and drivers.

Here’s how the hack went down: Two attackers accessed a private GitHub coding site used by Uber software engineers and then used login credentials they obtained there to access data stored on an Amazon Web Services account that handled computing tasks for the company. From there, the hackers discovered an archive of rider and driver information. Later, they emailed Uber asking for money, according to the company.

Uber could have avoided this breach by storing their API keys in a secret management system. In this tutorial, I'll show you how to do exactly this using the Key module in conjunction with the Lockr key management service.

This guide leverages a brand-new feature of Key module (as of 8.x-1.5) which allows overriding any configuration value with a secret. In this instance we will set up the MailChimp module using the this secure config override capability.

Service Set-Up

Before proceeding with the Drupal config, you will need a few accounts:

  • Mailchimp offer a "Forever Free" plan.
  • Lockr offer your first key and 1,500 requests for free.

These third-party services provide us with a simple example. Other services are available.


There are a few modules you'll need to add to your codebase.

composer require \
  "drupal/key:^1.5" \
  "drupal/lockr" \


  1. Go to /admin/modules  and enable the MailChimp, Lockr and Key modules.
  2. Go to /admin/config/system/lockr
  3. Use this form to generate a TLS certificate that Lockr uses to authenticate your site. Fill out the form and submit.
    Lockr Create Auth Certificate
  4. Enter the email address you used for your Lockr account and click Sign up.
  5. You should be now be re-prompted to log in - enter the email address and password for your Lockr account.
  6. In another tab, log into the MailChimp dashboard
    1. Go to the API settings page -
    2. Click Create A Key
    3. Note down this API key so we can configure in Drupal in the next step.
      MailChimp API Dashboard
  7. In your Drupal tab, go to /admin/config/system/keys and click Add Key
  8. Create a new Key entity for your MailChimp token. The important values here are:
    1. Key provider - ensure you select Lockr
    2. Value - paste the API token you obtained from the MailChimp dashboard.
      Key Create MailChimp Token
  9. Now we need to set up the configuration overrides. Go to /admin/config/development/configuration/key-overrides and click Add Override
  10. Fill out this form, the important values here are:
    1. Configuration type: Simple configuration
    2. Configuration name: mailchimp.settings
    3. Configuration item: api_key
    4. Key: The name of the key you created in the previous step.
      Key Override Create

... and it is that simple.


The purpose of this exercise is to ensure the API token for our external services are not saved in Drupal's database or code repository - so lets see what those look like now.

MailChimp Config Export - Before

If you configured MailChimp in the standard way, you'd see a config export similar to this. As you can see, the api_key value is in plaintext - anyone with access to your codebase would have full access to your MailChimp account.

api_key: 03ca2522dd6b117e92410745cd73e58c-us1
cron: false
batch_limit: 100
api_classname: Mailchimp\Mailchimp
test_mode: false

MailChimp Config Export - After

With the key overrides feature enabled, the api_key value in this file is now null.

api_key: null 
cron: false
batch_limit: 100
api_classname: Mailchimp\Mailchimp
test_mode: false

There are a few other relevant config export files - lets take a look at those.

Key Entity Export

This export is responsible for telling Drupal where Key module stored the API token. If you look at the key_provider and key_provider_settings values, you'll see that it is pointing to a value stored in Lockr. Still no API token in sight!

   - lockr
   - mailchimp
id: mailchimp_token
label: 'MailChimp Token'
description: 'API token used to authenticate to MailChimp email marketing platform.'
key_provider: lockr
 encoded: aes-128-ctr-sha256$nHlAw2BcTCHVTGQ01kDe9psWgItkrZ55qY4xV36BbGo=$+xgMdEzk6lsDy21h9j….
key_input: text_field

Key Override Export

The final config export is where the Key entity is mapped to override MailChimp's configuration item. 

status: true
   - key.key.mailchimp_token
   - mailchimp.settings
id: mailchimp_api_token
label: 'MailChimp API Token'
config_type: system.simple
config_name: mailchimp.settings
config_item: api_key
key_id: mailchimp_token


Hopefully this tutorial shows you how accessible these security-hardening techniques have become. 

With this solution implemented, an attacker can not take control of your MailChimp account simply by gaining access to your repository or a database dump. Also remember that this exact technique can be applied to any module which uses the Configuration API to store API tokens.

Why? Here are a few examples of ways popular Drupal modules could harm your organisation if their configs were exposed (tell me about your own worst-case scenarios in the comments!).

  • s3fs - An attacker could leak or delete all of the data stored in your bucket. They could also ramp up your AWS bill by storing or transferring terabytes of data.
  • SMTP - An attacker could use your own SMTP server against you to send customers phishing emails from a legitimate email address. They could also leak any emails the compromised account has access to.

What other Drupal modules could be made more securing in this way? Post your ideas in the comments!

Go forth, and build secure Drupal projects!


Posted by nick.santamaria
Systems Operations Developer



Comment by Hamza


Serves as a nice reminder that even though Drupal is already quite secure out-of-the-box, there are still some things which could be vulnerable. This post highlights quite a good method of securing the site further.

Comment by Hugo


Je trouve cet article très intéressant et instructif.
Je suis en train de développer un logiciel qui permet à mes clients de relier leurs autorépondeurs via leur clé d'API.

Actuellement je stocke les jetons d'API dans ma base de données, je ne souhaite pas sortir le logiciel comme ça car évidemment si quelqu'un s'empare de la base de données ce sont tous mes clients qui voient leurs base emails compromise, sans parler des personnes qui peuvent être contactées par le pirate ou des @ qui peuvent être revendues...

Je cherche à reproduire la manipulation que vous faites à travers cet article mais sur un site en dur (sans CMS).
Auriez-vous une ressource ou un conseil à me donner pour que je puisse intégrer les clés d'API de Mailchimp et autres de manière cryptée et inviolable via Lockr notamment ?

Comment by nick.santamaria


Hi Hugo, Lockr have out-of-the-box integration with Drupal and Wordpress. Given you are not using either of these frameworks and there is no public API documentation, I would strongly advise to find another product to solve your secrets management problem. I recommend you look into an alternative such as AWS Secrets Manager.

Google-translated version of original comment:

Hello, I find this article very interesting and informative. I am developing software that allows my clients to link their autoresponders via their API key. Currently I store the API tokens in my database, I do not want to release the software like that because obviously if someone seizes the database all my customers who see their base emails compromised without talk about people who can be contacted by the hacker or @ who can be resold ... I try to reproduce the manipulation that you do through this article but on a hard site (without CMS). Do you have a resource or advice to give me so that I can integrate Mailchimp and other API's keys in encrypted and tamper-proof way via Lockr in particular?