Cómo restringir el acceso a la Consola de ZITADEL a usuarios no administradores

En implementaciones de ZITADEL donde conviven administradores y usuarios finales, existe un comportamiento por defecto que puede resultar problemático: cualquier usuario autenticado tiene acceso técnico a la ruta /ui/console.

Aunque ZITADEL restringe lo que pueden ver basándose en sus permisos, permitir el acceso a la interfaz de gestión plantea dos problemas:

1. Superficie de ataque: Se expone innecesariamente el panel de control a usuarios que no deberían interactuar con él.
2. Experiencia de Usuario (UX): Los usuarios finales pueden acceder por error a un entorno técnico confuso.

Es común intentar solucionar esto mediante ZITADEL Actions (scripts de intercepción), pero estos métodos suelen ser frágiles y difíciles de mantener. En este artículo, explicaremos la solución arquitectónica correcta: configurar el proyecto IAM para exigir una validación estricta de roles (projectRoleCheck) a través de la API.

Estrategia: Validación estricta de roles

La solución consiste en modificar la configuración del proyecto interno ZITADEL para activar la propiedad projectRoleCheck.

Al habilitar esta opción en lugar de permitir el acceso a cualquier usuario autenticado, ZITADEL verificará si el usuario posee un rol explícito en el proyecto antes de conceder el acceso. Si no existe tal asignación, el acceso es denegado a nivel de protocolo.

Pasos a seguir

Paso 1: Crear el Rol de Administración

El primer paso es definir el rol que actuará como «llave» de acceso.

1. Accede a la Consola como administrador.
2. Navega a Projects y selecciona el proyecto ZITADEL.
3. En la sección Roles, pulsa en New.
4. Crea un rol con la clave console_admin.

Paso 2: Asignación de permisos al Administrador

⚠️ Advertencia Crítica: Este paso es vital. Debes asignarte el rol a tu propio usuario administrador antes de activar el bloqueo. De no hacerlo, perderás el acceso a la consola inmediatamente.

1. Dirígete al menú Authorizations.
2. Pulsa en New.
3. Selecciona tu usuario administrador actual.
4. En el proyecto ZITADEL, marca el rol console_admin creado anteriormente.
5. Guarda los cambios.

Paso 3: Configuración de una cuenta de servicio

Como buena práctica en entornos de producción, es necesario disponer de un método de acceso alternativo vía API en caso de error en la configuración web.

1. Navega a Users → Service Users → New.
2. Crea un usuario llamado admin-system (Token type: Bearer).
3. Ve a default settings → Add Manager
4. Selecciona el usuario admin-system y asignale el rol IAM Owner.
5. Navega de nuevo a Users → Service Users → admin-system
6. Genera un Personal Access Token (PAT) y guárdalo en un lugar seguro.

Paso 4: Activación del bloqueo mediante API

Dado que la interfaz gráfica protege la configuración del proyecto IAM, utilizaremos la API de administración para aplicar el cambio. Ejecuta el siguiente comando en tu terminal (reemplaza las variables ${PAT} y ${PROJECT_ZITADEL_ID}):

curl -L -X PUT "https://tudominio.com/management/v1/projects/${PROJECT_ZITADEL_ID}" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ${PAT}" \
  --data-raw '{
    "name": "ZITADEL",
    "projectRoleAssertion": false,
    "projectRoleCheck": true,
    "hasProjectCheck": true,
    "privateLabelingSetting": "PRIVATE_LABELING_SETTING_UNSPECIFIED"
  }'

La propiedad "projectRoleCheck": true es la encargada de activar la restricción estricta.

Rollback: Cómo deshacer los cambios

Si necesitas desactivar esta protección por algún error, utiliza el usuario de servicio creado en el paso 3 y ejecuta el mismo comando cURL cambiando los valores a false:

"projectRoleCheck": false,
"hasProjectCheck": false

Conclusión

Implementar la seguridad basada en la configuración del proyecto (projectRoleCheck) ofrece una barrera de seguridad robusta y nativa, garantizando que solo el personal autorizado tenga visibilidad sobre la infraestructura de identidad.