Key
Key provides the ability to improve Drupal security by managing sensitive keys such as API and encryption keys, giving site administrators control over how and where keys are stored.
key
Install
composer require 'drupal/key:8.x-1.20'
composer require 'drupal/key:8.x-1.17'
Overview
The Key module provides a centralized management system for sensitive keys used across your Drupal site. It separates key storage from key usage, allowing administrators to define how and where keys are stored while enabling other modules to retrieve and use those keys without needing to know storage details.
Key uses a flexible plugin architecture with three plugin types: Key Types (define the purpose of the key), Key Providers (define where the key is stored), and Key Inputs (define how key values are entered). This architecture allows for high configurability and extensibility.
The module supports storing keys in various locations including Drupal configuration, files outside the web root, environment variables, or Drupal's state system. This flexibility allows sites to meet regulatory or compliance requirements for sensitive data handling.
Additionally, Key provides Configuration Overrides functionality, which allows key values to be injected into any Drupal configuration item at runtime, keeping sensitive values out of exported configuration files.
Features
- Centralized key management through an administrative interface for creating, editing, and deleting site-wide keys
- Plugin-based architecture with extensible Key Types (Authentication, Encryption, User/Password), Key Providers (Configuration, File, Environment, State), and Key Inputs (Text Field, Textarea, Generate)
- Secure storage options including file-based storage outside the web root, environment variables, and Drupal's state system for keeping keys out of the database
- Configuration Override system that allows key values to be dynamically injected into any Drupal configuration item at runtime
- Support for multivalue keys storing complex data like username/password pairs in JSON format
- Base64 encoding support for encryption keys and binary key values
- key_select form element for easily adding key selection to other modules' forms
- Comprehensive API via the key.repository service for programmatic key management
- Drush commands for command-line key management operations
- Automatic key value generation for encryption keys with configurable key sizes
Use Cases
Securing API credentials for external services
Store API keys for services like PayPal, MailChimp, Authorize.net, or AWS using the File or Environment key provider. Create a key with type 'Authentication', select the appropriate provider, and configure the file path or environment variable name. Other modules can then use the key_select form element to allow administrators to select the key in their configuration forms.
Managing encryption keys for data protection
Create encryption keys for use with the Encrypt module. Choose the 'Encryption' key type and specify the required key size (128 or 256 bits). Use the File provider with a location outside the web root for security. Enable Base64 encoding if needed. The Generate key input can automatically create cryptographically secure random keys.
Storing database credentials for external connections
Use the 'User/password' key type to store credentials for external database connections. The key value will be stored as JSON with 'username' and 'password' fields. Use getKeyValues() to retrieve the credentials as an array.
Overriding sensitive configuration values
Use Key Configuration Overrides to inject key values into any Drupal configuration at runtime. This keeps sensitive values like SMTP passwords out of exported configuration files. Create an override mapping a key to a specific configuration item (e.g., system.mail:password), and enable 'Clear overridden value' to remove the sensitive data from stored configuration.
Environment-specific key management
Use the Environment key provider to retrieve keys from environment variables set in your hosting environment. This is ideal for containerized deployments where secrets are injected via environment variables, or for CI/CD pipelines that manage secrets separately from code.
Adding key selection to custom modules
Use the key_select form element to add key selection capability to your module's forms. The element automatically lists available keys and can be filtered by type, provider, or type group using the #key_filters property. Example: '#type' => 'key_select', '#title' => 'API Key', '#key_filters' => ['type' => 'authentication'].
Tips
- Never use the Configuration key provider for production sites - it stores key values in the database and configuration exports
- Store encryption key files outside the web root and ensure proper file permissions (readable only by web server user)
- Use environment variables for containerized deployments and secrets managed by orchestration platforms
- The key_select form element automatically adds a link to create new keys if none are available
- Use key configuration overrides to keep SMTP passwords, API secrets, and other sensitive values out of config exports
- When using multivalue key types, retrieve values with getKeyValues() which returns an array, or getKeyValue() for the raw JSON
- Drush commands are useful for scripting key management in deployment pipelines
- Consider creating a dedicated directory for key files with restricted permissions (e.g., /etc/drupal-keys/)
Technical Details
Admin Pages 6
/admin/config/system/keys
Main administrative interface for managing site-wide keys. Displays a list of all defined keys showing their name, type, provider, and any configuration overrides using each key. From this page, administrators can add new keys, edit or delete existing keys, and create configuration overrides.
/admin/config/system/keys/add
Form for creating a new key. Allows administrators to define the key name, description, type, provider, and value settings. The form dynamically updates based on selected key type and provider.
/admin/config/system/keys/manage/{key}
Form for editing an existing key. Shows a warning about the risks of editing keys before allowing changes. Requires confirmation before displaying the edit form.
/admin/config/system/keys/manage/{key}/delete
Confirmation form for deleting a key. Warns about potential consequences of key deletion.
/admin/config/development/configuration/key-overrides
Administrative interface for managing key configuration overrides. These overrides allow key values to be dynamically injected into Drupal configuration items at runtime, keeping sensitive values out of configuration exports.
/admin/config/development/configuration/key-overrides/add
Form for creating a new configuration override that injects a key value into a Drupal configuration item.
Permissions 2
Hooks 1
hook_key_provider_info_alter
Allows modules to alter the definitions of Key Provider plugins, enabling customization of provider behavior or swapping provider implementations.
Drush Commands 6
drush key:save
Save (create or update) a key with the specified ID and optional settings.
drush key:delete
Delete a key by its ID. Prompts for confirmation before deletion.
drush key:list
Display a list of all available keys with their types and providers.
drush key:type-list
Display a list of available key type plugins.
drush key:provider-list
Display a list of available key provider plugins.
drush key:value-get
Retrieve and display the value of a key. Use with caution as this exposes the key value.
Troubleshooting 5
Verify the key provider settings are correct. For File provider, check that the file exists and is readable by the web server. For Environment provider, ensure the environment variable is set in the context where PHP runs. For State provider, verify the state variable exists using drush state:get.
Ensure the key configuration override is correctly configured with the right configuration type, name, and item. Clear the Drupal cache after creating overrides. Check that the key itself has a valid value. Note that overrides won't show in config exports or the config sync interface.
Editing keys displays a warning and requires confirmation due to potential impacts on dependent functionality. If a key is used by other modules, consider the implications before modifying. The Key module doesn't prevent deletion of keys in use - coordinate with any dependent modules first.
The file must exist and be readable at the time the key is saved. Verify the file path is correct (absolute path, relative to Drupal root, or valid stream wrapper). Check file permissions allow the web server user to read the file.
For security, generated key values are only displayed once when 'Display value' is checked during key creation. If you miss it, you'll need to delete the key and create a new one, or retrieve it using drush key:value-get with the --base64 option.
Security Notes 7
- Key values stored with the Configuration provider are visible in the database, configuration exports, and the admin UI - use only for development
- The File and Environment providers keep key values out of the database, improving security
- Key configuration overrides remove sensitive values from configuration exports but the override mappings themselves are still exported
- Users with 'administer keys' permission can view Configuration-stored key values and create keys that could affect site security
- Encryption keys should use secure random generation (provided by the Generate input) rather than human-chosen values
- Consider file system security when using the File provider - ensure key files are not accessible via web server misconfiguration
- Environment variables may be logged or exposed in process listings - understand your hosting environment's security model