Roles
Agrupe permisos de API en roles y asígnelos a usuarios y grupos, para que las aplicaciones autoricen en función del rol.
Nota sobre el plan: El control de acceso basado en roles (RBAC) está disponible a partir del plan Advanced (y en Trial).
Un rol es un conjunto con nombre de permisos de API que usted asigna a usuarios y grupos. Cuando un usuario inicia sesión en una aplicación y esta solicita un token para una API con RBAC habilitado, la plataforma puede incluir los roles y permisos del usuario en el token, de modo que la aplicación pueda tomar decisiones de autorización detalladas sin mantener su propio modelo de permisos.
Los roles se gestionan en Integraciones → Roles en la Admin Console.
Nota: Los administradores delegados (de nivel desarrollador) gestionan los roles a través de los Workspaces a los que pertenecen. Un rol añadido a un Workspace puede ser gestionado y asignado por los miembros con el permiso Gestionar recursos; los administradores completos siguen gestionando todos los roles como hasta ahora.
Los roles se refieren a las aplicaciones, no a la Admin Console
Conviene dejar claro lo que estos roles no regulan. Controlan lo que un usuario puede hacer dentro de sus aplicaciones, mediante los scopes incluidos en los tokens de API. No controlan quién puede administrar la plataforma; eso se regula por separado mediante los niveles de acceso que asigna a su equipo de administración en el área Seguridad.
Roles del sistema y roles personalizados
- Los roles del sistema están integrados. Su nombre, descripción y permisos son fijos; puede consultarlos, pero no editarlos ni eliminarlos.
- Los roles personalizados son los que usted crea y gestiona. Establece su nombre y descripción, elige sus permisos y los asigna a usuarios y grupos.
Crear un rol y añadir permisos
- En la página Roles, elija Crear rol y asígnele un nombre y una descripción.
- Abra el rol y vaya a su pestaña Permisos.
- Elija Añadir permisos, seleccione una Custom API y elija los scopes de esa API que desea incluir.
- Guarde.
Los permisos de un rol siempre están vinculados a una Custom API concreta. Solo las Custom APIs con RBAC habilitado pueden aportar permisos a un rol, así que active primero Incluir roles y permisos (RBAC) en la API (consulte APIs). Si un rol contiene permisos de una API en la que posteriormente se desactivó RBAC, o cuya API se eliminó, esas entradas se marcan en el rol para que pueda depurarlas.
Nota (CIAM): en los despliegues con la capacidad de clientes empresariales (B2B), el formulario de creación de roles ofrece un campo allowed relationship: elija si el rol está disponible para todos los usuarios, solo para usuarios customer o solo para usuarios employee. Esto determina a qué población de usuarios se aplica el rol y queda fijado en el momento de la creación. Sin esa capacidad, un rol se aplica a todos los usuarios.

Asignar roles
Abra un rol y utilice su pestaña Usuarios para asignarlo. Puede asignar un rol a:
- usuarios individuales: consulte Personas, y
- grupos: consulte Grupos, de modo que cada miembro herede el rol.
Para quitar un rol a un usuario, elimínelo de la lista de usuarios del rol. Al eliminar un rol personalizado, se retira de todas las personas a las que estaba asignado.
Cuando un usuario tiene un rol, los permisos que este agrupa pueden incluirse en los tokens de las APIs con RBAC habilitado correspondientes.
Cómo llega un permiso a un token
La cadena desde la definición de un permiso hasta su aplicación en su aplicación:
- Define un permiso (un scope) en una Custom API con RBAC habilitado.
- Lo agrupa en un rol en la pestaña de permisos del rol.
- Asigna el rol a un usuario, directamente o mediante un grupo para que cada miembro lo herede.
- Cuando ese usuario inicia sesión y una aplicación solicita un token para la API, se resuelven los permisos a los que el usuario tiene derecho y pueden incluirse en el access token.
Que los nombres de rol y los permisos aparezcan realmente en el token se controla por API mediante las opciones roles in access token y permissions in access token (consulte APIs). La disyuntiva:
- Activado: la aplicación lee los roles y permisos directamente del token, sin consultas adicionales. El coste es un token más grande, y un token emitido antes de un cambio de rol conserva los claims antiguos hasta que caduca (posible desactualización).
- Desactivado: el token sigue siendo ligero; la aplicación resuelve por sí misma los derechos del usuario cuando los necesita, lo que se mantiene actualizado pero requiere una llamada adicional.
Aplicar en el access token, no en el ID token
Una aplicación que solicita el scope roles también recibe un claim roles en su ID token. Utilícelo solo para la presentación: mostrar una entrada de menú de administración, ocultar un botón. No tome nunca una decisión de acceso basándose en él.
Los dos claims no son intercambiables. El ID token acredita quién ha iniciado sesión y va dirigido a la propia aplicación; no está pensado para reenviarse a una API, y un servicio que lo acepta como prueba de derechos confía en un token que nunca se emitió para él. Su claim roles es además el menos preciso de los dos: enumera nombres de rol sin referencia a ninguna API, por lo que no puede indicarle si un rol tiene algún significado para el recurso al que se llama.
El access token es el que va dirigido a la API, y sus claims se limitan a esa API. Aplique el control ahí.
Referencia
| Término | Significado |
|---|---|
| Rol | Un conjunto con nombre de permisos de API asignado a usuarios y grupos. |
| Rol del sistema | Un rol integrado y no editable. |
| Rol personalizado | Un rol que usted crea y gestiona. |
| Permiso | Un único scope de API que un rol aporta a los tokens de un usuario. |
Consulte también el glosario.
APIs
Proteja sus APIs como recursos OAuth: defina scopes, controle el acceso machine-to-machine y de usuarios, y fije formato y duración de los tokens.
Conexiones
Permita el inicio de sesión con un proveedor de identidad externo (OIDC, SAML, Microsoft Entra, social), con vinculación de cuentas y creación JIT.