CRUGE
Extensión para el Control de Usuarios y Roles.
Ir al repositorio de Cruge Bitbucket
visita mi blog
Comunidad de Yii Framework en Español
PROYECTO BASICO DE DEMOSTRACION
Entorno en donde se ha probado.
PHP Version 5.2.6, 5.4.4, 5.4.5 (ya no hace falta el uso de E_STRICT)
Yii Framework 1.10, 1.11, 1.12
Apache/2.0.58
Que es Cruge ?
Cruge te permite administrar y controlar de forma muy eficiente y segura a tus usuarios y los roles que ellos deban tener en tu aplicacion.
Cruge tiene una alta Arquitectura OOP, basada en interfaces, lo que ayuda enormemente a usarla sin modificar en lo absoluto su propio core. Si necesitas cambiar de ORDBM, cruge lo permite. Si necesitas extender el funcionamiento de autenticacion para admitir nuevos metodos tambien lo permite mediante la implantacion de filtros de autenticacion, incluso dispones ademas de filtros insertables para controlar el otorgamiento de una sesion a un usuario y finalmente para controlar los registros y actualizaciones de perfil de tus usuarios. Todo eso sin tocar en lo absoluto el core de Cruge.
Cruge es un API, que incluye una interfaz de usuario predeterminada con el objeto que puedas usar el sistema como viene ahorrandote mucho tiempo. Esta interfaz hace uso del API de forma estricta, es decir, no hay "dependencias espaguetti" las cuales son las primeras destructoras de todo software.
La arquitectura que tu usarás en Cruge es asi:
internamente esta arquitectura dentro de Cruge es asi:
esto significa, que aun dentro de Cruge las dependencias son estrictamente organizadas, es decir, no verás en ningun lado que el API vaya a instanciar a un modelo cualquiera, si eso fuera asi estariamos hablando de otra "extension" espaguetti, como aquellas que solo le funcionan a su creador, o que en el mejor de los casos, funcionan...pero manipulandoles el core.
Cruge es una extension en todo lo ancho de la palabra, realmente extiende las funciones basicas
de manejo de usuario de Yii Framework, incorporando mas funciones en los paquetes originales.
La interfaz de usuario de Cruge es opcional, con esto quiero decirte que puedes usar Cruge en modo API, para lo cual debes conocer el modelo con detalles, aunque es muy intuitivo y de referencias cortas, para hacerlo entendible.
Instalación
Primero voy a asumir que Cruge ha sido descargado a tu carpeta:
puedes descargar cruge directamente desde un ZIP, o mediante un comando GIT como: git clone [URL DE GIT].
En el archivo de configuración de tu aplicacion (config/main.php) deberas colocar lo siguiente:
usuario=admin
clave=admin
Uso básico de Cruge
Obtener un usuario:
Campos Personalizados:
Verificar un permiso de acceso:
Acceder a las variables del sistema:
Acceder a la Interfaz de Usuario de Cruge:
Personalizando el Layout
Cruge te permite que su interfaz de usuario predeterminada pueda ajustarse a tu sitio web usando lo que en Yii se conoce como Layouts.
Por ejemplo, quieres que el formulario de registro de nuevo usuario se presente en un esquema de diseño distinto al que yii trae por defecto, entonces tu podrias crear un nuevo layout que se ajuste a tus necesidades y luego indicarle a Cruge mediante la configuracion del componente cual seria ese layout a usar cuando un usuario quiera registrarse, asi:
Te cuidado especial con "generalUserManagementLayout": este es un layout especial, porque las funciones de administracion de usuarios requieren un Portlet para presentar las opciones administrativas, por defecto Cruge apunta este valor a: "ui", el cual es el nombre de un layout prefabricado que ya trae un Portlet, practicamente idendico al que Yii trae por defecto llamado //layouts/column2.
El Layout para UI de Cruge por defecto es:
En este layout (ui.php) hay un Portlet, que será llenado con los items de administracion en linea de Cruge, estos items salen del modulo UI de Cruge, el cual es accesible usando:
Presentando el menu de administracion de usuarios
Este menu ya viene listo en cruge, trae todos los items para que te evites el trabajo de ir
a CrugeUi a ver cuales son los links.
Para acceder al array de menu items lo haces desde:
Si usas bootstrap, puedes hacerlo asi:
Usando RBAC
RBAC es el sistema de control de acceso basado en roles (por sus siglas en ingles). Todo el mecanismo RBAC puede ser manejado mediante la interfaz (UI) de Cruge, o mediante su API. Las dos modalidades para usar en este mecanismo son:
Consulta Manual de Permisos.
Es basicamente el mismo mecanismo que provee Yii, pero en Cruge se ha ampliado un poco mas. Para usar este mecanismo: en cualquier parte de tu codigo fuente puedes poner lo siguiente:
user->checkAccess('puede_ver_menu_sistema')) { ...mostar menu sistema... }
?>
Consulta Automatizada segun controller/action.
Este mecanismo es muy util, porque permite controlar el acceso a tus controllers/actions de forma totalmente automatizada y controlada mediante la UI de Cruge. Para usar este mecanismo, necesitarás incluir en tu Controller (cualquiera que tu uses y que desees controlar a nivel de permisos) el siguiente codigo:
Al usar CrugeAccessControlFilter estas permitiendo que Cruge controle el acceso tanto al controller en general como al action especifico.
Ejemplo:
Si tu quieres denegar el total acceso a un controller simplemente no le asignas al usuario la operacion que tenga el nombre del controller antecedido de la palabra 'controller_'.
Si tu quieres denegar el acceso a un action de un controller simplemente no le asignas al usuario la operacion que tenga el nombre del action: 'action_nombrecontroller_nombreaction'.
Modo de Programacion del RBAC
Para activarlo, en la configuracion de tu aplicacion debes considerar estos dos argumentos:
'rbacSetupEnabled'=>true,
'allowUserAlways'=>true,
Para conocer que operaciones se requieren para un usuario especifico debes poner en tu layout principal la siguiente linea:
Usando el LOG
Adicionalmente todos los errores de permiso que se generen seran reportados en el log bajo el key 'rbac', para poder visualizar los errores en protected/runtime/application.log deberas configurar tu config/main.php para indicar el key del log:
eso causara que en:
se emitan mensajes como estos:
EL usuario Invitado
Cruge hace especial tratamiento al usuario invitado. Para esto CrugeModule contiene un atributo llamado guestUserId , el cual es usado para indicarle al sistema Cruge cual de sus usuarios existentes en la base de datos de usuarios es el invitado.
Por defecto cuando Cruge es instalado desde el script de base de datos (protected/modules/cruge/data), se crean dos usuarios:
Siendo 'admin' el usuario con ID 1, y siendo 'invitado' el usuario con ID 2. Por esto veras que por defecto en CrugeModule.php ya esta predefinido el atributo guestUserId en 2. No lo cambies a menos que cambies el ID del usuario invitado.
Roles para el usuario Invitado
Si no asignas al usuario invitado a ningun rol entonces no tendrá acceso a ninguna parte. Por tanto debes:
Crea un rol llamado 'invitado'.
Asignale a ese rol las operaciones necesarias, por ejemplo 'controller_site', 'action_site_index', 'action_site_contact', 'action_site_login' y otras que vayas viendo que se requieran (usa el LOG, ver tema anterior).
Asigna este rol creado al usuario invitado.
No necesariamente el rol del 'invitado' debe llamarse 'invitado'. Por conveniencia es sano que asi sea pero no es indispensable.
Como trata el sistema de usuarios al inviatdo
Por defecto en YII cuando tu llamas a Yii::app()->user->id esta devuelve 0 (cero) cuando un usuario es invitado.
En Cruge esta misma llamada a Yii::app()->user->id devolverá al valor de: CrugeModule::guestUserId, por defecto 2.
Puedes confiar en Yii::app()->user->isGuest. ya que ésta considera todo esto para saber si el usuario es un invitado.
Encriptando las claves
Por defecto Cruge trae dos usuarios, admin e invitado. En el caso de admin la clave es 'admin', y por defecto además Cruge trae la encriptacion de claves desactivada, para facilitar el trabajo mientras se instala. Esto se modifica en: 'useEncryptedPassword' => false (del config/main).
Si quieres encriptar las claves, es decir, que en la tabla de usuarios estas no sean visibles, entonces deberas tomar un paso extra: encriptar tu clave de admin y guardarla via base de datos en la tabla de usuarios (cruge_user),
luego activas la encriptacion y con eso podrás acceder y veras que los nuevos usuarios que se vayan creando tendránsu nueva clave encriptada.
Encriptación MD5. Donde esta ubicada y donde cambiarla
Hay dos sitios en Cruge en donde se maneja la encriptacion:
cruge\models\auth\CrugeAuthDefault.php
Aqui se valida la autenticacion del usuario que esta intentando acceder, se convierte la clave a su MD5 y se compara con la almacenada.
cruge\components\CrugeUserManager.php
Aqui se maneja el cambio de clave.
Filtros
Cruge permite que se pueda extender mas alla usando filtros. Existen varios tipos de filtros, todos se instalan en config/main y disponen de una interfaz (interface) que debes respetar, a continuación la lista de filtros, si necesitas crear un filtro nuevo fijate en como esta hecho el filtro por defecto:
filtros de autenticacion:
permite que amplies como se busca un usuario para ser autenticado.
protected\modules\cruge\models\auth\CrugeAuthDefault.php
filtros de sesion:
permite que puedas controlar como se entrega una sesion a un usuario, inclusive puedes denegarla.
protected\modules\cruge\models\filters\DefaultSessionFilter.php
filtro de actualizacion:
permite saber si un usuario actualizo su perfil.
protected\modules\cruge\models\filters\DefaultUserFilter.php
Debido a lo extenso de Cruge no he tenido tiempo de documentar bien estos filtros, pero es bastante intuitivo.
Traduccion
Si ves, Cruge escribe los mensajes en español, mientras que su codigo esta en inglés. Todos los mensajes se dirigen a la clase CrugeTranslator::t("mensaje en español"), por tanto ese es el punto para traducir a otro idioma. En un futuro nuevo commit hare un nuevo filtro, para traducir, sin que tengas que tocar nada dentro de CrugeTranslator.