Important

You are browsing the documentation for version 4.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Protect Entities Using ACLs

Using ACLs you can granularly grant access to your entities. Doing so requires three steps:

  1. Activate ACL checks for your entities.

  2. Create access control lists for all available actions.

  3. Add access checks to where your entities are displayed or manipulated.

Activating ACL Checks on your Entities

In order to have your entity available in the admin UI to be able to assign permissions to your users you have to enable ACLs for these entities using the @Config annotation:

 1// src/AppBundle/Entity/Task.php
 2namespace AppBundle\Entity;
 3
 4use Oro\Bundle\EntityConfigBundle\Metadata\Annotation\Config;
 5
 6/**
 7 * @Config(
 8 *     defaultValues={
 9 *         "security"={
10 *             "type"="ACL",
11 *             "group_name"=""
12 *         }
13 *     }
14 * )
15 */
16class Task
17{
18    // ...
19}

After you have done this and have cleared the cache you can toggle all kinds of permission checks (CREATE, EDIT, DELETE, VIEW, and ASSIGN) in the user role management interface.

Tip

You can use the optional group_name attribute to group entities by application. The value of this attribute is used to split the configured access control list into application scopes.

Creating Access Control Lists

You have two options to define your custom access control lists:

  1. In your controller class, you can use the @Acl annotation:

     1// src/AppBundle/Controller/TaskController.php
     2namespace AppBundle\Controller;
     3
     4use AppBundle\Entity\Task;
     5use Oro\Bundle\SecurityBundle\Annotation\Acl;
     6use Symfony\Bundle\FrameworkBundle\Controller\Controller;
     7use Symfony\Component\HttpFoundation\Request;
     8
     9class TaskController extends Controller
    10{
    11    /**
    12     * @Acl(
    13     *   id="app_task_view",
    14     *   type="entity",
    15     *   class="AppBundle:Task",
    16     *   permission="VIEW"
    17     * )
    18     */
    19    public function indexAction()
    20    {
    21        // ...
    22    }
    23
    24    /**
    25     * @Acl(
    26     *   id="app_task_create",
    27     *   type="entity",
    28     *   class="AppBundle:Task",
    29     *   permission="CREATE"
    30     * )
    31     */
    32    public function createAction(Request $request)
    33    {
    34        // ...
    35    }
    36
    37    /**
    38     * @Acl(
    39     *   id="app_task_edit",
    40     *   type="entity",
    41     *   class="AppBundle:Task",
    42     *   permission="EDIT"
    43     * )
    44     */
    45    public function editAction(Task $task, Request $request)
    46    {
    47        // ...
    48    }
    49}
    

    Using the @Acl annotation does not only create new access control lists to which you can refer in other parts of your code it will also trigger the access decision manager when your actions are accessed by users and thus protect them from being accessed without the needed permissions.

  2. If you do not want to protect any controller methods or if you prefer to keep the definition of your ACLs separated from the application code, you can define them using some YAML config in a file named acls.yml:

     1# src/AppBundle/Resources/config/oro/acls.yml
     2acls:
     3    app_task_create:
     4        type: entity
     5        class: AppBundle\Entity\Task
     6        permission: CREATE
     7
     8    app_task_delete:
     9        type: entity
    10        class: AppBundle\Entity\Task
    11        permission: DELETE
    12
    13    app_task_edit:
    14        type: entity
    15        class: AppBundle\Entity\Task
    16        permission: EDIT
    17
    18    app_task_view:
    19        type: entity
    20        class: AppBundle\Entity\Task
    21        permission: VIEW
    

Performing Access Checks

Once you have configured the ACLs you can protect all parts of your application. Anywhere in your PHP code you can use the isGranted() method of the security.authorization_checker service (which is an instance of the Symfony\Component\Security\Core\Authorization\AuthorizationCheckerInterface class):

1$authorizationChecker = $this->get('security.authorization_checker');
2
3if ($authorizationChecker->isGranted('app_static_pages')) {
4    // do something when the user is granted permissions for the app_static_pages ACL
5}

You can set the second parameter to check access on Object level (with Access Level check):

1$taskEntity = $this->getTask();
2
3$authorizationChecker = $this->get('security.authorization_checker');
4
5if ($authorizationChecker->isGranted('app_task_edit', $taskEntity)) {
6     // do something when the user is granted permissions for the app_task_edit ACL of the entity in $taskEntity
7}

In case if you does not have proper ACL annotation, you can set the first parameter as the permission name you want to check:

1$taskEntity = $this->getTask();
2
3$authorizationChecker = $this->get('security.authorization_checker');
4
5if ($authorizationChecker->isGranted('EDIT', $taskEntity)) {
6    // do something when the user is granted EDIT permission for the $taskEntity
7}

This example will work the same as before. It will check an EDIT permission for the Task instance object.

However, there are ways to make this checks in different parts of your application:

Hiding Menu Items

Use the acl_resource_id option to hide navigation items from users who are not granted to access the action being linked. The value of this option is the name of the ACL to check for:

1# src/AppBundle/Resources/config/oro/navigation.yml
2menu_config:
3    items:
4        task_list:
5            label: Tasks
6            route: app_task_index
7            acl_resource_id: app_task_view

Protecting Controllers Refering to Existing ACLs

As shown above you can define new ACLs and protect your controllers with them in a single step using the @Acl annotation. However, you can also refer to an existing access control list using the @AclAncestor annotation:

 1// src/AppBundle/Controller/TaskController.php
 2namespace AppBundle\Controller;
 3
 4use AppBundle\Entity\Task;
 5use Oro\Bundle\SecurityBundle\Annotation\AclAncestor;
 6use Symfony\Bundle\FrameworkBundle\Controller\Controller;
 7
 8class TaskController extends Controller
 9{
10    /**
11     * @AclAncestor("app_task_view")
12     */
13    public function viewAction(Task $task)
14    {
15        // ...
16    }
17
18    // ...
19}

Show Parts of Templates Based on Permissions

Inside your templates you can use the is_granted() Twig function to check for certain permissions to hide parts of your views for users who do not have the required permissions:

1{# src/AppBundle/Resources/views/Task/update.html.twig #}
2{% block someBlock %}
3    {% if is_granted('app_task_edit') %}
4        Some info if access is granted
5    {% endif %}
6{% endblock %}

In this example we check access by ACL annotation info without Object to test. So, is_granted will return true as result if user have any access level to EDIT permission to Task entity.

In case if you want to check access more deeply, you can set the entity instance as the second parameter of is_granted() function:

1{# src/AppBundle/Resources/views/Task/update.html.twig #}
2{% block someBlock %}
3    {# an `entity` variable contains an Test entity instance #}
4    {% if is_granted('app_task_edit', entity) %}
5        Some info if access is granted
6    {% endif %}
7{% endblock %}

At this example, will be checked access level for the given object instance.

In case if you have no an ACL annotation, you can set the permission name directly as the first parameter:

1{# src/AppBundle/Resources/views/Task/update.html.twig #}
2{% block someBlock %}
3    {# an `entity` variable contains an Test entity instance #}
4    {% if is_granted('EDIT', entity) %}
5        Some info if access is granted
6    {% endif %}
7{% endblock %}

Restrict Access to Data Grid Results

In a data grid you can protect the entire result set (to not show results if the user is not granted access and the action embedding the grid accidentally was not protected):

1# src/AppBundle/Resources/config/oro/datagrids.yml
2datagrids:
3    app-tasks-grid:
4        source:
5            acl_resource: app_task_view
6
7    # ...

Hide Unaccessible Grid Actions

Also use the acl_resource option to hide actions in a data grid the user does not have access to:

 1# src/AppBundle/Resources/config/oro/datagrids.yml
 2datagrids:
 3    app-tasks-grid:
 4        # ...
 5        actions:
 6            # ...
 7            edit:
 8                type: navigate
 9                label: Edit
10                link: update_link
11                icon: edit
12                acl_resource: app_task_edit
13            delete:
14                type: delete
15                label: Delete
16                link: delete_link
17                icon: trash
18                acl_resource: app_task_delete

Check Access on ORM Queries

You can protect your Doctrine ORM query with apply method of oro_security.acl_helper service.

 1use Doctrine\ORM\Query;
 2use Doctrine\ORM\QueryBuilder;
 3
 4use Oro\Bundle\SecurityBundle\ORM\Walker\AclHelper;
 5
 6class TaskController extends Controller
 7{
 8    public function viewAction(Task $task)
 9    {
10        /** @var QueryBuilder $qb */
11        $qb = $this->getSomeQuery();
12
13        /** @var Query $query */
14        $query = $this->getContainer()->get('oro_security.acl_helper')->apply($qb);
15
16        $result = $query->getResult();
17
18        // ...
19    }
20
21    // ...
22}

As result, the query will be modified and the result data set will contain only the records user can see.

By default, VIEW permission used as the second parameter. If you want to check another permission, you can set it as the second parameter of apply method.