Better documentation for the admin_permissions key

Looking at the "links" key in the @ContentEntityType annotation, I see...

• The admin_permission key affects view access at my collection path, which in my case are administrative lists of entities.
• The admin_permission key does NOT affect access or use of canonical, add-form, edit-form and delete-form paths.
• If my user doesn't have the permission in the admin_permission key, they can't view the administrative list of entities, but can perform all other operations if permitted in a class that extends EntityAccessControlHandler.

If I dump the $operation in my checkAccess method (in my class extending EntityAccessControlHandler), I see that in my collection path, checks are performed for each of the "Operations" buttons -- in my case the "update" and "delete" strings are dumped. Thus, an access check is performed for determining which options to present in the operations widget, but no check is performed on the collection path itself.

So, it seems to be the job of the admin_permissions key to determine if the user can view the contents of a list, but the links in the operations widget are determined by the checkAccess method.

I'm having a difficult time determining what controls the inclusion of links in menus.

The admin_permission key in some cases does affect whether links are included in menus, but not in all cases. There are definitely times when changing the admin_permission key affects links in my menu block for one of my users. However, I can't determine any pattern. This behavior seems to be erratic and is affected by a combination of factors, somehow.

The admin_permission key in some cases does affect whether links are included in menus, but not in all cases. There are definitely times when changing the admin_permission key affects links in my menu block for one of my users. However, I can't determine any pattern. This behavior seems to be erratic and is affected by a combination of factors, somehow.

I had a bug in my code that was making it seem like the menu behavior was erratic, but now it looks like it all works as designed.

The admin_permission key controls...

1) Whether the user can access the page/resource at the 'collection' path (as set in the entity type annotation).
2) Whether the link to that page/resource will be visible to the user in menus.

Meanwhile, the appropriate place to control access for all entity operations (view, update, delete, add) is in one's implementation of EntityAccessControlHandler. That implementation controls access to the operations and, appropriately enough, whether the corresponding action links are visible to the user.

To alter the access to routes more generally, extend RouteSubscriberBase. This class can be extended to alter access to any route, including, in theory, the same route affected by the admin_permission key. If a route subscriber sets a different access level for the same route as the one affected by admin_permission, the more restrictive permission is applied.

All of the above seems like good design to me, and it all seems to work consistently at the moment.

Arguably, for clarity's sake, a permission string like the following would make sense to use in custom modules...

admin_permission = "access my_entity collection",

...since the admin_permission key controls access to the collection path. Or even something that references the annotation keys explicitly like...

admin_permission = "my_entity links_collection",

Looking at it another way, this is probably a bad use of the admin_permission key...

admin_permission = "administer my_entity entities",

...because that could lead another developer or admin to think that if they tick the box for the admin permission in the UI, that they are granting the user administrative privileges, when most likely they are only granting the user permission to access one page in the admin interface... unless the "administer my_entity entities" permission is *also* used for some other purpose, which would likely be bad design in a lot of cases.

I just discovered that the admin_permission key also affects $entity_type->getAdminPermission(). The getAdminPermission method returns the string set in the admin_permission key.

This adds some uncertainty about how best to set the admin_permission key. It's not very surprising that a getAdminPermission method would return a value set in an admin_permission key, but I figure there is a chance other developers will expect they can call that getAdminPermission method on my entity, so I have to provide something in the admin_permission key that makes sense. What I might end up doing is set it to "do_not_use". That is probably more than sufficient within the context of my project to make it clear to all collaborators that we aren't using the key, and I guess we'll probably know soon enough if this somehow will cause a problem in terms of how the core interacts with our modules.

I might actually be making too much of it but I am trying to think through the access very deliberately because there will be a lot of code built on top of my code and I don't want to take a wrong turn.

Thanks again Berdir. I am once again thinking the code is probably all fine and I just need to understand it better.

Just because the route builder uses it for the collection doesn't mean it's not also used for CRUD, it most certainly is

I just generated a module with console called my_debug. If I do not give the user "administer debug entities" permissions, but do give the user "create debug entities" permission, the user can create debug entities. I don't see any sense in which the admin_permission key affects any CRUD operations. Am I missing something, or is there something idiosyncratic about the modules generated by console?

Even if I remove the checkAccess function from MyDebugAccessControlHandler, the user can still add an entity if they have create permission but not the admin_permission.

So it seems to me the admin_permission controls access to these two pages...

• admin/structure/my_debug
• admin/structure/my_debug/settings

Berdir,

Just because the specific create permission allows create access doesn't mean that the administer permission doesn't also allow that.

Though it may not be authoritative, the module generated by Drupal console doesn't support what you are saying. No doubt a developer could modify the code subsequent to generation to make it support what you are saying, but I'm noting that directly after generation, assignment of the admin_permission does not affect whether my user can CRUD an entity.

I understand that the console-generated module is not the ultimate authority, but as I try to learn how access works in Drupal 8, I am referring to the module code generated by console just because that is a fixed point that I can test against. Is there something idiosyncratic about the console-generated module? Is the console-generated module leading me astray? Do we need to suggest changes to the console-generated module to bring it in line with Drupal best practices? (As you can see, I'm in the process of learning what Drupal 8 best practices might be, with regard to entity access.)

I am just going on direct obervation. If I generate a module and content type with console, and make no changes at all to that code, and then assign a user create perms but not the admin permission, the user can indeed create entities.

Whatever is actually the case, that is what I will want to describe in my documentation. Are you finding that the admin_permission affects CRUD operations? If so, how can I reproduce that?

Also, create access is checked in checkCreateAccess(), not checkAccess(), so removing that won't change that.

True! Thanks for catching that. However, unfortunately it doesn't change my findings. I still can't configure my way to any situation where the admin_permission affects CRUD access unless I modify the code that console generated. And if I remove both the checkAccess and createCheckAccess functions, the admin_permission still does not affect CRUD access.

(I know there may be some meta considerations here, like whether I should be thinking of the console-generated module as a kind of documentation... but I think in many cases developers will learn how things work from the example modules and from the console-generated modules. And probably moreso the latter.)

Berdir,

#15 is very helpful. I can now confirm that the in the console-generated module, the admin permission does (or can) affect access to CRUD operations, and the only reason I thought it didn't was, as you say, the checkCreateAccess method in MyDebugAccessControlHandler. When I remove the checkCreateAccess function and make no other changes to the console-generated module, this is clear.

The point is that the admin permission is an optional feature that the entity system provides that you can use if you have a simple use case for your permission handling. If you don't want it, then don't use it.

Yes, we should note this in the documentation somewhere, perhaps at https://www.drupal.org/docs/8/api/entity-api/structure-of-an-entity-anno...

Strictly speaking, we probably can't say it's an optional feature of the annotation itself, because its value will be returned when other developers call getAdminPermission(). If the key is removed from the annotation, there is an error when you install the module. It is optional in the sense that a module developer need not call getAdminPermission() in their own module if they don't want, and can also override the methods in EntityAccessControlHandler where getAdminPermission is called.

The existing bit of documentation that I noted in the issue summary:

The admin_permission key automatically allows all access for users with that permission. In case more logic is required, a custom access controller can be specified.

Maybe we can be more explicit. Maybe something like...

In a simple, default implementation, the admin_permission provides full access to the entity, including all CRUD operations. To change this default behavior, you can override the EntityAccessControlHandler::checkAccess or EntityAccessControlHandler::checkCreateAccess in your custom module.

For an example showing how you can override the checkAccess and checkCreateAccess in a custom access controller, refer to the content_entity_example module, or generate a content entity module with Drupal console. In the content_entity_example and console-generated module, note how the getAdminPermission() method serves to retrieve the admin_permission value for an entity type.

What do you think of the above?

What I'd recommend is create an issue for console so that their default implementation actually considers the admin permission.

I suppose the trick is to add something to the example module and console-generated module that helps document the feature, but without adding code to the module that no one would actually use. Maybe the default implementation in example modules could be...

  /**
   * {@inheritdoc}
   */
  protected function checkCreateAccess(AccountInterface $account, array $context, $entity_bundle = NULL) {

    if ($admin_permission = $this->entityType->getAdminPermission()) {
      // Check the admin_permission as defined in your @ContentEntityType annotation.
      return AccessResult::allowedIfHasPermission($account, $admin_permission);
    }
    else {
      return AccessResult::allowedIfHasPermission($account, 'add my_entity entities');
    }
  }

No, there is no error.

Here is what I see when I try to install a custom module without the admin_permission key:
The website encountered an unexpected error. Please try again later.</br></br><em class="placeholder">InvalidArgumentException</em>: Routing requirement for &quot;_permission&quot; must be a string. in <em class="placeholder">Symfony\Component\Routing\Route-&gt;sanitizeRequirement()</em> (line <em class="placeholder">572</em> of <em class="placeholder">/var/www/my/path/vendor/symfony/routing/Route.php</em>).

Another possibility for checkCreateAccess() for the examples module:

/**
   * {@inheritdoc}
   */
  protected function checkCreateAccess(AccountInterface $account, array $context, $entity_bundle = NULL) {

    if (\Drupal::currentUser()->hasPermission($this->entityType->getAdminPermission())) {
      return AccessResult::allowed();
    }
    else {
      return AccessResult::allowedIfHasPermission($account, 'add my_entity entities');
    }
  }

Yes, the previous attempt was incorrect, for the reason you mentioned.