Escudo de Autenticación PHP
Crea un escudo simple de autenticación básica HTTP para proteger sitios Drupal contra accesos no autorizados, tratando el sitio como un "jardín amurallado".
shield
Install
composer require 'drupal/shield:8.x-1.8'
composer require 'drupal/shield:8.x-1.6'
Overview
Shield es un módulo de autenticación PHP que crea un escudo simple de autenticación básica HTTP para sitios Drupal. Protege tu sitio web requiriendo que los visitantes ingresen un nombre de usuario y contraseña antes de poder acceder a cualquier contenido. Esto es particularmente útil para proteger sitios de desarrollo, staging o pre-lanzamiento del acceso público mientras permite que los miembros autorizados del equipo trabajen en el sitio.
El módulo intercepta todas las solicitudes HTTP entrantes a través de una capa de middleware que se ejecuta antes del almacenamiento en caché de páginas de Drupal, asegurando que incluso las páginas en caché no puedan ser accedidas sin la autenticación adecuada. Shield soporta múltiples métodos de almacenamiento de credenciales incluyendo configuración integrada, integración con el módulo Key para almacenamiento seguro de contraseñas, y soporte de clave multi-valor para almacenar tanto el nombre de usuario como la contraseña en una única clave segura.
Shield proporciona amplias capacidades de manejo de excepciones permitiendo a los administradores omitir la autenticación basándose en varios criterios incluyendo acceso por línea de comandos (Drush, cron), direcciones IP específicas o rangos, métodos de solicitud HTTP (útil para CORS), nombres de dominio (permitiendo acceso al front-office mientras se protege el back-office), y rutas específicas (con modos de inclusión y exclusión). Una función de encabezado de depuración ayuda a los administradores a diagnosticar por qué se está o no solicitando autenticación en escenarios específicos.
Features
- Protección de autenticación básica HTTP para todo el sitio Drupal con nombre de usuario y contraseña configurables
- Múltiples opciones de proveedor de credenciales: almacenamiento integrado de Shield, integración con módulo Key, o módulo Key multi-valor para mayor seguridad
- Excepción de interfaz de línea de comandos (CLI) para permitir operaciones de Drush, cron y otras operaciones de línea de comandos sin autenticación
- Lista de permitidos basada en IP que soporta direcciones IP individuales, direcciones IPv6 y rangos de red CIDR para omitir la autenticación
- Lista de permitidos de métodos HTTP para excluir métodos de solicitud específicos (GET, POST, OPTIONS, etc.) de la autenticación - útil para solicitudes preflight de CORS
- Excepciones basadas en dominio para permitir que nombres de host específicos omitan la autenticación - ideal para configuraciones multi-dominio donde el front-office debe ser público
- Filtrado basado en rutas con modo de exclusión (proteger todo excepto las rutas listadas) o modo de inclusión (proteger solo las rutas listadas) usando coincidencia de patrones
- Encabezado de depuración (X-Shield-Status) que proporciona información detallada del estado incluyendo: pending, authenticated, disabled, skipped (cli), skipped (ip), skipped (http method), skipped (subrequest), skipped (domain), skipped (path)
- Mensaje de autenticación personalizable mostrado en el diálogo de inicio de sesión del navegador con soporte para tokens [user] y [pass]
- Integración con el módulo Basic Auth de Drupal con limpieza automática de encabezados para prevenir conflictos de autenticación
- Soporte de anulación de configuración vía settings.php para configuraciones específicas del entorno (habilitar shield en staging, deshabilitar en producción)
- Soporte de migración desde el módulo Shield de Drupal 7 con transformación automática de configuración
- Middleware HTTP de alta prioridad (prioridad 250) asegurando que shield se ejecute antes del almacenamiento en caché de páginas para prevenir que páginas en caché sean servidas a usuarios no autenticados
- Integración de etiquetas de caché asegurando la invalidación apropiada del caché cuando cambia la configuración de Shield
- Soporte de alias de ruta asegurando que las excepciones basadas en rutas funcionen tanto con rutas internas como con alias de URL
- Soporte multi-idioma con eliminación automática del prefijo de idioma para la coincidencia de rutas
Use Cases
Proteger un sitio de desarrollo o staging
Shield se usa comúnmente para proteger entornos de desarrollo y staging del acceso público y la indexación de motores de búsqueda. Habilita Shield en estos entornos con un nombre de usuario y contraseña compartidos que el equipo de desarrollo conoce. Usa anulaciones de configuración en settings.php para deshabilitar automáticamente Shield en producción mientras lo mantienes habilitado en otros entornos. Por ejemplo: $config['shield.settings']['shield_enable'] = (getenv('ENVIRONMENT') !== 'production');
Configuración multi-dominio con back-office protegido
Para sitios con dominios separados de front-office (público) y back-office (administración), usa la lista de dominios permitidos de Shield para mantener el dominio público accesible mientras proteges el dominio administrativo. Añade tu dominio público (ej. www.example.com) al campo de Dominios permitidos, y todas las solicitudes a admin.example.com requerirán autenticación.
Endpoints de API que requieren soporte CORS
Cuando tu sitio Drupal sirve como API backend con requerimientos de CORS, los navegadores envían solicitudes preflight OPTIONS antes de las llamadas API reales. Añade 'OPTIONS' a la lista de métodos HTTP permitidos para permitir que estas solicitudes preflight pasen sin autenticación, mientras sigues protegiendo las solicitudes de datos reales.
Proteger solo rutas específicas
Usa el modo de inclusión con rutas específicas para proteger solo ciertas áreas de tu sitio. Por ejemplo, protege solo las rutas /admin/* configurando el Método de rutas a 'Incluir' y añadiendo /admin/* al campo de Rutas. Todas las demás páginas serán accesibles públicamente.
Permitir servicios automatizados
Configura la lista de IPs permitidas con las IPs de tu servidor CI/CD, IPs de servicios de monitoreo, o IPs de servidores edge de CDN para permitir acceso automatizado sin credenciales. Por ejemplo, añade la IP de tu servidor Jenkins para permitir despliegues automatizados sin solicitudes de autenticación.
Almacenamiento seguro de credenciales con módulo Key
Para organizaciones con requisitos de seguridad estrictos, usa Shield con el módulo Key para almacenar credenciales de forma segura. Configura una clave basada en archivo o en variable de entorno para almacenar credenciales fuera de la base de datos, asegurando que los volcados de base de datos no expongan las contraseñas de Shield.
Tips
- Usa anulaciones de configuración en settings.php ($config['shield.settings']['shield_enable'] = FALSE;) para deshabilitar Shield en producción mientras lo mantienes habilitado en entornos de staging.
- Cuando uses Shield con Varnish u otro almacenamiento en caché de proxy inverso, evita usar listas de IPs permitidas ya que las respuestas en caché pueden servirse a IPs no permitidas.
- Los tokens [user] y [pass] en el mensaje de autenticación ya no se muestran en la mayoría de los navegadores modernos por razones de seguridad, así que no dependas de ellos para comunicar credenciales.
- Para pipelines de CI/CD, configura la IP del servidor CI en la lista de permitidos o usa la excepción CLI para permitir despliegues automatizados sin autenticación.
- Rota regularmente las credenciales de Shield, especialmente cuando miembros del equipo dejan el proyecto o las credenciales pueden haber sido compartidas más allá de la audiencia prevista.
- Usa el módulo Key con variables de entorno o almacenamiento seguro de archivos para mantener las credenciales fuera de la base de datos y las exportaciones de configuración.
- Prueba los patrones de ruta usando el encabezado de depuración para confirmar qué rutas están protegidas antes de desplegar a producción.
Technical Details
Admin Pages 1
/admin/config/system/shield
Configura la protección de autenticación básica HTTP para tu sitio Drupal. Esta página permite a los administradores habilitar/deshabilitar la protección de Shield, configurar credenciales de autenticación y configurar varias reglas de excepción para controlar cuándo se debe omitir la autenticación.
Permissions 1
Hooks 1
hook_help
Implementa hook_help para proporcionar texto de ayuda para el módulo Shield en la página de ayuda.
Troubleshooting 5
Habilita la opción de encabezado de depuración y verifica el encabezado de respuesta X-Shield-Status. Causas comunes incluyen: IP en la lista de permitidos, excepción CLI activa, ruta excluida, método HTTP permitido, o dominio en la lista de permitidos. El encabezado mostrará exactamente por qué Shield fue omitido.
Esto ocurre cuando el módulo basic_auth está habilitado y las credenciales de Shield coinciden con un patrón que basic_auth intenta validar. Asegúrate de que 'Eliminar encabezados basic auth' esté marcado en la configuración de Shield para prevenir que basic_auth interfiera con la autenticación de Shield.
Shield resuelve automáticamente los alias de ruta a sus rutas internas para la coincidencia. Asegúrate de que tus patrones de ruta usen las rutas URL reales como aparecen a los visitantes, no las rutas internas node/X.
La lista de IPs permitidas puede causar problemas con proxies inversos ya que las respuestas podrían almacenarse en caché y servirse a IPs no permitidas. Evita usar listas de IPs permitidas cuando uses almacenamiento en caché de proxy inverso. Configura tu CDN para reenviar el encabezado X-Forwarded-For y asegúrate de que Drupal esté configurado para confiar en tu proxy.
Verifica que la configuración del proveedor de credenciales coincida con donde están almacenadas tus credenciales. Si usas el módulo Key, asegúrate de que la entidad key exista y contenga credenciales válidas. Verifica errores tipográficos en nombre de usuario/contraseña.
Security Notes 7
- Las credenciales de autenticación básica HTTP se transmiten en codificación base64 (no encriptación). Siempre usa HTTPS cuando Shield esté habilitado para proteger las credenciales en tránsito.
- Las credenciales de Shield se almacenan en texto plano en la configuración de Drupal por defecto. Para mayor seguridad, usa la integración con el módulo Key para almacenar credenciales fuera de la base de datos.
- La función de lista de IPs permitidas puede ser evadida si un atacante puede falsificar la dirección IP del cliente. Esto es más probable en entornos sin configuración adecuada de proxy.
- Shield no es un sustituto del control de acceso apropiado. Proporciona una barrera simple pero no debe usarse para proteger datos verdaderamente sensibles.
- Evita usar las mismas credenciales para Shield que las usadas para otros servicios o cuentas de usuario.
- Al exportar configuración, ten en cuenta que las credenciales de Shield en el modo de proveedor 'shield' se incluirán en la exportación. Usa el módulo Key para entornos sensibles.
- El mensaje de autenticación puede filtrar el nombre de usuario y contraseña si se usan los tokens [user] y [pass], aunque los navegadores modernos típicamente no muestran este mensaje.