Key
Key proporciona la capacidad de mejorar la seguridad de Drupal mediante la gestión de claves sensibles como claves API y de cifrado, dando a los administradores del sitio control sobre cómo y dónde se almacenan las claves.
key
Install
composer require 'drupal/key:8.x-1.20'
composer require 'drupal/key:8.x-1.17'
Overview
El módulo Key proporciona un sistema de gestión centralizado para claves sensibles utilizadas en todo el sitio Drupal. Separa el almacenamiento de claves del uso de claves, permitiendo a los administradores definir cómo y dónde se almacenan las claves mientras habilita a otros módulos para recuperar y usar esas claves sin necesidad de conocer los detalles de almacenamiento.
Key utiliza una arquitectura de plugins flexible con tres tipos de plugins: Key Types (definen el propósito de la clave), Key Providers (definen dónde se almacena la clave) y Key Inputs (definen cómo se introducen los valores de las claves). Esta arquitectura permite una alta configurabilidad y extensibilidad.
El módulo soporta el almacenamiento de claves en varias ubicaciones incluyendo configuración de Drupal, archivos fuera del directorio raíz web, variables de entorno o el sistema de estado de Drupal. Esta flexibilidad permite que los sitios cumplan con requisitos regulatorios o de cumplimiento para el manejo de datos sensibles.
Además, Key proporciona funcionalidad de Anulaciones de Configuración, que permite inyectar valores de claves en cualquier elemento de configuración de Drupal en tiempo de ejecución, manteniendo los valores sensibles fuera de los archivos de configuración exportados.
Features
- Gestión centralizada de claves a través de una interfaz administrativa para crear, editar y eliminar claves de todo el sitio
- Arquitectura basada en plugins con Key Types extensibles (Authentication, Encryption, User/Password), Key Providers (Configuration, File, Environment, State) y Key Inputs (Text Field, Textarea, Generate)
- Opciones de almacenamiento seguro incluyendo almacenamiento basado en archivos fuera del directorio raíz web, variables de entorno y el sistema de estado de Drupal para mantener las claves fuera de la base de datos
- Sistema de anulación de configuración que permite inyectar dinámicamente valores de claves en cualquier elemento de configuración de Drupal en tiempo de ejecución
- Soporte para claves multivalor que almacenan datos complejos como pares de usuario/contraseña en formato JSON
- Soporte de codificación Base64 para claves de cifrado y valores de claves binarios
- Elemento de formulario key_select para agregar fácilmente selección de claves a formularios de otros módulos
- API completa a través del servicio key.repository para gestión programática de claves
- Comandos Drush para operaciones de gestión de claves por línea de comandos
- Generación automática de valores de clave para claves de cifrado con tamaños de clave configurables
Use Cases
Asegurar credenciales de API para servicios externos
Almacenar claves API para servicios como PayPal, MailChimp, Authorize.net o AWS usando el proveedor de clave File o Environment. Crear una clave con tipo 'Authentication', seleccionar el proveedor apropiado y configurar la ruta del archivo o nombre de la variable de entorno. Otros módulos pueden entonces usar el elemento de formulario key_select para permitir a los administradores seleccionar la clave en sus formularios de configuración.
Gestionar claves de cifrado para protección de datos
Crear claves de cifrado para usar con el módulo Encrypt. Elegir el tipo de clave 'Encryption' y especificar el tamaño de clave requerido (128 o 256 bits). Usar el proveedor File con una ubicación fuera del directorio raíz web por seguridad. Habilitar codificación Base64 si es necesario. La entrada de clave Generate puede crear automáticamente claves aleatorias criptográficamente seguras.
Almacenar credenciales de base de datos para conexiones externas
Usar el tipo de clave 'User/password' para almacenar credenciales para conexiones a bases de datos externas. El valor de la clave se almacenará como JSON con campos 'username' y 'password'. Usar getKeyValues() para recuperar las credenciales como un array.
Anular valores de configuración sensibles
Usar Anulaciones de Configuración de Clave para inyectar valores de clave en cualquier configuración de Drupal en tiempo de ejecución. Esto mantiene los valores sensibles como contraseñas SMTP fuera de los archivos de configuración exportados. Crear una anulación mapeando una clave a un elemento de configuración específico (p. ej., system.mail:password), y habilitar 'Limpiar valor anulado' para eliminar los datos sensibles de la configuración almacenada.
Gestión de claves específica por entorno
Usar el proveedor de clave Environment para recuperar claves desde variables de entorno establecidas en tu entorno de alojamiento. Esto es ideal para despliegues en contenedores donde los secretos se inyectan via variables de entorno, o para pipelines de CI/CD que gestionan secretos separadamente del código.
Agregar selección de clave a módulos personalizados
Usar el elemento de formulario key_select para agregar capacidad de selección de clave a los formularios de tu módulo. El elemento lista automáticamente las claves disponibles y puede filtrarse por tipo, proveedor o grupo de tipo usando la propiedad #key_filters. Ejemplo: '#type' => 'key_select', '#title' => 'Clave API', '#key_filters' => ['type' => 'authentication'].
Tips
- Nunca usar el proveedor de clave Configuration para sitios en producción - almacena los valores de las claves en la base de datos y las exportaciones de configuración
- Almacenar archivos de clave de cifrado fuera del directorio raíz web y asegurar permisos de archivo apropiados (legible solo por el usuario del servidor web)
- Usar variables de entorno para despliegues en contenedores y secretos gestionados por plataformas de orquestación
- El elemento de formulario key_select agrega automáticamente un enlace para crear nuevas claves si no hay ninguna disponible
- Usar anulaciones de configuración de clave para mantener contraseñas SMTP, secretos de API y otros valores sensibles fuera de las exportaciones de configuración
- Cuando uses tipos de clave multivalor, recuperar valores con getKeyValues() que devuelve un array, o getKeyValue() para el JSON sin procesar
- Los comandos Drush son útiles para automatizar la gestión de claves en pipelines de despliegue
- Considerar crear un directorio dedicado para archivos de clave con permisos restringidos (p. ej., /etc/drupal-keys/)
Technical Details
Admin Pages 6
/admin/config/system/keys
Interfaz administrativa principal para gestionar claves de todo el sitio. Muestra una lista de todas las claves definidas mostrando su nombre, tipo, proveedor y cualquier anulación de configuración que use cada clave. Desde esta página, los administradores pueden agregar nuevas claves, editar o eliminar claves existentes y crear anulaciones de configuración.
/admin/config/system/keys/add
Formulario para crear una nueva clave. Permite a los administradores definir el nombre de la clave, descripción, tipo, proveedor y configuración de valor. El formulario se actualiza dinámicamente según el tipo de clave y proveedor seleccionados.
/admin/config/system/keys/manage/{key}
Formulario para editar una clave existente. Muestra una advertencia sobre los riesgos de editar claves antes de permitir cambios. Requiere confirmación antes de mostrar el formulario de edición.
/admin/config/system/keys/manage/{key}/delete
Formulario de confirmación para eliminar una clave. Advierte sobre las posibles consecuencias de la eliminación de la clave.
/admin/config/development/configuration/key-overrides
Interfaz administrativa para gestionar anulaciones de configuración de claves. Estas anulaciones permiten que los valores de las claves se inyecten dinámicamente en elementos de configuración de Drupal en tiempo de ejecución, manteniendo los valores sensibles fuera de las exportaciones de configuración.
/admin/config/development/configuration/key-overrides/add
Formulario para crear una nueva anulación de configuración que inyecta un valor de clave en un elemento de configuración de Drupal.
Permissions 2
Hooks 1
hook_key_provider_info_alter
Permite a los módulos alterar las definiciones de los plugins de Key Provider, habilitando la personalización del comportamiento del proveedor o el intercambio de implementaciones de proveedores.
Drush Commands 6
drush key:save
Guardar (crear o actualizar) una clave con el ID especificado y configuraciones opcionales.
drush key:delete
Eliminar una clave por su ID. Solicita confirmación antes de la eliminación.
drush key:list
Mostrar una lista de todas las claves disponibles con sus tipos y proveedores.
drush key:type-list
Mostrar una lista de plugins de tipo de clave disponibles.
drush key:provider-list
Mostrar una lista de plugins de proveedor de clave disponibles.
drush key:value-get
Recuperar y mostrar el valor de una clave. Usar con precaución ya que esto expone el valor de la clave.
Troubleshooting 5
Verificar que la configuración del proveedor de clave sea correcta. Para el proveedor File, comprobar que el archivo existe y es legible por el servidor web. Para el proveedor Environment, asegurar que la variable de entorno esté establecida en el contexto donde PHP se ejecuta. Para el proveedor State, verificar que la variable de estado exista usando drush state:get.
Asegurar que la anulación de configuración de clave esté correctamente configurada con el tipo de configuración, nombre y elemento correctos. Limpiar la caché de Drupal después de crear anulaciones. Comprobar que la propia clave tiene un valor válido. Notar que las anulaciones no se mostrarán en las exportaciones de configuración o en la interfaz de sincronización de configuración.
Editar claves muestra una advertencia y requiere confirmación debido a los posibles impactos en la funcionalidad dependiente. Si una clave es usada por otros módulos, considerar las implicaciones antes de modificarla. El módulo Key no previene la eliminación de claves en uso - coordinar primero con cualquier módulo dependiente.
El archivo debe existir y ser legible en el momento en que se guarda la clave. Verificar que la ruta del archivo sea correcta (ruta absoluta, relativa a la raíz de Drupal, o stream wrapper válido). Comprobar que los permisos del archivo permitan al usuario del servidor web leer el archivo.
Por seguridad, los valores de clave generados solo se muestran una vez cuando 'Mostrar valor' está marcado durante la creación de la clave. Si lo perdiste, necesitarás eliminar la clave y crear una nueva, o recuperarla usando drush key:value-get con la opción --base64.
Security Notes 7
- Los valores de clave almacenados con el proveedor Configuration son visibles en la base de datos, exportaciones de configuración y la interfaz de administración - usar solo para desarrollo
- Los proveedores File y Environment mantienen los valores de las claves fuera de la base de datos, mejorando la seguridad
- Las anulaciones de configuración de clave eliminan los valores sensibles de las exportaciones de configuración pero los mapeos de anulación en sí mismos aún se exportan
- Los usuarios con permiso 'administer keys' pueden ver los valores de clave almacenados en Configuration y crear claves que podrían afectar la seguridad del sitio
- Las claves de cifrado deben usar generación aleatoria segura (proporcionada por la entrada Generate) en lugar de valores elegidos por humanos
- Considerar la seguridad del sistema de archivos cuando se usa el proveedor File - asegurar que los archivos de clave no sean accesibles por mala configuración del servidor web
- Las variables de entorno pueden ser registradas o expuestas en listados de procesos - entender el modelo de seguridad de tu entorno de alojamiento