.. _borealis-acl-label:

============================
 BorealisACL
============================
This driver for access authorization uses the borealis-acl library based on a user/action/resource triplet.


Geoprisma setting
-----------------
.. code-block:: php
    
    <?php
    
    org_geoprisma_SettingImpl::setACLClass('org_geoprisma_acl_BorealisACL');

    ?>
    
Driver extra parameter
----------------------
This driver needs the username of the current logged user.  For Geoprisma to know this name, you need to set it in th org_geoprisma_acl_BorealisACL class.

.. code-block:: php
    
    <?php

    org_geoprisma_acl_BorealisACL::setUsername('Current logged username');

    ?>
    
Optional - You can activate acl caching in a php session to improve speed

.. code-block:: php
    
    <?php

    org_geoprisma_acl_BorealisACL::setCaching(true);

    ?>
    
Driver setting
---------------
Borealis-acl currently supports two types of datastores : XML File and PDO compatible database

.. code-block:: php
    
    <?php

    com_borealis_acl_SettingImpl::setDataStore('com_borealis_acl_datastore_XMLDataStore');
    // or
    com_borealis_acl_SettingImpl::setDataStore('com_borealis_acl_datastore_PDODataStore');

    ?>

Driver setting - XMLDataStore
------------------------------
This datastore driver only needs the path to the xml datastore file.

.. code-block:: php
    
    <?php

    com_borealis_acl_SettingImpl::setDataStore('com_borealis_acl_datastore_XMLDataStore');
    com_borealis_acl_SettingImpl::setXMLConfigFile("acl.xml");

    ?>

example of acl.xml file
    
.. code-block:: xml
    
    <?xml version="1.0" encoding="iso-8859-1"?>
    <acl>
      <actions>
        <action>
          <id>1</id>
          <name>Action1</name>
        </action>
      </actions>
      <ressources>
        <ressource>
          <id>1</id>
          <name>Ressource1</name>
          <actions>
            <action>1</action>
          </actions>
        </ressource>
        <ressource>
          <id>2</id>
          <name>Ressource2</name>
          <actions>
            <action>1</action>
          </actions>
        </ressource>
      </ressources>
      <roles>
        <role>
          <id>1</id>
          <name>Role1</name>
          <members>
            <member>user1</member>
            <member>user2</member>
            <member>user3</member>
          </members>
        </role>
        <role>
          <id>2</id>
          <name>Role2</name>
          <members>
            <member>user2</member>
          </members>
        </role>
        <role>
          <id>3</id>
          <name>Role3</name>
          <members>
            <member>user3</member>
          </members>
        </role>
      </roles>
      <permissions>
        <permission>
          <role>1</role>
          <ressource>1</ressource>
          <action>1</action>
        </permission>
        <permission>
          <role>1</role>
          <ressource>2</ressource>
          <action>1</action>
        </permission>
        <permission>
          <role>2</role>
          <ressource>1</ressource>
          <action>1</action>
        </permission>
      </permissions>
    </acl>

Driver setting - PDODataStore
------------------------------
PHP PDO Compatible database


.. code-block:: php
    
    <?php

    com_borealis_acl_SettingImpl::setDataStore('com_borealis_acl_datastore_PDODataStore');
    com_borealis_acl_SettingImpl::setPDODataStoreDSN('pgsql:host=localhost;port=5432;dbname=acl;user=postgres;password=postgres');

    ?>
    
Optional setting if you not change database structure All database query are configurable with com_borealis_acl_SettingImpl setter check this api doc   

SQL Postgresql Database structure script

.. code-block:: sql

    CREATE TABLE bis_acl_action
    (
      id_action serial NOT NULL,
      "name" character varying,
      CONSTRAINT bis_acl_action_pk PRIMARY KEY (id_action),
      CONSTRAINT bis_acl_action_uk UNIQUE (name)
    );

    CREATE TABLE bis_acl_ressource
    (
      id_ressource serial NOT NULL,
      "name" character varying,
      CONSTRAINT bis_acl_ressource_pk PRIMARY KEY (id_ressource),
      CONSTRAINT bis_acl_ressource_uk UNIQUE (name)
    );

    CREATE TABLE bis_acl_role
    (
      id_role serial NOT NULL,
      "name" character varying,
      CONSTRAINT bis_acl_role_pk PRIMARY KEY (id_role),
      CONSTRAINT bis_acl_role_uk UNIQUE (name)
    );

    CREATE TABLE bis_acl_role_member
    (
      id_role_member serial NOT NULL,
      id_role integer,
      username character varying NOT NULL,
      CONSTRAINT bis_acl_role_member_pk PRIMARY KEY (id_role_member),
      CONSTRAINT bis_acl_role_member_id_role_fk FOREIGN KEY (id_role)
          REFERENCES bis_acl_role (id_role) MATCH SIMPLE
          ON UPDATE NO ACTION ON DELETE NO ACTION,
      CONSTRAINT bis_acl_role_member_uk UNIQUE (id_role, username)
    );

    CREATE TABLE bis_acl_ressource_action
    (
      id_ressource integer,
      id_ressource_action serial NOT NULL,
      id_action integer,
      CONSTRAINT bis_acl_ressource_action_pk PRIMARY KEY (id_ressource_action),
      CONSTRAINT bis_acl_ressource_action_id_action_fk FOREIGN KEY (id_action)
          REFERENCES bis_acl_action (id_action) MATCH SIMPLE
          ON UPDATE NO ACTION ON DELETE NO ACTION,
      CONSTRAINT bis_acl_ressource_action_id_ressource_fk FOREIGN KEY (id_ressource)
          REFERENCES bis_acl_ressource (id_ressource) MATCH SIMPLE
          ON UPDATE NO ACTION ON DELETE NO ACTION,
      CONSTRAINT bis_acl_ressource_action_uk UNIQUE (id_ressource, id_action)
    );

    CREATE TABLE bis_acl_permission
    (
      id_role integer NOT NULL,
      id_ressource_action integer NOT NULL,
      CONSTRAINT bis_acl_permission_pk PRIMARY KEY (id_role, id_ressource_action),
      CONSTRAINT bis_acl_permission_id_ressource_action_fk FOREIGN KEY (id_ressource_action)
          REFERENCES bis_acl_ressource_action (id_ressource_action) MATCH SIMPLE
          ON UPDATE NO ACTION ON DELETE NO ACTION
    );

SQL Postgresql Database some data script

.. code-block:: sql

    insert into bis_acl_action (name) values('update');

    insert into bis_acl_ressource (name) values('administration.acl');

    insert into bis_acl_ressource_action (id_ressource, id_action) values(
                                (select id_ressource from bis_acl_ressource where name = 'administration.acl'),
                                (select id_action    from bis_acl_action    where name = 'update'));

    insert into bis_acl_role (name) values('administrator');

    insert into bis_acl_role_member (id_role, username) values(
                                (select id_role from bis_acl_role where name = 'administrator'),
                                'admin');

    insert into bis_acl_permission (id_role, id_ressource_action) values(
                            (select id_role from bis_acl_role where name = 'administrator'),
                            (select id_ressource_action from bis_acl_ressource_action where id_ressource = (select id_ressource from bis_acl_ressource where name = 'administration.acl') and id_action = (select id_action from bis_acl_action where name = 'update') ));