Modelado de estructura en Keycloak
Este documento describe la estructura recomendada para gestionar todos los usuarios de alpura con acceso diferenciado a múltiples aplicaciones y rutas, utilizando Keycloak como Identity Provider.
🎯 Objetivo
Organizar y gestionar el acceso de usuarios de una misma organización a múltiples portales y rutas específicas, manteniendo una administración centralizada, segura y escalable.
Se muestra el diagrama de organización
+----------------+
| Realm |
+----------------+
|
+--------------+---------------+
| |
+---------------+ +---------------+
| Realm Roles | | Clients |
+---------------+ +---------------+
| |
+---------------+ +---------------+
| (Roles globales) | Client Roles |
| Ej: admin, empleado | (Roles por app)
+---------------+ +---------------+
|
+--------------------+
| Ej: ver-reportes |
| crear-pedido |
+--------------------+
|
+--------------+--------------+
| |
+---------------+ +---------------+
| Groups | | Group to |
+---------------+ | Role Mapping |
| +---------------+
+--------------+---------------+ |
| | |
+---------------+ +---------------+ |
| User 1 | | User 2 | |
+---------------+ +---------------+ |
| | |
+--------------+---------------+---------------+
|
+-------------------------+
| Heredan Realm Roles y |
| Client Roles asignados |
| al Group |
+-------------------------+
🗂️ Estructura recomendada
1. Realm / Reino
Se recomienda utilizar un solo Realm para toda la organización.
Ejemplo:
Alpura
Un Reino es la unidad principal de aislamiento. Es como un "contenedor" que agrupa usuarios, roles, clientes (aplicaciones), grupos y configuraciones de seguridad.
Los datos y configuraciones de un Reino no son visibles ni accesibles desde otro Reino. Esto significa que puedes tener, por ejemplo:
- Un Realm para producción (prod)
- Un Realm para pruebas (dev)
- Un Realm para un cliente específico
Cada uno será totalmente independiente.
2. Clients / Clientes
Un cliente es básicamente una aplicación o servicio que quiere usar los servicios de autenticación y autorización que ofrece Keycloak.
👉 El cliente es quien "consume" el Reino(Realm) para autenticar usuarios.
Se deberá crear un Client por cada aplicación o portal que requiera autenticación. Por ejemplo:
| Aplicación | Client ID |
|---|---|
| Portal Principal | portal-principal |
| Docusaurus Docs | docusaurus |
| Portal de Compras | portal-compras |
| Portal de Ventas | portal-ventas |
Es importante que en la configuración de cada cliente clients se deberá establecer como Confidential y habilitar:
Standard Flow (Authorization Code)Direct Access Grants- Configurar Redirect URIs y Web Origins
3. Groups / Grupos
Modelar los grupos según áreas o perfiles funcionales.
Un grupo (Group) es una manera de organizar usuarios y asignar permisos de forma masiva.
La estructura sugerida a aplicar deberá ser de acuerdo a las áreas funcionale dentro de alpura:
- /auditoria-interna
- /industrial
- /cadena-suministro
- /finanzas-administracion
- /calidad-seguridad
- /capital-humano
- /comercial
- /compras
- /consejo
- /finanzas
- /estrategia-transformacion
- /finanzas-administracion
- /general
- /investigacion-desarrollo-innovacion
- /juridico
- /mercadotecnica
- /recursos-humanos
- /trade-marketing
Asociar a los usuarios a uno o varios grupos según sus permisos.
La asociación de los usuarios a uno o mas grupos ayudará a gestionar de manera eficiente el control de accesos
4. Roles
Realm Roles
Un Realm Role es un rol global dentro de un Reino(Realm). Es decir, son permisos o perfiles que no dependen de ningún cliente específico, sino que son válidos para todo el Reino(Realm).
Sirve para definir perfiles, permisos o niveles de acceso que aplican a nivel general, por ejemplo:
- admin
- soporte
- supervisor
- usuario-interno
Cuando asignas un Realm Role a un usuario o grupo:
- ✅ Ese rol estará presente en el access token y se puede consultar desde cualquier aplicación (cliente) dentro del mismo Realm.
- ✅ Es independiente de los Client Roles (que son específicos de cada cliente/aplicación)
Roles estandar:
super-adminsoporte-tecnicoreport-viewer
Client Roles
Estos roles son específicos para cada aplicación o cliente y deberán ser definidos al momento de crear el aplicativo.
Ejemplo (para client portal-compras):
- compras-admin
- compras-user
- compras-guest
A continuación se muestra una tabla comparativa entre roles de cliente y roles de reino
| Característica | Realm Role | Client Role |
|---|---|---|
| Ámbito | Global dentro del Realm | Específico para un cliente (aplicación) |
| Visibilidad | Disponible para todas las aplicaciones del Realm | Sólo visible para el cliente al que pertenece |
| Uso recomendado | Permisos generales o transversales | Permisos específicos para una aplicación |
| Asignación | A usuarios y grupos | A usuarios y grupos, pero dentro del cliente |
| Herencia | Puede ser heredado por grupos | Puede ser heredado por grupos |
| Token | Se incluye en el campo realm_access del token | Se incluye en el campo resource_access del token |
| Ejemplos | admin, empleado, supervisor | crear-pedido (para app-ventas), ver-reportes (para app-finanzas) |
| Independencia | No depende de ningún cliente | Depende de un cliente específico |
5. Group to Role Mapping
Con la asociación de roles a los grupos nos ayudará a que los usuarios que pertenezcan a ese grupo heredarán automáticamente esos roles.
Asignar roles a los grupos, para evitar asignar roles uno por uno a los usuarios.
Ejemplo:
- Grupo
/compras→ Role:compras-user - Grupo
/admin→ Role:super-admin
🔑 Configuración de Mappers
Configurar en cada Client los siguientes mappers para que la información viaje en el Access Token:
1. Group Membership Mapper
- Name:
groups - Mapper Type:
Group Membership - Token Claim Name:
groups - Full group path:
ON - Add to ID token:
ON - Add to Access token:
ON
2. User Realm Role Mapper
- Name:
realm_access - Mapper Type:
User Realm Role - Token Claim Name:
realm_access.roles - Add to ID token:
ON - Add to Access token:
ON
3. User Client Role Mapper
- Name:
client_roles - Mapper Type:
User Client Role - Token Claim Name:
resource_access.${client_id}.roles - Add to ID token:
ON - Add to Access token:
ON
🚀 Ejemplo de Token generado
{
"sub": "usuario1",
"email": "usuario1@empresa.com",
"groups": ["/compras", "/soporte"],
"realm_access": {
"roles": ["super-admin", "report-viewer"]
},
"resource_access": {
"portal-compras": {
"roles": ["compras-user"]
}
}
}