Usermanagement

The usermanagement modul contains a backend for user administration and a generic business component - based on the GenericORMapper - that can be used for authentication purposes and to manage the users, groups, roles, permissions and permission sets. The built-in module is aimed to standardize user management. On the other hand, it is intended to be a reliable and reusable tool for this central issue, that eases daily work.

The following chapters describe the design of the module and present examples for usage of the business component and the Inclusion of the backend into existing applications.

1. Design of the module

The module consists of a business component, the UmgtManager, and a management backend. The manager uses the GenericORMapper as the data layer component. The backend is completely based on the business layer of the module. This means, that other applications or modules can use the UmgtManager as a fully qualified business component for authentication and user management purposes.

1.1. Datamodel

The data model contains fife different objects:

• User
• Grouos
• Roles
• Permission sets
• Permissions

The separation in these five types makes a granular and generic usermanagement possible. The following UML diagram shows the objects mentioned and the relations between them:



Note: Groups are typically used to represent permissions on objects, roles are aimed to control permissions on functions. To be able to reuse permission definitions within different roles, the permission set was introduced. This container encapsulated one or more permissions, that can thus be assignet to a role.

1.2. UmgtManager

The business component features a set of methods, that provide abstract data access to the data model presented above. The list does not only contain CRUD functionality but also functions to create, read, update and delete relations between the objects. Futher, functions for user authentication and effective usage of the usermanagement have been implemented.

The following list gives you a overview of the API methods available. Details can be taken from the API documentation of the UmgtManager class:

• loadUserByEMailAndPassword(): Loads a user object by email and password.
• loadUserByUsernameAndPassword(): Loads a user object by username and password.
• loadUserPermissions(): Loads the list of permissions a user has got.
• saveUser($user): Saves a user object within the current application.
• saveGroup($group): Saves a group object within the current application.
• saveRole($role): Saves a role object within the current application.
• savePermissionSet($permissionSet): Saves a permission set object within the current application.
• savePermission($permission): Saves a permission object within the current application.
• getPagedUserList(): Returns a list of users concerning the current page.
• getPagedGroupList(): Returns a list of groups concerning the current page.
• getPagedRoleList(): Returns a list of roles concerning the current page.
• getPagedPermissionSetList(): Returns a list of permission sets concerning the current page.
• getPagedPermissionList(): Returns a list of permissions concerning the current page.
• loadUserByID($userID): Returns a user domain object.
• loadGroupByID($groupID): Returns a group domain object.
• loadRoleByID($roleID): Returns a role domain object.
• loadPermissionSetByID($permissionSetID): Loads a permission set by it's id.
• loadPermissionList(): Loads a list of permissions of the current application.
• loadPermissionByID($permID): Loads a permission by it's id.
• loadRolesNotWithPermissionSet($permissionSet): Loads a list of roles, that are not associated with the permission set.
• loadRolesWithPermissionSet($permissionSet): Loads a list of roles, that are associated with the permission set.
• assignPermissionSet2Roles($permissionSet,$roles): Associates a given permission set to a list of roles.
• detachPermissionSetFromRoles($permissionSet,$roles): Removes a given permission set from a list of roles.
• deleteUser($user): Deletes a user.
• deleteGroup($group): Deletes a group.
• deleteRole($role): Deletes a role.
• deletePermissionSet($permissionSet): Deletes a PermissionSet.
• deletePermission($permission): Deletes a Permission.
• assignUser2Groups($user,$groups): Associates a user with a list of groups.
• assignUsers2Group($users,$group): Associates users with a group.
• assignRole2Users($role,$users): Associates a role with a list of users.
• loadGroupsWithUser(&$user): Loads all groups, that are assigned to a given user.
• loadGroupsNotWithUser(&$user): Loads all groups, that are not assigned to a given user.
• loadUsersWithGroup(&$group): Loads all users, that are assigned to a given group.
• loadUsersNotWithGroup(&$group): Loads all users, that are not assigned to a given group.
• loadRolesWithUser(&$user): Loads all roles, that are assigned to a given user.
• loadRolesNotWithUser(&$user): Loads all roles, that are not assigned to a given user.
• loadUsersWithRole(&$role): Loads a list of users, that have a certail role.
• loadUsersNotWithRole(&$role): Loads a list of users, that don't have the given role.
• loadPermissionsOfPermissionSet(&$permissionSet): Loads the permissions associated with a permission set.
• detachUserFromRole($user,$role): Detaches a user from a role.
• detachUsersFromRole($users,$role): Detaches users from a role.
• detachUserFromGroup($user,$group): Removes a user from the given groups.
• detachUserFromGroups($user,$groups): Removes a user from the given groups.
• detachUsersFromGroup($users,$group): Removes users from a given group.
• loadUserByFirstName($firstName): Loads a user by it's first name.
• loadUserByLastName($lastName): Loads a user by it's last name.
• loadUserByEMail($email): Loads a user by it's email.
• loadUserByFirstNameAndLastName($firstName,$lastName): Loads a user by it's first and last name.
• loadUserByUserName($username): Loads a user by it's user name.

2. Installation

The installation contains three major steps:

• Configuration of the module itself
• Configuration of the GenericORMappers
• Installation of the database

2.1. Configuration of the module

The configuration file of the usermanagement module covers three params: the key of the database connection, the id of the application container and the service mode, that is used to create the OR mapper instance: The adventure-configpack-* package contains an example configuration file with a detailed description of the params.

Due to the fact, that the data object model features an Application object, the usermanagement can be used for several applications at the same time and the same database. This again enables you to create a common user database for different applications or modules and reuse users within them. When using the UmgtManager, the ApplicationID must be defined, that the component knows, which application instance should be used.

2.2. Configuration of the O/R mapper

Because of the fact, that the module is completely based on the GenericORMapper a set of configuration files must be provided for the UML above. To ease setup, the adventure-configpack-* package contains the configuration files, that are necessary to setup the OR mapper. The files located under /modules/usermanagement/ must therefor be copied into the correct config namespace. Please be aware, that the configuration files must be located within the correct context folder. Details can be taken from the configuration chapter.

As you can read about in the GenericORMapper documentation, a pair of configuration files is used to define the objects and relations available within one onstance of the mapper.

2.3. Installation of the database

As a last step, the database must be prepared. For this reason, the /modules/usermanagement/data/scripts/setup.sql script must be executed against the desired database. After that, the module is ready for use.

It is recommended to use a seperate database for the module. Basically, there is no restriction installing the tables within an existing database. Because of the usage of the ConnectionManager, within one application multiple databases can be addressed.

3. Usage

3.1. Backend

In order to use the integrated backend, a seperate bootstrap file must be created or the application can be integrated within another using taglibs.Thanks to the generic implementation, the url creation recognizes external params (e.g. for navigation purposes).

Because the backend is completely based on the front controller (e.g. displaying of the icons is realized by the <*:mediastream /> tags), the index.php must contain the following code: If the backend should be included as a view, the following tag definition can be used: In case, the application the usermanagement is integrated in is based on a front controller action that is used for navigation, the module must be included using the <generic:importdesign /> tag. Please note, that the navigation action class must then be defined with $__KeepInURL = true to enable the Link creation method to include these params. If not, navigation probably is not working. Details on the tag can be taken from the special taglibs chapter.

As mentioned above, the image and icon delivery of the module is done by <*:mediastream /> tags. These tags generate an image source url, that contains a front controller action directive. As described in the front controller chapter, every action must be defined within a configuration file. To enable the image display, please create the configuration file within the namespace The content of the file is as follows: Details on the naming of configuration files can be taken from the corresponding configuration chapter.

3.2. Business component

The API of the UmgtManager class basically works with objects. This means, that arguments applied to the class' methods must be instances of the GenericDomainObject class. Return values are also instances or lists of GenericDomainObject objects or null.

3.2.1. Login via username and password

The following example shows, how easily authentication can be done by URL values:

3.2.2. Login via email and password

In order to authenticate by email and password, the call must be replaced by

3.2.3. Loading of groups and roles

If a user was authenticated succesfully by the methods described in 3.2.1 and 3.2.2, the user's groups and roes can be loaded as follows:

3.2.4. Loading of user permissions

If the developer needs to access the user's function permissions, these can be accesed via the associated roles or the API method intended for this task: The disatvantage of the first variant is, that permissions may apear twice ore more with in the list of permissions, because one or more roles can have the same permissions associated.

3.2.5. Manipulation of objects

For the manipulation of objects a couple of methods are included in the API. The following code box depicts, how user, groups and roles can be created, updated and deleted. Because of the fact, that all business objects are instances of the GenericDomainObject class, the developer must take care, that the name of the desired object is set correctly dusing instanciation. The name must be equal to the object's name within the configuration. The same is true for the attributes. Details can be taken from the object definition chapter on the OR mapper documantation page.

3.2.6. Manipulation of relations

In order to create, modify and delete relations between the objects managed by the OR mapper (see UML for details), the developer is provided several functions. These are focused on the dedicated application use case and expect instances of the GenericDomainObject as arguments. The follwing code boy describes several use cases:

3.2. Direct access

If the API of the UmgtManager does not support a special case, the GenericORMapper can be used to directly access the database. Please be aware to use the same configuration files, you took for the usermanagement setup to ensure data consistency. The next code example shows you how to create the OR mapper instance: The params $connectionKey and $serviceMode must be filled with the values of the configuration file of the usermanagement module. The ServiceMode directive is optional.

After creating the mapper it can be used concerning the configuration files. The following source code example counts the users within on group. The $oRM contains a mapper instance as defined above. If you want to test, if a user is included in a dedicated group or if it has associated a dedicated role, the following code can be used: In order to freely define the selection criterions, the GenericORMapper features the methods

• loadObjectByStatement()
• loadObjectByTextStatement()
• loadObjectByCriterion()
• loadObjectListByStatement()
• loadObjectListByTextStatement()
• loadObjectListByCriterion()

These functions expect sql statements or a GenericCriterionObject. To load all permissions associated with one role, you can use this code snippet: To get a list of available application containers, the following code can be used: Details on the objects, attributes and relations of the module can be taken from the configuration file or the UML diagram. The usage of the OR mapper can be read about in the GenericORMapper chapter.

4. Extension

4.1. Password encryption

4.1.1. Enhancement-of-the-manager

The business component uses the MD5 algorithm to create a password hash. If you intend to change this behaviour (e.g. to SHA1), this goal can be achieved by extending the umgtManager class and overwrite the __createPasswordHash() method. Please be aware, that the new class does not overwrite the init() function.

The new class can be used exactly as the old one. The following example shows, how you can change the hashing algo:

4.1.2. Implementation of the PasswordHashProvider

Since version Version 1.11, you can define your own PasswordHashProvider within the configuration file of the usermanagement module. This component is responsible for creating a password hash for the umgtManager. In default case, md5 is used so far.

In order to provide a custom password hash component, a new PHP class must be created implementing the PasswordHashProvider interface. It defines a method, that calculates a hash key out of a given clear text password. Going along with the above example, the class is as follows: To activate this provider, the configuration must be added the two directies, that specify the namespace and (class) name of the component: Complete usermanagement sample configuration files can be found in the apf-configpack-* release packages.

4.2. Display name manipulation

The display name of a user is generated as by default. In order to influence this, the umgtManager must be extended as described earlier in this chapter. For this reason, the __getDisplayName($user) must be overridden. The type of the argument is GenericDomainObject and the user management manager expects it to return the desired display name or the given user as string.

To take the email address as a display name, the following code snippet can be used:

Comments

QUICKNAVI

• All releases
• Roadmap
• Subversion repository
• Bugtracking
• Why APF?
• Articles
• Wiki
• RPM Installation HOWTO
• Partner sites
• APF auf SourceForge.net

• Imprint
• Contact
• Privacy policy
• Legal notice
• Security
• License

Adventure PHP Framework (APF) is a product developed by the APF Developer Team. It's released under the GNU Lesser General Public License (LGPGL)
Commercial use is permitted.

Copyright © 2009 Adventure PHP Framework
All textual content on this site is protected by Copyright Law and may be used under the Terms of the GNU Free Documentation License (GNU FDL) See Legal notice for more information.