Quick links: Content - sections - sub sections
EN FR

Before using jAcl2 API and its db driver, you have to setup a database and fill it with elements composing rights.

Installation

jAcl2.db driver requires a database to work. You have to create it with the needed tables and setup a connection profile.

Connection configuration

See the documentation about jDb setup.

If jAcl2 tables are not located in your default db profile, you should setup a profile called jacl2_profile, or an alias jacl2_profile to an existing profile. An example profiles.ini.php:


[jdb:default]
driver="mysql"
database="jelix"
host= "localhost"
user= "jelix"
password= "jelix"
persistent= on
force_encoding=true

[jdb:jacl2_profile]
driver="mysql"
database="rights"
host= "localhost"
user= "jelix"
password= "xilej"
persistent= on
force_encoding=true

jAcl2.db tables

To create and initialise tables needed by the driver, you should install the module jacl2db.


php cmd.php installmodule jacl2db

If you want to initialize rights for a first user/group named "admin":


php cmd.php installmodule -p defaultuser jacl2db

Once created, you can start configuring rights.

Rights configuration

Now you configure jacl2db with its two dedicated commands: acl2group and acl2right. Each one take a subcommand argument and following subcommand parameters.

In the following examples, with take "myapp" as the name of the application. Change it of course by the name of your application.

Note that you have a module, jacl2db_admin, which allow you to do everything described below with an interface, except the creation of subjects.

Subjects creation

In jAcl2 rights, you define subjects symbolizing a right value or concretely an operation.

Imagine a CMS where you want to define rights about articles. You could define right subjects for some actions like reading, listing, creating, deleting, updating. Concretely, you defines this topics:

  • "cms.articles.read",
  • "cms.articles.list",
  • "cms.articles.create",
  • "cms.articles.delete",
  • "cms.articles.update"

Note that topic id begin with a prefix, allowing to identify precisely what about it is. Using only "read" is not really explicit. So always add in the id, a name indicating what it is about precisely. Your code is then more readable.

Let's start by listing aleady existing subjects:


$ php cmd.php acl2right subject_list

You should have an empty list:


----Subject list

id			label key
--------------------------------------------------------

A subject record is a pair of identifier/label key. label keys should be existing locale key identifiers.

Let's create your subjects:


$ php cmd.php acl2right subject_create "cms.articles.create" "cms~acl2.articles.create"
$ php cmd.php acl2right subject_create "cms.articles.update" "cms~acl2.articles.update"
$ php cmd.php acl2right subject_create "cms.articles.delete" "cms~acl2.articles.delete"
$ php cmd.php acl2right subject_create "cms.articles.list" "cms~acl2.articles.list"
$ php cmd.php acl2right subject_create "cms.articles.read" "cms~acl2.articles.read"

If you don't use jAcl2 in a module then the locale key selector is not required. Just put any string of yours.

After execution, you get:


----Subject creation

OK

The OK message is always echoed upon success of an Acl2 command. Let's list the subjects again:


$ php cmd.php acl2right subject_list
----Subject list

id			label key
--------------------------------------------------------
cms.articles.create	cms~acl2.articles.create
cms.articles.delete	cms~acl2.articles.delete
cms.articles.list	cms~acl2.articles.list
cms.articles.read	cms~acl2.articles.read
cms.articles.update	cms~acl2.articles.update

You can delete a subject with the following command:


$ php cmd.php acl2right subject_delete  <subject id>

User group creation

A jAcl2.db right is a combination of a subject and a user group. You have to create user groups. Use acl2group commmand.

Let's create a writers group for our users. You should indicate an key and optionaly a label


$ php cmd.php acl2group  create "writers" "Writers"

Let's create a second group and make it the default one with -defaultgroup , ie. every new user will be added to this group.


$ php cmd.php acl2group -defaultgroup create "readers" "Readers"

You can now list your groups with list:


$ php cmd.php acl2group  list
----User group list

id           label name              default
--------------------------------------------------------
readers       Readers                 yes
writers       Writers

You can switch the "default" group with setdefault command:


$ php cmd.php acl2group setdefault readers true
# or
$ php cmd.php acl2group setdefault readers false

Or change a group name with groupname:


$ php cmd.php acl2group changename writers "Authors"

Or delete a group with delete:


$ php cmd.php acl2group delete writers

Managing users into groups

In groups, you should add users. To add a user, you should declare him:


$ php cmd.php acl2group createuser laurent

Note that it doesn't create the user into jAuth, just in jAcl2. A private group is created.

Then you can add him to a group. You should use the sub-command "adduser" and indicated the key of the group.


$ php cmd.php acl2group adduser readers laurent

To remove a user from a group:


$ php cmd.php acl2group removeuser readers laurent

To see the list of users of a group:


$ php cmd.php acl2group userslist readers

To see the list of all users:


$ php cmd.php acl2group alluserslist

Rights creation

You have every needed elements to create a right. Let's go and execute acl2right command.

You want to add readers the right to read and list articles. Let's associate readers group to cms.articles.list and cms.articles.read to the readers group:


$ php cmd.php acl2right add readers  "cms.articles.list"
$ php cmd.php acl2right add readers "cms.articles.read"

Check rights list with list subcommand:


$ php cmd.php acl2right list
----Rights list

group	subject		resource
---------------------------------------------------------------
- anonymous group

- group readers
	cms.articles.list
		-
	cms.articles.read
		-

Since Jelix 1.4.1, "-" for a resource means "no resource". So the indicated right is a right that is not applied on a resource. Before Jelix 1.4.1, the resource field was empty for this case.

Now, you want to deal with writers and give them all rights on cms.articles.


$ php cmd.php acl2right add  writers "cms.articles.list"
$ php cmd.php acl2right add  writers "cms.articles.read"
$ php cmd.php acl2right add  writers "cms.articles.create"
$ php cmd.php acl2right add  writers "cms.articles.delete"
$ php cmd.php acl2right add  writers "cms.articles.update"

Again, let's list all rights:


$ php cmd.php acl2right list
----Rights list

group   subject value           resource
---------------------------------------------------------------
- group readers
	cms.articles.list
		-
	cms.articles.read
		-
- group writers
	cms.articles.create
		-
	cms.articles.delete
		-
	cms.articles.list
		-
	cms.articles.read
		-
	cms.articles.update

However in your CMS you have an "advices" article which you want your readers to edit. you should add the right to update this specific article to readers group. Let's create a right on the resource "advices" with @@c@add@ subcommand:


$ php cmd.php acl2right add  readers "cms.articles.update" "advices"

checking of rights list:


$ php cmd.php acl2right list
----Rights list

group   subject value           resource
---------------------------------------------------------------
- group readers
	cms.articles.list
		-
	cms.articles.read
		-
	cms.articles.update 
		-
		advices


- group writers
	cms.articles.create
		-
	cms.articles.delete
		-
	cms.articles.list
		-
	cms.articles.read
		-
	cms.articles.update
		-

You can also remove a right, by passing a user group and a subject similarly to create (and optionally a resource if one is involved).

Say you change your mind over "advices" article, because there is too much crap ;-) :


$ php cmd.php acl2right remove  readers "cms.articles.update" "advices"

Once all rights are injected, your application is able to work following your rights rules.