Why Drupal secrets management with Key matters before the first integration goes live
The Key module stores secret values such as payment gateway credentials, CRM tokens, mail relay passwords and AI service keys outside the configuration entities that reference them, and points to each secret by a key name. Teams need it as soon as the first integration will call an external API, because without it the secret usually ends up typed into a settings form or a module configuration screen. That value then lands in the configuration tree, gets exported with drush config:export, and is committed to Git, copied into staging databases and visible to anyone with access to the repository. Planning this before go-live is far cheaper than rotating every credential after a developer's export has been shared.
Drupal core and its contributed modules are licensed under GPL-2.0-or-later, and there is no paid edition of Drupal that bundles a secrets service. The secrets pattern is therefore assembled from contributed modules, site configuration and whatever store your infrastructure already runs. Key is the Drupal-side reference layer, while the actual value may live in an environment variable, a file outside the web root, or an external vault that your team operates. Each site needs its own decisions here, because the right storage backend depends on your hosting model, your deployment pipeline and who is allowed to rotate credentials. Confirm with your platform team which of these stores is already approved before the integration design starts.
Before the first integration goes live, decide three things in writing: which secrets the site holds, where each value is stored, and who can read or change it in each environment. Then check that the exported configuration contains only key names and no values, and that local, staging and production environments do not share credentials. This check is quick to run on a clean site and expensive to retrofit once a live payment or CRM integration is already in use. Our engagements begin with that inventory, so the secrets pattern is agreed alongside the integration scope rather than patched in after a security review.
Storage options for Key values and when each fits
This table compares four places to keep values that the Key module references, from environment variables to database storage. Read each row for when the option fits, what your operations team must run, and the main risk, then confirm available provider modules against the Key project page before choosing an external store.
| Storage option | When it fits | What operations must manage | Main risk |
|---|---|---|---|
| Environment variables | Single-environment sites where the web server or PHP-FPM pool can receive values at startup and your container or hosting platform already injects secrets this way | Injecting the variable into every web and cron runtime, rotating it through a deployment, and confirming it is absent from exported configuration and logs | Values visible to anyone who can read the process environment, phpinfo output or a debug page if one is exposed |
| External secret store via a provider module | Regulated estates that already run a central secret manager and need audit logs, rotation and access policies outside the Drupal site | Confirming the provider module supports your store, configuring authentication from the site to the store, handling store outages and monitoring access | Drupal becomes dependent on the store's availability, and a misconfigured credential can expose or block every key it serves |
| File-based storage outside the web root | Sites on servers you control where a root-owned key file can be read only by the PHP runtime user and deployed separately from code | Setting file ownership and permissions, placing the file in backups with equal protection, and rotating the file during maintenance windows | A file inside the web root or a world-readable path can be downloaded, and copies of the file can linger in backups or deployment artifacts |
| Database storage for non-sensitive values | Low-sensitivity settings such as public identifiers or non-secret endpoints that teams need to edit through the admin interface | Keeping this option limited to values that are not credentials, reviewing what editors can change, and including these values in configuration reviews | Anyone with database or configuration access can read the value, so credentials stored here are exposed in backups and exports |
When field encryption with Encrypt adds protection beyond key storage
Key and Encrypt solve different problems, and teams often mix them up. The Key module keeps a secret, such as an API key or an encryption key, out of the database and out of configuration exports, so the value lives in an environment variable, a file outside the web root or an external secret store. Encrypt operates on data. It encrypts values stored in fields or other entities, so the database holds ciphertext instead of readable text. Encrypt does not replace Key. It needs a key to work, and that key is itself a secret that must be stored somewhere. Plan the two decisions in that order: first where the key lives, then which data gets encrypted with it.
- Key protects the secret itself: It governs where an API key or encryption key is read from at runtime.
- Encrypt protects stored values: It encrypts selected field data at rest in the Drupal database.
- Encrypt depends on Key: The encryption key Encrypt uses is referenced through a Key entity, so its storage location is the critical choice.
- Exports stay clean in both cases: Configuration exports should contain key references and never the secret or the decryption key.
- Backups carry the risk: Database backups hold ciphertext, but a backup that also captures the key location and key material weakens the protection.
Before enabling anything, confirm with your team which secrets and fields are in scope and that the Key and Encrypt versions you plan to use support your Drupal version.
Access tokens and refresh tokens for external services, such as a CRM or a payment or messaging provider, are usually the strongest case for field encryption. A stored token grants access to another system, so a readable copy in the database is a direct path to that system. Encrypting the stored token value adds protection against a database dump or a read-only database compromise, while the application still needs the decryption key at runtime. Where the token is only needed for a short session or can be re-issued, consider not storing it at all. Where it must be stored, the decision about where the encryption key lives matters more than the cipher itself.
- Token rotation: Plan how tokens are refreshed and how encrypted values are re-encrypted after a key change.
- Key location: Keep the encryption key in an external store or environment variable, never in a database table or an exported configuration.
- Access scope: Limit which roles and code paths can read the decrypted value.
- Logging: Make sure token values do not appear in watchdog logs, error reports or debug output.
- Revocation path: Document how to revoke a token at the provider when a site is suspected of compromise.
Confirm with the owning team of each integration which tokens exist, how long they live and whether the provider supports revocation.
Personal data stored in fields, such as national identifiers, dates of birth, health details or bank references, may warrant field-level encryption, depending on your legal and internal requirements. Encryption at the field level can limit exposure if the database is copied, but it does not control what authorized users see on screen, in views, in exports or in search indexes. Those paths decrypt the value in normal operation, so access control and data minimization still matter. Ask your privacy and compliance leads which fields qualify and whether a field should be stored at all. DeployOpen can prepare the technical controls and evidence, but the classification decision belongs to your organization.
- Field inventory: List each personal data field with its purpose, retention period and who can view it.
- Search and indexing: Encrypted values usually cannot be searched or sorted in the database, so check which views, filters and reports depend on them.
- Derived copies: Confirm whether search indexes, caches, logs or exports hold plain copies of the value.
- Key rotation: Plan how existing records are re-encrypted and how old keys are retired.
- Access logging: Decide whether reads of sensitive fields need to be logged.
Confirm the legal basis and retention rules with your data protection function before you choose which fields to encrypt.
Most content on a Drupal site, such as articles, landing pages, images and public documents, does not need field encryption. Encrypting it adds a decryption step to every read, complicates search and caching, and makes content migration harder, without a corresponding gain in protection because the content is meant to be published. The protections that matter for this content are the ones that control who can edit and publish it, keep the platform patched and restrict direct access to private files. Encryption effort is better spent on the small set of values that grant access or identify people. Keeping the encrypted set small also keeps the key management process manageable.
- Public content: Articles, pages and media that are published by design gain little from encryption.
- Private files: Files that are not public need access control and storage isolation, which are separate from field encryption.
- Editorial data: Drafts and revisions are usually protected through roles and workflow rather than encryption.
- Performance cost: Encrypted fields add work to every read and can affect listing pages and caching.
- Maintainability: A small encrypted set is easier to document, test and rotate.
Before you decide, ask the content owner whether the content is meant to be public and confirm that the access rules, not encryption, are the control that protects it.
How to set up Key, move credentials out of config and verify exports
This sequence moves API keys and encryption keys out of Drupal configuration, points each integration at a named key, and proves with a configuration export and live tests that no credential remains in version-controlled files. It produces a site where config can be shared safely between environments.
Inventory every credential the site uses
Before installing anything, list each API key, client secret, SMTP password, webhook token and encryption key the site depends on, including those stored in custom modules, theme settings and contributed module forms. Record which environment uses each value and who owns the upstream account. The output is a short register that the developer and the security lead both sign off, and it becomes the checklist for every later step. Confirm with the team whether any credential is shared across sites, because shared values change how you rotate them.
Install Key and provider modules with Composer
Add the Key module to the codebase with Composer so the version is pinned in the lock file and deployed the same way as the rest of the site. Add only the provider or encryption modules that match your storage choice, such as an environment variable or file-based provider, and check each module's Drupal.org project page for compatibility with your Drupal core version before you require it. Enable the modules in a development environment and confirm the Key configuration pages load without errors. The step is complete when the modules appear in the code repository and the lock file has been committed.
Define a key entity for each credential
Create one key entity per credential in the Key administration pages, giving each a machine name that describes its purpose, such as
crm_api_keyorsmtp_password. Choose the key provider for each entry: an environment variable, a file outside the web root, or an external secrets service where your platform supports one. Confirm with the provider documentation what the provider expects and where the value must sit in each environment. The check is that every key entity shows a valid status, and that the value is not visible in the export of the entity configuration.Point integration settings at key names
Edit each module setting that currently holds a secret so it selects a key entity instead of storing the value directly. Most integrations that support Key expose a key selector on their settings form, so the field saves a reference such as
crm_api_key, not the secret. For custom code, call the Key service to fetch the value at runtime rather than reading a literal from configuration. The step is complete when the settings forms show the key name and the configuration files contain only the reference.Move existing plaintext values into the providers
Copy each current secret into its provider location (for example, the environment of the target server or the protected file), then clear the plaintext value from the site database and any settings file that held it. Work through one environment at a time, starting with development, and keep a record of which values were moved and when. Treat the old values as exposed if they have been in version control or shared channels, and plan rotation with the upstream service owner. The check is that the old value no longer appears in the database fields and the new provider returns a value when the key is loaded.
Run a configuration export and search it for residual secrets
Export the site configuration with the standard configuration export command, then search the export directory for the known secret values and for common patterns such as the word
token,secret,passwordandapi_keyfollowed by a string. Use a search tool that covers every YAML file and the Git diff of the commit. Any match must be explained, fixed and re-exported until the search returns nothing that is a real credential. Store the search pattern and output with the change record so auditors can see the check was run. The step is complete when the export contains only key entity references and no secret values.Test each integration against its key
Run a live test for every integration that uses a key, such as sending a test email, calling the CRM read endpoint, or submitting a test webhook, in a non-production environment first. Confirm the call succeeds with the value loaded from the provider, and that a deliberate wrong key fails with a logged error rather than exposing the value. Record the result for each integration against the register from the first step. The step closes when every entry in the register has a passing test and an owner has signed the record.
Document rotation and keep the export check in release
Write a short runbook that names the owner of each key, the provider location, and the steps to rotate it without a configuration change. Add the export search to the team's release checklist so every configuration change is scanned before it is merged. Ask your partner or internal team to confirm which external secrets service, if any, your hosting platform supports, since that decision shapes the rotation procedure. The output is a runbook and a repeatable check that keeps the site clean after the project ends.
Security and operational risks to control once secrets leave the database
Moving secrets out of the database fixes one exposure and creates several others. The cards below cover the failure modes we see most often on Key and Encrypt projects, and the checks that keep them manageable after launch.
Lost encryption keys
Fields protected with Encrypt are unreadable without the key that encrypted them. If the key file, environment variable or vault entry is lost, or replaced without re-encrypting stored values, the affected content cannot be recovered from backups alone. Confirm that every encryption key has a second, access-controlled copy held outside the web tier, and test a restore that includes decrypting a sample record. Losing the key means losing the data.
Secrets leaking through logs
Secrets reach logs through debug output, verbose Drush commands, PHP error pages, watchdog entries and exception traces that print configuration arrays. Once a value is in a log shipper or support ticket, rotating it is the only fix. Check that Key values are never rendered in admin previews, that error display is off in production, and that log retention and log access follow the same rules as the secrets themselves.
Coordinated rotation across environments
A rotated API key must change in the Key configuration, the hosting environment or vault, and every developer, staging and CI environment that calls the same service. Rotating one copy and not the others causes outages that look like integration bugs. Write a rotation runbook per key that names the owner, the order of changes, the cache clears needed and the check that proves the new value works before the old one is revoked.
Access to the vault and environment
Whoever can read the environment variables, the secrets backend or the external store can read every secret the site uses. Access often grows silently through shared hosting accounts, CI variables and deployment tokens. Ask who can view, edit and export these values, separate production access from staging, and review those grants on the same schedule as other privileged access reviews.
Keeping Key and Encrypt patched
Key and Encrypt are contributed projects, so their security fixes arrive through the Drupal Security Team process, which publishes advisories with CVE identifiers and risk scores. Security releases ship on the third Wednesday of the month. Add both modules to the same advisory subscription and patch window as core, and record which version runs in each environment so a late update is visible.
Questions buyers ask about Drupal secrets management and effort
What drives the cost of Drupal secrets management work?
The main drivers are the number of integrations that hold credentials, how many secrets currently sit in plaintext in configuration, and which storage and provider model you choose. Each integration (identity provider, CRM, search, object storage, payment or mail service) adds a credential to inventory, a place to read it from at runtime, and a test. Existing plaintext secrets add cleanup work, including rotating anything that may already be exposed in exports, backups or version control. The storage choice matters too: environment variables, a file outside the web root, or an external secret store each carry different setup and operating effort. Recurring costs come from rotation, access reviews and keeping the storage platform itself running, so ask a quote to separate one-time migration effort from ongoing operations.
How long does a scoped Drupal secrets project take?
Duration depends on the written scope, so the timeline appears only in the agreed document. A useful scope lists each integration, the chosen storage and provider, the number of secrets to move, the environments covered (development, staging, production), and whether field encryption with the Encrypt module is included. Work that involves a new external secret store or an audit of existing exports usually takes longer than a single-site change with environment variables. Ask for the milestones, what each one delivers, and what the client must do to unblock them.
What must our team provide before the work starts?
Most of the work depends on access and decisions from your side. Typical inputs include:
- Access to the secret store or hosting platform where values will live, with rights to create and read entries for each environment
- A named owner for each environment and each integration, who can confirm which credentials are live
- A written rotation process approved by your security team, including who rotates, how often, and how applications pick up new values
- A list of integrations and any existing encryption keys, with their current storage location
Without these, the team cannot verify that the site works after credentials move out of configuration.
Can our internal team manage Drupal secrets without a partner?
Yes, many internal teams can, provided they have Drupal configuration experience, access to the chosen secret store, and time to test each integration in every environment. The Key module provides a consistent way to reference secrets from code and configuration, so the work is mostly inventory, migration and verification. Teams that lack operational experience with a secret store, or that must produce evidence for an external assessment, often find the inventory and testing steps take the longest. A partner can take on a fixed-scope piece of that work, while your team keeps ownership of rotation and access. Decide this by comparing the skills and hours your team can commit against the written scope.
How does secrets management relate to a security test scope?
Secrets management is a control, and a security test checks whether that control holds. A test scope for a Drupal site can ask whether API keys appear in exported configuration, whether file permissions protect any local secret files, and whether encryption keys are reachable from the web root. Testing also confirms that a leaked credential can be revoked and replaced without downtime. Agree the test scope with the people who own the secrets, because some checks need test credentials and a clear rule for what happens if a finding exposes a live key. Consider the related Drupal penetration test scope and configuration review pages when you define boundaries.
Does moving secrets out of configuration affect our Drupal upgrades?
It can, and the risk is manageable when the change is planned. Drupal runs on a regular release cycle with bugfix releases on the first Wednesday of each month and security releases on the third Wednesday, so any secrets change should be tested against those updates. Keeping credentials out of exported configuration also means a new environment needs its own values, which should be documented before an upgrade. Check the Drupal core release schedule for the current major version and its end-of-life date, and confirm with your team how a major upgrade will be tested against the secret store.
What should we ask for in a written quote?
Ask the quote to list each deliverable, the integrations and environments in scope, the storage and provider model, and the number of secrets to migrate. Request the assumptions about your access and approvals, the acceptance criteria for each step, and what is handed over at the end, such as an inventory, runbooks and rotation steps. Separate one-time effort from recurring support, and ask what would change the price if the scope grows, for example a new integration found during discovery. DeployOpen works from a written scope, and the quote follows from it.
How to rotate keys and recover encrypted data without downtime
Rotating a secret in a Drupal site built with the Key module is a sequence you can run while the site stays live. Start by creating a new Key entity that points to the new value, whether that is an environment variable, a file outside the web root or an external store, and leave the existing key in place. Then change each consumer, such as a payment connector, SMTP setting or API client, to reference the new key ID, and confirm the old one is no longer referenced in configuration. Run the integration end to end in a non-production copy first, then in production, before you delete the old value at the source. Ask your team to record who approved each step, because the change history is the evidence an auditor will look for.
Encrypted fields need a separate track because the data itself has to change. Field encryption through the Encrypt module ties stored values to an encryption key, so rotating that key means decrypting each affected value with the old key and re-encrypting it with the new one, usually through a batch job run during a low-traffic window. Confirm the exact re-encryption procedure, batch tooling and any module-specific steps against the Key and Encrypt documentation for the versions you have installed, since these modules change across releases. Keep the old encryption key available until the batch job finishes and a sample of records has been read back successfully.
The most serious recovery risk is losing the encryption key itself. If it is gone, encrypted values in the database cannot be read, and a restored database backup will not help on its own. Back up the encryption key on its own schedule, stored separately from the database dump and under access controls that match your secrets policy, and test a restore that brings back both together. Your recovery runbook should state who holds each copy, how a restore is authorized and how long it takes to validate. Ask your implementation partner to show this restore working on a staging copy before go-live.
How DeployOpen scopes, delivers and supports Drupal secrets management
DeployOpen plans and implements Drupal secrets and API key management with the Key module inside your own infrastructure, so credentials stay out of configuration exports and under your control. Engagements are fixed-scope, with the scope, deliverables and timeline agreed in writing before work starts.
How we scope
- Inventory every API key, token and encryption key the site uses, including contributed modules and integrations
- Agree where each secret will live: environment variables, a file outside the webroot, or an external secret store
- Define which fields, if any, need encryption with Encrypt, and who holds recovery responsibility for those keys
How we build
- Configure Key key providers and bind each module setting to a key entity rather than a stored value
- Verify that configuration exports contain key identifiers only, with no secret values, before each release
- Test backup, restore and environment promotion so secrets resolve correctly in staging and production
How we hand over
- Deliver a written register of secrets, their storage location, owners and rotation steps for your team
- Document the Key configuration, provider settings and the deployment checks that guard against leaked values
- Walk your engineers through the runbook for rotating a key and recovering from a missing or changed secret
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover
- Review the secrets register when new contributed modules or integrations are added to the site
- Confirm with your security and platform teams how key material is backed up and rotated in your environment
