SSO para aplicaciones internas: mapear claims SAML/OIDC a roles y equipos

Por qué importa el mapeo de claims en apps internas

El inicio de sesión único (SSO) parece simple: haces clic en "Iniciar sesión con Okta" o "Iniciar sesión con Azure AD" y ya estás dentro. Lo difícil es lo que ocurre después. Sin un mapeo de claims claro, la gente acaba con demasiado acceso (un agente de soporte ve la nómina) o con muy poco acceso (un nuevo empleado no puede abrir la herramienta que necesita desde el primer día).

Las apps internas son más complejas que las públicas porque se comparten entre equipos y cambian constantemente. Una misma herramienta puede usarla Soporte, Finanzas y Ventas al mismo tiempo. Los organigramas se mueven, los contratistas entran y salen, y los equipos se renombran o dividen. Si las reglas de acceso viven solo en la cabeza de la gente, el SSO copiará fielmente ese desorden dentro de tu app.

El mapeo de claims es la forma de convertir los datos de identidad que envía tu proveedor de identidad (IdP), como grupos, departamento o cargo, en permisos que tu app entiende. Normalmente eso significa decidir:

• Qué roles existen en la app (admin, manager, viewer, etc.)
• A qué equipos o espacios de trabajo pertenecen los usuarios
• Qué puede hacer cada rol y qué puede ver cada equipo
• Quién obtiene acceso automáticamente y quién necesita aprobación

Dos riesgos causan la mayoría de los problemas:

• Mapeos incorrectos. Un nombre de grupo coincide con el rol equivocado, o un grupo amplio como "Todos los empleados" concede accidentalmente privilegios de administrador.
• Claims faltantes. El IdP no envía grupos para algunos usuarios, algún atributo está vacío, o el token es demasiado grande y se recorta.

Tu app necesita valores por defecto seguros para que datos faltantes o inesperados nunca se conviertan en accesos accidentales.

SAML vs OIDC en términos sencillos

Cuando inicias sesión con SSO, tu IdP envía a tu app un pequeño paquete de hechos sobre ti. Cada hecho es un claim, básicamente un campo etiquetado como "email = [email protected]" o "department = Finance".

SAML y OIDC pueden transportar hechos similares, pero los empaquetan de forma distinta.

SAML es común en infraestructuras empresariales más antiguas. Normalmente envía un documento XML (una assertion) con atributos. Esos atributos son los claims que tu app lee.

OIDC es más nuevo y está construido sobre OAuth 2.0. Suele enviar un token JSON firmado (un ID token) más información de usuario opcional; los campos dentro del token son los claims.

Para apps internas normalmente te interesa un conjunto pequeño de claims:

• Dirección de email
• Un ID de usuario estable del IdP (subject)
• Nombre completo (o nombre y apellido)
• Pertenencia a grupos (equipos, security groups)
• Departamento o cargo

Una distinción evita mucha confusión:

La autenticación responde "¿quién es este usuario?" Claims como un ID de usuario estable y el email te ayudan a vincular el inicio de sesión SSO con la cuenta correcta.

La autorización responde "¿qué puede hacer?" Claims como grupos o departamento te ayudan a mapear al usuario a roles y equipos dentro de la app.

Dos personas pueden autenticarse con éxito, pero solo la que tenga el claim de grupo "Finance" debería poder entrar en una pantalla de facturación.

Roles y equipos: decide a qué vas a mapear

Antes de mapear atributos SAML o convertir claims OIDC en permisos, aclara dos cosas diferentes que tu app necesita saber:

• Los roles definen qué puede hacer alguien (permisos).
• Los equipos definen dónde pertenece (alcance).

Los roles responden preguntas como: ¿puede esta persona ver, editar, aprobar, exportar, gestionar usuarios o cambiar configuraciones?

Los equipos responden preguntas como: ¿en qué departamento, región, cola o centro de coste trabaja esta persona y qué registros debe ver?

Mantén los roles pequeños y estables. La mayoría de las apps internas solo necesita unos pocos roles que cambian raramente, incluso cuando la gente se mueve. Los equipos deberían reflejar la realidad diaria: Soporte Tier 2, cobertura EMEA, un responsable temporal de cola.

El principio de menor privilegio es el valor por defecto más seguro. Muchas apps internas funcionan bien con tres roles:

• Viewer: puede leer datos y hacer búsquedas
• Editor: puede crear y actualizar registros
• Admin: puede gestionar configuraciones, usuarios y reglas de acceso

Escribe en lenguaje sencillo lo que permite cada rol. Eso evita accesos de "admin sorpresa" cuando cambia un nombre de grupo y facilita las revisiones posteriores.

Acceso basado en grupos: cómo pensar en los grupos del IdP

El acceso basado en grupos significa que tu app no decide permisos persona por persona. En su lugar, confía en que el IdP mantenga la pertenencia a grupos y tu app mapea esos grupos a roles y equipos.

Empieza por decidir qué concede un grupo. En muchas herramientas, un grupo mapea a un rol (como "Support Agent") y opcionalmente a un equipo (como "Tier 2"). La clave es que el mapeo se mantenga aburrido y predecible: el mismo grupo siempre significa el mismo acceso.

Cuando los usuarios están en varios grupos

La gente suele pertenecer a más de un grupo del IdP. Necesitas una regla para resolver eso y que sea estable.

Enfoques comunes:

• Reglas aditivas: combinar permisos de todos los grupos coincidentes (funciona cuando los permisos están bien acotados)
• Reglas por prioridad: elegir el grupo de mayor prioridad y ignorar el resto (útil cuando los roles confligen)
• Híbrido: aditivo para equipos, prioridad para roles

Pase lo que pase, documenta la elección. Cambiar esto más tarde puede hacer que los usuarios ganen o pierdan acceso de forma inesperada.

Usa una convención de nombres escalable

Nombres claros de grupos reducen errores y facilitan auditorías. Un patrón práctico es:

• --

Por ejemplo, support-tool-prod-agent o finance-tool-staging-viewer. Esto ayuda a evitar reutilizar nombres vagos como "Admins" entre varias apps.

Si un usuario no pertenece a ningún grupo relevante, por defecto no le des acceso (o un estado de invitado claramente limitado) y muestra un mensaje que explique cómo solicitar acceso.

Vinculación de cuentas: emparejar usuarios SSO con cuentas de la app

SSO prueba quién es alguien, pero tu app aún tiene que decidir a qué cuenta existente adjuntar esa identidad. Sin vínculo de cuentas, la misma persona puede acabar con múltiples cuentas a lo largo del tiempo porque los identificadores cambian: nuevo email, actualización de nombre, cambio entre filiales, cambio de IdP.

Elige una clave estable y única como coincidencia primaria.

• En OIDC esto suele ser el claim sub (subject).
• En SAML suele ser un NameID persistente o un atributo de usuario inmutable dedicado.

Almacena ese valor como el "IdP user ID" junto con el issuer/entity ID del IdP, para que el mismo sub de otro IdP no pueda colisionar.

El email es útil, pero trátalo como una clave de conveniencia, no como la fuente de verdad. La gente cambia de email por renombrados, migraciones de dominio o fusiones. Los alias y buzones compartidos también pueden crear coincidencias sorprendentes. Si emparejas por email, hazlo solo cuando la señal del IdP esté verificada y considera un paso de confirmación único.

En el primer inicio de sesión, la mayoría de las herramientas internas escogen uno de estos patrones de onboarding:

• Auto-create: crear la cuenta inmediatamente y asignar acceso mínimo.
• Invite-only: permitir inicios de sesión solo para usuarios precreados (o preaprobados) en la app.
• Approval flow: crear la cuenta pero bloquear el acceso hasta que un manager o admin apruebe rol/equipo.

Un valor por defecto seguro es auto-crear con ningún permiso por defecto, y luego otorgar acceso en base a grupos o un paso de aprobación.

Paso a paso: mapear claims a roles y equipos

Un buen mapeo de claims hace que el SSO sea invisible: la gente inicia sesión y cae en el lugar correcto con el acceso adecuado.

Empieza escribiendo tu modelo de acceso en lenguaje sencillo. Lista cada rol (Viewer, Agent, Manager, Admin) y cada equipo (Support, Finance, IT), más quién debería recibirlos y por qué.

Luego confirma qué puede enviar realmente tu IdP. Para SAML u OIDC normalmente quieres un ID de usuario estable (subject o NameID), email y uno o más atributos de grupo. Captura los valores exactos de los grupos tal como aparecen, incluyendo mayúsculas y prefijos. "Support" y "support" no son lo mismo.

Un flujo práctico:

• Define roles y equipos, y asigna un responsable para cada uno (alguien que pueda aprobar cambios).
• Enumera los claims disponibles y los nombres exactos de grupos desde el IdP, incluyendo casos límite (contratistas, buzones compartidos).
• Escribe reglas de mapeo: group-to-role, group-to-team y un orden de override cuando múltiples grupos coincidan.
• Prueba con 3 a 5 tipos de usuarios reales (nuevo empleado, manager, contratista, admin) usando cuentas reales del IdP.
• Para cada usuario de prueba, escribe antes el resultado esperado de rol/equipo, luego inicia sesión y compara.

Mantén un ejemplo pequeño a mano para concretar las reglas. Si un usuario está en "okta-support", se convierte en equipo Support con rol Agent. Si también está en "okta-support-managers", el rol Manager sobrescribe a Agent.

Por último, añade una forma simple de depurar. Registra los claims crudos recibidos (de forma segura), las reglas que coincidieron y el resultado final de rol/equipo. Cuando alguien diga "Inicié sesión y no veo mi herramienta", esto convierte un juego de adivinanzas en una comprobación rápida.

Valores por defecto seguros cuando faltan claims

Los claims faltantes son normales. El IdP podría no enviar grupos para cuentas de servicio, un conector podría omitir un campo, o un usuario podría estar en migración. Trata "sin datos" como "sin confianza".

El valor más seguro es denegar por defecto: ningún rol, ningún equipo, sin acceso. Si debes permitir entrada para que alguien solicite acceso, mantenla de solo lectura y claramente limitada.

Elige un comportamiento y documéntalo:

• Bloquear el login con un mensaje claro: "Tu cuenta no tiene acceso asignado. Contacta soporte."
• Permitir acceso limitado con una advertencia y deshabilitar acciones sensibles.
• Crear el registro de usuario pero asignar ningún rol o equipo hasta que se apruebe.

Nunca pongas por defecto el rol de administrador, ni siquiera temporalmente.

Planifica para datos parciales. Si recibes un email pero no grupos, aún puedes crear una cuenta y dirigirla a aprobación. Si recibes grupos pero no un identificador estable, evita auto-vincularla con una cuenta existente porque eso puede asociar a la persona equivocada.

Ten una ruta de escalado para fallos:

• Un responsable nombrado (IT o admin de la app) que pueda aprobar acceso
• Un flujo de asignación manual con nota de auditoría
• Una forma de volver a comprobar los claims en el próximo inicio de sesión
• Un tiempo límite para cuentas en "pendiente de acceso"

Manejar cambios, bajas y offboarding

La gente cambia de equipo, cambia de manager y deja la empresa. Tu configuración SSO debe tratar esto como algo normal.

Cuando alguien cambia de equipo, actualiza el acceso en el siguiente inicio de sesión: reevalúa los claims de grupo y aplica el mapeo actual. Evita accesos "pegajosos" que se queden para siempre porque fueron concedidos una vez.

Los que se van son distintos. Esperar al siguiente inicio de sesión no es suficiente. Quieres que su acceso termine pronto, incluso si aún tienen sesión activa. Eso normalmente implica desactivar la cuenta en el IdP, y tu app debe tratar una identidad desactivada o ausente como bloqueada inmediatamente.

La desprovisión debe ser predecible: desactivar al usuario, quitar pertenencias a equipos y conservar datos de auditoría. A menudo necesitas preservar registros como aprobaciones, comentarios e historial para cumplimiento, mientras bloqueas nuevas acciones.

Los contratistas y accesos temporales merecen cuidado extra. Ponlos en grupos con fecha límite en el IdP, o adjunta una fecha de revisión a su rol para que el acceso no perdure tras terminar el proyecto.

Una política práctica de offboarding:

• Volver a comprobar claims en cada login y refrescar la pertenencia a equipos desde el IdP
• Cuando un usuario se elimina de grupos requeridos, eliminar privilegios de forma inmediata (siguiente login o próximo sync)
• Desactivar la cuenta preservando auditoría e historial de propiedad
• Requerir una fecha de finalización para acceso de contratistas y revisarla antes de renovar
• Ejecutar revisiones periódicas de acceso para roles sensibles como finanzas o admin

Errores comunes y trampas a evitar

La mayoría de las incidencias de SSO no se deben a que SAML u OIDC sean "difíciles". Ocurren porque la app hace suposiciones inseguras sobre personas, grupos e identificadores.

Un error común es mezclar el mapeo de roles con el de equipos. Los roles son "qué puedes hacer". Los equipos son "dónde perteneces". Si mapeas un grupo de equipo directamente a un rol potente como Admin, a menudo acabarás concediendo acceso amplio a cualquiera que casualmente pertenezca a ese equipo.

Otra trampa es fiarse del email como único identificador para el enlace de cuentas. Los emails cambian y los alias pueden crear duplicados. Prefiere un IdP user ID estable (como sub/NameID) como clave primaria y trata el email como campo de visualización y notificación.

Otros problemas frecuentes:

• Abrir por defecto cuando faltan grupos (mejor no acceder o acceso limitado que acceso total)
• Nombres de grupo poco claros que se reutilizan entre dev, staging y producción
• Tratar la pertenencia a grupos como una lista de permisos sin revisar qué significa cada grupo
• No manejar usuarios multi-equipo que necesitan acceso a más de un área sin convertirse en admin
• Olvidar a partners y contratistas que deben estar aislados de equipos exclusivos para empleados

Prueba casos límite antes del lanzamiento. Un analista de finanzas en respuesta a incidentes podría necesitar dos equipos y un rol elevado. Si tus reglas solo permiten un equipo, perderá acceso o recibirá permisos excesivos.

Lista rápida antes de lanzar

Antes de habilitar SSO para todos, haz una prueba con algunas cuentas de cada equipo. La mayoría de los problemas de acceso aparecen de inmediato cuando pruebas un nuevo empleado, un cambio de rol y un caso de offboarding.

Empieza con el enlace de cuentas. Elige un identificador único que no cambie con el tiempo y úsalo. En OIDC esto suele ser sub. En SAML suele ser NameID o un atributo inmutable específico.

Luego decide qué ocurre cuando faltan claims. El valor por defecto más seguro es no dar acceso elevado (y en muchas apps, ningún acceso) cuando faltan o están vacíos los claims de grupo o rol. Asegúrate de tener al menos un rol de bajo privilegio que deje entrar a la gente sin exponer acciones sensibles, si eso encaja en tu flujo.

Una lista simple previa al lanzamiento:

• Confirma que tu identificador de enlace es estable y único (y que puedes verlo en logs)
• Verifica que claims de grupo faltantes no concedan acceso más allá de un rol de bajo privilegio
• Requiere que el acceso admin se corresponda con un grupo admin explícito, más un segundo paso de aprobación (incluso si es manual)
• Prueba la eliminación: cuando un usuario sale de un grupo, el acceso cae en el siguiente login (o siguiente sync)
• Escribe las reglas de mapeo para que un compañero pueda entenderlas en una sola página

Ejemplo: una herramienta interna de soporte y finanzas con grupos SSO

Imagínate una herramienta operativa usada diariamente por Soporte, Finanzas y algunos managers. Quieres que la gente inicie sesión y obtenga inmediatamente las pantallas y acciones correctas sin que un admin arregle cuentas a mano.

Crea unos pocos grupos en el IdP y mapea a roles y equipos en la app:

• ops-support -> Rol: Support Agent, Equipo: Support
• ops-finance -> Rol: Finance Analyst, Equipo: Finance
• ops-managers -> Rol: Manager, Equipo: Management

Así es cómo se desarrolla:

Ahora un caso de cambio de email: Omar cambia de [email protected] a [email protected]. Como la app enlaza cuentas usando el IdP user ID estable (como sub en OIDC, o un NameID persistente en SAML) en lugar del email, no se crea una cuenta duplicada. Mantiene el mismo historial y trazabilidad de auditoría.

Para verificar el acceso sin adivinar, conserva una vista de "acceso efectivo" que muestre la identidad IdP vinculada del usuario, los grupos recibidos, el rol resultante y el equipo. Cuando algo parezca mal, puedes saber rápido si es un problema del IdP, de la regla de mapeo o de un claim faltante.

Siguientes pasos: mantener el acceso predecible conforme cambia la org

Lo más difícil no es el primer lanzamiento. Es mantener el acceso sano tras reorganizaciones, nuevos equipos y excepciones "temporales".

Mantén un documento de mapeo de una página que responda:

• Qué grupos del IdP se mapean a qué roles y equipos en la app
• Cuál es el valor por defecto cuando falta un claim (y quién aprueba cambios)
• Quién es dueño de cada rol de alto riesgo (admin de finanzas, admin de usuarios, exportación de datos)
• Cómo se manejan contratistas y cuentas de servicio
• Dónde vive la fuente de la verdad (IdP vs app)

Realiza un piloto pequeño con un departamento de límites claros, corrige casos límite y expande sin inventar nuevas reglas. Programa revisiones periódicas para accesos que puedan causar daño real: mensual para roles admin y de alto riesgo, trimestral para roles normales.

Si construyes la app interna tú mismo, ayuda que roles, equipos y lógica de negocio vivan cerca para que los cambios sean fáciles de probar. AppMaster (appmaster.io) es una opción para equipos que quieren modelar roles y flujos visualmente y regenerar código backend, web y móvil real a medida que cambian los requisitos, sin acumular soluciones puntuales para permisos.