
Dans Drupal, une vérification d’accès ne répond pas seulement « oui » ou « non ». Elle répond aussi pour qui et pour combien de temps cette réponse est valable. Oublier cette deuxième partie, c’est prendre le risque qu’une décision calculée pour un administrateur soit servie depuis le cache à un simple visiteur.
Cet article couvre les access checkers personnalisés, la logique de AccessResult, ses métadonnées de cache, et la différence souvent mal comprise entre hook_entity_access et les node grants.
AccessResult : trois états, pas deux
Toute vérification d’accès moderne retourne un AccessResultInterface, avec trois états possibles :
- allowed : j’autorise ;
- neutral : je n’ai pas d’avis ;
- forbidden : j’interdis, et personne ne peut passer outre.
Ils se combinent avec deux opérateurs :
orIf() |
andIf() |
|
|---|---|---|
| Un des deux est forbidden | forbidden | forbidden |
| Au moins un allowed | allowed | neutral si l’autre est neutral |
| Les deux allowed | allowed | allowed |
| Les deux neutral | neutral | neutral |
C’est ce qui permet à plusieurs modules de voter sur le même accès : hook_entity_access est combiné avec orIf(), et un seul forbidden suffit à fermer la porte. Selon le contexte, un neutral final vaut un refus : c’est le cas pour l’accès aux routes, qui exige un allowed.
Surtout, orIf() et andIf() fusionnent les métadonnées de cache des résultats qui ont participé à la décision. Un résultat d’accès est un objet cacheable, au même titre qu’un render array.
Un access checker personnalisé
Cas d’usage : un site de gestion de projets. La page /project/{node}/reports doit être accessible aux membres du projet (un champ field_members qui référence des utilisateurs) et aux administrateurs.
La route
# my_module.routing.yml
my_module.project_reports:
path: '/project/{node}/reports'
defaults:
_controller: '\Drupal\my_module\Controller\ProjectReportsController::view'
_title: 'Rapports'
requirements:
_project_member: 'TRUE'
options:
parameters:
node:
type: entity:node
Le service
# my_module.services.yml
services:
my_module.project_member_access:
class: Drupal\my_module\Access\ProjectMemberAccessCheck
tags:
- { name: access_check, applies_to: _project_member }
Le tag access_check avec applies_to associe le service à la clé _project_member des requirements. Toutes les routes qui déclarent cette clé passent par lui.
La classe
<?php
namespace Drupal\my_module\Access;
use Drupal\Core\Access\AccessResult;
use Drupal\Core\Access\AccessResultInterface;
use Drupal\Core\Routing\Access\AccessInterface;
use Drupal\Core\Session\AccountInterface;
use Drupal\node\NodeInterface;
final class ProjectMemberAccessCheck implements AccessInterface {
public function access(AccountInterface $account, NodeInterface $node): AccessResultInterface {
if ($node->bundle() !== 'project') {
return AccessResult::forbidden('Not a project.')->addCacheableDependency($node);
}
$is_member = in_array(
$account->id(),
array_column($node->get('field_members')->getValue(), 'target_id')
);
return AccessResult::allowedIfHasPermission($account, 'administer projects')
->orIf(
AccessResult::allowedIf($is_member)
->addCacheContexts(['user'])
->addCacheableDependency($node)
);
}
}
Les arguments de access() sont résolus par leur nom et leur type : $account reçoit l’utilisateur courant, $node le paramètre de route déjà converti en entité. Vous pouvez aussi demander RouteMatchInterface $route_match, Route $route ou Request $request.
Le vrai sujet : les métadonnées de cache
Relisons le code sous l’angle du cache :
allowedIfHasPermission()ajoute automatiquement le contexteuser.permissions.allowedIf($is_member)ne sait rien de la façon dont$is_membera été calculé. C’est à vous de dire que le résultat dépend de l’utilisateur (user) et du nœud (addCacheableDependency($node), qui ajoute le tagnode:42).- Sans
addCacheableDependency($node), retirer un membre du projet n’invaliderait pas les résultats déjà en cache.
Où ça fuit en pratique
L’accès à la route elle-même n’est pas mis en cache tel quel. La fuite arrive quand ce résultat sert à construire un rendu : un lien « Voir les rapports » dans un bloc, un menu, un teaser.
// ❌ Le booléen perd toutes les métadonnées de cache.
$url = Url::fromRoute('my_module.project_reports', ['node' => $node->id()]);
if ($url->access()) {
$build['reports'] = Link::fromTextAndUrl($this->t('Rapports'), $url)->toRenderable();
}
Ce bloc est mis en cache sans contexte user. Le premier utilisateur qui l’affiche décide pour tout le monde : si c’est un membre, tous les visiteurs voient le lien ; sinon, aucun membre ne le voit.
// ✅ L'objet AccessResult est passé à #access, le renderer fusionne sa cacheabilité.
$url = Url::fromRoute('my_module.project_reports', ['node' => $node->id()]);
$build['reports'] = Link::fromTextAndUrl($this->t('Rapports'), $url)->toRenderable();
$build['reports']['#access'] = $url->access(NULL, TRUE);
Le deuxième argument TRUE de access() demande un objet AccessResultInterface au lieu d’un booléen. Le renderer accepte cet objet dans #access et ajoute ses contextes et tags au rendu. La règle s’applique aussi à $entity->access('update', NULL, TRUE).
Et si le résultat n’est pas utilisé dans un render array ? Appliquez-le explicitement :
CacheableMetadata::createFromObject($access)->applyTo($build);
Choisir le bon contexte
| Contexte | Varie selon | Cardinalité |
|---|---|---|
user.permissions |
L’ensemble des permissions | Faible |
user.roles |
Les rôles | Faible |
user.roles:editor |
Le fait d’avoir le rôle editor |
2 variantes |
user |
L’utilisateur | Une variante par utilisateur |
Le contexte user est correct mais coûteux : il déclenche l’auto-placeholdering (voir l’article sur les lazy builders). Si l’accès dépend d’une donnée partagée par beaucoup d’utilisateurs (une équipe, une organisation), un contexte de cache personnalisé (un service tagué cache.context) réduit fortement le nombre de variantes.
hook_entity_access vs node grants
C’est la confusion la plus fréquente, et elle produit de vraies fuites de données.
hook_entity_access : décision au cas par cas
function my_module_node_access(NodeInterface $node, $operation, AccountInterface $account) {
if ($operation === 'view' && $node->bundle() === 'project') {
$members = array_column($node->get('field_members')->getValue(), 'target_id');
return AccessResult::forbiddenIf(!in_array($account->id(), $members))
->addCacheContexts(['user'])
->addCacheableDependency($node);
}
return AccessResult::neutral();
}
Ce hook est appelé quand une entité précise est vérifiée : affichage d’une page, $node->access(), rendu d’une entité. Il n’est pas appelé quand une requête liste des entités. Une vue « Derniers projets » affichera donc les titres de projets dont l’utilisateur n’est pas membre, même s’il obtient une 403 en cliquant.
Notez aussi que hook_node_access() n’est pas invoqué pour les utilisateurs qui ont la permission bypass node access.
Node grants : décision appliquée aux requêtes
Le système de grants (hook_node_access_records() + hook_node_grants()) stocke les droits dans la table node_access. Drupal les injecte automatiquement dans toutes les requêtes marquées node_access, ce qui comprend les entity queries avec accessCheck(TRUE) et les Views (sauf si « Disable SQL rewriting » est coché).
function my_module_node_access_records(NodeInterface $node) {
if ($node->bundle() !== 'project') {
return [];
}
$grants = [];
foreach ($node->get('field_members') as $item) {
$grants[] = [
'realm' => 'project_member',
'gid' => $item->target_id,
'grant_view' => 1,
'grant_update' => 0,
'grant_delete' => 0,
];
}
return $grants;
}
function my_module_node_grants(AccountInterface $account, $operation) {
return ['project_member' => [$account->id()]];
}
Le prix à payer : les grants sont précalculés. Modifier la logique impose de reconstruire les permissions (node_access_rebuild()), une opération longue sur un gros site. Ils ne concernent que les nœuds.
Et les autres entités ?
Pour les entités qui ne sont pas des nœuds, les entity queries avec accessCheck(TRUE) ajoutent le tag {entity_type}_access (par exemple media_access). Vous pouvez filtrer les listes avec hook_query_TAG_alter(), ou utiliser le module contrib Entity API, qui fournit un « query access » générique (événement entity.query_access) pour les entités qui le déclarent.
Drupal 10 : une entity query sur une entité de contenu doit appeler
->accessCheck(TRUE)ou->accessCheck(FALSE)explicitement, sinon une exception est levée. C’est le bon moment pour relire chaqueaccessCheck(FALSE)de votre code : chacun est une liste qui ignore les droits.
Résumé
| Besoin | Outil |
|---|---|
| Protéger une route | Access checker (_custom_access ou tag access_check) |
| Décider de l’accès à une entité affichée | hook_entity_access / hook_ENTITY_TYPE_access |
| Filtrer des listes de nœuds | Node grants |
| Filtrer des listes d’autres entités | hook_query_TAG_alter() sur {entity_type}_access |
Tester l’accès et sa cacheabilité
Un test Kernel peut vérifier les deux en même temps :
public function testMemberAccess(): void {
$member = $this->createUser();
$stranger = $this->createUser();
$project = $this->createNode(['type' => 'project', 'field_members' => [$member->id()]]);
$check = new ProjectMemberAccessCheck();
$result = $check->access($member, $project);
$this->assertTrue($result->isAllowed());
$this->assertContains('user', $result->getCacheContexts());
$this->assertContains('node:' . $project->id(), $result->getCacheTags());
$this->assertFalse($check->access($stranger, $project)->isAllowed());
}
Les assertions sur les contextes et les tags sont celles qui manquent le plus souvent, alors que ce sont elles qui protègent contre les fuites en production.
Conclusion
Un contrôle d’accès correct dans Drupal a deux dimensions : la décision, et sa cacheabilité. Retournez des objets AccessResult plutôt que des booléens, déclarez systématiquement de quoi dépend la décision, et choisissez entre hook_entity_access et node grants selon qu’il faut protéger une entité ou une liste. Ce sont trois réflexes simples qui évitent les failles les plus courantes sur les sites Drupal.
