Saltar al contenido principal

Control de Acceso Basado en Reglas

Roles, Permisos y Usuarios en OmniCRM​

OmniCRM utiliza control de acceso basado en roles (RBAC): las personas (Usuarios) son asignadas a uno o más Roles, y cada Rol es un conjunto de Permisos. Los Permisos son la unidad más pequeña de acceso (por ejemplo, view_customer, create_inventory). El acceso efectivo de un usuario es la unión de los permisos de todos los roles asignados.

Propósito​

RBAC permite:

  1. Protección de Datos --- Los usuarios solo ven y hacen lo que se les permite.
  2. Ajuste Operativo --- Los roles reflejan funciones laborales (Admin, Soporte, Finanzas, Administrador de Clientes).
  3. Administración Simple --- Conceder acceso asignando roles; evitar la microgestión por usuario.
  4. Aislamiento de Inquilinos --- Los permisos de "ver propio ..." limitan la visibilidad a los datos de cliente/inquilino propios de un usuario.

RBAC Permissions

Cómo se Integran Usuarios, Roles y Permisos​

  • Usuarios --- Personas reales que inician sesión en OmniCRM.
  • Permisos --- Capacidades atómicas (por ejemplo, view_customer, delete_product).
  • Roles --- Conjuntos nombrados de permisos (por ejemplo, Admin, Soporte, Finanzas).
  • Asignación --- Los usuarios reciben uno o más roles; los permisos se agregan.

RBAC Permissions

La autenticación prueba quién eres (JWT, clave API o IP en lista blanca). La autorización (roles/permisos) decide qué puedes hacer.

Gestión de Usuarios​

El sistema de gestión de usuarios de OmniCRM permite a los administradores crear y gestionar usuarios del personal (administradores, agentes de servicio al cliente), ver y modificar roles de usuario, restablecer contraseñas, gestionar la autenticación de dos factores y controlar el acceso de los usuarios.

Tipos de Usuarios​

Usuarios Clientes - Creado a través de auto-registro o por administradores. Asignado automáticamente el rol de "Cliente". Estos usuarios acceden al portal de autoservicio para gestionar sus servicios, ver el uso, pagar facturas, etc.

Usuarios del Personal - Creado por administradores con permisos apropiados. Pueden ser asignados roles como Admin, Soporte, Finanzas, etc. Estos usuarios acceden a la interfaz de CRM para gestionar clientes, provisionar servicios, manejar facturación, etc.

Usuarios Administrativos - Usuarios con el permiso admin. Tienen acceso completo al sistema, incluyendo gestión de usuarios, gestión de roles y todos los puntos finales protegidos.

El usuario administrativo inicial es creado por el equipo de Omnitouch cuando se despliega el sistema.

Agregar Nuevos Usuarios (Administradores y CSAs)​

Los administradores pueden crear nuevos usuarios del personal a través de la interfaz web o API.

A través de la Interfaz Web​

  1. Navegar a Usuarios y Roles - Acceder a la interfaz de gestión de usuarios desde el menú de administración.
  2. Hacer clic en "Agregar Usuario" - Abre el formulario de creación de usuario.

Adding a User

  1. Completar los Detalles del Usuario:
    • Nombre de Usuario - Nombre de usuario único para iniciar sesión (requerido).
    • Correo Electrónico - Dirección de correo electrónico del usuario (requerido, debe ser único).
    • Contraseña - Contraseña temporal (requerido, el usuario debe cambiarla en el primer inicio de sesión).
    • Nombre - Primer nombre del usuario (requerido).
    • Segundo Nombre - Segundo nombre del usuario (opcional).
    • Apellido - Apellido del usuario (requerido).
    • Número de Teléfono - Número de teléfono de contacto (opcional).
    • Rol - Seleccionar uno o más roles para asignar (requerido).
    • Contacto del Cliente - Opcionalmente vincular al usuario a un registro de contacto del cliente (para usuarios clientes).
  2. Hacer clic en "Crear Usuario" - El usuario es creado y puede iniciar sesión inmediatamente con las credenciales proporcionadas.
  3. El usuario recibe notificación - Opcionalmente enviar un correo electrónico de bienvenida con instrucciones de inicio de sesión.

Mejores Prácticas:

  • Usar una contraseña temporal como TempP@ssw0rd! y requerir que el usuario la cambie en el primer inicio de sesión.
  • Asignar roles apropiados según la función laboral (ver Diseños de Roles Típicos a continuación).
  • Habilitar 2FA para todo el personal administrativo y de soporte.
  • Vincular usuarios clientes a su registro de contacto del cliente para un correcto alcance de datos.

A través de la API​

Crear un usuario programáticamente:

Endpoint: POST /auth/users

Permiso Requerido: admin

Cuerpo de la Solicitud:

{
  "username": "john.smith",
  "email": "john.smith@company.com",
  "password": "TempP@ssw0rd!",
  "first_name": "John",
  "middle_name": "D",
  "last_name": "Smith",
  "phone_number": "+61412345678",
  "role": "Support"
}

Respuesta:

{
  "id": 123,
  "username": "john.smith",
  "email": "john.smith@company.com",
  "first_name": "John",
  "last_name": "Smith",
  "roles": ["Support"],
  "created": "2025-01-04T10:30:00Z"
}

Asignando Múltiples Roles:

Los usuarios pueden tener múltiples roles. Los permisos son aditivos (unión de todos los permisos de roles asignados).

Para asignar múltiples roles, inclúyelos en la solicitud:

{
  "username": "jane.doe",
  "email": "jane.doe@company.com",
  "password": "TempP@ssw0rd!",
  "first_name": "Jane",
  "last_name": "Doe",
  "role": "Support,Finance"
}

O usa el endpoint de asignación de roles después de la creación del usuario:

POST /auth/roles/{role_id}/users/{user_id}

Ver y Buscar Usuarios​

Listar Todos los Usuarios (Admin):

GET /auth/users

Devuelve una lista paginada de todos los usuarios con sus roles e información básica.

Buscar Usuarios:

GET /auth/users/search?search={query}&filters={"role":["Support"]}&page=1&per_page=50

Filtrar por:

  • Nombre del rol
  • Dominio de correo electrónico
  • Estado activo/eliminado
  • Estado de habilitación de 2FA
  • Fecha del último inicio de sesión

Obtener Usuario Específico:

GET /auth/users/{user_id}

Devuelve detalles completos del usuario, incluyendo:

  • Información personal
  • Roles asignados y permisos efectivos
  • Estado de 2FA
  • Último inicio de sesión e información de sesión
  • Contacto del cliente vinculado (si aplica)

Crear y Gestionar Roles​

Los roles son colecciones de permisos que pueden ser asignados a los usuarios. En lugar de asignar permisos individualmente a cada usuario, creas roles que agrupan permisos relacionados y asignas esos roles a los usuarios.

Crear un Nuevo Rol​

A través de la Interfaz Web:

  1. Navegar a Usuarios y Roles → pestaña Roles.
  2. Hacer clic en "Crear Rol".
  3. Ingresar detalles del rol:
    • Nombre - Nombre corto y descriptivo (por ejemplo, "Tier2_Support").
    • Descripción - Explicar el propósito y responsabilidades del rol.
  4. Hacer clic en "Crear".
  5. El rol es creado sin permisos; agregar permisos en el siguiente paso.

A través de la API:

Endpoint: POST /auth/roles

Permiso Requerido: admin

Solicitud:

{
  "name": "Tier2_Support",
  "description": "Equipo de soporte de nivel 2 con acceso elevado a aprovisionamiento"
}

Respuesta:

{
  "id": 45,
  "name": "Tier2_Support",
  "description": "Equipo de soporte de nivel 2 con acceso elevado a aprovisionamiento",
  "permissions": [],
  "users": []
}

Agregar Permisos a un Rol​

Una vez que se crea un rol, asigna permisos para definir lo que los usuarios con ese rol pueden hacer.

A través de la Interfaz Web:

  1. Navegar a Usuarios y Roles → pestaña Roles.
  2. Hacer clic en el nombre del rol para ver detalles.
  3. En la sección Permisos, hacer clic en "Agregar Permiso".
  4. Seleccionar uno o más permisos de la lista.
  5. Hacer clic en "Agregar" - Los permisos se asignan inmediatamente.

Managing Role Permissions

Assigning Permissions to Role

A través de la API:

Endpoint: POST /auth/roles/{role_id}/permissions

Solicitud:

{
  "permission_id": 123
}

O agregar múltiples permisos:

{
  "permission_ids": [123, 124, 125]
}

Ejemplo: Creando un Rol de "Especialista en Aprovisionamiento"

Este rol puede ver clientes, gestionar servicios y aprovisionar:

  1. Crear el rol:

    POST /auth/roles
    {
      "name": "Provisioning_Specialist",
      "description": "Puede aprovisionar servicios y gestionar servicios de clientes"
    }

  2. Agregar permisos:

    POST /auth/roles/45/permissions
    {
      "permission_ids": [
        1,   # view_customer
        20,  # view_customer_service
        21,  # create_customer_service
        22,  # update_customer_service
        30,  # view_provision
        31,  # create_provision
        40,  # view_inventory
        50,  # view_product
      ]
    }

Eliminar Permisos de un Rol​

A través de la Interfaz Web:

  1. Navegar a los detalles del rol.
  2. En la lista de Permisos, hacer clic en el botón "X" o "Eliminar" junto al permiso.
  3. Confirmar la eliminación.

A través de la API:

Endpoint: DELETE /auth/roles/{role_id}/permissions/{permission_id}

Ejemplo:

DELETE /auth/roles/45/permissions/31

Esto elimina el permiso create_provision del rol.

Editar Detalles del Rol​

Actualizar el nombre o la descripción del rol:

A través de la Interfaz Web:

  1. Navegar a Usuarios y Roles → pestaña Roles.
  2. Hacer clic en el rol para editar.
  3. Modificar el nombre o la descripción del rol.
  4. Hacer clic en "Guardar".

Editing Role Details

A través de la API:

Endpoint: PUT /auth/roles/{role_id}

{
  "name": "Senior_Support",
  "description": "Equipo de soporte senior con acceso completo a clientes"
}

Eliminar un Rol​

Advertencia: Eliminar un rol lo quita de todos los usuarios asignados. Asegúrate de que los usuarios tengan roles alternativos o perderán el acceso.

A través de la API:

DELETE /auth/roles/{role_id}

Mejor Práctica: En lugar de eliminar, considera archivar o renombrar roles que ya no son necesarios.

Asignar Roles a Usuarios​

Durante la Creación de Usuarios:

Incluir el rol en la solicitud de creación de usuario (ver "Agregar Nuevos Usuarios" arriba).

Para Usuarios Existentes:

A través de la Interfaz Web:

  1. Navegar a Usuarios y Roles → pestaña Usuarios.
  2. Hacer clic en el usuario para editar.
  3. En la sección Roles, seleccionar/deseleccionar roles.
  4. Hacer clic en "Guardar".

Editing User Roles

A través de la API:

Actualizar los roles del usuario:

Endpoint: PUT /auth/users/{user_id}

{
  "role": "Support,Finance"
}

O asignar un solo rol a un usuario a través del endpoint de rol:

Endpoint: POST /auth/roles/{role_id}/users/{user_id}

Ver Asignaciones de Roles​

Todos los usuarios en un rol:

GET /auth/roles/{role_id}/users

Devuelve una lista de todos los usuarios asignados a ese rol.

Todos los roles para un usuario:

GET /auth/users/{user_id}

La respuesta incluye un array roles con todos los roles asignados.

Gestión de Contraseñas de Usuario​

OmniCRM proporciona múltiples métodos para la gestión de contraseñas dependiendo del contexto.

Restablecimiento de Contraseña por Autogestión del Usuario​

Los usuarios que olvidaron su contraseña pueden restablecerla ellos mismos a través de la página de inicio de sesión:

  1. Hacer clic en "Olvidé mi Contraseña" en la página de inicio de sesión.
  2. Ingresar dirección de correo electrónico - El sistema envía un correo electrónico de restablecimiento de contraseña.
  3. Revisar correo electrónico - El correo contiene un enlace seguro de restablecimiento con token (válido por 1 hora).
  4. Hacer clic en el enlace - Abre el formulario de restablecimiento de contraseña.
  5. Ingresar nueva contraseña - Debe cumplir con los requisitos de complejidad de la contraseña:
    • Mínimo 8 caracteres.
    • Al menos una letra mayúscula.
    • Al menos una letra minúscula.
    • Al menos un número.
    • Al menos un carácter especial.
  6. Enviar - La contraseña se actualiza inmediatamente; el usuario puede iniciar sesión con la nueva contraseña.

Flujo de API:

  1. Solicitar restablecimiento:

    Endpoint: POST /auth/forgot_password

    {
      "email": "user@example.com"
    }

    El sistema genera un token de restablecimiento y envía un correo electrónico.

  2. Restablecer con token:

    Endpoint: POST /auth/reset_password

    {
      "token": "abc123...",
      "new_password": "NewSecureP@ssw0rd!"
    }

Restablecimiento de Contraseña por Administrador​

Los administradores pueden restablecer la contraseña de un usuario sin requerir verificación por correo electrónico. Esto establece una contraseña temporal que el usuario debe cambiar en el siguiente inicio de sesión.

A través de la Interfaz Web:

  1. Navegar a Usuarios y Roles → Usuarios.
  2. Encontrar al usuario y hacer clic en el botón "Restablecer Contraseña".
  3. Ingresar una contraseña temporal.
  4. Hacer clic en "Restablecer".
  5. Notificar al usuario sobre su contraseña temporal (a través de un canal seguro).
  6. El usuario debe cambiar la contraseña en el siguiente inicio de sesión.

A través de la API:

Endpoint: POST /auth/users/{user_id}/admin_reset_password

Permiso Requerido: admin

Solicitud:

{
  "new_password": "TempP@ssw0rd!",
  "force_change": true
}

Parámetros:

  • new_password - Contraseña temporal a establecer.
  • force_change (opcional) - Si es verdadero, el usuario debe cambiar la contraseña en el siguiente inicio de sesión.

Cambio de Contraseña por el Usuario​

Los usuarios autenticados pueden cambiar su propia contraseña desde su perfil:

Endpoint: POST /auth/change_password

Solicitud:

{
  "current_password": "OldP@ssw0rd!",
  "new_password": "NewSecureP@ssw0rd!"
}

El sistema valida la contraseña actual antes de permitir el cambio.

Seguridad de Contraseña​

  • Las contraseñas se almacenan utilizando bcrypt (seguridad de werkzeug).
  • Nunca se almacenan en texto plano.
  • Los tokens de restablecimiento expiran después de 1 hora.
  • Los intentos fallidos de inicio de sesión pueden activar el bloqueo de la cuenta (configurable).
  • El seguimiento del historial de contraseñas previene la reutilización (configurable).
  • Se aplican requisitos de complejidad.

Gestión de la Autenticación de Dos Factores (2FA)​

OmniCRM admite la autenticación de dos factores basada en TOTP para mayor seguridad. Los administradores pueden habilitar, deshabilitar y restablecer 2FA para los usuarios.

OmniCRM 2FA nag popup shown to admin users

Habilitar 2FA para un Usuario​

A través de la Interfaz Web:

  1. Navegar a Usuarios y Roles → Usuarios.
  2. Hacer clic en el usuario para ver detalles.
  3. En la sección Seguridad, hacer clic en "Habilitar 2FA".
  4. El sistema genera:
    • Secreto TOTP (se muestra el código QR).
    • 10 códigos de respaldo (uso único).
  5. El usuario escanea el código QR con la aplicación de autenticación (Google Authenticator, Authy, etc.).
  6. El usuario ingresa el código de verificación de la aplicación para confirmar la configuración.
  7. El usuario guarda los códigos de respaldo en un lugar seguro.
  8. 2FA ahora está habilitado; se requiere para todos los futuros inicios de sesión.

OmniCRM 2FA enrollment page

A través de la API:

  1. Generar secreto TOTP:

    Endpoint: POST /2fa/enable/user/{user_id}

    Respuesta:

    {
      "totp_secret": "JBSWY3DPEHPK3PXP",
      "qr_code_url": "otpauth://totp/OmniCRM:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=OmniCRM",
      "backup_codes": [
        "12345678",
        "23456789",
        "34567890",
        ...
      ]
    }

  2. Verificar configuración:

    Endpoint: POST /2fa/verify-setup/user/{user_id}

    {
      "code": "123456"
    }

    Devuelve {"verified": true} en caso de éxito.

Flujo de Inicio de Sesión 2FA​

Una vez que 2FA está habilitado, el proceso de inicio de sesión cambia:

  1. El usuario ingresa nombre de usuario y contraseña.
  2. El sistema valida las credenciales.
  3. Si son válidas, solicita el código 2FA.
  4. El usuario ingresa el código de la aplicación de autenticación O el código de respaldo.
  5. El sistema verifica el código.
  6. En caso de éxito, el usuario inicia sesión.

OmniCRM 2FA Login

Códigos de Respaldo:

  • 10 códigos generados durante la configuración de 2FA.
  • Solo de un solo uso (consumidos después de su uso).
  • Utilizados si la aplicación de autenticación no está disponible.
  • Pueden ser regenerados por el usuario o el administrador.

Verificando el Código 2FA​

Endpoint: POST /2fa/verify/user/{user_id}

{
  "code": "123456"
}

Acepta ambos:

  • Código TOTP (6 dígitos de la aplicación de autenticación).
  • Código de respaldo (8 dígitos de la lista de códigos de respaldo).

Regenerando Códigos de Respaldo​

Si un usuario agota los códigos de respaldo o los pierde, genera nuevos:

A través de la Interfaz Web:

  1. Navegar a los detalles del usuario.
  2. Hacer clic en "Regenerar Códigos de Respaldo".
  3. Mostrar o enviar nuevos códigos al usuario.
  4. Los códigos antiguos se invalidan.

A través de la API:

Endpoint: POST /2fa/backup-codes/regenerate/user/{user_id}

Respuesta:

{
  "backup_codes": [
    "98765432",
    "87654321",
    "76543210",
    ...
  ]
}

Restablecimiento de 2FA por Administrador​

Si un usuario pierde el acceso a su aplicación de autenticación y todos los códigos de respaldo, un administrador puede deshabilitar y volver a habilitar 2FA.

A través de la Interfaz Web:

  1. Navegar a Usuarios y Roles → Usuarios.
  2. Hacer clic en el usuario.
  3. Hacer clic en el botón "Restablecer 2FA".
  4. Confirmar el restablecimiento.
  5. 2FA está deshabilitado; el usuario puede iniciar sesión solo con la contraseña.
  6. Guiar al usuario para que configure 2FA nuevamente con el nuevo secreto.

OmniCRM 2FA Reset

A través de la API:

Endpoint: POST /2fa/admin/disable/user/{user_id}

Permiso Requerido: admin

Esto deshabilita completamente 2FA para el usuario:

  • Se borra el secreto TOTP.
  • Se borran los códigos de respaldo.
  • Se establece la bandera is_2fa_enabled en falso.

El usuario puede volver a habilitar 2FA para obtener un nuevo secreto y códigos de respaldo.

Restablecimiento de 2FA por el Usuario (Nuevo Dispositivo)​

Si un usuario obtiene un nuevo dispositivo pero aún tiene acceso a los códigos de respaldo:

Endpoint: POST /2fa/reset-for-new-device/user/{user_id}

{
  "backup_code": "12345678"
}

El sistema valida el código de respaldo, luego genera un nuevo secreto TOTP y códigos de respaldo. El usuario puede configurar la aplicación de autenticación en el nuevo dispositivo.

Mejores Prácticas de 2FA​

  • Requerir 2FA para todo el personal administrativo y de soporte.
  • Almacenar los códigos de respaldo de forma segura (gestor de contraseñas o nota segura).
  • Regenerar códigos de respaldo después de usar varios.
  • Usar aplicaciones de autenticación de buena reputación (Google Authenticator, Authy, Microsoft Authenticator).
  • Documentar los procedimientos de restablecimiento de 2FA para el personal de soporte.
  • Auditar el uso de 2FA - monitorear qué usuarios tienen 2FA habilitado.

Actualizando la Información del Usuario​

Los administradores pueden actualizar los detalles del usuario en cualquier momento.

A través de la Interfaz Web:

  1. Navegar a Usuarios y Roles → Usuarios.
  2. Hacer clic en el usuario para editar.
  3. Modificar cualquier campo editable:
    • Nombre, segundo nombre, apellido.
    • Dirección de correo electrónico (requiere verificación).
    • Número de teléfono.
    • Roles.
    • Vinculación de contacto del cliente.
  4. Hacer clic en "Guardar".

A través de la API:

Endpoint: PUT /auth/users/{user_id}

{
  "first_name": "Jane",
  "last_name": "Doe-Smith",
  "email": "jane.doesmith@newcompany.com",
  "phone_number": "+61498765432",
  "role": "Support,Finance"
}

Cambios de Correo Electrónico:

Cuando se cambia el correo electrónico, el nuevo correo se marca como pendiente hasta que se verifique:

  • El campo pending_email almacena el nuevo correo.
  • Se envía un correo electrónico de verificación a la nueva dirección.
  • El usuario hace clic en el enlace para verificar.
  • El campo email se actualiza al nuevo valor.
  • La bandera email_verified se establece en verdadero.

Eliminando Usuarios​

OmniCRM utiliza eliminaciones suaves para los usuarios: se marcan como eliminados pero no se eliminan de la base de datos. Esto preserva las auditorías y los datos históricos.

Eliminar un Usuario​

A través de la Interfaz Web:

  1. Navegar a Usuarios y Roles → Usuarios.
  2. Encontrar al usuario a eliminar.
  3. Hacer clic en el botón "Eliminar".
  4. Confirmar la eliminación.
  5. El usuario es inmediatamente desconectado y no puede iniciar sesión nuevamente.

A través de la API:

Endpoint: DELETE /auth/users/{user_id}

Permiso Requerido: admin

Qué Ocurre:

  • La bandera deleted se establece en True.
  • Se registra la marca de tiempo deleted_at.
  • El usuario no puede iniciar sesión.
  • Todas las sesiones activas se invalidan.
  • El usuario aún aparece en los registros de auditoría y registros históricos.
  • Los datos vinculados (contactos de clientes, actividades) se preservan.

Ver Usuarios Eliminados​

Filtrar por usuarios eliminados:

GET /auth/users/search?filters={"deleted":[true]}

Restaurar un Usuario Eliminado​

Si un usuario fue eliminado por error, los administradores pueden restaurarlo:

Endpoint: PUT /auth/users/{user_id}

{
  "deleted": false
}

Esto borra la bandera deleted y permite que el usuario inicie sesión nuevamente.

Nota: La contraseña del usuario permanece sin cambios, por lo que puede usar su contraseña anterior.

Eliminación Permanente de un Usuario​

Advertencia: Esto es irreversible y elimina todos los datos del usuario de la base de datos.

No se expone a través de la interfaz de usuario. Solo está disponible a través de acceso directo a la base de datos por razones de cumplimiento (por ejemplo, solicitudes de eliminación de datos GDPR).

Mejores Prácticas para la Eliminación de Usuarios​

  • Eliminar suavemente por defecto - Preserva las auditorías.
  • Documentar razones de eliminación - Agregar nota en el registro de actividad antes de eliminar.
  • Transferir propiedad - Reasignar los tickets abiertos y tareas del usuario antes de eliminar.
  • Revisar acceso - Asegurarse de que no haya procesos críticos que dependan del usuario.
  • Archivar datos - Exportar el historial de trabajo del usuario si es necesario.
  • Notificar a los equipos relevantes - Informar a gerentes/compañeros sobre la eliminación.

Catálogo de Permisos​

Los permisos generalmente siguen patrones CRUD:

  • view\_\* --- leer/navegar.
  • create\_\* --- crear/agregar.
  • update\_\* --- editar/modificar.
  • delete\_\* --- eliminar/remover.

Algunas entidades también incluyen variantes "ver propio ..." que restringen la visibilidad a los datos del cliente/inquilino propio del usuario.

RBAC Permissions

Global / Administrativo​

  • admin --- Acceso administrativo completo (gestionar usuarios, roles y permisos; acceder a todos los puntos finales protegidos).
  • can_impersonate --- Actuar temporalmente como otro usuario (auditado; para soporte/troubleshooting).

Clientes y Registros Relacionados​

  • Cliente
    • view_customer, create_customer, update_customer, delete_customer
    • Alcance propio: ver propio cliente
  • Sitio del Cliente
    • view_customer_site, create_customer_site, update_customer_site, delete_customer_site
    • Alcance propio: ver propio sitio del cliente
  • Contacto del Cliente
    • view_customer_contact, create_customer_contact, update_customer_contact, delete_customer_contact
    • Alcance propio: ver propio contacto del cliente
  • Atributo del Cliente (ver Atributos del Cliente)
    • view_customer_attribute, create_customer_attribute, update_customer_attribute, delete_customer_attribute
    • Alcance propio: ver propio atributo del cliente
  • Etiqueta del Cliente (ver Etiquetas del Cliente)
    • view_customer_tag, create_customer_tag, update_customer_tag, delete_customer_tag
    • Alcance propio: ver propia etiqueta del cliente
  • Servicio del Cliente
    • view_customer_service, create_customer_service, update_customer_service, delete_customer_service
    • Alcance propio: ver propio servicio del cliente
  • Actividad del Cliente
    • view_customer_activity, create_customer_activity, update_customer_activity, delete_customer_activity
    • Alcance propio: ver propia actividad del cliente

Facturación​

  • Tarjeta de Stripe
    • view_customer_stripe_card, create_customer_stripe_card, update_customer_stripe_card, delete_customer_stripe_card
    • Alcance propio: ver propia tarjeta de stripe del cliente
  • Transacciones
    • view_customer_transaction, create_customer_transaction, update_customer_transaction, delete_customer_transaction
    • Alcance propio: ver propia transacción del cliente
  • Facturas
    • view_customer_invoice, create_customer_invoice, update_customer_invoice, delete_customer_invoice
    • Alcance propio: ver propia factura del cliente

Comunicaciones​

  • view_communication, create_communication, update_communication, delete_communication
  • Alcance propio: ver propia comunicación

Inventario y Plantillas​

  • Inventario
    • view_inventory, create_inventory, update_inventory, delete_inventory
    • Alcance propio: ver propio inventario
  • Plantilla de Inventario
    • view_inventory_template, create_inventory_template, update_inventory_template, delete_inventory_template
    • Alcance propio: ver propia plantilla de inventario

Productos​

  • view_product, create_product, update_product, delete_product

Difusión Celular (CBC)​

  • view_cbc_message, create_cbc_message, update_cbc_message, delete_cbc_message

Aprovisionamiento​

  • Aprovisionar
    • view_provision, create_provision, update_provision, delete_provision
    • Alcance propio: ver propio aprovisionamiento
  • Evento de Aprovisionamiento
    • view_provision_event, create_provision_event, update_provision_event, delete_provision_event

Acceso "Ver Propio"​

Los permisos "ver propio ..." limitan las lecturas (y opcionalmente las ediciones, donde se implementen) a los datos asociados con el propio cliente/inquilino del usuario. Por ejemplo, un rol de Administrador de Clientes puede gestionar los contactos, sitios, facturas y servicios de su inquilino, pero no puede ver otros inquilinos.

Diseños de Rol Típicos​

Rol Permisos Típicos Notas

Administrador del Sistema admin, opcionalmente can_impersonate; además de CRUD amplio según sea necesario Control total sobre usuarios/roles/permisos Soporte view_customer, view_customer_service, view_communication, view_provision; actualizaciones opcionales Agregar can_impersonate si está permitido Finanzas view_customer_invoice, view_customer_transaction, view_product; opcional create_customer_invoice Enfocado en lectura; escritura limitada Administrador de Clientes (inquilino) "ver propio ..." en clientes, sitios, contactos, servicios, inventario, facturas, transacciones, comunicaciones, aprovisionamiento Gestión con alcance de inquilino Auditor Solo Lectura Amplio view_* solamente Sin crear/actualizar/eliminar

: Ejemplo de Roles y Permisos Incluidos (resumen)

Gestión de Roles y Permisos a través de la API​

Todos los endpoints requieren permiso admin.

Listar permisos​

Endpoint: GET /auth/permissions

Crear un permiso (raro)​

Endpoint: POST /auth/permissions

Cuerpo de la Solicitud:

{
    "name": "view_example",
    "description": "Acceso solo de lectura a objetos de ejemplo"
}

Listar roles​

Endpoint: GET /auth/roles

Crear un rol​

Endpoint: POST /auth/roles

Cuerpo de la Solicitud:

{
"name": "Support",
"description": "Equipo de soporte de nivel 1"
}

Agregar un permiso a un rol​

Endpoint: POST /auth/roles/{role_id}/permissions

Cuerpo de la Solicitud:

{
  "permission_id": 123
}

Eliminar un permiso de un rol​

Endpoint: DELETE /auth/roles/{role_id}/permissions/{permission_id}

Asignando Roles a Usuarios​

Crear un usuario con rol​

Endpoint: POST /auth/users

Cuerpo de la Solicitud:

{
  "username": "sara",
  "email": "sara@example.com",
  "password": "TempP@ssw0rd!",
  "first_name": "Sara",
  "last_name": "Ng",
  "phone_number": "+61...",
  "role": "Support"
}

Actualizar el rol de un usuario​

Endpoint: PUT /auth/users/{user_id}

Cuerpo de la Solicitud:

{
  "role": "Finance"
}

Listar usuarios (solo Admin)​

Endpoint: GET /auth/users

Suplantación (Controlada)​

  • Requerido: can_impersonate o admin

Iniciar suplantación​

Endpoint: POST /auth/impersonate

Cuerpo de la Solicitud:

{ "user_id": 42 }

Detener suplantación​

Endpoint: POST /auth/stop_impersonation

Mejores Prácticas​

  • Menor privilegio primero. Comenzar con roles mínimos; agregar permisos según sea necesario.
  • Preferir "ver propio ...". Usar permisos con alcance de inquilino para roles orientados al cliente.
  • Mantener roles estables. Actualizar permisos de rol cuando cambien las características---no editar cada usuario.
  • Auditar regularmente. Revisar quién tiene admin o can_impersonate.

Preguntas Frecuentes​

¿Puede un usuario tener múltiples roles? Sí. Los permisos son aditivos.

¿Necesito permisos personalizados? Generalmente no. El catálogo incorporado cubre la mayoría de las necesidades.

¿Cómo saben las reglas "ver propio ..." qué es mío? Evalúan la vinculación entre tu usuario/contacto y tu cliente (inquilino).